new manual page ASN1_BIT_STRING_num_asc(3)

documenting the three functions using the BIT_STRING_BITNAME structure

4 files changed, 154 insertions, 5 deletions

diff --git a/lib/libcrypto/man/ASN1_BIT_STRING_num_asc.3 b/lib/libcrypto/man/ASN1_BIT_STRING_num_asc.3
new file mode 100644
index 00000000000..3891ced8a80
--- /dev/null
+++ b/lib/libcrypto/man/ASN1_BIT_STRING_num_asc.3
@@ -0,0 +1,146 @@
+.\" $OpenBSD: ASN1_BIT_STRING_num_asc.3,v 1.1 2021/11/19 16:00:54 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 19 2021 $
+.Dt ASN1_BIT_STRING_NUM_ASC 3
+.Os
+.Sh NAME
+.Nm ASN1_BIT_STRING_num_asc ,
+.Nm ASN1_BIT_STRING_set_asc ,
+.Nm ASN1_BIT_STRING_name_print
+.Nd names for individual bits
+.Sh SYNOPSIS
+.In openssl/asn1.h
+.Bd -unfilled
+typedef struct {
+	int bitnum;
+	const char *lname;
+	const char *sname;
+} BIT_STRING_BITNAME;
+.Ed
+.Pp
+.Ft int
+.Fo ASN1_BIT_STRING_num_asc
+.Fa "const char *name"
+.Fa "BIT_STRING_BITNAME *table"
+.Fc
+.Ft int
+.Fo ASN1_BIT_STRING_set_asc
+.Fa "ASN1_BIT_STRING *bitstr"
+.Fa "const char *name"
+.Fa "int set"
+.Fa "BIT_STRING_BITNAME *table"
+.Fc
+.Ft int
+.Fo ASN1_BIT_STRING_name_print
+.Fa "BIO *bio"
+.Fa "ASN1_BIT_STRING *bitstr"
+.Fa "BIT_STRING_BITNAME *table"
+.Fa "int indent"
+.Fc
+.Sh DESCRIPTION
+These functions provide access to individual bits of an ASN.1 BIT STRING
+based on a
+.Fa table
+assigning names to individual bits.
+The
+.Fa table
+is a variable-sized array.
+Each element contains a long name
+.Fa lname
+and a short name
+.Fa sname
+for the bit with the bit number
+.Fa bitnum .
+The table needs to be terminated with a dummy element containing a
+.Dv NULL
+pointer in the
+.Fa lname
+field.
+.Pp
+.Fn ASN1_BIT_STRING_num_asc
+retrieves the
+.Fa bitnum
+from the first element in the
+.Fa table
+where at least one of the names matches the
+.Fa name
+argument in the sense of
+.Xr strcmp 3 .
+That bit number can then be used for
+.Xr ASN1_BIT_STRING_get_bit 3 .
+.Pp
+.Fn ASN1_BIT_STRING_set_asc
+converts the
+.Fa name
+to a bit number using
+.Fn ASN1_BIT_STRING_num_asc
+and sets or clears that bit in
+.Fa bitstr
+according to the
+.Fa set
+argument, using
+.Xr ASN1_BIT_STRING_set_bit 3 .
+If
+.Fa bitstr
+is a
+.Dv NULL
+pointer, no action occurs.
+.Pp
+.Fn ASN1_BIT_STRING_name_print
+prints a single line of text to the given
+.Fa BIO .
+The line starts with
+.Fa indent
+space characters, contains the long names of the bit contained in the
+.Fa table
+that are set in
+.Fa bitstr ,
+separated by commas, and ends with a newline character.
+If any bits are set in
+.Fa bitstr
+that have no corresponding entries in the
+.Fa table ,
+those bits are silently ignored and nothing is printed for them.
+.Sh RETURN VALUES
+.Fn ASN1_BIT_STRING_num_asc
+returns a non-negative bit number or \-1 if the
+.Fa name
+is not found in the
+.Fa table .
+.Pp
+.Fn ASN1_BIT_STRING_set_asc
+returns 1 on success or 0 if the
+.Fa name
+is not found in the
+.Fa table
+or if memory allocation fails.
+.Pp
+.Fn ASN1_BIT_STRING_name_print
+is intended to return 1 for success or 0 for failure.
+.Sh SEE ALSO
+.Xr ASN1_BIT_STRING_new 3 ,
+.Xr ASN1_BIT_STRING_set 3 ,
+.Xr BIO_new 3 ,
+.Xr strcmp 3
+.Sh HISTORY
+These functions first appeared in OpenSSL 0.9.5
+and have been available since
+.Ox 2.7 .
+.Sh BUGS
+.Fn ASN1_BIT_STRING_name_print
+ignores all errors and always returns 1,
+even if nothing or only part of the desired output was printed.
diff --git a/lib/libcrypto/man/ASN1_BIT_STRING_set.3 b/lib/libcrypto/man/ASN1_BIT_STRING_set.3
index 608c3ef1b88..5b18c1c438b 100644
--- a/lib/libcrypto/man/ASN1_BIT_STRING_set.3
+++ b/lib/libcrypto/man/ASN1_BIT_STRING_set.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: ASN1_BIT_STRING_set.3,v 1.1 2021/11/15 16:18:36 schwarze Exp $
+.\" $OpenBSD: ASN1_BIT_STRING_set.3,v 1.2 2021/11/19 16:00:54 schwarze Exp $
 .\"
 .\" Copyright (c) 2021 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 19 2021 $
 .Dt ASN1_BIT_STRING_SET 3
 .Os
 .Sh NAME
@@ -161,6 +161,7 @@ or if no bit is set in
 .Fa bitstr .
 .Sh SEE ALSO
 .Xr ASN1_BIT_STRING_new 3 ,
+.Xr ASN1_BIT_STRING_num_asc 3 ,
 .Xr ASN1_STRING_set 3 ,
 .Xr d2i_ASN1_BIT_STRING 3
 .Sh HISTORY
diff --git a/lib/libcrypto/man/ASN1_STRING_new.3 b/lib/libcrypto/man/ASN1_STRING_new.3
index fbc999a3257..619ab91e481 100644
--- a/lib/libcrypto/man/ASN1_STRING_new.3
+++ b/lib/libcrypto/man/ASN1_STRING_new.3
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: ASN1_STRING_new.3,v 1.22 2021/11/15 16:18:36 schwarze Exp $
+.\"	$OpenBSD: ASN1_STRING_new.3,v 1.23 2021/11/19 16:00:54 schwarze Exp $
 .\"	OpenSSL 99d63d46 Tue Mar 24 07:52:24 2015 -0400
 .\"
 .\" Copyright (c) 2017 Ingo Schwarze <schwarze@openbsd.org>
@@ -15,7 +15,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 19 2021 $
 .Dt ASN1_STRING_NEW 3
 .Os
 .Sh NAME
@@ -203,6 +203,7 @@ object if successful; otherwise
 is returned and an error code can be retrieved with
 .Xr ERR_get_error 3 .
 .Sh SEE ALSO
+.Xr ASN1_BIT_STRING_num_asc 3 ,
 .Xr ASN1_BIT_STRING_set 3 ,
 .Xr ASN1_INTEGER_get 3 ,
 .Xr ASN1_item_pack 3 ,
diff --git a/lib/libcrypto/man/Makefile b/lib/libcrypto/man/Makefile
index 830c556849f..5d3a7d3d233 100644
--- a/lib/libcrypto/man/Makefile
+++ b/lib/libcrypto/man/Makefile
@@ -1,10 +1,11 @@
-# $OpenBSD: Makefile,v 1.216 2021/11/17 16:08:32 schwarze Exp $
+# $OpenBSD: Makefile,v 1.217 2021/11/19 16:00:54 schwarze Exp $
 
 .include <bsd.own.mk>
 
 MAN=	\
 	ACCESS_DESCRIPTION_new.3 \
 	AES_encrypt.3 \
+	ASN1_BIT_STRING_num_asc.3 \
 	ASN1_BIT_STRING_set.3 \
 	ASN1_INTEGER_get.3 \
 	ASN1_OBJECT_new.3 \