Manual Page Result
0
Command: X509_VERIFY_PARAM_new | Section: 3 | Source: OpenBSD | File: X509_VERIFY_PARAM_new.3
X509_VERIFY_PARAM_NEW(3) FreeBSD Library Functions Manual
NAME
X509_VERIFY_PARAM_new, X509_VERIFY_PARAM_inherit, X509_VERIFY_PARAM_set1,
X509_VERIFY_PARAM_free, X509_VERIFY_PARAM_add0_table,
X509_VERIFY_PARAM_lookup, X509_VERIFY_PARAM_get_count,
X509_VERIFY_PARAM_get0, X509_VERIFY_PARAM_table_cleanup - X509
verification parameter objects
SYNOPSIS
#include <openssl/x509_vfy.h>
X509_VERIFY_PARAM *
X509_VERIFY_PARAM_new(void);
int
X509_VERIFY_PARAM_inherit(X509_VERIFY_PARAM *destination,
const X509_VERIFY_PARAM *source);
int
X509_VERIFY_PARAM_set1(X509_VERIFY_PARAM *destination,
const X509_VERIFY_PARAM *source);
void
X509_VERIFY_PARAM_free(X509_VERIFY_PARAM *param);
int
X509_VERIFY_PARAM_add0_table(X509_VERIFY_PARAM *param);
const X509_VERIFY_PARAM *
X509_VERIFY_PARAM_lookup(const char *name);
int
X509_VERIFY_PARAM_get_count(void);
const X509_VERIFY_PARAM *
X509_VERIFY_PARAM_get0(int id);
void
X509_VERIFY_PARAM_table_cleanup(void);
DESCRIPTION
X509_VERIFY_PARAM_new() allocates and initializes an empty
X509_VERIFY_PARAM object.
X509_VERIFY_PARAM_inherit() copies some data from the source object to
the destination object.
The verification flags set with X509_VERIFY_PARAM_set_flags(3) in the
source object are always OR'ed into the verification flags of the
destination object.
Fields having their default value in the source object are not copied.
By default, fields in the destination object already having a non-default
value are not overwritten. However, if at least one of the source or
destination objects was created during a call to X509_STORE_CTX_init(3)
that did not have a store argument, and if that object was not previously
used as the destination in an earlier call to
X509_VERIFY_PARAM_inherit(), this restriction is waived and even non-
default fields in the destination object get overwritten. If fields
overwritten in this way contain pointers to allocated memory, that memory
is freed.
As far as permitted by the above rules, the following fields are copied:
o the verification purpose identifier set with
X509_VERIFY_PARAM_set_purpose(3)
o the trust setting set with X509_VERIFY_PARAM_set_trust(3)
o the verification time set with X509_VERIFY_PARAM_set_time(3); in this
case, the only condition is that X509_V_FLAG_USE_CHECK_TIME is not set
in the destination object, whereas the time value in the destination
object is not inspected before overwriting it
o the acceptable policy set with X509_VERIFY_PARAM_set1_policies(3)
o the maximum verification depth set with X509_VERIFY_PARAM_set_depth(3)
o flags that were set with X509_VERIFY_PARAM_set_hostflags(3)
o the list of expected DNS hostnames built with
X509_VERIFY_PARAM_set1_host(3) and X509_VERIFY_PARAM_add1_host(3)
o the expected RFC 822 email address set with
X509_VERIFY_PARAM_set1_email(3)
o the expected IP address set with X509_VERIFY_PARAM_set1_ip(3) or
X509_VERIFY_PARAM_set1_ip_asc(3)
Some data that may be contained in the source object is never copied, for
example the subject name of the peer certificate that can be retrieved
with X509_VERIFY_PARAM_get0_peername(3).
If source is a NULL pointer, the function has no effect but returns
successfully.
X509_VERIFY_PARAM_set1() is identical to X509_VERIFY_PARAM_inherit()
except that fields in the destination object are overwritten even if they
do not match their default values. Still, fields having their default
value in the source object are not copied.
If X509_VERIFY_PARAM_inherit() or X509_VERIFY_PARAM_set1() fail, partial
copying may have occurred, so all data in the destination object should
be regarded as invalid.
X509_VERIFY_PARAM_inherit() is used internally by X509_STORE_CTX_init(3)
and by X509_STORE_CTX_set_default(3), and X509_VERIFY_PARAM_set1() is
used internally by X509_STORE_set1_param(3).
X509_VERIFY_PARAM_free() clears all data contained in param and releases
all memory used by it. If param is a NULL pointer, no action occurs.
X509_VERIFY_PARAM_add0_table() adds param to a static list of
X509_VERIFY_PARAM objects maintained by the library. This function is
extremely dangerous because contrary to the name of the function, if the
list already contains an object that happens to have the same name, that
old object is not only silently removed from the list, but also silently
freed, which may silently invalidate various pointers existing elsewhere
in the program.
X509_VERIFY_PARAM_lookup() searches this list for an object of the given
name. If no match is found, the predefined objects built-in to the
library are also inspected.
X509_VERIFY_PARAM_get_count() returns the sum of the number of objects on
this list and the number of predefined objects built-in to the library.
Note that this is not necessarily the total number of X509_VERIFY_PARAM
objects existing in the program because there may be additional such
objects that were never added to the list.
X509_VERIFY_PARAM_get0() accesses predefined and user-defined objects
using id as an index, useful for looping over objects without knowing
their names. An argument less than the number of predefined objects
selects one of the predefined objects; a higher argument selects an
object from the list.
X509_VERIFY_PARAM_table_cleanup() deletes all objects from this list. It
is extremely dangerous because it also invalidates all data that was
contained in all objects that were on the list and because it frees all
these objects, which may invalidate various pointers existing elsewhere
in the program.
RETURN VALUES
X509_VERIFY_PARAM_new() returns a pointer to the new object, or NULL on
allocation failure.
X509_VERIFY_PARAM_inherit(), X509_VERIFY_PARAM_set1(), and
X509_VERIFY_PARAM_add0_table() return 1 for success or 0 for failure.
X509_VERIFY_PARAM_lookup() and X509_VERIFY_PARAM_get0() return a pointer
to an existing built-in or user-defined object, or NULL if no object with
the given name is found, or if id is at least
X509_VERIFY_PARAM_get_count().
X509_VERIFY_PARAM_get_count() returns a number of objects.
SEE ALSO
SSL_set1_param(3), X509_STORE_CTX_set0_param(3),
X509_STORE_set1_param(3), X509_verify_cert(3),
X509_VERIFY_PARAM_set_flags(3)
HISTORY
X509_VERIFY_PARAM_new(), X509_VERIFY_PARAM_inherit(),
X509_VERIFY_PARAM_set1(), X509_VERIFY_PARAM_free(),
X509_VERIFY_PARAM_add0_table(), X509_VERIFY_PARAM_lookup(), and
X509_VERIFY_PARAM_table_cleanup() first appeared in OpenSSL 0.9.8 and
have been available since OpenBSD 4.5.
X509_VERIFY_PARAM_get_count() and X509_VERIFY_PARAM_get0() first appeared
in OpenSSL 1.0.2 and have been available since OpenBSD 6.3.
FreeBSD 14.1-RELEASE-p8 May 24, 2023 FreeBSD 14.1-RELEASE-p8