X509_LOOKUP_NEW(3) | Library Functions Manual | X509_LOOKUP_NEW(3) |
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
#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, X509_LOOKUP_TYPE 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, X509_LOOKUP_TYPE type,
X509_NAME *name, ASN1_INTEGER
*serial, X509_OBJECT *object);
int
X509_LOOKUP_by_fingerprint
(X509_LOOKUP
*lookup, X509_LOOKUP_TYPE type,
const unsigned char *bytes, int
length, X509_OBJECT *object);
int
X509_LOOKUP_by_alias
(X509_LOOKUP
*lookup, X509_LOOKUP_TYPE 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);
X509_LOOKUP_new
()
allocates a new, empty X509_LOOKUP object and
associates it with the method which is a static object
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_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_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_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.
With LibreSSL,
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.
With LibreSSL,
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_new
() returns the new object
or NULL
if memory allocation fails.
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_LOOKUP_by_subject
() returns 1 for
success or 0 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. With library implementations other than LibreSSL, 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. With LibreSSL, they always return 1.
With LibreSSL,
X509_LOOKUP_by_issuer_serial
(),
X509_LOOKUP_by_fingerprint
(), and
X509_LOOKUP_by_alias
() always return 0.
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".
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
().
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"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"X509_LOOKUP_by_subject
().X509_R_INVALID_DIRECTORY
"invalid directory"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"X509_LOOKUP_ctrl
() or
X509_LOOKUP_by_subject
().ERR_R_PEM_LIB
"PEM lib"X509_LOOKUP_ctrl
().ERR_R_SYS_LIB
"system lib"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.
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)
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.
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.
November 12, 2021 | OpenBSD-current |