OpenBSD manual page server

Manual Page Search Parameters
X509_STORE_CTX_SET_FLAGS(3) Library Functions Manual X509_STORE_CTX_SET_FLAGS(3)

X509_STORE_CTX_set_flags, X509_STORE_CTX_set_time, X509_STORE_CTX_set_depth, X509_STORE_CTX_set_trust, X509_STORE_CTX_set_purpose, X509_STORE_CTX_get0_param, X509_STORE_CTX_set0_param, X509_STORE_CTX_set_default — X509_STORE_CTX parameter initialisation

#include <openssl/x509_vfy.h>

void
X509_STORE_CTX_set_flags(X509_STORE_CTX *ctx, unsigned long flags);

void
X509_STORE_CTX_set_time(X509_STORE_CTX *ctx, unsigned long dummy, time_t time);

void
X509_STORE_CTX_set_depth(X509_STORE_CTX *ctx, int depth);

int
X509_STORE_CTX_set_trust(X509_STORE_CTX *ctx, int trust);

int
X509_STORE_CTX_set_purpose(X509_STORE_CTX *ctx, int purpose);

X509_VERIFY_PARAM *
X509_STORE_CTX_get0_param(X509_STORE_CTX *ctx);

void
X509_STORE_CTX_set0_param(X509_STORE_CTX *ctx, X509_VERIFY_PARAM *param);

int
X509_STORE_CTX_set_default(X509_STORE_CTX *ctx, const char *name);

These functions operate on the X509_VERIFY_PARAM object used by ctx. Usually, X509_STORE_CTX_init(3) is called on ctx before these functions, and X509_verify_cert(3) afterwards.

() sets the internal verification parameter flags to flags. See X509_VERIFY_PARAM_set_flags(3) for a description of the verification flags.

() sets the verification time using X509_VERIFY_PARAM_set_time(3). The dummy argument is ignored.

() sets the maximum verification depth using X509_VERIFY_PARAM_set_depth(3). That is the maximum number of untrusted CA certificates that can appear in a chain.

() sets the trust identifier that can also be set using X509_VERIFY_PARAM_set_trust(3). If the trust argument is 0 or invalid or the trust identifier is already set to a non-zero value in the X509_VERIFY_PARAM object, no action occurs.

() sets the purpose identifier that can also be set using X509_VERIFY_PARAM_set_purpose(3). If the purpose argument is 0 or any failure occurs, nothing is changed.

In the following, the trust identifier contained in the X509_PURPOSE object associated with purpose is called the “associated trust”.

The function fails if the purpose argument or the associated trust is invalid but not 0; otherwise, () also does the equivalent of calling X509_STORE_CTX_set_trust() with the associated trust.

If the purpose identifier is already set to a non-zero value in the X509_VERIFY_PARAM object, it is not changed, even if the purpose argument is valid, too.

() retrieves an internal pointer to the verification parameters associated with ctx.

() sets the internal verification parameter pointer to param. After this call param should not be used.

() looks up and sets the default verification method to name. This uses the function X509_VERIFY_PARAM_lookup(3) to find an appropriate set of parameters from name and copies them using X509_VERIFY_PARAM_inherit(3).

X509_STORE_CTX_set_trust() returns 1 if the trust argument is 0 or valid or 0 if it is invalid but not 0. A return value of 1 does imply that the trust identifier stored in the X509_VERIFY_PARAM object was changed.

X509_STORE_CTX_set_purpose() returns 1 if both the purpose argument and the associated trust are 0 or valid. It returns 0 if either the purpose argument or the associated trust is invalid but not 0. A return value of 1 does not imply that any data was changed.

X509_STORE_CTX_get0_param() returns a pointer to an X509_VERIFY_PARAM structure or NULL if an error occurred.

X509_STORE_CTX_set_default() returns 1 for success or 0 if an error occurred.

The following diagnostics can be retrieved with ERR_get_error(3), ERR_GET_REASON(3), and ERR_reason_error_string(3):

"unknown trust id"
X509_STORE_CTX_set_trust() was called with a trust argument that is invalid but not 0. Other implementations may also return this when X509_STORE_CTX_set_purpose() is called with a purpose argument with invalid associated trust.
"unknown purpose id"
The purpose argument is invalid but not 0.

The other functions provide no diagnostics.

X509_STORE_CTX_get_error(3), X509_STORE_CTX_new(3), X509_STORE_CTX_set_verify(3), X509_STORE_CTX_set_verify_cb(3), X509_STORE_new(3), X509_STORE_set1_param(3), X509_STORE_set_verify_cb(3), X509_verify_cert(3), X509_VERIFY_PARAM_new(3), X509_VERIFY_PARAM_set_flags(3)

X509_STORE_CTX_set_depth() first appeared in OpenSSL 0.9.3 and has been available since OpenBSD 2.4.

X509_STORE_CTX_set_trust() and X509_STORE_CTX_set_purpose() first appeared in OpenSSL 0.9.5 and have been available since OpenBSD 2.7.

X509_STORE_CTX_set_flags() and X509_STORE_CTX_set_time() first appeared in OpenSSL 0.9.6 and have been available since OpenBSD 2.9.

X509_STORE_CTX_get0_param(), X509_STORE_CTX_set0_param(), and X509_STORE_CTX_set_default() first appeared in OpenSSL 0.9.8 and have been available since OpenBSD 4.5.

The precise effect of a successful call to X509_STORE_CTX_set_trust() and X509_STORE_CTX_set_purpose() is unclear unless only one of these functions is used immediately after X509_STORE_CTX_init(3). It is therefore recommended to use X509_STORE_CTX_get0_param(), X509_VERIFY_PARAM_set_trust(3), and X509_VERIFY_PARAM_set_purpose(3) instead.

The confusingly named X509_TRUST_DEFAULT is less than X509_TRUST_MIN and different implementations treat it as valid or invalid when used as an associated trust or as a trust argument for X509_STORE_CTX_set_trust().

January 12, 2024 OpenBSD-7.5