new manual page X509at_get_attr(3)

documenting five X.501 Attribute read accessors

3 files changed, 163 insertions, 4 deletions

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 <bsd.own.mk>
 
@@ -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 <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: 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 <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: 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 .