X509_STORE_CTX_SET_FLAGS(3ssl)

📦 version 4.1.0, in opensuse-leap 16.0

💅 X509_STORE_CTX_SET_FLAGS(3) — like, the whole parameter-initialisation situation

okay bestie so this is a page from the Library Functions Manual (yes that one, the OpenSSL section 3ssl girlies) and it's literally all about the eight functions that poke at the X509_VERIFY_PARAM object hanging out inside your X509_STORE_CTX. parameter initialisation, but make it ✨fashion✨.

🌸 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 🦋

okay so all of these functions operate on the X509_VERIFY_PARAM object that ctx is using. the usual order of operations, iykyk: you call X509_STORE_CTX_init(3) on ctx before these, and X509_verify_cert(3) after. main character sequencing, no cap 💅

  • X509_STORE_CTX_set_flags() — sets the internal verification parameter flags to flags. for the whole rundown on what verification flags even mean, go read X509_VERIFY_PARAM_set_flags(3). 🏳️
  • X509_STORE_CTX_set_time() — sets the verification time, using X509_VERIFY_PARAM_set_time(3). the dummy argument is literally ignored, it's just there living its life. 🙈
  • X509_STORE_CTX_set_depth() — sets the maximum verification depth using X509_VERIFY_PARAM_set_depth(3). translation: that's the maximum number of untrusted CA certificates that can appear in a chain. so like, the chain limit. ⛓️
  • X509_STORE_CTX_set_trust() — sets the trust identifier, which you can also set via X509_VERIFY_PARAM_set_trust(3). here's the tea: 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 — nothing happens. no action, no drama. 💀
  • X509_STORE_CTX_set_purpose() — sets the purpose identifier, also settable via X509_VERIFY_PARAM_set_purpose(3). if the purpose argument is 0 or any failure occurs, nothing is changed. respectfully, it stays exactly as it was. 🫶

and now, the terminology moment, pay attention bestie: from here on, the trust identifier contained in the X509_PURPOSE object associated with purpose is called the “associated trust”. iconic name, honestly.

  • 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. two-for-one. 🎀
  • 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. it's taken, sorry. 💅
  • X509_STORE_CTX_get0_param() — retrieves an internal pointer to the verification parameters associated with ctx. just a peek, no take-backs needed. 👀
  • X509_STORE_CTX_set0_param() — sets the internal verification parameter pointer to param. ⚠️ after this call, param should not be used. like, it's been claimed, hands off.
  • X509_STORE_CTX_set_default() — looks up and sets the default verification method to name. it uses X509_VERIFY_PARAM_lookup(3) to find an appropriate set of parameters from name, then copies them with X509_VERIFY_PARAM_inherit(3). cute little inheritance moment. 🧬

🔥 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. and ngl, a return value of 1 does not imply that the trust identifier stored in the X509_VERIFY_PARAM object was actually changed. plot twist. 😭
  • 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. and again — 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 💀

here are the diagnostics you can retrieve 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. they simply don't gossip. 🙈

🌈 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 🎀

a little lore drop for you, bestie — here's the timeline:

  • X509_STORE_CTX_set_depth() first appeared in OpenSSL 0.9.3 and has been available since OpenBSD 2.4. elder. 👑
  • 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 babies of the group. 🍓

⚠️ CAVEATS ⚠️

okay, real talk, this is the part you actually need to internalise:

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). that's genuinely fuzzy territory, not a vibe.

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. do that, bestie. save yourself the confusion. 🫶

💖 and that's the page!! brought to you by Debian, dated August 29, 2024, filed under X509_STORE_CTX_SET_FLAGS(3) in the Library Functions Manual — go forth and initialise those parameters, you absolute icon. periodt. 💅✨🎀

📦 where this page comes from