X509_STORE_SET1_PARAM(3)

📦 version 4.4.0, in alpine 3.24, arch rolling

okay so welcome to X509_STORE_SET1_PARAM(3) — that's the title, and this is a Library Functions Manual page, bestie. It's giving libcrypto energy and it's here to explain how to get and set X509_STORE data. 💖✨

🎀 NAME 🎀

This whole squad is about getting and setting X509_STORE data: X509_STORE_set1_param, X509_STORE_set_flags, X509_STORE_set_purpose, X509_STORE_set_trust, X509_STORE_set_depth, X509_STORE_add_cert, X509_STORE_add_crl, X509_STORE_get0_param, X509_STORE_get1_objects, X509_STORE_get0_objects, X509_STORE_get_ex_new_index, X509_STORE_set_ex_data, and X509_STORE_get_ex_data. Periodt. 💅

✨ SYNOPSIS ✨

The synopsis tea, copied exactly so the signatures stay iconic:

library “libcrypto” #include <openssl/x509_vfy.h>

int
X509_STORE_set1_param(X509_STORE *store, X509_VERIFY_PARAM *pm);

int
X509_STORE_set_flags(X509_STORE *store, unsigned long flags);

int
X509_STORE_set_purpose(X509_STORE *store, int purpose);

int
X509_STORE_set_trust(X509_STORE *store, int trust);

int
X509_STORE_set_depth(X509_STORE *store, int depth);

int
X509_STORE_add_cert(X509_STORE *store, X509 *x);

int
X509_STORE_add_crl(X509_STORE *store, X509_CRL *crl);

X509_VERIFY_PARAM *
X509_STORE_get0_param(X509_STORE *store);

STACK_OF(X509_OBJECT) *
X509_STORE_get1_objects(X509_STORE *store);

STACK_OF(X509_OBJECT) *
X509_STORE_get0_objects(X509_STORE *store);

int
X509_STORE_get_ex_new_index(long argl, void *argp,
    CRYPTO_EX_new *new_func, CRYPTO_EX_dup *dup_func,
    CRYPTO_EX_free *free_func);

int
X509_STORE_set_ex_data(X509_STORE *store, int idx, void *arg);

void *
X509_STORE_get_ex_data(X509_STORE *store, int idx);

💅 DESCRIPTION 💅

  • X509_STORE_set1_param() — copies the verification parameters from pm using X509_VERIFY_PARAM_set1(3) into the verification parameter object contained in the store. Copy-paste but make it cert-verify, basically.
  • X509_VERIFY_PARAM_set_flags(), X509_STORE_set_purpose(), X509_STORE_set_trust(), and X509_STORE_set_depth() — lowkey this exact lineup calls X509_VERIFY_PARAM_set_flags(), X509_VERIFY_PARAM_set_purpose(), X509_VERIFY_PARAM_set_trust(), and X509_VERIFY_PARAM_set_depth() on the verification parameter object contained in the store. Yep, that first name is X509_VERIFY_PARAM_set_flags() in the original description — no cap, iykyk. 🫶
  • X509_STORE_add_cert() and X509_STORE_add_crl() — add the certificate x or the certificate revocation list crl to the store, increasing its reference count by 1 in case of success. Untrusted objects should not be added in this way. That's a hard no, bestie. 🚫
  • X509_STORE_get_ex_new_index(), X509_STORE_set_ex_data(), and X509_STORE_get_ex_data() — handle application specific data in X509_STORE objects. Their usage is identical to that of RSA_get_ex_new_index(3), RSA_set_ex_data(3), and RSA_get_ex_data(3). Also X509_STORE_get_ex_new_index() is implemented as a macro. Macro moment. ✨

🫶 RETURN VALUES 🫶

  • X509_STORE_set1_param(), X509_STORE_set_purpose(), X509_STORE_set_trust(), and X509_STORE_set_ex_data() return 1 for success or 0 for failure.
  • X509_STORE_set_flags() and X509_STORE_set_depth() always return 1, indicating success. They're not here to stress you out.
  • X509_STORE_add_cert() and X509_STORE_add_crl() return 1 for success or 0 for failure. For example, they fail if x or crl is a NULL pointer, if a certificate with the same subject name as x or a revocation list with the same issuer name as crl are already contained in the store, or if memory allocation fails. Memory allocation said nope. 💀
  • X509_STORE_get0_param() returns an internal pointer to the verification parameter object contained in the store. The returned pointer must not be freed by the calling application.
  • X509_STORE_get1_objects() returns a newly allocated stack containing the certificates, revocation lists, and private keys in store, as well as cached objects added by X509_LOOKUP_hash_dir(3). The caller must release the result with sk_pop_free(3) and X509_OBJECT_free(3) when done. Cleanup era. 🧚
  • X509_STORE_get0_objects() is a deprecated function returning an internal pointer to the stack of certificates, revocation lists, and private keys contained in store. The returned pointer must not be modified or freed by the calling application.
⚠️ Deprecated alert: X509_STORE_get0_objects() is not thread-safe. If store is shared across multiple threads, callers cannot safely inspect the result of this function, because another thread may have concurrently added to it. In particular, X509_LOOKUP_hash_dir(3) treats this list as a cache and may add to it in the course of certificate verification. Do not casually poke the cache, bestie. 😭
  • X509_STORE_get_ex_new_index() returns a new index or -1 on failure.
  • X509_STORE_get_ex_data() returns the application data or NULL on failure.

👑 SEE ALSO 👑

🌸 HISTORY 🌸

  • X509_STORE_add_cert() first appeared in SSLeay 0.8.0. X509_STORE_add_crl() first appeared in SSLeay 0.9.0. These functions have been available since OpenBSD 2.4. Ancient icon behavior. 🏺
  • X509_STORE_set_flags(), X509_STORE_set_purpose(), and X509_STORE_set_trust() first appeared in OpenSSL 0.9.7 and have been available since OpenBSD 3.2.
  • X509_STORE_set1_param() and X509_STORE_set_depth() first appeared in OpenSSL 0.9.8 and have been available since OpenBSD 4.5.
  • X509_STORE_get0_param(), X509_STORE_get0_objects(), X509_STORE_get_ex_new_index(), X509_STORE_set_ex_data(), and X509_STORE_get_ex_data() first appeared in OpenSSL 1.1.0 and have been available since OpenBSD 6.3.
  • X509_STORE_get1_objects() first appeared in BoringSSL and has been available since OpenBSD 7.5.

Source/version: Debian, dated June 8, 2025 — and this is X509_STORE_SET1_PARAM(3) signing off. Stay encrypted, bestie 💖✨

📦 where this page comes from