.\" $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 .