new manual page ASN1_BIT_STRING_set(3) documenting four BIT STRING accessors

4 files changed, 184 insertions, 3 deletions

diff --git a/lib/libcrypto/man/ASN1_BIT_STRING_set.3 b/lib/libcrypto/man/ASN1_BIT_STRING_set.3
new file mode 100644
index 00000000000..608c3ef1b88
--- /dev/null
+++ b/lib/libcrypto/man/ASN1_BIT_STRING_set.3
@@ -0,0 +1,178 @@
+.\" $OpenBSD: ASN1_BIT_STRING_set.3,v 1.1 2021/11/15 16:18:36 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 15 2021 $
+.Dt ASN1_BIT_STRING_SET 3
+.Os
+.Sh NAME
+.Nm ASN1_BIT_STRING_set ,
+.Nm ASN1_BIT_STRING_set_bit ,
+.Nm ASN1_BIT_STRING_get_bit ,
+.Nm ASN1_BIT_STRING_check
+.Nd ASN.1 BIT STRING accessors
+.Sh SYNOPSIS
+.In openssl/asn1.h
+.Ft int
+.Fo ASN1_BIT_STRING_set
+.Fa "ASN1_BIT_STRING *bitstr"
+.Fa "unsigned char *data"
+.Fa "int len"
+.Fc
+.Ft int
+.Fo ASN1_BIT_STRING_set_bit
+.Fa "ASN1_BIT_STRING *bitstr"
+.Fa "int bitnumber"
+.Fa "int set"
+.Fc
+.Ft int
+.Fo ASN1_BIT_STRING_get_bit
+.Fa "ASN1_BIT_STRING *bitstr"
+.Fa "int bitnumber"
+.Fc
+.Ft int
+.Fo ASN1_BIT_STRING_check
+.Fa "ASN1_BIT_STRING *bitstr"
+.Fa "const unsigned char *goodbits"
+.Fa "int goodbits_len"
+.Fc
+.Sh DESCRIPTION
+.Fn ASN1_BIT_STRING_set
+sets the length attribute of
+.Fa bitstr
+to
+.Fa len
+and copies that number of bytes from
+.Fa data
+into
+.Fa bitstr ,
+overwriting any previous data, by merely calling
+.Xr ASN1_STRING_set 3 .
+This function does no validation whatsoever.
+In particular, it neither checks that
+.Fa bitstr
+is actually of the type
+.Dv V_ASN1_BIT_STRING
+nor, even if it is, that the
+.Fa data
+and
+.Fa len
+arguments make sense for this particular bit string.
+.Pp
+If the
+.Fa set
+argument is non-zero,
+.Fn ASN1_BIT_STRING_set_bit
+sets the bit with the given
+.Fa bitnumber
+in the
+.Fa bitstr ;
+otherwise, it clears that bit.
+A
+.Fa bitnumber
+of 0 addresses the most significant bit in the first data byte of
+.Fa bitstr ,
+7 the least significant bit in the same byte,
+8 the most significant bit in the second data byte, and so on.
+.Pp
+If setting a bit is requested beyond the last existing data byte,
+additional bytes are added to the
+.Fa bitstr
+as needed.
+After clearing a bit, any trailing NUL bytes are removed from the
+.Fa bitstr .
+.Pp
+.Fn ASN1_BIT_STRING_get_bit
+checks that the bit with the given
+.Fa bitnumber
+is set in
+.Fa bitstr .
+.Pp
+.Fn ASN1_BIT_STRING_check
+checks that all bits set in
+.Fa bitstr
+are also set in
+.Fa goodbits .
+Expressed symbolically, it evaluates:
+.Pp
+.D1 Po Fa bitstr No & Pf \(ti Fa goodbits Pc == 0
+.Pp
+The buffer
+.Fa goodbits
+is expected to contain
+.Fa goodbits_len
+bytes.
+.Sh RETURN VALUES
+.Fn ASN1_BIT_STRING_set
+returns 1 on success or 0 if memory allocation fails or if
+.Fa data
+is
+.Dv NULL
+and
+.Fa len
+is \-1 in the same call.
+.Pp
+.Fn ASN1_BIT_STRING_set_bit
+returns 1 on success or 0 if
+.Fa bitstr
+is
+.Dv NULL
+or if memory allocation fails.
+.Pp
+.Fn ASN1_BIT_STRING_get_bit
+returns 1 if the bit with the given
+.Fa bitnumber
+is set in the
+.Fa bitstr
+or 0 if
+.Fa bitstr
+is
+.Dv NULL ,
+if
+.Fa bitnumber
+points beyond the last data byte in
+.Fa bitstr ,
+or if the requested bit is not set.
+.Pp
+.Fn ASN1_BIT_STRING_check
+returns 0
+if at least one bit is set in
+.Fa bitstr
+that is not set in
+.Fa goodbits ,
+or 1 otherwise.
+In particular, it returns 1 if
+.Fa bitstr
+is
+.Dv NULL
+or if no bit is set in
+.Fa bitstr .
+.Sh SEE ALSO
+.Xr ASN1_BIT_STRING_new 3 ,
+.Xr ASN1_STRING_set 3 ,
+.Xr d2i_ASN1_BIT_STRING 3
+.Sh HISTORY
+.Fn ASN1_BIT_STRING_set
+first appeared in SSLeay 0.6.5.
+.Fn ASN1_BIT_STRING_set_bit
+and
+.Fn ASN1_BIT_STRING_get_bit
+first appeared in SSLeay 0.9.0.
+These functions have been available since
+.Ox 2.4 .
+.Pp
+.Fn ASN1_BIT_STRING_check
+first appeared in OpenSSL 1.0.0 and has have been available since
+.Ox 4.9 .
diff --git a/lib/libcrypto/man/ASN1_STRING_length.3 b/lib/libcrypto/man/ASN1_STRING_length.3
index 5a113ecb223..da0d7468c3e 100644
--- a/lib/libcrypto/man/ASN1_STRING_length.3
+++ b/lib/libcrypto/man/ASN1_STRING_length.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: ASN1_STRING_length.3,v 1.25 2021/11/15 13:39:40 schwarze Exp $
+.\" $OpenBSD: ASN1_STRING_length.3,v 1.26 2021/11/15 16:18:36 schwarze Exp $
 .\" full merge up to: OpenSSL 24a535ea Sep 22 13:14:20 2020 +0100
 .\"
 .\" This file is a derived work.
@@ -380,6 +380,7 @@ and
 the reason can be determined with
 .Xr ERR_get_error 3 .
 .Sh SEE ALSO
+.Xr ASN1_BIT_STRING_set 3 ,
 .Xr ASN1_mbstring_copy 3 ,
 .Xr ASN1_PRINTABLE_type 3 ,
 .Xr ASN1_STRING_new 3 ,
diff --git a/lib/libcrypto/man/ASN1_STRING_new.3 b/lib/libcrypto/man/ASN1_STRING_new.3
index 23679cdb3cc..fbc999a3257 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.21 2021/11/15 13:39:40 schwarze Exp $
+.\"	$OpenBSD: ASN1_STRING_new.3,v 1.22 2021/11/15 16:18:36 schwarze Exp $
 .\"	OpenSSL 99d63d46 Tue Mar 24 07:52:24 2015 -0400
 .\"
 .\" Copyright (c) 2017 Ingo Schwarze <schwarze@openbsd.org>
@@ -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_set 3 ,
 .Xr ASN1_INTEGER_get 3 ,
 .Xr ASN1_item_pack 3 ,
 .Xr ASN1_mbstring_copy 3 ,
diff --git a/lib/libcrypto/man/Makefile b/lib/libcrypto/man/Makefile
index 2af6c166578..46ca3ba3d4e 100644
--- a/lib/libcrypto/man/Makefile
+++ b/lib/libcrypto/man/Makefile
@@ -1,10 +1,11 @@
-# $OpenBSD: Makefile,v 1.214 2021/11/15 13:39:40 schwarze Exp $
+# $OpenBSD: Makefile,v 1.215 2021/11/15 16:18:36 schwarze Exp $
 
 .include <bsd.own.mk>
 
 MAN=	\
 	ACCESS_DESCRIPTION_new.3 \
 	AES_encrypt.3 \
+	ASN1_BIT_STRING_set.3 \
 	ASN1_INTEGER_get.3 \
 	ASN1_OBJECT_new.3 \
 	ASN1_PRINTABLE_type.3 \