path: root/lib/libcrypto/man/X509_STORE_get_by_subject.3

.\" $OpenBSD: X509_STORE_get_by_subject.3,v 1.3 2021/11/12 14:05:28 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: November 12 2021 $
.Dt X509_STORE_GET_BY_SUBJECT 3
.Os
.Sh NAME
.Nm X509_STORE_CTX_get_by_subject ,
.Nm X509_STORE_CTX_get_obj_by_subject ,
.Nm X509_STORE_get_by_subject ,
.Nm X509_STORE_get1_certs ,
.Nm X509_STORE_get1_crls ,
.Nm X509_STORE_CTX_get1_issuer
.Nd retrieve objects from a certificate store
.Sh SYNOPSIS
.In openssl/x509_vfy.h
.Ft int
.Fo X509_STORE_CTX_get_by_subject
.Fa "X509_STORE_CTX *ctx"
.Fa "X509_LOOKUP_TYPE type"
.Fa "X509_NAME *name"
.Fa "X509_OBJECT *object"
.Fc
.Ft X509_OBJECT *
.Fo X509_STORE_CTX_get_obj_by_subject
.Fa "X509_STORE_CTX *ctx"
.Fa "X509_LOOKUP_TYPE type"
.Fa "X509_NAME *name"
.Fc
.Ft int
.Fo X509_STORE_get_by_subject
.Fa "X509_STORE_CTX *ctx"
.Fa "X509_LOOKUP_TYPE type"
.Fa "X509_NAME *name"
.Fa "X509_OBJECT *object"
.Fc
.Ft STACK_OF(X509) *
.Fo X509_STORE_get1_certs
.Fa "X509_STORE_CTX *ctx"
.Fa "X509_NAME *name"
.Fc
.Ft STACK_OF(X509_CRL) *
.Fo X509_STORE_get1_crls
.Fa "X509_STORE_CTX *ctx"
.Fa "X509_NAME *name"
.Fc
.Ft int
.Fo X509_STORE_CTX_get1_issuer
.Fa "X509 **issuer"
.Fa "X509_STORE_CTX *ctx"
.Fa "X509 *certificate"
.Fc
.Sh DESCRIPTION
.Fn X509_STORE_CTX_get_by_subject
retrieves the first object having a matching
.Fa type
and
.Fa name
from the
.Vt X509_STORE
associated with the
.Fa ctx .
The
.Fa type
can be
.Dv X509_LU_X509
to retrieve a certificate or
.Dv X509_LU_CRL
to retrieve a revocation list.
.Pp
If the store does not yet contain a matching object or if the type is
.Dv X509_LU_CRL ,
.Xr X509_LOOKUP_by_subject 3
is called on
.Vt X509_LOOKUP
objects associated with the store until a match is found,
which may add zero or more objects to the store.
.Pp
In case of success, the content of the
.Fa object
provided by the caller is overwritten with a pointer to the first
match, and the reference count of that certificate or revocation
list is incremented by 1.
Avoiding a memory leak by making sure the provided
.Fa object
is empty is the responsibility of the caller.
.Pp
.Fn X509_STORE_CTX_get_obj_by_subject
is similar except that a new object is allocated and returned.
.Pp
.Fn X509_STORE_get_by_subject
is a deprecated alias for
.Fn X509_STORE_CTX_get_by_subject .
.Pp
.Fn X509_STORE_get1_certs
retrieves all certificates matching the subject
.Vt name
from the
.Vt X509_STORE
associated with
.Fa ctx .
If there are none yet,
.Fn X509_STORE_get_by_subject
is called to try and add some.
In case of success, the reference counts of all certificates
added to the returned array are incremented by 1.
.Pp
.Fn X509_STORE_get1_crls
is similar except that it operates on certificate revocation lists
rather than on certificates and that it always calls
.Fn X509_STORE_get_by_subject ,
even if the
.Vt X509_STORE
already contains a matching revocation list.
.Pp
.Fn X509_STORE_CTX_get1_issuer
retrieves the
.Fa issuer
CA certificate for the given
.Fa certificate
from the
.Vt X509_STORE
associated with
.Fa ctx .
Internally, the issuer name is retrieved with
.Xr X509_get_issuer_name 3
and the candidate issuer CA certificate with
.Fn X509_STORE_get_by_subject
using that issuer name.
.Xr X509_check_issued 3
or a user-supplied replacement function is used to check whether the
.Fa certificate
was indeed issued using the
.Fa issuer
CA certificate before returning it.
If verification parameters associated with
.Fa ctx
encourage checking of validity times, CAs with a valid time are
preferred, but if no matching CA has a valid time, one with an
invalid time is accepted anyway.
.Sh RETURN VALUES
.Fn X509_STORE_CTX_get_by_subject
and
.Fn X509_STORE_get_by_subject
return 1 if a match is found or 0 on failure.
In addition to simply not finding a match,
they may also fail due to memory allocation failure in
.Xr X509_LOOKUP_by_subject 3 .
With library implementations other than LibreSSL,
they might also return negative values for internal errors.
.Pp
.Fn X509_STORE_CTX_get_obj_by_subject
returns the new object or
.Dv NULL
on failure, in particular if no match is found or memory allocation fails.
.Pp
.Fn X509_STORE_get1_certs
returns a newly allocated and populated array of certificates or
.Dv NULL
on failure.
It fails if no match is found, if
.Fn X509_STORE_get_by_subject
fails, or if memory allocation fails.
.Pp
.Fn X509_STORE_get1_crls
returns a newly allocated and populated array of CRLs or
.Dv NULL
on failure.
It fails if
.Fn X509_STORE_get_by_subject
finds no new match, even if the associated
.Vt X509_STORE
already contains matching CRLs, or if memory allocation fails.
.Pp
.Fn X509_STORE_CTX_get1_issuer
returns 1 if a matching
.Fa issuer
CA certificate is found or 0 otherwise.
With library implementations other than LibreSSL,
it might also return negative values for internal errors.
.Sh SEE ALSO
.Xr STACK_OF 3 ,
.Xr X509_check_issued 3 ,
.Xr X509_CRL_new 3 ,
.Xr X509_get_issuer_name 3 ,
.Xr X509_LOOKUP_by_subject 3 ,
.Xr X509_NAME_new 3 ,
.Xr X509_new 3 ,
.Xr X509_OBJECT_retrieve_by_subject 3 ,
.Xr X509_STORE_CTX_new 3 ,
.Xr X509_VERIFY_PARAM_set_flags 3
.Sh HISTORY
.Fn X509_STORE_get_by_subject
first appeared in SSLeay 0.8.0 and has been available since
.Ox 2.4 .
.Pp
.Fn X509_STORE_CTX_get1_issuer
first appeared in OpenSSL 0.9.6 and has been available since
.Ox 2.9 .
.Pp
.Fn X509_STORE_get1_certs
and
.Fn X509_STORE_get1_crls
first appeared in OpenSSL 1.0.0 and have been available since
.Ox 4.9 .
.Pp
.Fn X509_STORE_CTX_get_by_subject
and
.Fn X509_STORE_CTX_get_obj_by_subject
first appeared in OpenSSL 1.1.0 and have been available since
.Ox 7.1 .