man.bsd.lv manual page server

DESCRIPTION

X509_STORE_CTX_new() allocates an empty X509_STORE_CTX object not yet containing the subobjects required for normal operation.

X509_STORE_CTX_init() needs to be called on each new ctx before any of the other functions become useful. It prepares ctx for one single verification operation using X509_verify_cert(3). The trusted certificate store to be used, the end entity certificate x to be verified, and a set of additional untrusted certificates, to be used for building the chain, can be supplied, or any or all of them can be set to NULL. The three pointers passed in are stored internally, the three objects pointed to are not copied, their reference count is not incremented, and the caller remains responsible for managing their storage and for not freeing them before X509_STORE_CTX_free() is called on ctx.

X509_STORE_CTX_cleanup() internally cleans up ctx, returning it to an empty state similar to the one after X509_STORE_CTX_new(). It can then be reused with a new call to X509_STORE_CTX_init().

X509_STORE_CTX_free() calls X509_STORE_CTX_cleanup() and frees the storage pointed to by ctx. If ctx is a NULL pointer, no action occurs.

X509_STORE_CTX_get0_store() returns the internal pointer to the trusted certificate store that was set with X509_STORE_CTX_init().

X509_STORE_CTX_set0_trusted_stack() sets the set of trusted certificates used by ctx. This is an alternative way of specifying trusted certificates instead of using the store. X509_STORE_CTX_trusted_stack() is a deprecated alias for X509_STORE_CTX_set0_trusted_stack().

X509_STORE_CTX_set_cert() sets the certificate to be verified in ctx to x, overriding the certificate that was set with X509_STORE_CTX_init(). Again, the certificate is not copied and its reference count is not incremented.

X509_STORE_CTX_get0_cert() retrieves the internal pointer to the certificate being verified by ctx, i.e. the last one set using either X509_STORE_CTX_init() or X509_STORE_CTX_set_cert().

X509_STORE_CTX_set_chain() and X509_STORE_CTX_set0_untrusted() are identical and set the additional, untrusted certificates used by ctx, overriding the set of additional, untrusted certificates that was set with X509_STORE_CTX_init(). Again, the set and the certificates contained in it are not copied and their reference counts are not incremented.

X509_STORE_CTX_get0_untrusted() retrieves the internal pointer to the set of additional, untrusted certificates associated with ctx, i.e. the last one set using either X509_STORE_CTX_init(), X509_STORE_CTX_set_chain(), or X509_STORE_CTX_set0_untrusted().

X509_STORE_CTX_set0_crls() sets a set of crls to use during certificate verification. These CRLs will only be used if CRL verification is enabled in the associated X509_VERIFY_PARAM structure. This might be used where additional "useful" CRLs are supplied as part of a protocol, for example in a PKCS#7 structure.

Legacy applications might implicitly use an X509_STORE_CTX like this:

X509_STORE_CTX ctx;
X509_STORE_CTX_init(&ctx, store, cert, chain);

This is not recommended in new applications. They should instead do:

X509_STORE_CTX *ctx;
ctx = X509_STORE_CTX_new();
if (ctx == NULL)
	/* Bad error */
X509_STORE_CTX_init(ctx, store, cert, chain);