From c2fb21d5b440bb986631c498969454e1d42d36c4 Mon Sep 17 00:00:00 2001 From: schwarze <> Date: Mon, 26 Aug 2019 11:41:31 +0000 Subject: document ASN1_put_object(3) and ASN1_put_eoc(3) --- src/lib/libcrypto/man/ASN1_TYPE_get.3 | 5 +- src/lib/libcrypto/man/ASN1_put_object.3 | 181 ++++++++++++++++++++++++++++++++ src/lib/libcrypto/man/Makefile | 3 +- 3 files changed, 186 insertions(+), 3 deletions(-) create mode 100644 src/lib/libcrypto/man/ASN1_put_object.3 (limited to 'src') diff --git a/src/lib/libcrypto/man/ASN1_TYPE_get.3 b/src/lib/libcrypto/man/ASN1_TYPE_get.3 index 3d6ad0bc63..a31f762335 100644 --- a/src/lib/libcrypto/man/ASN1_TYPE_get.3 +++ b/src/lib/libcrypto/man/ASN1_TYPE_get.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: ASN1_TYPE_get.3,v 1.10 2019/06/10 09:49:48 schwarze Exp $ +.\" $OpenBSD: ASN1_TYPE_get.3,v 1.11 2019/08/26 11:41:31 schwarze Exp $ .\" OpenSSL 99d63d46 Mon Jun 6 00:43:05 2016 -0400 .\" .\" This file is a derived work. @@ -65,7 +65,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd $Mdocdate: June 10 2019 $ +.Dd $Mdocdate: August 26 2019 $ .Dt ASN1_TYPE_GET 3 .Os .Sh NAME @@ -277,6 +277,7 @@ returns 0 for a match or non-zero for a mismatch. .Xr ASN1_generate_nconf 3 , .Xr ASN1_item_free 3 , .Xr ASN1_OBJECT_new 3 , +.Xr ASN1_put_object 3 , .Xr ASN1_STRING_dup 3 , .Xr ASN1_STRING_new 3 , .Xr crypto 3 , diff --git a/src/lib/libcrypto/man/ASN1_put_object.3 b/src/lib/libcrypto/man/ASN1_put_object.3 new file mode 100644 index 0000000000..f1f0021fe5 --- /dev/null +++ b/src/lib/libcrypto/man/ASN1_put_object.3 @@ -0,0 +1,181 @@ +.\" $OpenBSD: ASN1_put_object.3,v 1.1 2019/08/26 11:41:31 schwarze Exp $ +.\" +.\" Copyright (c) 2019 Ingo Schwarze +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd $Mdocdate: August 26 2019 $ +.Dt ASN1_PUT_OBJECT 3 +.Os +.Sh NAME +.Nm ASN1_put_object , +.Nm ASN1_put_eoc +.Nd start and end the BER encoding of an arbitrary ASN.1 data element +.Sh SYNOPSIS +.In openssl/asn1.h +.Ft void +.Fo ASN1_put_object +.Fa "unsigned char **ber_out" +.Fa "int constructed" +.Fa "int length" +.Fa "int tag" +.Fa "int class" +.Fc +.Ft int +.Fo ASN1_put_eoc +.Fa "unsigned char **ber_out" +.Fc +.Sh DESCRIPTION +.Fn ASN1_put_object +begins writing the BER encoding of an arbitrary ASN.1 data element +to the buffer +.Pf * ber_out +by writing the identifier and the length bytes. +Making sure that there is sufficient space in the buffer +is the responsibility of the caller. +This function does not write any content bytes +nor any end-of-content bytes. +.Pp +The tag +.Fa class +can be +.Dv V_ASN1_UNIVERSAL , +.Dv V_ASN1_APPLICATION , +.Dv V_ASN1_CONTEXT_SPECIFIC , +or +.Dv V_ASN1_PRIVATE +and is written to the two most significant bits of the first byte written. +.Pp +The +.Fa constructed +argument can have the following values: +.Bl -tag -width 1n -offset 2n -compact +.It 0 +Start a primitive value by setting the third most significant bit +of the first byte written to 0. +Always use the definite form. +.It 1 +Start a constructed value by setting the third most significant bit +of the first byte written to 1, and use the definite form. +.It 2 +Start a constructed value and use the indefinite form, +.El +.Pp +If the +.Fa tag +is less than 0x1f, it is written to the five least significant bits +of the only identifier byte written. +Otherwise, these five bits are all set to 1, and the +.Fa tag +is encoded in one or more following identifier bytes as needed. +.Pp +After completing the identifier byte(s), +when using the definite form, the given +.Fa length +is encoded in one or more bytes as needed. +Otherwise, the special byte 0x80 is written instead and the +.Ar length +argument is ignored. +.Pp +At the end, +.Pf * Fa ber_out +is set to the byte following the last byte written. +The calling code can then start writing content bytes. +.Pp +If the indefinite form was selected, +the calling code is also responsible for calling +.Fn ASN1_put_eoc +which writes an end-of-content marker to +.Pf * Fa ber_out , +consisting of two NUL bytes, and advances +.Pf * Fa ber_out +by two bytes. +.Sh RETURN VALUES +.Fn ASN1_put_eoc +returns the number of bytes written, which is always 2. +.Sh SEE ALSO +.Xr ASN1_item_i2d 3 , +.Xr ASN1_TYPE_get 3 , +.Xr i2d_ASN1_NULL 3 , +.Xr i2d_ASN1_OBJECT 3 , +.Xr i2d_ASN1_OCTET_STRING 3 , +.Xr i2d_ASN1_SEQUENCE_ANY 3 +.Sh HISTORY +.Fn ASN1_put_object +first appeared in SSLeay 0.5.1 and has been available since +.Ox 2.4 . +.Pp +.Fn ASN1_put_eoc +first appeared in OpenSSL 0.9.8 and has been available since +.Ox 4.5 . +.Sh CAVEATS +Neither +.Fn ASN1_put_object +nor +.Fn ASN1_put_eoc +do any sanity checking. +When called in inconsistent ways, invalid content may result in +.Pf * Fa ber_out , +for example +.Bl -dash -compact +.It +a +.Fa tag +number less than 0x1f with a non-universal +.Fa class +.It +a +.Fa tag +number equal to 0x00 or 0x1f +.It +a +.Vt BOOLEAN , +.Vt INTEGER , +.Vt NULL +etc. with the +.Fa constructed +bit set +.It +a +.Vt SEQUENCE +or +.Vt SET +etc. without the +.Fa constructed +bit set +.It +a +.Fa length +that makes no sense for the given +.Fa tag +.It +a +.Fa length +that disagrees with the following data +.It +a +.Vt BOOLEAN , +.Vt INTEGER , +.Vt NULL +etc. in indefinite form +.It +an end-of-content marker even though no indefinite form was started +.It +\&... +.El +.Pp +If the calling code wants to find out how many bytes were written, +it needs to save a copy of the pointer +.Pf * Fa ber_out +before calling +.Fn ASN1_put_object . diff --git a/src/lib/libcrypto/man/Makefile b/src/lib/libcrypto/man/Makefile index e3e8e710c2..2938a65cda 100644 --- a/src/lib/libcrypto/man/Makefile +++ b/src/lib/libcrypto/man/Makefile @@ -1,4 +1,4 @@ -# $OpenBSD: Makefile,v 1.156 2019/08/25 17:08:20 schwarze Exp $ +# $OpenBSD: Makefile,v 1.157 2019/08/26 11:41:31 schwarze Exp $ .include @@ -15,6 +15,7 @@ MAN= \ ASN1_generate_nconf.3 \ ASN1_item_d2i.3 \ ASN1_item_new.3 \ + ASN1_put_object.3 \ ASN1_time_parse.3 \ AUTHORITY_KEYID_new.3 \ BASIC_CONSTRAINTS_new.3 \ -- cgit v1.2.3-55-g6feb