mischief/openbsd-src
1
0
Fork 0
mirror of https://github.com/openbsd/src.git synced 2025-01-03 06:45:37 -08:00
Code

new manual page X509at_get_attr(3)

Browse Source 
documenting five X.501 Attribute read accessors
This commit is contained in:
schwarze 2021-10-22 11:24:45 +00:00
parent 2defcb5299
commit fd04fa5bfc
3 changed files with 163 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
lib/libcrypto/man/Makefile
View File

@ -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 \

7
lib/libcrypto/man/X509_ATTRIBUTE_new.3
View File

@ -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

157
lib/libcrypto/man/X509at_get_attr.3 Normal file
View File

@ -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 .