---
name: "libressl-X509_STORE_get_by_subject"
section: "3"
platform: "linux"
package: "libressl"
version: "4.4.0-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/libressl-X509_STORE_get_by_subject"
---

# libressl-X509\_STORE\_get\_by\_subject(3)

retrieve objects from a certificate store

## 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

Crypto Library (libcrypto, -lcrypto)

**#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.