NAME

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_purpose_inherit, X509_STORE_CTX_get0_param, X509_STORE_CTX_set0_param, X509_STORE_CTX_set_default —

SYNOPSIS

#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); int
X509_STORE_CTX_purpose_inherit(X509_STORE_CTX *ctx, int def_purpose, int purpose, int trust); 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);

DESCRIPTION

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. X509_STORE_CTX_set_flags() sets the internal verification parameter flags to flags. See X509_VERIFY_PARAM_set_flags(3) for a description of the verification flags. X509_STORE_CTX_set_time() sets the verification time using X509_VERIFY_PARAM_set_time(3). The dummy argument is ignored. X509_STORE_CTX_set_depth() 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. X509_STORE_CTX_set_trust() 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. Here and in the following, X509_TRUST_DEFAULT counts as invalid. X509_STORE_CTX_set_purpose() 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 not 0 but invalid; otherwise, X509_STORE_CTX_set_purpose() 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. X509_STORE_CTX_purpose_inherit() is similar to X509_STORE_CTX_set_purpose(), with the following modifications:

• If the purpose argument is 0, def_purpose is used instead.
• If the associated trust is X509_TRUST_DEFAULT, the trust associated with def_purpose is used instead, or if def_purpose is 0 or invalid, the function fails.
• If the trust argument is not 0, it is used instead of the associated trust, and the equivalent of calling X509_STORE_CTX_set_trust() is done even if both purpose and def_purpose are 0. Even if the trust argument is not 0, if the (then unused) associated trust is X509_TRUST_DEFAULT, def_purpose is still required to be valid.

Note that, even if all arguments are valid and the return value is 1, it is possible that nothing changed, or that only either one of the purpose and trust identifiers were set, or that both were set. It can also happen that the purpose identifier gets set according to the purpose argument, but the trust identifier gets set according to the def_purpose argument in the same call. The intended way of using this function is to pass the purpose and trust attributes of another structure of an arbitrary type as the purpose and trust arguments, and to provide def_purpose as a fallback in case the settings in the other structure are incomplete. X509_STORE_CTX_get0_param() retrieves an internal pointer to the verification parameters associated with ctx. X509_STORE_CTX_set0_param() sets the internal verification parameter pointer to param. After this call param should not be used. X509_STORE_CTX_set_default() 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.

RETURN VALUES

X509_STORE_CTX_set_trust() returns 1 if the trust argument is 0 or valid or 0 if it is not 0 but invalid. A return value of 1 does not 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 not 0 but invalid. A return value of 1 does not imply that any data was changed. X509_STORE_CTX_purpose_inherit() returns 0 if:

• The purpose argument is not 0 and invalid.
• The purpose argument is 0 and the def_purpose argument is not 0 and invalid.
• The associated trust is X509_TRUST_DEFAULT and the def_purpose argument is 0 or invalid, or the trust identifier associated with it is not 0 but invalid.
• The trust argument is not 0 and invalid.
• The trust argument is 0 and the associated trust is neither 0 nor X509_TRUST_DEFAULT but invalid.

Otherwise, X509_STORE_CTX_purpose_inherit() returns 1, which 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.

ERRORS

For X509_STORE_CTX_set_trust(), X509_STORE_CTX_set_purpose(), and X509_STORE_CTX_purpose_inherit(), the following diagnostics can be retrieved with ERR_get_error(3), ERR_GET_REASON(3), and ERR_reason_error_string(3):

X509_R_UNKNOWN_TRUST_ID “unknown trust id”

The trust argument or the trust identifier associated with purpose or def_purpose is not 0 but invalid,

X509_R_UNKNOWN_PURPOSE_ID “unknown purpose id”

The purpose argument is not 0 and invalid. Or it is 0 and the def_purpose argument is not 0 and invalid. Or the associated trust is X509_TRUST_DEFAULT and def_purpose is 0 or invalid.

The other functions provide no diagnostics.

SEE ALSO

X509_STORE_CTX_get_error(3), X509_STORE_CTX_new(3), X509_STORE_new(3), X509_STORE_set1_param(3), X509_verify_cert(3), X509_VERIFY_PARAM_set_flags(3)

HISTORY

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(), X509_STORE_CTX_set_purpose(), and X509_STORE_CTX_purpose_inherit() 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.