.\" $OpenBSD: X509_STORE_get_by_subject.3,v 1.5 2023/11/16 20:27:43 schwarze Exp $ .\" .\" Copyright (c) 2021, 2023 Ingo Schwarze .\" .\" 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 16 2023 $ .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_CTX_get1_certs , .Nm X509_STORE_CTX_get1_crls , .Nm X509_STORE_CTX_get1_issuer , .Nm X509_STORE_get_by_subject , .Nm X509_STORE_get1_certs , .Nm X509_STORE_get1_crls .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 STACK_OF(X509) * .Fo X509_STORE_CTX_get1_certs .Fa "X509_STORE_CTX *ctx" .Fa "X509_NAME *name" .Fc .Ft STACK_OF(X509_CRL) * .Fo X509_STORE_CTX_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 .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 .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_CTX_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_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. .Pp .Fn X509_STORE_CTX_get1_crls is similar except that it operates on certificate revocation lists rather than on certificates and that it always calls .Fn X509_STORE_CTX_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_X509_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. .Pp The following are deprecated aliases implemented as macros: .Bl -column X509_STORE_get_by_subject F X509_STORE_CTX_get_by_subject .It Fn X509_STORE_get_by_subject Ta for Ta Fn X509_STORE_CTX_get_by_subject .It Fn X509_STORE_get1_certs Ta for Ta Fn X509_STORE_CTX_get1_certs .It Fn X509_STORE_get1_crls Ta for Ta Fn X509_STORE_CTX_get1_crls .El .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_CTX_get1_certs and .Fn X509_STORE_get1_certs return a newly allocated and populated array of certificates or .Dv NULL on failure. They fail if no match is found, if .Fn X509_STORE_CTX_get_by_subject fails, or if memory allocation fails. .Pp .Fn X509_STORE_CTX_get1_crls and .Fn X509_STORE_get1_crls return a newly allocated and populated array of CRLs or .Dv NULL on failure. They fail if .Fn X509_STORE_CTX_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 . .Pp .Fn X509_STORE_CTX_get1_certs and .Fn X509_STORE_CTX_get1_crls first appeared in OpenSSL 1.1.0 and have been available since .Ox 7.4 .