161 lines
4.1 KiB
Groff
161 lines
4.1 KiB
Groff
.\" $OpenBSD: X509at_get_attr.3,v 1.7 2022/03/28 08:18:13 claudio 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: March 28 2022 $
|
|
.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 Attribute 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
|
|
.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 EVP_PKEY_get_attr 3 ,
|
|
.Xr OBJ_nid2obj 3 ,
|
|
.Xr PKCS8_pkey_get0_attrs 3 ,
|
|
.Xr STACK_OF 3 ,
|
|
.Xr X509_ATTRIBUTE_get0_data 3 ,
|
|
.Xr X509_ATTRIBUTE_new 3 ,
|
|
.Xr X509_REQ_get_attr 3 ,
|
|
.Xr X509at_add1_attr 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 .
|