---
name: "libressl-X509_LOOKUP_new"
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_LOOKUP_new"
---

# libressl-X509\_LOOKUP\_new(3)

certificate lookup object

## NAME

**X509\_LOOKUP\_free**, **X509\_LOOKUP\_ctrl**, **X509\_LOOKUP\_add\_dir**, **X509\_LOOKUP\_load\_file**, **X509\_LOOKUP\_add\_mem**, **X509\_get\_default\_cert\_dir**, **X509\_get\_default\_cert\_file**, **X509\_get\_default\_cert\_dir\_env**, **X509\_get\_default\_cert\_file\_env** – certificate lookup object

## SYNOPSIS

Crypto Library (libcrypto, -lcrypto)

**#include \<openssl/x509\_vfy.h\>**

*void*\

**X509\_LOOKUP\_free**(*X509\_LOOKUP \*lookup*);

*int*\

**X509\_LOOKUP\_ctrl**(*X509\_LOOKUP \*lookup*, *int command*, *const char \*source*, *long type*, *char \*\*ret*);

*int*\

**X509\_LOOKUP\_add\_dir**(*X509\_LOOKUP \*lookup*, *const char \*source*, *long type*);

*int*\

**X509\_LOOKUP\_load\_file**(*X509\_LOOKUP \*lookup*, *const char \*source*, *long type*);

*int*\

**X509\_LOOKUP\_add\_mem**(*X509\_LOOKUP \*lookup*, *const struct iovec \*source*, *long type*);

**#include \<openssl/x509.h\>**

*const* *char* *\**\

**X509\_get\_default\_cert\_dir**(*void*);

*const* *char* *\**\

**X509\_get\_default\_cert\_file**(*void*);

*const* *char* *\**\

**X509\_get\_default\_cert\_dir\_env**(*void*);

*const* *char* *\**\

**X509\_get\_default\_cert\_file\_env**(*void*);

## DESCRIPTION

**X509\_LOOKUP\_free**() is a deprecated function that releases the memory used by *lookup*. It is provided for compatibility only. If *lookup* is a NULL pointer, no action occurs.

The operation of **X509\_LOOKUP\_ctrl**() depends on the *X509\_LOOKUP\_METHOD* used by *lookup*:

- X509\_LOOKUP\_hash\_dir(3)

  The *command* is required to be X509\_L\_ADD\_DIR and the *source* argument is interpreted as a colon-separated, NUL-terminated list of directory names. These directories are added to an internal list of directories to search for certificate files of the given *type*.

  If *type* is X509\_FILETYPE\_DEFAULT, the *source* argument is ignored and */etc/ssl/certs* and a type of X509\_FILETYPE\_PEM are used instead.

  **X509\_LOOKUP\_add\_dir**() is a macro that calls **X509\_LOOKUP\_ctrl**() with a *command* of X509\_L\_ADD\_DIR and *ret* set to NULL.

  This lookup method is peculiar in so far as calling **X509\_LOOKUP\_ctrl**() on a lookup object using it does not yet add any certificates to the associated *X509\_STORE* object.

- X509\_LOOKUP\_file(3)

  The *command* is required to be X509\_L\_FILE\_LOAD and the *source* argument is interpreted as a NUL-terminated file name. If the *type* is X509\_FILETYPE\_PEM, the file is read with BIO\_new\_file(3) and PEM\_X509\_INFO\_read\_bio(3) and the certificates and revocation lists found are added to the *X509\_STORE* object associated with *lookup* using X509\_STORE\_add\_cert(3) and X509\_STORE\_add\_crl(3). If *type* is X509\_FILETYPE\_DEFAULT, the *source* argument is ignored and */etc/ssl/certs.pem* and a type of X509\_FILETYPE\_PEM are used instead. If *type* is X509\_FILETYPE\_ASN1, the file is read with d2i\_X509\_bio(3) and the single certificate is added to the *X509\_STORE* object associated with *lookup* using X509\_STORE\_add\_cert(3).

  **X509\_LOOKUP\_load\_file**() is a macro calling **X509\_LOOKUP\_ctrl**() with a *command* of X509\_L\_FILE\_LOAD and *ret* set to NULL.

- X509\_LOOKUP\_mem(3)

  The *command* and *type* are required to be X509\_L\_MEM and X509\_FILETYPE\_PEM, respectively. The *source* argument is interpreted as a pointer to an *iovec* structure defined in ⟨sys/uio.h⟩. The memory area described by that structure is read with BIO\_new\_mem\_buf(3) and PEM\_X509\_INFO\_read\_bio(3) and the certificates and revocation lists found are added to the *X509\_STORE* object associated with *lookup* using X509\_STORE\_add\_cert(3) and X509\_STORE\_add\_crl(3).

  **X509\_LOOKUP\_add\_mem**() is a macro calling **X509\_LOOKUP\_ctrl**() with a command of X509\_L\_MEM and *ret* set to NULL.

With LibreSSL, **X509\_LOOKUP\_ctrl**() always ignores the *ret* argument.

If the *type* is X509\_LU\_X509, it searches the configured directories for files having that name, with a file name extension that is a small, non-negative decimal integer starting at ".0". These files are read with X509\_load\_cert\_file(3). In each directory, the search is ended once a file with the expected name and extension does not exists.

If the *type* is X509\_LU\_CRL, the file name extensions are expected to have a prefix of "r", i.e. they start with ".r0", and the files are read with X509\_load\_crl\_file(3).

In case of success, the first match is returned in the \**object* provided by the caller, overwriting any previous content.

## RETURN VALUES

**X509\_LOOKUP\_ctrl**() returns 1 for success or 0 for failure. With library implementations other than LibreSSL, it might also return -1 for internal errors.

**X509\_get\_default\_cert\_dir**() returns a pointer to the constant string "/etc/ssl/certs", **X509\_get\_default\_cert\_file**() to "/etc/ssl/certs.pem", **X509\_get\_default\_cert\_dir\_env**() to "SSL\_CERT\_DIR", and **X509\_get\_default\_cert\_file\_env**() to "SSL\_CERT\_FILE".

## ENVIRONMENT

For reasons of security and simplicity, LibreSSL ignores the environment variables SSL\_CERT\_DIR and SSL\_CERT\_FILE, but other library implementations may use their contents instead of the standard locations for trusted certificates, and a few third-party application programs also inspect these variables directly and may pass their values to **X509\_LOOKUP\_add\_dir**() and **X509\_LOOKUP\_load\_file**().

## FILES

- */etc/ssl/certs/*

  default directory for storing trusted certificates

- */etc/ssl/certs.pem*

  default file for storing trusted certificates

## ERRORS

The following diagnostics can be retrieved with ERR\_get\_error(3), ERR\_GET\_REASON(3), and ERR\_reason\_error\_string(3):

- ERR\_R\_ASN1\_LIB "ASN1 lib"

  d2i\_X509\_bio(3) failed in **X509\_LOOKUP\_ctrl**().

- X509\_R\_BAD\_X509\_FILETYPE "bad x509 filetype"

  **X509\_LOOKUP\_ctrl**() was called with an invalid *type*.

- ERR\_R\_BUF\_LIB "BUF lib"

  Memory allocation failed.

- X509\_R\_INVALID\_DIRECTORY "invalid directory"

  The *source* argument of **X509\_LOOKUP\_ctrl**() with X509\_L\_ADD\_DIR or **X509\_LOOKUP\_add\_dir**() was NULL or an empty string.

- X509\_R\_LOADING\_CERT\_DIR "loading cert dir"

  **X509\_LOOKUP\_ctrl**() with X509\_L\_ADD\_DIR or **X509\_LOOKUP\_add\_dir**() was called with X509\_FILETYPE\_DEFAULT and adding the default directories failed. This error is added after and in addition to a more specific diagnostic.

- X509\_R\_LOADING\_DEFAULTS "loading defaults"

  **X509\_LOOKUP\_ctrl**() with X509\_L\_FILE\_LOAD or **X509\_LOOKUP\_load\_file**() was called with X509\_FILETYPE\_DEFAULT and adding the certificates and revocation lists failed. This error is added after and in addition to a more specific diagnostic.

- ERR\_R\_MALLOC\_FAILURE "malloc failure"

  Memory allocation failed.

- ERR\_R\_PEM\_LIB "PEM lib"

  PEM\_X509\_INFO\_read\_bio(3), PEM\_read\_bio\_X509\_AUX(3), or PEM\_read\_bio\_X509\_CRL(3) failed in **X509\_LOOKUP\_ctrl**().

- ERR\_R\_SYS\_LIB "system lib"

  BIO\_new(3), BIO\_new\_file(3), or BIO\_read\_filename(3) failed in **X509\_LOOKUP\_ctrl**().

- X509\_R\_WRONG\_LOOKUP\_TYPE "wrong lookup type"

  X509\_STORE\_CTX\_get\_by\_subject(3) was called with an invalid *type*.

Passing an invalid *command* to **X509\_LOOKUP\_ctrl**() causes failure but provides no diagnostics.

## SEE ALSO

d2i\_X509\_bio(3), PEM\_read\_bio\_X509\_AUX(3), PEM\_X509\_INFO\_read\_bio(3), X509\_load\_cert\_file(3), X509\_LOOKUP\_hash\_dir(3), X509\_NAME\_hash(3), X509\_NAME\_new(3), X509\_new(3), X509\_OBJECT\_get\_type(3), X509\_STORE\_add\_cert(3), X509\_STORE\_get\_by\_subject(3)

## HISTORY

**X509\_get\_default\_cert\_dir**(), **X509\_get\_default\_cert\_file**(), **X509\_get\_default\_cert\_dir\_env**(), and **X509\_get\_default\_cert\_file\_env**() first appeared in SSLeay 0.4.1 and have been available since OpenBSD 2.4.

**X509\_LOOKUP\_add\_mem**() first appeared in OpenBSD 5.7.

The other functions first appeared in SSLeay 0.8.0 and have been available since OpenBSD 2.4.

## BUGS

If the *type* is X509\_FILETYPE\_DEFAULT or X509\_FILETYPE\_PEM, **X509\_LOOKUP\_ctrl**() with X509\_L\_FILE\_LOAD and **X509\_LOOKUP\_load\_file**() silently ignore failure of X509\_STORE\_add\_cert(3) and X509\_STORE\_add\_crl(3) and indicate success anyway.

Handling of a NULL *source* is inconsistent for **X509\_LOOKUP\_ctrl**() with X509\_L\_FILE\_LOAD and for **X509\_LOOKUP\_load\_file**(). With X509\_FILETYPE\_PEM, it causes failure, but with X509\_FILETYPE\_ASN1, no action occurs and success is indicated.

When called on a *lookup* object using X509\_LOOKUP\_mem(3), **X509\_LOOKUP\_ctrl**() raises ERR\_R\_PEM\_LIB when called with an invalid *command* or *type*, when BIO\_new\_mem\_buf(3) fails, when *source* contains zero objects, or when X509\_STORE\_add\_cert(3) fails on the first object encountered, which is all inconsistent with the behaviour of the other lookup methods.