X509_STORE_CTX_SET_FLAGS(3) | Library Functions Manual | X509_STORE_CTX_SET_FLAGS(3)

# 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

library “libcrypto”
`#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.

June 8, 2025 | Debian