NAME
X509_STORE_CTX_get_by_subject,
X509_STORE_CTX_get_obj_by_subject,
X509_STORE_CTX_get1_certs,
X509_STORE_CTX_get1_crls,
X509_STORE_CTX_get1_issuer,
X509_STORE_get_by_subject,
X509_STORE_get1_certs,
X509_STORE_get1_crls —
retrieve objects from a certificate
store
SYNOPSIS
#include
<openssl/x509_vfy.h>
int
X509_STORE_CTX_get_by_subject(X509_STORE_CTX
*ctx, X509_LOOKUP_TYPE type,
X509_NAME *name, X509_OBJECT
*object);
X509_OBJECT *
X509_STORE_CTX_get_obj_by_subject(X509_STORE_CTX
*ctx, X509_LOOKUP_TYPE type,
X509_NAME *name);
STACK_OF(X509) *
X509_STORE_CTX_get1_certs(X509_STORE_CTX
*ctx, X509_NAME *name);
STACK_OF(X509_CRL) *
X509_STORE_CTX_get1_crls(X509_STORE_CTX
*ctx, X509_NAME *name);
int
X509_STORE_CTX_get1_issuer(X509
**issuer, X509_STORE_CTX *ctx,
X509 *certificate);
int
X509_STORE_get_by_subject(X509_STORE_CTX
*ctx, X509_LOOKUP_TYPE type,
X509_NAME *name, X509_OBJECT
*object);
STACK_OF(X509) *
X509_STORE_get1_certs(X509_STORE_CTX
*ctx, X509_NAME *name);
STACK_OF(X509_CRL) *
X509_STORE_get1_crls(X509_STORE_CTX
*ctx, X509_NAME *name);
DESCRIPTION
X509_STORE_CTX_get_by_subject()
retrieves the first object having a matching type and
name from the X509_STORE
associated with the ctx. The
type can be X509_LU_X509 to
retrieve a certificate or X509_LU_CRL to retrieve a
revocation list.
If the store does not yet contain a matching object or if the type
is X509_LU_CRL, a lookup by subject is performed on
X509_LOOKUP objects associated with the store until a
match is found, which may add zero or more objects to the store.
In case of success, the content of the 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 object is empty is the responsibility of the caller.
X509_STORE_CTX_get_obj_by_subject()
is similar except that a new object is allocated and returned.
X509_STORE_CTX_get1_certs()
retrieves all certificates matching the subject name
from the X509_STORE associated with
ctx. If there are none yet,
X509_STORE_CTX_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.
X509_STORE_CTX_get1_crls()
is similar except that it operates on certificate revocation lists rather
than on certificates and that it always calls
X509_STORE_CTX_get_by_subject(), even if the
X509_STORE already contains a matching revocation
list.
X509_STORE_CTX_get1_issuer()
retrieves the issuer CA certificate for the given
certificate from the X509_STORE
associated with ctx. Internally, the issuer name is
retrieved with
X509_get_issuer_name(3) and the candidate issuer CA
certificate with
X509_STORE_X509_get_by_subject()
using that issuer name.
X509_check_issued(3) or a user-supplied replacement function
is used to check whether the certificate was indeed
issued using the issuer CA certificate before
returning it. If verification parameters associated with
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.
The following are deprecated aliases implemented as macros:
X509_STORE_get_by_subject() |
for | X509_STORE_CTX_get_by_subject() |
X509_STORE_get1_certs() |
for | X509_STORE_CTX_get1_certs() |
X509_STORE_get1_crls() |
for | X509_STORE_CTX_get1_crls() |
RETURN VALUES
X509_STORE_CTX_get_by_subject() and
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. With library implementations
other than LibreSSL, they might also return negative values for internal
errors.
X509_STORE_CTX_get_obj_by_subject()
returns the new object or NULL on failure, in
particular if no match is found or memory allocation fails.
X509_STORE_CTX_get1_certs() and
X509_STORE_get1_certs() return a newly allocated and
populated array of certificates or NULL on failure.
They fail if no match is found, if
X509_STORE_CTX_get_by_subject() fails, or if memory
allocation fails.
X509_STORE_CTX_get1_crls() and
X509_STORE_get1_crls() return a newly allocated and
populated array of CRLs or NULL on failure. They
fail if X509_STORE_CTX_get_by_subject() finds no new
match, even if the associated X509_STORE already
contains matching CRLs, or if memory allocation fails.
X509_STORE_CTX_get1_issuer() returns 1 if
a matching issuer CA certificate is found or 0
otherwise. With library implementations other than LibreSSL, it might also
return negative values for internal errors.
SEE ALSO
STACK_OF(3), X509_check_issued(3), X509_CRL_new(3), X509_get_issuer_name(3), X509_NAME_new(3), X509_new(3), X509_OBJECT_retrieve_by_subject(3), X509_STORE_CTX_new(3), X509_VERIFY_PARAM_set_flags(3)
HISTORY
X509_STORE_get_by_subject() first appeared
in SSLeay 0.8.0 and has been available since OpenBSD
2.4.
X509_STORE_CTX_get1_issuer() first
appeared in OpenSSL 0.9.6 and has been available since
OpenBSD 2.9.
X509_STORE_get1_certs() and
X509_STORE_get1_crls() first appeared in OpenSSL
1.0.0 and have been available since OpenBSD 4.9.
X509_STORE_CTX_get_by_subject() and
X509_STORE_CTX_get_obj_by_subject() first appeared
in OpenSSL 1.1.0 and have been available since OpenBSD
7.1.
X509_STORE_CTX_get1_certs() and
X509_STORE_CTX_get1_crls() first appeared in OpenSSL
1.1.0 and have been available since OpenBSD 7.4.