X509_STORE_GET_BY_SUBJECT(3) | Library Functions Manual | X509_STORE_GET_BY_SUBJECT(3)

# 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

library “libcrypto”
`#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.

June 8, 2025 | Debian