From d2c7d94ed700a97e515bc3062184517d251ab89f Mon Sep 17 00:00:00 2001 From: schwarze Date: Mon, 15 Nov 2021 16:18:36 +0000 Subject: [PATCH] new manual page ASN1_BIT_STRING_set(3) documenting four BIT STRING accessors --- lib/libcrypto/man/ASN1_BIT_STRING_set.3 | 178 ++++++++++++++++++++++++ lib/libcrypto/man/ASN1_STRING_length.3 | 3 +- lib/libcrypto/man/ASN1_STRING_new.3 | 3 +- lib/libcrypto/man/Makefile | 3 +- 4 files changed, 184 insertions(+), 3 deletions(-) create mode 100644 lib/libcrypto/man/ASN1_BIT_STRING_set.3 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 +.\" +.\" 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 @@ -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 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 \ -- 2.20.1