X509_VERIFY_PARAM_NEW(3)

📦 version 4.1.0, in opensuse-leap 16.0

💅 X509_VERIFY_PARAM_NEW — like, the whole X509 verification parameter object saga

okay bestie, so this is the X509_VERIFY_PARAM_NEW(3) page from the library functions manual, and it's literally all about X509 verification parameter objects — the little config blobs that tell certificate verification how to behave. buckle up 🎀

✨ NAME ✨

X509_VERIFY_PARAM_new, X509_VERIFY_PARAM_inherit, X509_VERIFY_PARAM_set1, X509_VERIFY_PARAM_free, X509_VERIFY_PARAM_add0_table, X509_VERIFY_PARAM_lookup, X509_VERIFY_PARAM_get_count, X509_VERIFY_PARAM_get0, X509_VERIFY_PARAM_table_cleanup — X509 verification parameter objects 🦋

🌸 SYNOPSIS 🌸

#include <openssl/x509_vfy.h>

X509_VERIFY_PARAM *
X509_VERIFY_PARAM_new(void);

int
X509_VERIFY_PARAM_inherit(X509_VERIFY_PARAM *destination,
    const X509_VERIFY_PARAM *source);

int
X509_VERIFY_PARAM_set1(X509_VERIFY_PARAM *destination,
    const X509_VERIFY_PARAM *source);

void
X509_VERIFY_PARAM_free(X509_VERIFY_PARAM *param);

int
X509_VERIFY_PARAM_add0_table(X509_VERIFY_PARAM *param);

const X509_VERIFY_PARAM *
X509_VERIFY_PARAM_lookup(const char *name);

int
X509_VERIFY_PARAM_get_count(void);

const X509_VERIFY_PARAM *
X509_VERIFY_PARAM_get0(int id);

void
X509_VERIFY_PARAM_table_cleanup(void);

💖 DESCRIPTION 💖

X509_VERIFY_PARAM_new() allocates and initializes an empty X509_VERIFY_PARAM object. brand new, fresh out the box ✨

X509_VERIFY_PARAM_inherit() copies some data from the source object to the destination object. not all of it, bestie — some. 👀

The verification flags set with X509_VERIFY_PARAM_set_flags(3) in the source object are always OR'ed into the verification flags of the destination object. always. no exceptions, periodt.

Fields having their default value in the source object are not copied. if it's already default, it's not invited to the party 🙈

By default, fields in the destination object already having a non-default value are not overwritten. BUT — and this is the plot twist — if at least one of the source or destination objects was created during a call to X509_STORE_CTX_init(3) that did not have a store argument, and if that object was not previously used as the destination in an earlier call to X509_VERIFY_PARAM_inherit(), this restriction is waived and even non-default fields in the destination object get overwritten. If fields overwritten in this way contain pointers to allocated memory, that memory is freed. so yeah, memory management main character energy 😭

As far as permitted by the above rules, the following fields are copied:

Some data that may be contained in the source object is never copied — for example the subject name of the peer certificate that can be retrieved with X509_VERIFY_PARAM_get0_peername(3). sorry girl, that one's staying home 💀

If source is a NULL pointer, the function has no effect but returns successfully. slay, no crash, we love a graceful no-op 🫶

X509_VERIFY_PARAM_set1() is identical to X509_VERIFY_PARAM_inherit() except that fields in the destination object are overwritten even if they do not match their default values. Still, fields having their default value in the source object are not copied. so it's the more aggressive version, basically inherit with a gym membership 🔥

⚠️ If X509_VERIFY_PARAM_inherit() or X509_VERIFY_PARAM_set1() fail, partial copying may have occurred, so all data in the destination object should be regarded as invalid. like, do not trust it, do not look at it, it's giving corrupted vibes 😭

X509_VERIFY_PARAM_inherit() is used internally by X509_STORE_CTX_init(3) and by X509_STORE_CTX_set_default(3), and X509_VERIFY_PARAM_set1() is used internally by X509_STORE_set1_param(3). iykyk 👑

X509_VERIFY_PARAM_free() clears all data contained in param and releases all memory used by it. If param is a NULL pointer, no action occurs. clean, simple, no drama 💅

X509_VERIFY_PARAM_add0_table() adds param to a static list of X509_VERIFY_PARAM objects maintained by the library.

💀 this function is EXTREMELY DANGEROUS because — contrary to the name of the function — if the list already contains an object that happens to have the same name, that old object is not only silently removed from the list, but also silently freed, which may silently invalidate various pointers existing elsewhere in the program. not me reading this and screaming. fr fr, be careful.

X509_VERIFY_PARAM_lookup() searches this list for an object of the given name. If no match is found, the predefined objects built-in to the library are also inspected. 🔍

X509_VERIFY_PARAM_get_count() returns the sum of the number of objects on this list and the number of predefined objects built-in to the library. Note that this is not necessarily the total number of X509_VERIFY_PARAM objects existing in the program, because there may be additional such objects that were never added to the list. math is mathing but only partially 🧮

X509_VERIFY_PARAM_get0() accesses predefined and user-defined objects using id as an index, useful for looping over objects without knowing their names. An argument less than the number of predefined objects selects one of the predefined objects; a higher argument selects an object from the list. perfect for a little for loop moment 🌈

💀 X509_VERIFY_PARAM_table_cleanup() deletes all objects from this list. It is extremely dangerous because it also invalidates all data that was contained in all objects that were on the list and because it frees all these objects, which may invalidate various pointers existing elsewhere in the program. this one ate and also destroyed everything, lowkey terrifying 🍓

⭐ RETURN VALUES ⭐

  • X509_VERIFY_PARAM_new() returns a pointer to the new object, or NULL on allocation failure.
  • X509_VERIFY_PARAM_inherit(), X509_VERIFY_PARAM_set1(), and X509_VERIFY_PARAM_add0_table() return 1 for success or 0 for failure.
  • X509_VERIFY_PARAM_lookup() and X509_VERIFY_PARAM_get0() return a pointer to an existing built-in or user-defined object, or NULL if no object with the given name is found, or if id is at least X509_VERIFY_PARAM_get_count().
  • X509_VERIFY_PARAM_get_count() returns a number of objects.

🦋 SEE ALSO 🦋

SSL_set1_param(3), X509_STORE_CTX_set0_param(3), X509_STORE_set1_param(3), X509_verify_cert(3), X509_VERIFY_PARAM_set_flags(3)

go read those next bestie, the lore goes deep 🫶

👑 HISTORY 👑

X509_VERIFY_PARAM_new(), X509_VERIFY_PARAM_inherit(), X509_VERIFY_PARAM_set1(), X509_VERIFY_PARAM_free(), X509_VERIFY_PARAM_add0_table(), X509_VERIFY_PARAM_lookup(), and X509_VERIFY_PARAM_table_cleanup() first appeared in OpenSSL 0.9.8 and have been available since OpenBSD 4.5. vintage icon behavior ✨

X509_VERIFY_PARAM_get_count() and X509_VERIFY_PARAM_get0() first appeared in OpenSSL 1.0.2 and have been available since OpenBSD 6.3. the newer babies of the family 🎀

and that's the whole page, bestie 💖 this was the Debian edition, dated May 24, 2023 — go forth and verify those params responsibly, mwah 🧚💜

📦 where this page comes from