import the relevant parts of a new ASN1_INTEGER_get(3) manual page

from OpenSSL, fixing many bugs and polishing many details

2 files changed, 240 insertions, 1 deletions

diff --git a/lib/libcrypto/man/ASN1_INTEGER_get.3 b/lib/libcrypto/man/ASN1_INTEGER_get.3
new file mode 100644
index 00000000000..e3585b40887
--- /dev/null
+++ b/lib/libcrypto/man/ASN1_INTEGER_get.3
@@ -0,0 +1,238 @@
+.\" $OpenBSD: ASN1_INTEGER_get.3,v 1.1 2018/07/08 23:00:17 schwarze Exp $
+.\" selective merge up to:
+.\" OpenSSL man3/ASN1_INTEGER_get_int64 eaf39a9f Jun 23 10:24:00 2018 +0200
+.\"
+.\" This file was written by Dr. Stephen Henson <steve@openssl.org>.
+.\" Copyright (c) 2015 The OpenSSL Project.  All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\"
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\"
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in
+.\"    the documentation and/or other materials provided with the
+.\"    distribution.
+.\"
+.\" 3. All advertising materials mentioning features or use of this
+.\"    software must display the following acknowledgment:
+.\"    "This product includes software developed by the OpenSSL Project
+.\"    for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
+.\"
+.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
+.\"    endorse or promote products derived from this software without
+.\"    prior written permission. For written permission, please contact
+.\"    openssl-core@openssl.org.
+.\"
+.\" 5. Products derived from this software may not be called "OpenSSL"
+.\"    nor may "OpenSSL" appear in their names without prior written
+.\"    permission of the OpenSSL Project.
+.\"
+.\" 6. Redistributions of any form whatsoever must retain the following
+.\"    acknowledgment:
+.\"    "This product includes software developed by the OpenSSL Project
+.\"    for use in the OpenSSL Toolkit (http://www.openssl.org/)"
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
+.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
+.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
+.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
+.\" OF THE POSSIBILITY OF SUCH DAMAGE.
+.\"
+.Dd $Mdocdate: July 8 2018 $
+.Dt ASN1_INTEGER_GET 3
+.Os
+.Sh NAME
+.Nm ASN1_INTEGER_get ,
+.Nm ASN1_INTEGER_set ,
+.Nm BN_to_ASN1_INTEGER ,
+.Nm ASN1_INTEGER_to_BN ,
+.Nm ASN1_ENUMERATED_get ,
+.Nm ASN1_ENUMERATED_set ,
+.Nm BN_to_ASN1_ENUMERATED ,
+.Nm ASN1_ENUMERATED_to_BN
+.Nd ASN.1 INTEGER and ENUMERATED utilities
+.Sh SYNOPSIS
+.In openssl/asn1.h
+.Ft long
+.Fo ASN1_INTEGER_get
+.Fa "const ASN1_INTEGER *a"
+.Fc
+.Ft int
+.Fo ASN1_INTEGER_set
+.Fa "ASN1_INTEGER *a"
+.Fa "long v"
+.Fc
+.Ft ASN1_INTEGER *
+.Fo BN_to_ASN1_INTEGER
+.Fa "const BIGNUM *bn"
+.Fa "ASN1_INTEGER *ai"
+.Fc
+.Ft BIGNUM *
+.Fo ASN1_INTEGER_to_BN
+.Fa "const ASN1_INTEGER *ai"
+.Fa "BIGNUM *bn"
+.Fc
+.Ft long
+.Fo ASN1_ENUMERATED_get
+.Fa "const ASN1_ENUMERATED *a"
+.Fc
+.Ft int
+.Fo ASN1_ENUMERATED_set
+.Fa "ASN1_ENUMERATED *a"
+.Fa "long v"
+.Fc
+.Ft ASN1_ENUMERATED *
+.Fo BN_to_ASN1_ENUMERATED
+.Fa "const BIGNUM *bn"
+.Fa "ASN1_ENUMERATED *ai"
+.Fc
+.Ft BIGNUM *
+.Fo ASN1_ENUMERATED_to_BN
+.Fa "const ASN1_ENUMERATED *ai"
+.Fa "BIGNUM *bn"
+.Fc
+.Sh DESCRIPTION
+These functions convert to and from
+.Vt ASN1_INTEGER
+and
+.Vt ASN1_ENUMERATED
+objects.
+.Pp
+.Fn ASN1_INTEGER_get
+converts
+.Fa a
+to the
+.Vt long
+type.
+.Pp
+.Fn ASN1_INTEGER_set
+sets the value of
+.Fa a
+to
+.Fa v .
+.Pp
+.Fn BN_to_ASN1_INTEGER
+converts
+.Fa bn
+to an
+.Vt ASN1_INTEGER .
+If
+.Fa ai
+is
+.Dv NULL ,
+a new
+.Vt ASN1_INTEGER
+object is returned.
+Otherwise, the existing object
+.Fa ai
+is used instead.
+.Pp
+.Fn ASN1_INTEGER_to_BN
+converts
+.Fa ai
+into a
+.Vt BIGNUM .
+If
+.Fa bn
+is
+.Dv NULL ,
+a new
+.Vt BIGNUM
+object is returned.
+Otherwise, the existing object
+.Fa bn
+is used instead.
+.Pp
+.Fn ASN1_ENUMERATED_get ,
+.Fn ASN1_ENUMERATED_set ,
+.Fn BN_to_ASN1_ENUMERATED ,
+and
+.Fn ASN1_ENUMERATED_to_BN
+behave like their
+.Vt ASN1_INTEGER
+counterparts except that they operate on an
+.Vt ASN1_ENUMERATED
+object.
+.Sh RETURN VALUES
+.Fn ASN1_INTEGER_get
+and
+.Fn ASN1_ENUMERATED_get
+return the converted value, 0 if
+.Fa a
+is
+.Dv NULL ,
+or \-1 on error, which is ambiguous because \-1 is a legitimate
+value for an
+.Vt ASN1_INTEGER .
+.Pp
+.Fn ASN1_INTEGER_set
+and
+.Fn ASN1_ENUMERATED_set
+return 1 for success or 0 for failure.
+They only fail if a memory allocation error occurs.
+.Pp
+.Fn BN_to_ASN1_INTEGER
+and
+.Fn BN_to_ASN1_ENUMERATED
+return an
+.Vt ASN1_INTEGER
+or
+.Vt ASN1_ENUMERATED
+object, respectively, or
+.Dv NULL
+if an error occurs.
+They only fail due to memory allocation errors.
+.Pp
+.Fn ASN1_INTEGER_to_BN
+and
+.Fn ASN1_ENUMERATED_to_BN
+return a
+.Vt BIGNUM
+object of
+.Dv NULL
+if an error occurs.
+They can fail if the passed type is incorrect (due to a programming error)
+or due to memory allocation failures.
+.Sh HISTORY
+.Fn ASN1_INTEGER_set
+first appeared in SSLeay 0.5.1.
+.Fn ASN1_INTEGER_get ,
+.Fn BN_to_ASN1_INTEGER ,
+and
+.Fn ASN1_INTEGER_to_BN
+first appeared in SSLeay 0.6.0.
+These functions have been available since
+.Ox 2.3 .
+.Pp
+.Fn ASN1_ENUMERATED_get ,
+.Fn ASN1_ENUMERATED_set ,
+.Fn BN_to_ASN1_ENUMERATED ,
+and
+.Fn ASN1_ENUMERATED_to_BN
+first appeared in OpenSSL 0.9.2b and have been available since
+.Ox 2.6 .
+.Sh CAVEATS
+In general an
+.Vt ASN1_INTEGER
+or
+.Vt ASN1_ENUMERATED
+type can contain an integer of almost arbitrary size
+and so cannot always be represented by a C
+.Vt long
+type.
+The ambiguous return values of
+.Fn ASN1_INTEGER_get
+and
+.Fn ASN1_ENUMERATED_get
+imply that these functions should be avoided if possible.
diff --git a/lib/libcrypto/man/Makefile b/lib/libcrypto/man/Makefile
index c8e5d51fd6e..fe5a87e608c 100644
--- a/lib/libcrypto/man/Makefile
+++ b/lib/libcrypto/man/Makefile
@@ -1,9 +1,10 @@
-# $OpenBSD: Makefile,v 1.141 2018/04/18 01:13:37 schwarze Exp $
+# $OpenBSD: Makefile,v 1.142 2018/07/08 23:00:17 schwarze Exp $
 
 .include <bsd.own.mk>
 
 MAN=	\
 	ACCESS_DESCRIPTION_new.3 \
+	ASN1_INTEGER_get.3 \
 	ASN1_OBJECT_new.3 \
 	ASN1_STRING_length.3 \
 	ASN1_STRING_new.3 \