.\" $OpenBSD: X509_OBJECT_get0_X509.3,v 1.14 2022/01/15 23:38:50 jsg Exp $
.\"
.\" Copyright (c) 2018, 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: January 15 2022 $
.Dt X509_OBJECT_GET0_X509 3
.Os
.Sh NAME
.Nm X509_OBJECT_get_type ,
.Nm X509_OBJECT_new ,
.Nm X509_OBJECT_up_ref_count ,
.Nm X509_OBJECT_free_contents ,
.Nm X509_OBJECT_free ,
.Nm X509_OBJECT_get0_X509 ,
.Nm X509_OBJECT_get0_X509_CRL ,
.Nm X509_OBJECT_idx_by_subject ,
.Nm X509_OBJECT_retrieve_by_subject ,
.Nm X509_OBJECT_retrieve_match
.Nd certificate, CRL, private key, and string wrapper for certificate stores
.Sh SYNOPSIS
.In openssl/x509_vfy.h
.Ft X509_LOOKUP_TYPE
.Fo X509_OBJECT_get_type
.Fa "const X509_OBJECT *obj"
.Fc
.Ft X509_OBJECT *
.Fo X509_OBJECT_new
.Fa void
.Fc
.Ft int
.Fo X509_OBJECT_up_ref_count
.Fa "X509_OBJECT *obj"
.Fc
.Ft void
.Fo X509_OBJECT_free_contents
.Fa "X509_OBJECT *obj"
.Fc
.Ft void
.Fo X509_OBJECT_free
.Fa "X509_OBJECT *obj"
.Fc
.Ft X509 *
.Fo X509_OBJECT_get0_X509
.Fa "const X509_OBJECT *obj"
.Fc
.Ft X509_CRL *
.Fo X509_OBJECT_get0_X509_CRL
.Fa "X509_OBJECT *obj"
.Fc
.Ft int
.Fo X509_OBJECT_idx_by_subject
.Fa "STACK_OF(X509_OBJECT) *stack"
.Fa "X509_LOOKUP_TYPE type"
.Fa "X509_NAME *name"
.Fc
.Ft X509_OBJECT *
.Fo X509_OBJECT_retrieve_by_subject
.Fa "STACK_OF(X509_OBJECT) *stack"
.Fa "X509_LOOKUP_TYPE type"
.Fa "X509_NAME *name"
.Fc
.Ft X509_OBJECT *
.Fo X509_OBJECT_retrieve_match
.Fa "STACK_OF(X509_OBJECT) *stack"
.Fa "X509_OBJECT *obj"
.Fc
.Sh DESCRIPTION
The
.Vt X509_OBJECT
structure is a shallow wrapper around one
.Vt X509
certificate object or one
.Vt X509_CRL
certificate revocation list object.
The type of object stored at any given time can be inspected with
.Fn X509_OBJECT_get_type .
.Pp
Each
.Vt X509_STORE
object uses one stack of
.Vt X509_OBJECT
structures as its main storage area.
.Pp
.Fn X509_OBJECT_new
allocates a new
.Vt X509_OBJECT
structure.
It sets the object type to
.Dv X509_LU_NONE
and the pointer to the certificate or CRL to
.Dv NULL .
.Pp
If
.Fa obj
contains an
.Vt X509
certificate or an
.Vt X509_CRL
certificate revocation list,
.Fn X509_OBJECT_up_ref_count
increments the reference count of that inner object by 1.
Otherwise, no action occurs.
.Pp
If
.Fa obj
contains an
.Vt X509
certificate,
.Fn X509_OBJECT_free_contents
calls
.Xr X509_free 3
on that inner object.
If
.Fa obj
contains an
.Vt X509_CRL
certificate revocation list, it calls
.Xr X509_CRL_free 3
on that inner list.
Otherwise, no action occurs.
.Fn X509_OBJECT_free_contents
does not free
.Fa obj
itself.
.Pp
.Fn X509_OBJECT_free
calls
.Fn X509_OBJECT_free_contents
and then frees the storage used for the
.Fa obj
itself.
.Pp
If
.Fa type
is
.Dv X509_LU_X509 ,
.Fn X509_OBJECT_idx_by_subject
and
.Fn X509_OBJECT_retrieve_by_subject
search the given
.Fa stack
for a certificate with the subject
.Fa name .
If
.Fa type
is
.Dv X509_LU_CRL ,
they search for a certificate revocation list with the issuer
.Fa name
instead.
.Pp
If
.Fa obj
contains a certificate,
.Fn X509_OBJECT_retrieve_match
searches the given
.Fa stack
for a certificate with a matching subject name;
if it contains a certificate revocation list, it searches for a
certificate revocation list with a matching issuer name instead;
otherwise, it searches for an
.Vt X509_OBJECT
with a matching type.
.Sh RETURN VALUES
.Fn X509_OBJECT_get_type
returns
.Dv X509_LU_X509
if
.Fa obj
contains a certificate,
.Dv X509_LU_CRL
if it contains a certificate revocation list, or
.Dv X509_LU_NONE
if it contains neither.
.Pp
.Fn X509_OBJECT_up_ref_count
returns 1 on success and 0 on failure.
.Pp
.Fn X509_OBJECT_new
returns the new object or
.Dv NULL
if memory allocation fails.
.Pp
.Fn X509_OBJECT_get0_X509
returns an internal pointer to the certificate contained in
.Fa obj
or
.Dv NULL
if
.Fa obj
is
.Dv NULL
or contains no certificate.
.Pp
.Fn X509_OBJECT_get0_X509_CRL
returns an internal pointer to the certificate revocation list contained in
.Fa obj
or
.Dv NULL
if
.Fa obj
is
.Dv NULL
or contains no certificate revocation list.
.Pp
.Fn X509_OBJECT_idx_by_subject
returns the zero-based index of the first matching certificate
or revocation list in the
.Fa stack
or \-1 if
.Fa type
is neither
.Dv X509_LU_X509
nor
.Dv X509_LU_CRL
or if no match is found.
.Pp
.Fn X509_OBJECT_retrieve_by_subject
returns the first matching certificate or revocation list in the
.Fa stack
or
.Dv NULL
if
.Fa type
is neither
.Dv X509_LU_X509
nor
.Dv X509_LU_CRL
or if no match is found.
.Pp
.Fn X509_OBJECT_retrieve_match
returns the first matching
.Vt X509_OBJECT
or
.Dv NULL
if
.Fa stack
or
.Fa obj
is
.Dv NULL
or no match is found.
.Sh SEE ALSO
.Xr STACK_OF 3 ,
.Xr X509_CRL_new 3 ,
.Xr X509_LOOKUP_new 3 ,
.Xr X509_NAME_new 3 ,
.Xr X509_new 3 ,
.Xr X509_STORE_get0_objects 3 ,
.Xr X509_STORE_get_by_subject 3 ,
.Xr X509_STORE_load_locations 3 ,
.Xr X509_STORE_new 3
.Sh HISTORY
.Fn X509_OBJECT_up_ref_count
and
.Fn X509_OBJECT_free_contents
first appeared in SSLeay 0.8.0 and have been available since
.Ox 2.4 .
.Pp
.Fn X509_OBJECT_idx_by_subject ,
.Fn X509_OBJECT_retrieve_by_subject ,
and
.Fn X509_OBJECT_retrieve_match
first appeared in OpenSSL 0.9.6 and have been available since
.Ox 2.9 .
.Pp
.Fn X509_OBJECT_get_type ,
.Fn X509_OBJECT_get0_X509 ,
and
.Fn X509_OBJECT_get0_X509_CRL
first appeared in OpenSSL 1.1.0 and have been available since
.Ox 6.3 .
.Pp
.Fn X509_OBJECT_new
and
.Fn X509_OBJECT_free
first appeared in OpenSSL 1.1.0 and have been available since
.Ox 7.1 .