X509_VERIFY(3)

🌸 NAME 🌸

This is the X509_VERIFY(3) library functions manual page, bestie 💖. The whole function squad is x509_verify, x509_verify_ctx_new, x509_verify_ctx_free, x509_verify_ctx_set_max_depth, x509_verify_ctx_set_max_signatures, x509_verify_ctx_set_max_chains, x509_verify_ctx_set_purpose, x509_verify_ctx_set_intermediates, x509_verify_ctx_error_string, x509_verify_ctx_error_depth, and x509_verify_ctx_chain — and their whole mission is to discover and verify X.509 certificate chains. Slay ✨.

---

✨ SYNOPSIS ✨

#include <openssl/x509_verify.h>

size_t
x509_verify(X509_VERIFY_CTX *ctx, X509 *leaf, char *name);

X509_VERIFY_CTX *
x509_verify_ctx_new(STACK_OF(X509) *roots);

void
x509_verify_ctx_free(X509_VERIFY_CTX *ctx);

int
x509_verify_ctx_set_max_depth(X509_VERIFY_CTX *ctx, size_t max);

int
x509_verify_ctx_set_max_signatures(X509_VERIFY_CTX *ctx, size_t max);

int
x509_verify_ctx_set_max_chains(X509_VERIFY_CTX *ctx, size_t max);

int
x509_verify_ctx_set_purpose(X509_VERIFY_CTX *ctx, int purpose_id);

int
x509_verify_ctx_set_intermediates(X509_VERIFY_CTX *ctx,
    STACK_OF(X509) *intermediates);

const char *
x509_verify_ctx_error_string(X509_VERIFY_CTX *ctx);

size_t
x509_verify_ctx_error_depth(X509_VERIFY_CTX *ctx);

STACK_OF(X509) *
x509_verify_ctx_chain(X509_VERIFY_CTX *ctx, size_t index);

---

💖 DESCRIPTION 💖

okay so x509_verify() is literally the main character here: it attempts to discover and validate all certificate chains for the name from the leaf certificate based on the parameters in ctx. Multiple chains may be built and validated — it’s giving overachiever energy 🔥.

Important caveat, no cap: revocation checking is not done by this function, and should be performed by the caller on any returned chains if so desired. iykyk 😭.

• x509_verify_ctx_new() — allocates a new context using the trusted roots. In case of success, it increments the reference count of roots. 🫶
• x509_verify_ctx_free() — frees ctx and decrements the reference count of the roots and intermediates associated with it. If ctx is NULL, no action occurs. 💅
• x509_verify_ctx_set_max_depth() — sets the maximum depth of certificate chains that will be constructed to max, which can be in the range from 1 to the default of 32. 🌱
• x509_verify_ctx_set_max_signatures() — sets the maximum number of public key signature operations that will be used when verifying certificate chains to max, which can be in the range from 1 to 100000. The default is 256. ✨
• x509_verify_ctx_set_max_chains() — sets the maximum number of chains which may be returned to max, which can be in the range from 1 to the default of 8. 🎀
• x509_verify_ctx_set_purpose() — sets the certificate purpose for validation to purpose_id. The X509_PURPOSE_* constants listed in X509_check_purpose(3) can be used. 👑
• x509_verify_ctx_set_intermediates() — provides some intermediate certificates, typically received from the peer, to be used for building chains. In case of success, this function increases the reference count of intermediates. 🦋
• x509_verify_ctx_error_string() — extracts a description of the last error encountered by a previous call to x509_verify() from ctx. 😭
• x509_verify_ctx_error_depth() — extracts the depth of the last error encountered by a previous call to x509_verify() from ctx. 💀
• x509_verify_ctx_chain() — extracts the validated chain with the given index from ctx after a previous call to x509_verify(). The index starts at 0, and it is an error to pass a number greater than or equal to the return value of x509_verify(). The returned chain is neither copied, nor is its reference count increased. 🧚

---

🦋 RETURN VALUES 🦋

• x509_verify() returns the number of chains successfully built and validated or 0 on failure. 💖
• x509_verify_ctx_new() returns a newly allocated context or NULL on failure. 🌸
• x509_verify_ctx_set_max_depth(), x509_verify_ctx_set_max_signatures(), x509_verify_ctx_set_max_chains(), x509_verify_ctx_set_purpose(), and x509_verify_ctx_set_intermediates() return 1 on success or 0 on failure. ✅
• x509_verify_ctx_error_string() returns a pointer to a human readable error string. If no error occurred, "ok" is returned. 🫶
• x509_verify_ctx_chain() returns an internal pointer to a validated chain or NULL if index is greater than or equal to the number of chains that were successfully built and validated. The returned pointer becomes invalid when ctx is destroyed. ⭐

---

👑 SEE ALSO 👑

X509_verify_cert(3) 🌈

---

🌈 HISTORY 🌈

These functions first appeared in OpenBSD 6.8. 🎀

---

🎀 AUTHORS 🎀

Bob Beck <beck@openbsd.org> 💜

---

💅 cute little sign-off bestie: this X509_VERIFY(3) page is from Debian, dated September 14, 2020. go verify those chains and slay ✨🫶