From bba7eb3ad6eeef5c850d4743aa8f591c8874f803 Mon Sep 17 00:00:00 2001
From: schwarze <>
Date: Mon, 26 Aug 2019 12:45:27 +0000
Subject: document i2a_ASN1_INTEGER(3)

---
 src/lib/libcrypto/man/ASN1_INTEGER_get.3 | 55 +++++++++++++++++++++++++++++---
 1 file changed, 50 insertions(+), 5 deletions(-)

(limited to 'src/lib')

diff --git a/src/lib/libcrypto/man/ASN1_INTEGER_get.3 b/src/lib/libcrypto/man/ASN1_INTEGER_get.3
index ec744b5cdc..72342ec1e0 100644
--- a/src/lib/libcrypto/man/ASN1_INTEGER_get.3
+++ b/src/lib/libcrypto/man/ASN1_INTEGER_get.3
@@ -1,8 +1,25 @@
-.\" $OpenBSD: ASN1_INTEGER_get.3,v 1.2 2019/06/06 01:06:58 schwarze Exp $
+.\" $OpenBSD: ASN1_INTEGER_get.3,v 1.3 2019/08/26 12:45:27 schwarze Exp $
 .\" selective merge up to:
-.\" OpenSSL man3/ASN1_INTEGER_get_int64 eaf39a9f Jun 23 10:24:00 2018 +0200
+.\" OpenSSL man3/ASN1_INTEGER_get_int64 df75c2bf Dec 9 01:02:36 2018 +0100
 .\"
-.\" This file was written by Dr. Stephen Henson <steve@openssl.org>.
+.\" This file is a derived work.
+.\" The changes are covered by the following Copyright and license:
+.\"
+.\" Copyright (c) 2018, 2019 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
+.\" 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.
+.\"
+.\" The original 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
@@ -49,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: June 6 2019 $
+.Dd $Mdocdate: August 26 2019 $
 .Dt ASN1_INTEGER_GET 3
 .Os
 .Sh NAME
@@ -57,6 +74,7 @@
 .Nm ASN1_INTEGER_set ,
 .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 ,
@@ -83,6 +101,11 @@
 .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"
@@ -154,6 +177,16 @@ 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 ,
@@ -204,6 +237,17 @@ 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
 .Sh HISTORY
@@ -211,8 +255,9 @@ or due to memory allocation failures.
 first appeared in SSLeay 0.5.1.
 .Fn ASN1_INTEGER_get ,
 .Fn BN_to_ASN1_INTEGER ,
+.Fn ASN1_INTEGER_to_BN ,
 and
-.Fn ASN1_INTEGER_to_BN
+.Fn i2a_ASN1_INTEGER
 first appeared in SSLeay 0.6.0.
 These functions have been available since
 .Ox 2.3 .
-- 
cgit v1.2.3-55-g6feb