X509_STORE_CTX_NEW(3)

📦 version 4.1.0, in opensuse-leap 16.0

💅 X509_STORE_CTX_NEW — like, the whole X509_STORE_CTX glow-up page

okay bestie so this is from the X509_STORE_CTX_NEW(3) manual page, and it's literally all about setting up your X509_STORE_CTX object so it can ✨slay✨ during certificate verification. No cap, it's giving "prep work before the main character moment."

✨ NAME ✨

X509_STORE_CTX_new, X509_STORE_CTX_init, X509_STORE_CTX_cleanup, X509_STORE_CTX_free, X509_STORE_CTX_get0_store, X509_STORE_CTX_set0_trusted_stack, X509_STORE_CTX_trusted_stack, X509_STORE_CTX_set_cert, X509_STORE_CTX_get0_cert, X509_STORE_CTX_set_chain, X509_STORE_CTX_set0_untrusted, X509_STORE_CTX_get0_untrusted, X509_STORE_CTX_set0_crls — X509_STORE_CTX initialisation 🎀

🌸 SYNOPSIS 🌸

#include <openssl/x509_vfy.h>

X509_STORE_CTX *
X509_STORE_CTX_new(void);

int
X509_STORE_CTX_init(X509_STORE_CTX *ctx, X509_STORE *store, X509 *x,
    STACK_OF(X509) *untrusted);

void
X509_STORE_CTX_cleanup(X509_STORE_CTX *ctx);

void
X509_STORE_CTX_free(X509_STORE_CTX *ctx);

X509_STORE *
X509_STORE_CTX_get0_store(X509_STORE_CTX *ctx);

void
X509_STORE_CTX_set0_trusted_stack(X509_STORE_CTX *ctx,
    STACK_OF(X509) *trusted);

void
X509_STORE_CTX_trusted_stack(X509_STORE_CTX *ctx,
    STACK_OF(X509) *trusted);

void
X509_STORE_CTX_set_cert(X509_STORE_CTX *ctx, X509 *x);

X509 *
X509_STORE_CTX_get0_cert(X509_STORE_CTX *ctx);

void
X509_STORE_CTX_set_chain(X509_STORE_CTX *ctx,
    STACK_OF(X509) *untrusted);

void
X509_STORE_CTX_set0_untrusted(X509_STORE_CTX *ctx,
    STACK_OF(X509) *untrusted);

STACK_OF(X509) *
X509_STORE_CTX_get0_untrusted(X509_STORE_CTX *ctx);

void
X509_STORE_CTX_set0_crls(X509_STORE_CTX *ctx, STACK_OF(X509_CRL) *crls);

🦋 DESCRIPTION 🦋

So these functions are all about getting an X509_STORE_CTX object ready for its big moment — which is being used by X509_verify_cert(3) later. Think of it as the pre-game, the getting-ready-with-me segment. 💖

X509_STORE_CTX_new() allocates an empty X509_STORE_CTX object. And when I say empty, I mean empty — it does not yet contain the subobjects it needs for normal operation. It's a blank canvas, an unbothered icon with nothing in it yet. 🫶

X509_STORE_CTX_init() has to be called on each new ctx before any of the other functions become useful — like, none of them. It prepares ctx for one single verification operation using X509_verify_cert(3). You can supply the trusted certificate store to be used, the end entity certificate x to be verified, and a set of additional untrusted certificates (used for building the chain) — or any or all of them can be NULL. Your call, bestie. 💅

⚠️ Important vibe check: the three pointers you pass in are stored internally, but the three objects pointed to are not copied, and their reference count is not incremented. The caller remains responsible for managing their storage and for not freeing them before X509_STORE_CTX_free() is called on ctx. 😭 Do not free them early, I'm begging.

If a store is provided, the verification parameters contained in it are copied using X509_VERIFY_PARAM_inherit(3). Cute, inheritance.

X509_STORE_CTX_cleanup() internally cleans up ctx, returning it to an empty state similar to the one after X509_STORE_CTX_new(). Then you can reuse it with a new call to X509_STORE_CTX_init(). Recycle, reuse, iconic. 🌈

X509_STORE_CTX_free() calls X509_STORE_CTX_cleanup() and frees the storage pointed to by ctx. And if ctx is a NULL pointer? No action occurs. Nothing happens. It simply does not engage. 💀

X509_STORE_CTX_get0_store() returns the internal pointer to the trusted certificate store that was set with X509_STORE_CTX_init().

X509_STORE_CTX_set0_trusted_stack() sets the set of trusted certificates used by ctx. This is an alternative way of specifying trusted certificates instead of using the store. And X509_STORE_CTX_trusted_stack() is a deprecated alias for X509_STORE_CTX_set0_trusted_stack(). Yes, deprecated — it's giving legacy, use the set0_ one. 🎀

X509_STORE_CTX_set_cert() sets the certificate to be verified in ctx to x, overriding the certificate that was set with X509_STORE_CTX_init(). Again — the certificate is not copied and its reference count is not incremented. Same rule as before, bestie, don't free it early. 🙈

X509_STORE_CTX_get0_cert() retrieves the internal pointer to the certificate being verified by ctx — i.e. the last one set using either X509_STORE_CTX_init() or X509_STORE_CTX_set_cert(). Last one wins, periodt.

X509_STORE_CTX_set_chain() and X509_STORE_CTX_set0_untrusted() are identical and set the additional, untrusted certificates used by ctx, overriding the set of additional, untrusted certificates that was set with X509_STORE_CTX_init(). And again (say it with me 🗣️): the set and the certificates contained in it are not copied and their reference counts are not incremented.

X509_STORE_CTX_get0_untrusted() retrieves the internal pointer to the set of additional, untrusted certificates associated with ctx — i.e. the last one set using either X509_STORE_CTX_init(), X509_STORE_CTX_set_chain(), or X509_STORE_CTX_set0_untrusted().

X509_STORE_CTX_set0_crls() sets a set of crls to use during certificate verification. Heads up though — these CRLs will only be used if CRL verification is enabled in the associated X509_VERIFY_PARAM structure. This might be used where additional "useful" CRLs are supplied as part of a protocol, for example in a PKCS#7 structure. ✨

🧚 the legacy situation (iykyk)

Legacy applications might implicitly use an X509_STORE_CTX like this:

X509_STORE_CTX ctx;
X509_STORE_CTX_init(&ctx, store, cert, chain);

This is not recommended in new applications. They should instead do:

X509_STORE_CTX *ctx;
ctx = X509_STORE_CTX_new();
if (ctx == NULL)
        /* Bad error */
X509_STORE_CTX_init(ctx, store, cert, chain);

Like, please check for NULL. Be responsible. 🫶

👑 RETURN VALUES 👑

  • X509_STORE_CTX_new() — returns a newly allocated context, or NULL if an error occurred. 😭
  • X509_STORE_CTX_init() — returns 1 for success or 0 if an error occurred.
  • X509_STORE_CTX_get0_store() — returns the internal pointer to the trusted certificate store, or NULL if none was set.
  • X509_STORE_CTX_get0_cert() — returns the internal pointer to the certificate to be verified, or NULL if no such certificate was set.
  • X509_STORE_CTX_get0_untrusted() — returns the internal pointer to the set of additional, untrusted certificates, or NULL if no set of additional certificates was provided.

⭐ SEE ALSO ⭐

X509_CRL_new(3), X509_STORE_CTX_get_error(3), X509_STORE_CTX_get_ex_new_index(3), X509_STORE_CTX_set_flags(3), X509_STORE_CTX_set_verify(3), X509_STORE_CTX_set_verify_cb(3), X509_STORE_get_by_subject(3), X509_STORE_new(3), X509_STORE_set1_param(3), X509_STORE_set_verify_cb(3), X509_verify_cert(3), X509_VERIFY_PARAM_inherit(3), X509_VERIFY_PARAM_set_flags(3)

Like, go read them. Networking but for manpages. 💜

🌈 HISTORY 🌈

The lore, bestie:

  • X509_STORE_CTX_init(), X509_STORE_CTX_cleanup(), X509_STORE_CTX_set_cert(), and X509_STORE_CTX_set_chain() first appeared in SSLeay 0.8.0 and have been available since OpenBSD 2.4. Ancient. Elders. Respected. 🕯️
  • X509_STORE_CTX_new() and X509_STORE_CTX_free() first appeared in OpenSSL 0.9.5 and have been available since OpenBSD 2.7.
  • X509_STORE_CTX_trusted_stack() first appeared in OpenSSL 0.9.6 and has been available since OpenBSD 2.9.
  • X509_STORE_CTX_get0_store() first appeared in OpenSSL 1.0.2.
  • X509_STORE_CTX_set0_trusted_stack(), X509_STORE_CTX_get0_cert(), X509_STORE_CTX_set0_untrusted(), and X509_STORE_CTX_get0_untrusted() first appeared in OpenSSL 1.1.0. These functions have been available since OpenBSD 6.3.

okay that's the whole page, go forth and verify some certs responsibly 💅✨ this little beauty is from the Debian crew, dated November 16, 2022 — mwah, kisses to the maintainers, this page ate and left no crumbs 🎀🫶

📦 where this page comes from