NAME

X509_LOOKUP_new, X509_LOOKUP_free, X509_LOOKUP_ctrl, X509_LOOKUP_add_dir, X509_LOOKUP_load_file, X509_LOOKUP_add_mem, X509_LOOKUP_by_subject, X509_LOOKUP_init, X509_LOOKUP_shutdown, X509_LOOKUP_by_issuer_serial, X509_LOOKUP_by_fingerprint, X509_LOOKUP_by_alias, 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

#include <openssl/x509_vfy.h>

X509_LOOKUP *
X509_LOOKUP_new(X509_LOOKUP_METHOD *method);

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);

int
X509_LOOKUP_by_subject(X509_LOOKUP *lookup, int type, X509_NAME *name, X509_OBJECT *object);

int
X509_LOOKUP_init(X509_LOOKUP *lookup);

int
X509_LOOKUP_shutdown(X509_LOOKUP *lookup);

int
X509_LOOKUP_by_issuer_serial(X509_LOOKUP *lookup, int type, X509_NAME *name, ASN1_INTEGER *serial, X509_OBJECT *object);

int
X509_LOOKUP_by_fingerprint(X509_LOOKUP *lookup, int type, const unsigned char *bytes, int length, X509_OBJECT *object);

int
X509_LOOKUP_by_alias(X509_LOOKUP *lookup, int type, const char *string, int length, X509_OBJECT *object);

#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_new() allocates a new, empty X509_LOOKUP object and associates it with the method which is a static objects returned from either X509_LOOKUP_hash_dir(3) or X509_LOOKUP_file(3) or X509_LOOKUP_mem(3).

X509_LOOKUP_free() releases the memory used by lookup. 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. They need to be added selectively using X509_LOOKUP_by_subject().

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.

X509_LOOKUP_ctrl() always ignores the ret argument when the built-in X509_LOOKUP_METHOD objects are used.

When using built-in X509_LOOKUP_METHOD objects, X509_LOOKUP_by_subject() is only useful if lookup uses X509_LOOKUP_hash_dir(3). It passes the name to X509_NAME_hash(3) and converts the resulting hash to an eight-digit lower-case hexadecimal number.

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.

Unless an application program manually constructs its own X509_LOOKUP_METHOD object containing its own callback functions, X509_LOOKUP_init(), X509_LOOKUP_shutdown(), X509_LOOKUP_by_issuer_serial(), X509_LOOKUP_by_fingerprint(), and X509_LOOKUP_by_alias() have no effect. X509_LOOKUP_init() is supposed to be called after X509_LOOKUP_new() and before using the lookup object, X509_LOOKUP_shutdown() after using it and before X509_LOOKUP_free().

RETURN VALUES

X509_LOOKUP_new() returns the new object or NULL if memory allocation fails.

X509_LOOKUP_ctrl() returns 1 for success or 0 for failure. If lookup uses a user-defined X509_LOOKUP_METHOD object, it might also return -1 for internal errors.

X509_LOOKUP_by_subject() returns X509_LU_X509 for success or X509_LU_FAIL for failure. In particular, it fails if lookup uses X509_LOOKUP_file(3) or X509_LOOKUP_mem(3), if name is NULL, if type is neither X509_LU_X509 nor X509_LU_CRL, if no match is found, or if memory allocation fails. If lookup uses a user-defined X509_LOOKUP_METHOD object, it might also return negative values for internal errors.

X509_LOOKUP_init() and X509_LOOKUP_shutdown() are supposed to return 1 for success and 0 for failure. When using the built-in X509_LOOKUP_METHOD objects, they always return 1.

X509_LOOKUP_by_issuer_serial(), X509_LOOKUP_by_fingerprint(), and X509_LOOKUP_by_alias() always return X509_LU_FAIL when using the built-in X509_LOOKUP_METHOD objects.

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 in X509_LOOKUP_by_subject().

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 in X509_LOOKUP_ctrl() or X509_LOOKUP_by_subject().

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_LOOKUP_by_subject() was called with an invalid type.

Passing an invalid command to X509_LOOKUP_ctrl() or calling X509_LOOKUP_by_subject() with a NULL name or with arguments that yield no match 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_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.