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_get0_param, X509_STORE_CTX_set0_param, X509_STORE_CTX_set_default — X509_STORE_CTX parameter initialisation

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);

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.

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 invalid but not 0; 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_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 and copies them using X509_VERIFY_PARAM_inherit(3).

RETURN VALUES

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 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 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.

ERRORS

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"

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.

X509_R_UNKNOWN_PURPOSE_ID "unknown purpose id"

The purpose argument is invalid but not 0.

The other functions provide no diagnostics.

SEE ALSO

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)

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() 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.

CAVEATS

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.