Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
X509_VERIFY_PARAM_N... FreeBSD Library Functions Manual	X509_VERIFY_PARAM_N...

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 verifica-
     tion 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-de-
     fault fields in the destination object get	overwritten.  If fields	over-
     written 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 set with X509_VERIFY_PARAM_set1_policies(3)

     +o	the maximum verification depth set with	X509_VERIFY_PARAM_set_depth(3)

     +o	the list of expected DNS hostnames built with
	X509_VERIFY_PARAM_set1_host(3) and X509_VERIFY_PARAM_add1_host(3); if
	this list is copied, any flags that were set with
	X509_VERIFY_PARAM_set_hostflags(3) are copied together with the	list,
	without	inspecting any such flags that may already be present in the
	destination object before overwriting them

     +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 suc-
     cessfully.

     X509_VERIFY_PARAM_set1() is identical to X509_VERIFY_PARAM_inherit() ex-
     cept 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 li-
     brary 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 ob-
     jects that	were never added to the	list.

     X509_VERIFY_PARAM_get0() accesses predefined and user-defined objects us-
     ing 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 con-
     tained 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	13.0		       November	13, 2021		  FreeBSD 13.0

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | SEE ALSO | HISTORY

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=X509_VERIFY_PARAM_inherit&sektion=3&manpath=FreeBSD+13.1-RELEASE+and+Ports>

home | help