From a000f9e856f986c00ad874d0b7994d5f0b124275 Mon Sep 17 00:00:00 2001 From: schwarze Date: Fri, 19 Nov 2021 16:00:54 +0000 Subject: [PATCH] new manual page ASN1_BIT_STRING_num_asc(3) documenting the three functions using the BIT_STRING_BITNAME structure --- lib/libcrypto/man/ASN1_BIT_STRING_num_asc.3 | 146 ++++++++++++++++++++ lib/libcrypto/man/ASN1_BIT_STRING_set.3 | 5 +- lib/libcrypto/man/ASN1_STRING_new.3 | 5 +- lib/libcrypto/man/Makefile | 3 +- 4 files changed, 154 insertions(+), 5 deletions(-) create mode 100644 lib/libcrypto/man/ASN1_BIT_STRING_num_asc.3 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 +.\" +.\" 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 .\" @@ -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 @@ -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 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 \ -- 2.20.1