document a2i_ASN1_INTEGER(3),

i2a_ASN1_ENUMERATED(3), and a2i_ASN1_ENUMERATED(3)

2 files changed, 135 insertions, 69 deletions

diff --git a/src/lib/libcrypto/man/ASN1_INTEGER_get.3 b/src/lib/libcrypto/man/ASN1_INTEGER_get.3
index 1ed993efa6..df5a3bc821 100644
--- a/src/lib/libcrypto/man/ASN1_INTEGER_get.3
+++ b/src/lib/libcrypto/man/ASN1_INTEGER_get.3
@@ -1,11 +1,11 @@
-.\" $OpenBSD: ASN1_INTEGER_get.3,v 1.4 2021/11/20 13:06:26 schwarze Exp $
+.\" $OpenBSD: ASN1_INTEGER_get.3,v 1.5 2021/11/23 13:52:27 schwarze Exp $
 .\" selective merge up to:
-.\" OpenSSL man3/ASN1_INTEGER_get_int64 df75c2bf Dec 9 01:02:36 2018 +0100
+.\" OpenSSL man3/ASN1_INTEGER_get_int64 24a535ea Sep 22 13:14:20 2020 +0100
 .\"
 .\" This file is a derived work.
 .\" The changes are covered by the following Copyright and license:
 .\"
-.\" Copyright (c) 2018, 2019, 2021 Ingo Schwarze <schwarze@openbsd.org>
+.\" Copyright (c) 2018, 2021 Ingo Schwarze <schwarze@openbsd.org>
 .\"
 .\" Permission to use, copy, modify, and distribute this software for any
 .\" purpose with or without fee is hereby granted, provided that the above
@@ -66,7 +66,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: November 20 2021 $
+.Dd $Mdocdate: November 23 2021 $
 .Dt ASN1_INTEGER_GET 3
 .Os
 .Sh NAME
@@ -76,7 +76,6 @@
 .Nm ASN1_INTEGER_dup ,
 .Nm BN_to_ASN1_INTEGER ,
 .Nm ASN1_INTEGER_to_BN ,
-.Nm i2a_ASN1_INTEGER ,
 .Nm ASN1_ENUMERATED_get ,
 .Nm ASN1_ENUMERATED_set ,
 .Nm BN_to_ASN1_ENUMERATED ,
@@ -112,11 +111,6 @@
 .Fa "const ASN1_INTEGER *ai"
 .Fa "BIGNUM *bn"
 .Fc
-.Ft int
-.Fo i2a_ASN1_INTEGER
-.Fa "BIO *out_bio"
-.Fa "const ASN1_INTEGER *a"
-.Fc
 .Ft long
 .Fo ASN1_ENUMERATED_get
 .Fa "const ASN1_ENUMERATED *a"
@@ -212,16 +206,6 @@ Otherwise, the existing object
 .Fa bn
 is used instead.
 .Pp
-.Fn i2a_ASN1_INTEGER
-writes a hexadecimal representation of
-.Fa a
-to
-.Fa out_bio .
-The output optionally starts with a minus sign,
-followed by an even number of upper case ASCII hexadecimal digits.
-After each group of 70 digits, a backslash and a linefeed
-are inserted before the next digit.
-.Pp
 .Fn ASN1_ENUMERATED_get ,
 .Fn ASN1_ENUMERATED_set ,
 .Fn BN_to_ASN1_ENUMERATED ,
@@ -294,17 +278,6 @@ object of
 if an error occurs.
 They can fail if the passed type is incorrect (due to a programming error)
 or due to memory allocation failures.
-.Pp
-In case of success,
-.Fn i2a_ASN1_INTEGER
-returns the total number of bytes written, which is at least 2.
-It returns 0 if
-.Fa a
-is
-.Dv NULL
-or -1 if
-.Xr BIO_write 3
-fails.
 .Sh SEE ALSO
 .Xr ASN1_INTEGER_new 3 ,
 .Xr ASN1_STRING_length 3
@@ -313,9 +286,8 @@ fails.
 first appeared in SSLeay 0.5.1.
 .Fn ASN1_INTEGER_get ,
 .Fn BN_to_ASN1_INTEGER ,
-.Fn ASN1_INTEGER_to_BN ,
 and
-.Fn i2a_ASN1_INTEGER
+.Fn ASN1_INTEGER_to_BN
 first appeared in SSLeay 0.6.0.
 .Fn ASN1_INTEGER_cmp
 and
@@ -348,9 +320,8 @@ imply that these functions should be avoided if possible.
 .Sh BUGS
 .Fn ASN1_INTEGER_cmp ,
 .Fn ASN1_INTEGER_dup ,
-.Fn ASN1_INTEGER_to_BN ,
 and
-.Fn i2a_ASN1_INTEGER
+.Fn ASN1_INTEGER_to_BN
 do not check whether their arguments are really of the type
 .Dv V_ASN1_INTEGER
 or
diff --git a/src/lib/libcrypto/man/i2a_ASN1_STRING.3 b/src/lib/libcrypto/man/i2a_ASN1_STRING.3
index fa5f071c14..bf6266350e 100644
--- a/src/lib/libcrypto/man/i2a_ASN1_STRING.3
+++ b/src/lib/libcrypto/man/i2a_ASN1_STRING.3
@@ -1,6 +1,6 @@
-.\" $OpenBSD: i2a_ASN1_STRING.3,v 1.1 2021/11/15 10:41:11 schwarze Exp $
+.\" $OpenBSD: i2a_ASN1_STRING.3,v 1.2 2021/11/23 13:52:27 schwarze Exp $
 .\"
-.\" Copyright (c) 2021 Ingo Schwarze <schwarze@openbsd.org>
+.\" Copyright (c) 2019, 2021 Ingo Schwarze <schwarze@openbsd.org>
 .\"
 .\" Permission to use, copy, modify, and distribute this software for any
 .\" purpose with or without fee is hereby granted, provided that the above
@@ -14,12 +14,16 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd $Mdocdate: November 15 2021 $
+.Dd $Mdocdate: November 23 2021 $
 .Dt I2A_ASN1_STRING 3
 .Os
 .Sh NAME
 .Nm i2a_ASN1_STRING ,
-.Nm a2i_ASN1_STRING
+.Nm i2a_ASN1_INTEGER ,
+.Nm i2a_ASN1_ENUMERATED ,
+.Nm a2i_ASN1_STRING ,
+.Nm a2i_ASN1_INTEGER ,
+.Nm a2i_ASN1_ENUMERATED
 .Nd hexadecimal dump of an ASN.1 string
 .Sh SYNOPSIS
 .In openssl/asn1.h
@@ -30,16 +34,43 @@
 .Fa "int type"
 .Fc
 .Ft int
+.Fo i2a_ASN1_INTEGER
+.Fa "BIO *out_bio"
+.Fa "const ASN1_INTEGER *a"
+.Fc
+.Ft int
+.Fo i2a_ASN1_ENUMERATED
+.Fa "BIO *out_bio"
+.Fa "const i2a_ASN1_ENUMERATED *a"
+.Fc
+.Ft int
 .Fo a2i_ASN1_STRING
 .Fa "BIO *in_bio"
 .Fa "ASN1_STRING *out_string"
 .Fa "char *buffer"
 .Fa "int size"
 .Fc
+.Ft int
+.Fo a2i_ASN1_INTEGER
+.Fa "BIO *in_bio"
+.Fa "ASN1_INTEGER *out_string"
+.Fa "char *buffer"
+.Fa "int size"
+.Fc
+.Ft int
+.Fo a2i_ASN1_ENUMERATED
+.Fa "BIO *in_bio"
+.Fa "ASN1_ENUMERATED *out_string"
+.Fa "char *buffer"
+.Fa "int size"
+.Fc
 .Sh DESCRIPTION
-The function
-.Fn i2a_ASN1_STRING
-writes a hexadecimal representation of
+The functions
+.Fn i2a_ASN1_STRING ,
+.Fn i2a_ASN1_INTEGER ,
+and
+.Fn i2a_ASN1_ENUMERATED
+write a hexadecimal representation of
 .Fa a
 to
 .Fa out_bio .
@@ -57,33 +88,61 @@ If the
 .Xr ASN1_STRING_length 3
 of
 .Fa a
-is 0, the single digit
-.Ql 0
-is written instead.
+is 0, instead a pair of zero digits
+.Pq Qq 00
+is written by
+.Fn i2a_ASN1_INTEGER
+and
+.Fn i2a_ASN1_ENUMERATED
+and a single zero digit
+.Pq Qq 0
+by
+.Fn i2a_ASN1_STRING .
 If
 .Fa a
 is a
 .Dv NULL
 pointer, nothing is written.
 .Pp
-The function
-.Fn a2i_ASN1_STRING
-parses a hexadecimal representation of an ASN.1 string into
+If
+.Fa a
+represents a negative integer,
+.Fn i2a_ASN1_INTEGER
+prepends a minus sign to the output.
+.Pp
+The functions
+.Fn a2i_ASN1_STRING ,
+.Fn a2i_ASN1_INTEGER ,
+and
+.Fn a2i_ASN1_ENUMERATED
+parse a hexadecimal representation of an ASN.1 string into
 .Fa out_string .
 Both lower-case and upper-case hexadecimal digits are accepted.
 Every pair of input digits is converted into one output byte.
-At least one pair of input digits is required.
 .Pp
 On every input line, the trailing newline character and an optional
 carrier return character character preceding it are ignored.
 The trailing newline need not be present on the last line.
 If there is a backslash character before the newline character,
 parsing is continued on the next input line.
-In particular,
+.Pp
+At least one pair of input digits is required by
+.Fn a2i_ASN1_INTEGER
+and
+.Fn a2i_ASN1_ENUMERATED ,
+whereas
 .Fn a2i_ASN1_STRING
-is able to parse the output of
+converts empty input to an empty string.
+.Pp
+These functions are able to parse the output of
+.Fn i2a_ASN1_ENUMERATED .
+They can parse the output of
+.Fn i2a_ASN1_INTEGER
+unless
+.Fa a
+was negative, and they can parse the output of
 .Fn i2a_ASN1_STRING
-except when the
+unless the
 .Xr ASN1_STRING_length 3
 of
 .Fa a
@@ -92,39 +151,69 @@ was 0.
 Parsing fails if an input line contains an odd number of input
 digits or if memory allocation fails.
 .Pp
-This function uses the
+These functions use the
 .Fa buffer
-provided by the caller and assumes it is at least
+provided by the caller and assume it is at least
 .Fa size
 bytes long.
-It is unspecified what the buffer contains after the function returns.
+It is unspecified what the buffer contains after the functions return.
 .Sh RETURN VALUES
-The function
-.Fn i2a_ASN1_STRING
-returns the number of bytes written or \-1 if
+The functions
+.Fn i2a_ASN1_STRING ,
+.Fn i2a_ASN1_INTEGER ,
+and
+.Fn i2a_ASN1_ENUMERATED
+return the number of bytes written or \-1 if
 .Xr BIO_write 3
 fails.
+In particular, they all return 0 when
+.Fa a
+is a
+.Dv NULL
+pointer.
+.Fn i2a_ASN1_STRING
+returns 1 for an empty string or an even number greater than 1
+for a string that is not empty.
+.Fn i2a_ASN1_INTEGER
+returns an even number greater than 1 for positive input
+or an odd number greater than 2 for negative input.
+.Fn i2a_ASN1_ENUMERATED
+always returns a non-negative even number when successful.
 .Pp
-The function
-.Fn a2i_ASN1_STRING
-is intended to return 1 for success or 0 for failure, but see the
+The functions
+.Fn a2i_ASN1_STRING ,
+.Fn a2i_ASN1_INTEGER ,
+and
+.Fn a2i_ASN1_ENUMERATED
+are intended to return 1 for success or 0 for failure, but see the
 .Sx BUGS
 section for a number of traps.
 .Sh SEE ALSO
 .Xr ASN1_STRING_length 3 ,
 .Xr ASN1_STRING_new 3 ,
 .Xr ASN1_STRING_print_ex 3 ,
-.Xr i2a_ASN1_INTEGER 3 ,
 .Xr i2a_ASN1_OBJECT 3
 .Sh HISTORY
-These functions first appeared in SSLeay 0.6.5.
-The function
+.Fn i2a_ASN1_INTEGER
+and
+.Fn a2i_ASN1_INTEGER
+first appeared in SSLeay 0.6.0.
+.Fn i2a_ASN1_STRING
+and
+.Fn a2i_ASN1_STRING
+first appeared in SSLeay 0.6.5.
 .Fn a2i_ASN1_STRING
 has been part of the public API since SSLeay 0.6.5 and
 .Fn i2a_ASN1_STRING
 since SSLeay 0.8.0.
-They have been available since
+These functions have been available since
 .Ox 2.4 .
+.Pp
+.Fn i2a_ASN1_ENUMERATED
+and
+.Fn a2i_ASN1_ENUMERATED
+first appeared in OpenSSL 0.9.2 and have been available since
+.Ox 2.6 .
 .Sh BUGS
 If the first call to
 .Xr BIO_gets 3
@@ -142,7 +231,10 @@ returns a partial line, for example because the given
 .Fa size
 is insufficient to contain one of the input lines
 or for reasons specific to the BIO type,
-.Fn a2i_ASN1_STRING
+.Fn a2i_ASN1_STRING ,
+.Fn a2i_ASN1_INTEGER ,
+and
+.Fn a2i_ASN1_ENUMERATED
 may fail or silently return a truncated result.
 The caller is responsible for providing a
 .Fa buffer
@@ -150,9 +242,12 @@ of sufficient size to contain the longest possible input line
 and for choosing a BIO of a type that only returns complete
 input lines and does not perform partial reads.
 .Pp
-The function
-.Fn a2i_ASN1_STRING
-does not support non-blocking BIOs.
+The functions
+.Fn a2i_ASN1_STRING ,
+.Fn a2i_ASN1_INTEGER ,
+and
+.Fn a2i_ASN1_ENUMERATED
+do not support non-blocking BIOs.
 Reading is terminated as soon as
 .Xr BIO_gets 3
 returns a value less than 1.