From fd04fa5bfc56fd96c345a17c11b7275b8efb7bf4 Mon Sep 17 00:00:00 2001 From: schwarze Date: Fri, 22 Oct 2021 11:24:45 +0000 Subject: [PATCH] new manual page X509at_get_attr(3) documenting five X.501 Attribute read accessors --- lib/libcrypto/man/Makefile | 3 +- lib/libcrypto/man/X509_ATTRIBUTE_new.3 | 7 +- lib/libcrypto/man/X509at_get_attr.3 | 157 +++++++++++++++++++++++++ 3 files changed, 163 insertions(+), 4 deletions(-) create mode 100644 lib/libcrypto/man/X509at_get_attr.3 diff --git a/lib/libcrypto/man/Makefile b/lib/libcrypto/man/Makefile index 51c2cf45b7f..e31e6992a22 100644 --- a/lib/libcrypto/man/Makefile +++ b/lib/libcrypto/man/Makefile @@ -1,4 +1,4 @@ -# $OpenBSD: Makefile,v 1.196 2021/10/21 16:26:34 schwarze Exp $ +# $OpenBSD: Makefile,v 1.197 2021/10/22 11:24:45 schwarze Exp $ .include @@ -276,6 +276,7 @@ MAN= \ UI_new.3 \ X25519.3 \ X509V3_get_d2i.3 \ + X509at_get_attr.3 \ X509_ALGOR_dup.3 \ X509_ATTRIBUTE_get0_object.3 \ X509_ATTRIBUTE_new.3 \ diff --git a/lib/libcrypto/man/X509_ATTRIBUTE_new.3 b/lib/libcrypto/man/X509_ATTRIBUTE_new.3 index e0cff822dac..c25144531ab 100644 --- a/lib/libcrypto/man/X509_ATTRIBUTE_new.3 +++ b/lib/libcrypto/man/X509_ATTRIBUTE_new.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: X509_ATTRIBUTE_new.3,v 1.11 2021/10/21 16:26:34 schwarze Exp $ +.\" $OpenBSD: X509_ATTRIBUTE_new.3,v 1.12 2021/10/22 11:24:45 schwarze Exp $ .\" .\" Copyright (c) 2016, 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: October 21 2021 $ +.Dd $Mdocdate: October 22 2021 $ .Dt X509_ATTRIBUTE_NEW 3 .Os .Sh NAME @@ -119,7 +119,8 @@ fails on .Xr X509_ATTRIBUTE_set1_object 3 , .Xr X509_EXTENSION_new 3 , .Xr X509_new 3 , -.Xr X509_REQ_new 3 +.Xr X509_REQ_new 3 , +.Xr X509at_get_attr 3 .Sh STANDARDS .Bl -ohang .It Xo diff --git a/lib/libcrypto/man/X509at_get_attr.3 b/lib/libcrypto/man/X509at_get_attr.3 new file mode 100644 index 00000000000..8e1a65e2d18 --- /dev/null +++ b/lib/libcrypto/man/X509at_get_attr.3 @@ -0,0 +1,157 @@ +.\" $OpenBSD: X509at_get_attr.3,v 1.1 2021/10/22 11:24:45 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: October 22 2021 $ +.Dt X509AT_GET_ATTR 3 +.Os +.Sh NAME +.Nm X509at_get_attr , +.Nm X509at_get_attr_count , +.Nm X509at_get_attr_by_OBJ , +.Nm X509at_get_attr_by_NID , +.Nm X509at_get0_data_by_OBJ +.\" In the following line, "X.501" and "Attribute" are not typos. +.\" The "Attribute" type is defined in X.501, not in X.509. +.\" The type is called "Attribute" with capital "A", not "attribute". +.Nd X.501 Attribute array read accessors +.Sh SYNOPSIS +.In openssl/x509.h +.Ft X509_ATTRIBUTE * +.Fo X509at_get_attr +.Fa "const STACK_OF(X509_ATTRIBUTE) *attrs" +.Fa "int index" +.Fc +.Ft int +.Fo X509at_get_attr_count +.Fa "const STACK_OF(X509_ATTRIBUTE) *attrs" +.Fc +.Ft int +.Fo X509at_get_attr_by_OBJ +.Fa "const STACK_OF(X509_ATTRIBUTE) *attrs" +.Fa "const ASN1_OBJECT *obj" +.Fa "int start_after" +.Fc +.Ft int +.Fo X509at_get_attr_by_NID +.Fa "const STACK_OF(X509_ATTRIBUTE) *attrs" +.Fa "int nid" +.Fa "int start_after" +.Fc +.Ft void * +.Fo X509at_get0_data_by_OBJ +.Fa "STACK_OF(X509_ATTRIBUTE) *attrs" +.Fa "const ASN1_OBJECT *obj" +.Fa "int start_after" +.Fa "int type" +.Fc +.Sh DESCRIPTION +These functions retrieve information from the +.Fa attrs +array of X.501 Attibute objects. +They all fail if +.Fa attrs +is a +.Dv NULL +pointer. +.Pp +.Fn X509at_get_attr +returns the array element at the zero-based +.Fa index . +It fails if the +.Fa index +is negative or greater than or equal to the number of objects in the array. +.Pp +.Fn X509at_get_attr_count +returns the number of objects currently stored in the array. +.Pp +The three remaining functions search the array starting after the index +.Fa start_after . +They fail if no matching object is found. +.Fn X509at_get0_data_by_OBJ +also fails if the data is not of the requested +.Fa type . +.Pp +Additionally, the +.Fa start_after +argument of +.Fn X509at_get0_data_by_OBJ +is interpreted in a special way. +If +.Fa start_after +is \-2 or smaller, +.Fn X509at_get0_data_by_OBJ +also fails if +.Fa attrs +contains more than one matching object. +If +.Fa start_after +is \-3 or smaller, it also fails unless the matching object +contains exactly one value. +.Sh RETURN VALUES +.Fn X509at_get_attr +returns an internal pointer or +or +.Dv NULL +on failure. +.Pp +.Fn X509at_get_attr_count +returns the number of array elements or \-1 on failure. +.Pp +.Fn X509at_get_attr_by_OBJ +and +.Fn X509at_get_attr_by_NID +return the index of the first object in the array +that has an index greater than +.Fa start_after +and a type matching +.Fa obj +or +.Fa nid , +respectively, or \-1 on failure. +In addition, +.Fn X509at_get_attr_by_NID +returns \-2 +if +.Xr OBJ_nid2obj 3 +fails on the requested +.Fa nid . +.Pp +.Fn X509at_get0_data_by_OBJ +returns an internal pointer to the data contained in the value +of the first object that has an index greater than +.Fa start_after +and a type matching +.Fa obj , +or +.Dv NULL +on failure. +.Sh SEE ALSO +.Xr OBJ_nid2obj 3 , +.Xr STACK_OF 3 , +.Xr X509_ATTRIBUTE_get0_data 3 , +.Xr X509_ATTRIBUTE_new 3 +.Sh HISTORY +.Fn X509at_get_attr , +.Fn X509at_get_attr_count , +.Fn X509at_get_attr_by_OBJ , +and +.Fn X509at_get_attr_by_NID +first appeared in OpenSSL 0.9.5 and have been available since +.Ox 2.7 . +.Pp +.Fn X509at_get0_data_by_OBJ +first appeared in OpenSSL 0.9.8h and has been available since +.Ox 4.5 . -- 2.20.1