new manual page d2i_ASN1_BOOLEAN(3) also documenting i2d_ASN1_BOOLEAN(3)

5 files changed, 137 insertions, 7 deletions

diff --git a/lib/libcrypto/man/ASN1_TYPE_get.3 b/lib/libcrypto/man/ASN1_TYPE_get.3
index 284ad61b341..6a7d761f942 100644
--- a/lib/libcrypto/man/ASN1_TYPE_get.3
+++ b/lib/libcrypto/man/ASN1_TYPE_get.3
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: ASN1_TYPE_get.3,v 1.12 2021/07/11 19:03:45 schwarze Exp $
+.\"	$OpenBSD: ASN1_TYPE_get.3,v 1.13 2021/11/21 15:11:01 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: July 11 2021 $
+.Dd $Mdocdate: November 21 2021 $
 .Dt ASN1_TYPE_GET 3
 .Os
 .Sh NAME
@@ -283,6 +283,7 @@ returns 0 for a match or non-zero for a mismatch.
 .Xr ASN1_STRING_dup 3 ,
 .Xr ASN1_STRING_new 3 ,
 .Xr crypto 3 ,
+.Xr d2i_ASN1_BOOLEAN 3 ,
 .Xr d2i_ASN1_NULL 3 ,
 .Xr d2i_ASN1_SEQUENCE_ANY 3 ,
 .Xr d2i_ASN1_TYPE 3 ,
diff --git a/lib/libcrypto/man/ASN1_item_new.3 b/lib/libcrypto/man/ASN1_item_new.3
index 12340c7443e..6e36e86c6de 100644
--- a/lib/libcrypto/man/ASN1_item_new.3
+++ b/lib/libcrypto/man/ASN1_item_new.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: ASN1_item_new.3,v 1.8 2021/11/15 11:51:09 schwarze Exp $
+.\" $OpenBSD: ASN1_item_new.3,v 1.9 2021/11/21 15:11:01 schwarze Exp $
 .\"
 .\" Copyright (c) 2016, 2018 Ingo Schwarze <schwarze@openbsd.org>
 .\"
@@ -14,7 +14,7 @@
 .\" 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 21 2021 $
 .Dt ASN1_ITEM_NEW 3
 .Os
 .Sh NAME
@@ -112,6 +112,7 @@ is returned and an error code can be retrieved with
 .Xr ASN1_item_sign 3 ,
 .Xr ASN1_item_verify 3 ,
 .Xr ASN1_TYPE_new 3 ,
+.Xr d2i_ASN1_BOOLEAN 3 ,
 .Xr d2i_ASN1_NULL 3 ,
 .Xr OBJ_nid2obj 3
 .Sh HISTORY
diff --git a/lib/libcrypto/man/ASN1_put_object.3 b/lib/libcrypto/man/ASN1_put_object.3
index f1f0021fe50..e69550f0d2f 100644
--- a/lib/libcrypto/man/ASN1_put_object.3
+++ b/lib/libcrypto/man/ASN1_put_object.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: ASN1_put_object.3,v 1.1 2019/08/26 11:41:31 schwarze Exp $
+.\" $OpenBSD: ASN1_put_object.3,v 1.2 2021/11/21 15:11:01 schwarze Exp $
 .\"
 .\" Copyright (c) 2019 Ingo Schwarze <schwarze@openbsd.org>
 .\"
@@ -14,7 +14,7 @@
 .\" 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 $
+.Dd $Mdocdate: November 21 2021 $
 .Dt ASN1_PUT_OBJECT 3
 .Os
 .Sh NAME
@@ -106,6 +106,7 @@ 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_BOOLEAN 3 ,
 .Xr i2d_ASN1_NULL 3 ,
 .Xr i2d_ASN1_OBJECT 3 ,
 .Xr i2d_ASN1_OCTET_STRING 3 ,
diff --git a/lib/libcrypto/man/Makefile b/lib/libcrypto/man/Makefile
index 5d3a7d3d233..10f841bd8d7 100644
--- a/lib/libcrypto/man/Makefile
+++ b/lib/libcrypto/man/Makefile
@@ -1,4 +1,4 @@
-# $OpenBSD: Makefile,v 1.217 2021/11/19 16:00:54 schwarze Exp $
+# $OpenBSD: Makefile,v 1.218 2021/11/21 15:11:01 schwarze Exp $
 
 .include <bsd.own.mk>
 
@@ -368,6 +368,7 @@ MAN=	\
 	X509at_get_attr.3 \
 	X509v3_get_ext_by_NID.3 \
 	crypto.3 \
+	d2i_ASN1_BOOLEAN.3 \
 	d2i_ASN1_NULL.3 \
 	d2i_ASN1_OBJECT.3 \
 	d2i_ASN1_OCTET_STRING.3 \
diff --git a/lib/libcrypto/man/d2i_ASN1_BOOLEAN.3 b/lib/libcrypto/man/d2i_ASN1_BOOLEAN.3
new file mode 100644
index 00000000000..ecd768f081d
--- /dev/null
+++ b/lib/libcrypto/man/d2i_ASN1_BOOLEAN.3
@@ -0,0 +1,126 @@
+.\" $OpenBSD: d2i_ASN1_BOOLEAN.3,v 1.1 2021/11/21 15:11:01 schwarze Exp $
+.\"
+.\" Copyright (c) 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
+.\" 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: November 21 2021 $
+.Dt D2I_ASN1_BOOLEAN 3
+.Os
+.Sh NAME
+.Nm d2i_ASN1_BOOLEAN ,
+.Nm i2d_ASN1_BOOLEAN
+.Nd decode and encode an ASN.1 BOOLEAN value
+.Sh SYNOPSIS
+.In openssl/asn1.h
+.Bd -unfilled
+typedef int ASN1_BOOLEAN;
+.Ed
+.Pp
+.Ft int
+.Fo d2i_ASN1_BOOLEAN
+.Fa "int *val_out"
+.Fa "const unsigned char **der_in"
+.Fa "long length"
+.Fc
+.Ft int
+.Fo i2d_ASN1_BOOLEAN
+.Fa "int val_in"
+.Fa "unsigned char **der_out"
+.Fc
+.Sh DESCRIPTION
+These functions decode and encode
+an ASN.1 value TRUE or FALSE of the type BOOLEAN.
+In contrast to most other ASN.1 types,
+the library does not represent the BOOLEAN type by a structure.
+Instead,
+.Vt ASN1_BOOLEAN
+is simply an alias for the type
+.Vt int .
+.Pp
+.Fn d2i_ASN1_BOOLEAN
+verifies that the BER-encoded value at
+.Pf * Fa der_in
+is of the type BOOLEAN
+and that the number encoded in the length octets is 1.
+At most
+.Fa length
+bytes are inspected.
+.Pp
+Unless
+.Fa val_out
+is a
+.Dv NULL
+pointer, it copies the integer value of the single content octet to
+.Pf * Fa val_out .
+In case of success,
+.Pf * Fa der_in
+is advanced by three bytes to the byte after the content octet.
+.Pp
+.Fn i2d_ASN1_BOOLEAN
+encodes an ASN.1 value of the type BOOLEAN using DER.
+Specifically, unless
+.Fa der_out
+is a
+.Dv NULL
+pointer, it writes the identifier octet for the type BOOLEAN,
+0x01, the single length octet 0x01, one single content octet containing
+.Fa val_in ,
+and no end-of-content octets to
+.Pf * Fa der_out
+and advances the pointer
+.Pf * Fa der_out
+by three bytes to the byte after the content octet.
+Making sure that three bytes can be written to
+.Pf * Fa der_out
+is the responsibility of the caller.
+.Pp
+If
+.Fa val_in
+is 0, it encodes the FALSE value.
+If
+.Fa val_in
+is in the range from 1 to 255 inclusive, it encodes the TRUE value.
+.Sh RETURN VALUES
+In case of success,
+.Fn d2i_ASN1_BOOLEAN
+returns the integer value of the content octet.
+The number 0 represents the FALSE value and any number in the range
+from 1 to 255 inclusive represents the TRUE value.
+If the
+.Fa length
+argument is less than 3, if parsing fails, if the ASN.1 object at
+.Pf * Fa der_in
+is not of the type BOOLEAN, or if the number of content octets is not 1,
+.Fn d2i_ASN1_BOOLEAN
+returns \-1 to indicate the error.
+.Pp
+.Fn i2d_ASN1_BOOLEAN
+always returns 3, which is the number of bytes in the BER encoding
+of an ASN.1 BOOLEAN value.
+.Sh SEE ALSO
+.Xr ASN1_get_object 3 ,
+.Xr ASN1_item_d2i 3 ,
+.Xr ASN1_put_object 3
+.Sh HISTORY
+.Fn d2i_ASN1_BOOLEAN
+and
+.Fn i2d_ASN1_BOOLEAN
+first appeared in SSLeay 0.6.2 and have been available since
+.Ox 2.4 .
+.Sh CAVEATS
+The behaviour of
+.Fn i2d_ASN1_BOOLEAN
+is unspecified if
+.Fa val_in
+is negative or larger than 255.