X509_OBJECT_GET0_X509(3)

📦 version 4.1.0, in opensuse-leap 16.0

💅 X509_OBJECT_GET0_X509(3) — like, the certificate-store wrapper tea ☕

okay bestie, so this is a Library Functions Manual page and it's all about X509_OBJECT — the lil' glow-up wrapper that certificate stores use to hold their stuff. come sit with me, this one's actually so useful 🫶

✨ NAME ✨

X509_OBJECT_get_type, X509_OBJECT_new, X509_OBJECT_free, X509_OBJECT_get0_X509, X509_OBJECT_get0_X509_CRL, X509_OBJECT_idx_by_subject, X509_OBJECT_retrieve_by_subject, X509_OBJECT_retrieve_match — certificate, CRL, private key, and string wrapper for certificate stores 💖

(yes, all of those. one big friend group. iykyk.)

🌸 SYNOPSIS 🌸

#include <openssl/x509_vfy.h>

X509_LOOKUP_TYPE
X509_OBJECT_get_type(const X509_OBJECT *obj);

X509_OBJECT *
X509_OBJECT_new(void);

void
X509_OBJECT_free(X509_OBJECT *obj);

X509 *
X509_OBJECT_get0_X509(const X509_OBJECT *obj);

X509_CRL *
X509_OBJECT_get0_X509_CRL(X509_OBJECT *obj);

int
X509_OBJECT_idx_by_subject(STACK_OF(X509_OBJECT) *stack,
    X509_LOOKUP_TYPE type, X509_NAME *name);

X509_OBJECT *
X509_OBJECT_retrieve_by_subject(STACK_OF(X509_OBJECT) *stack,
    X509_LOOKUP_TYPE type, X509_NAME *name);

X509_OBJECT *
X509_OBJECT_retrieve_match(STACK_OF(X509_OBJECT) *stack,
    X509_OBJECT *obj);

🦋 DESCRIPTION 🦋

okay so the X509_OBJECT structure is a shallow wrapper around exactly one X509 certificate object or one X509_CRL certificate revocation list object. that's it. no cap. and the type of thing stored at any given moment? you can peek at it with X509_OBJECT_get_type() 👀

each X509_STORE object uses one stack of X509_OBJECT structures as its main storage area. like, that's the whole closet. that's where everything lives 💅

X509_OBJECT_new() allocates a brand-new X509_OBJECT structure — and it sets the object type to X509_LU_NONE and the pointer to the certificate or CRL to NULL. fresh out the box, literally nothing in it 🎀

if obj contains an X509 certificate, X509_OBJECT_free() calls X509_free(3) on that inner object. if obj contains an X509_CRL certificate revocation list, it calls X509_CRL_free(3) on that inner list instead. and then X509_OBJECT_free() frees the storage used for obj itself. clean up your room, bestie ✨

if type is X509_LU_X509, then both X509_OBJECT_idx_by_subject() and X509_OBJECT_retrieve_by_subject() search the given stack for a certificate with the subject name. if type is X509_LU_CRL, they go looking for a certificate revocation list with the issuer name instead. note the switch-up: subject for certs, issuer for CRLs 🧚

and for X509_OBJECT_retrieve_match():

  • if obj contains a certificate, it searches the given stack for a certificate with a matching subject name
  • if it contains a certificate revocation list, it searches for a certificate revocation list with a matching issuer name instead
  • otherwise, it searches for an X509_OBJECT with a matching type

three whole modes, main character energy honestly 👑

⭐ RETURN VALUES ⭐

X509_OBJECT_get_type() returns:

  • X509_LU_X509 if obj contains a certificate
  • X509_LU_CRL if it contains a certificate revocation list
  • X509_LU_NONE if it contains neither

X509_OBJECT_new() returns the new object — or NULL if memory allocation fails (sad, but it happens 😭).

X509_OBJECT_get0_X509() returns an internal pointer to the certificate contained in obj, or NULL if obj is NULL or contains no certificate. internal pointer, so like... don't go freeing it yourself, that's not your business 🙈

X509_OBJECT_get0_X509_CRL() returns an internal pointer to the certificate revocation list contained in obj, or NULL if obj is NULL or contains no certificate revocation list.

X509_OBJECT_idx_by_subject() returns the zero-based index of the first matching certificate or revocation list in the stack, or -1 if type is neither X509_LU_X509 nor X509_LU_CRL, or if no match is found.

X509_OBJECT_retrieve_by_subject() returns the first matching certificate or revocation list in the stack, or NULL if type is neither X509_LU_X509 nor X509_LU_CRL, or if no match is found.

X509_OBJECT_retrieve_match() returns the first matching X509_OBJECT, or NULL if stack or obj is NULL, or if no match is found.

reminder bestie: X509_OBJECT_free() returns void — there's literally nothing to check. just vibes and deallocation 🫶

🌈 SEE ALSO 🌈

STACK_OF(3), X509_CRL_new(3), X509_LOOKUP_new(3), X509_NAME_new(3), X509_new(3), X509_STORE_get0_objects(3), X509_STORE_get_by_subject(3), X509_STORE_load_locations(3), X509_STORE_new(3)

go read those next, they're the supporting cast 💜

🎀 HISTORY 🎀

X509_OBJECT_idx_by_subject(), X509_OBJECT_retrieve_by_subject(), and X509_OBJECT_retrieve_match() first appeared in OpenSSL 0.9.6 and have been available since OpenBSD 2.9. ancient. iconic. still here 🔥

X509_OBJECT_get_type(), X509_OBJECT_get0_X509(), and X509_OBJECT_get0_X509_CRL() first appeared in OpenSSL 1.1.0 and have been available since OpenBSD 6.3.

X509_OBJECT_new() and X509_OBJECT_free() first appeared in OpenSSL 1.1.0 and have been available since OpenBSD 7.1. the babies of the group, honestly 🍓

aaaand that's the page!! mwah 💋 this came from the Debian crew, dated March 8, 2025 — so go forth and wrap your certs responsibly, bestie 🦋✨

📦 where this page comes from