X509_LOOKUP_NEW(3) | Library Functions Manual | X509_LOOKUP_NEW(3)

# 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

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

June 8, 2025 | Debian