SSL_CTX_SET1...Y_CERT_STORE(3ossl)

📦
version 15.1 · 2 versions
, in freebsd 15.1

👑 SSL_CTX_SET1...Y_CERT_STORE(3ossl) — like, the whole set0/set1 get0 cert-store situation 💅

okay bestie, this is an OpenSSL manual page (the 3ossl girlies) and it's literally all about setting the certificate verification store or the chain store. Yes, both. Iconic behaviour.

✨ NAME ✨

So the full cast, in order, no one gets left out:

  • SSL_CTX_set0_verify_cert_store
  • SSL_CTX_set1_verify_cert_store
  • SSL_CTX_set0_chain_cert_store
  • SSL_CTX_set1_chain_cert_store
  • SSL_set0_verify_cert_store
  • SSL_set1_verify_cert_store
  • SSL_set0_chain_cert_store
  • SSL_set1_chain_cert_store
  • SSL_CTX_get0_verify_cert_store
  • SSL_CTX_get0_chain_cert_store
  • SSL_get0_verify_cert_store
  • SSL_get0_chain_cert_store

and collectively they do exactly one (1) thing: set certificate verification or chain store. main character energy fr fr 🌟

🌈 SYNOPSIS 🌈

okay so first you gotta bring in the header, obviously:

#include <openssl/ssl.h>

then the SSL_CTX girlies (the context-level ones):

int SSL_CTX_set0_verify_cert_store(SSL_CTX *ctx, X509_STORE *st);
int SSL_CTX_set1_verify_cert_store(SSL_CTX *ctx, X509_STORE *st);
int SSL_CTX_set0_chain_cert_store(SSL_CTX *ctx, X509_STORE *st);
int SSL_CTX_set1_chain_cert_store(SSL_CTX *ctx, X509_STORE *st);
int SSL_CTX_get0_verify_cert_store(SSL_CTX *ctx, X509_STORE **st);
int SSL_CTX_get0_chain_cert_store(SSL_CTX *ctx, X509_STORE **st);

and then the same vibes but per-SSL:

int SSL_set0_verify_cert_store(SSL *ctx, X509_STORE *st);
int SSL_set1_verify_cert_store(SSL *ctx, X509_STORE *st);
int SSL_set0_chain_cert_store(SSL *ctx, X509_STORE *st);
int SSL_set1_chain_cert_store(SSL *ctx, X509_STORE *st);
int SSL_get0_verify_cert_store(SSL *ctx, X509_STORE **st);
int SSL_get0_chain_cert_store(SSL *ctx, X509_STORE **st);

(yes, the parameter is literally named ctx in the SSL ones too — not me, that's just how it is 🫶)

🦋 DESCRIPTION 🦋

the setters 💖

SSL_CTX_set0_verify_cert_store() and SSL_CTX_set1_verify_cert_store() set the certificate store used for certificate verification to st. verification girlies, this one's for you.

SSL_CTX_set0_chain_cert_store() and SSL_CTX_set1_chain_cert_store() set the certificate store used for certificate chain building to st. chain-building girlies, this one's for you.

SSL_set0_verify_cert_store(), SSL_set1_verify_cert_store(), SSL_set0_chain_cert_store() and SSL_set1_chain_cert_store() are similar except they apply to the SSL structure ssl. same energy, smaller scope, we love a consistent queen ✨

the getters 🎀

SSL_CTX_get0_verify_chain_store(), SSL_get0_verify_chain_store(), SSL_CTX_get0_chain_cert_store() and SSL_get0_chain_cert_store() retrieve the objects you set earlier via the above calls. a pointer to the object — or NULL if no such object has been set — gets written to *st. so like, it's giving callback-out-param realness.

the macro tea ☕ (read this part, bestie)

all of these functions are implemented as macros. not kidding. so:

  • the ones containing a 1 — set1_ — increment the reference count of the supplied store, so it must be freed at some point after the operation.
  • the ones containing a 0 — set0_ — do not increment reference counts, and the supplied store MUST NOT be freed after the operation.
literally the most important distinction on this whole page. 1 = you own a ref, you free it later. 0 = hands off, do not free. do not mess this up 🙈

🧚 NOTES 🧚

the copy situation 📋

the store pointers associated with an SSL_CTX structure get copied to any SSL structures when SSL_new() is called. so basically: SSL structures will not be affected if the parent SSL_CTX store pointer is later set to a new value. they took a snapshot, they moved on, no take-backs 💅

what each store is actually for 🔍

  • the verification store is used to verify the certificate chain sent by the peer. so an SSL/TLS client uses it to verify the server's certificate chain, and an SSL/TLS server uses it to verify any client certificate chain. mutual verification, mutual respect. 🤝
  • the chain store is used to build the certificate chain. the details of the chain building and checking process live in "Certification Path Building" in openssl-verification-options(1) and "Certification Path Validation" in openssl-verification-options(1). go read those if you want the deep lore 📚

when auto chain building gets cancelled 🚫

if the mode SSL_MODE_NO_AUTO_CHAIN is set or a certificate chain is configured already (for example using functions such as SSL_CTX_add1_chain_cert(3) or SSL_CTX_add_extra_chain_cert(3)), then automatic chain building is disabled.

if the mode SSL_MODE_NO_AUTO_CHAIN is set then automatic chain building is disabled.

and yes — the page really does say the SSL_MODE_NO_AUTO_CHAIN bit twice. she said it, she meant it, she said it again. we're keeping both. 💀

the fallback 🫶

if the chain or the verification store is not set, then the store associated with the parent SSL_CTX is used instead, to retain compatibility with previous versions of OpenSSL. glow-up without breaking the old girlies, we stan.

⭐ RETURN VALUES ⭐

all these functions return 1 for success and 0 for failure. that's it, that's the whole section. one and zero, slay. ✅

🔥 SEE ALSO 🔥

go off, go read, here's the whole squad:

💜 HISTORY 💜

these functions were added in OpenSSL 1.0.2. vintage. still relevant. still eating. 👑

Copyright 2013-2022 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the "License"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at <https://www.openssl.org/source/license.html>.

and that's the page, bestie!! 🎀 this one's from OpenSSL 3.5.6, dated 2026-04-07, and it lives under the manual name SSL_CTX_SET1...Y_CERT_STORE(3ossl). mwah, go forth and set1 responsibly 💋✨

📦 where this page comes from