X509_STORE_GET1_CERTS(3ssl)

📦 version 4.1.0, in opensuse-leap 16.0

✨ X509_STORE_CTX_GET_BY_SUBJECT ✨

Okay bestie, so you know how the library functions manual is a whole vibe? This one's from it, and it's literally about grabbing objects out of a certificate store — like shopping in the most secure boutique ever. Let's get into it 💅

🎀 NAME 🎀

So we've got a whole squad of functions here, all about retrieving objects from a certificate store:

  • X509_STORE_CTX_get_by_subject
  • X509_STORE_CTX_get_obj_by_subject
  • X509_STORE_CTX_get1_certs
  • X509_STORE_CTX_get1_crls
  • X509_STORE_CTX_get1_issuer
  • X509_STORE_get_by_subject
  • X509_STORE_get1_certs
  • X509_STORE_get1_crls

They all do the same iconic thing: retrieve objects from a certificate store. Periodt. 🔥

🌈 SYNOPSIS 🌈

First things first, you gotta include this header, no cap:

#include <openssl/x509_vfy.h>

And here are all the signatures, exactly as they are — memorize them, bestie:

int
X509_STORE_CTX_get_by_subject(X509_STORE_CTX *ctx,
    X509_LOOKUP_TYPE type, X509_NAME *name, X509_OBJECT *object);

X509_OBJECT *
X509_STORE_CTX_get_obj_by_subject(X509_STORE_CTX *ctx,
    X509_LOOKUP_TYPE type, X509_NAME *name);

STACK_OF(X509) *
X509_STORE_CTX_get1_certs(X509_STORE_CTX *ctx, X509_NAME *name);

STACK_OF(X509_CRL) *
X509_STORE_CTX_get1_crls(X509_STORE_CTX *ctx, X509_NAME *name);

int
X509_STORE_CTX_get1_issuer(X509 **issuer, X509_STORE_CTX *ctx,
    X509 *certificate);

int
X509_STORE_get_by_subject(X509_STORE_CTX *ctx, X509_LOOKUP_TYPE type,
    X509_NAME *name, X509_OBJECT *object);

STACK_OF(X509) *
X509_STORE_get1_certs(X509_STORE_CTX *ctx, X509_NAME *name);

STACK_OF(X509_CRL) *
X509_STORE_get1_crls(X509_STORE_CTX *ctx, X509_NAME *name);

💜 DESCRIPTION 💜

Okay so let's break these down one by one because each one is lowkey iconic in its own way.

🌸 X509_STORE_CTX_get_by_subject() 🌸

This one retrieves the first object that matches a given type and name from the X509_STORE that's associated with ctx. The type can be:

  • X509_LU_X509 — to grab a certificate
  • X509_LU_CRL — to grab a revocation list

If the store doesn't already have a matching object — or if the type is X509_LU_CRL — then a lookup by subject gets performed on the X509_LOOKUP objects associated with the store until a match is found. And note: this lookup may add zero or more objects to the store. So like, it might add stuff, it might not. No promises 👀

When it succeeds, the content of the object you passed in gets overwritten with a pointer to the first match, and the reference count of that certificate or revocation list goes up by 1.

⚠️ Heads up bestie: avoiding a memory leak by making sure your provided object is empty? That's your responsibility as the caller. Not the function's. Yours. 💀

🦋 X509_STORE_CTX_get_obj_by_subject() 🦋

Similar vibe to the one above, except this one allocates a new object and returns it. Fresh out the box, literally.

🎀 X509_STORE_CTX_get1_certs() 🎀

This retrieves all certificates matching the subject name from the X509_STORE associated with ctx. If there aren't any yet, it calls X509_STORE_CTX_get_by_subject() to try and add some — like manifesting them into existence ✨

When it succeeds, the reference counts of all certificates added to the returned array get incremented by 1.

🧚 X509_STORE_CTX_get1_crls() 🧚

Similar to the certs one, except:

  • It operates on certificate revocation lists (CRLs) instead of certificates
  • It always calls X509_STORE_CTX_get_by_subject(), even if the X509_STORE already contains a matching revocation list. Like, it's gonna call it regardless. That's just how she is 💅

👑 X509_STORE_CTX_get1_issuer() 👑

This one retrieves the issuer CA certificate for a given certificate from the X509_STORE associated with ctx. Internally:

  1. The issuer name gets retrieved with X509_get_issuer_name(3)
  2. The candidate issuer CA certificate gets retrieved with X509_STORE_X509_get_by_subject() using that issuer name
  3. X509_check_issued(3) — or a user-supplied replacement function — is used to check whether the certificate was actually issued using the issuer CA certificate before returning it

And if the verification parameters associated with ctx encourage checking of validity times, then CAs with a valid time are preferred. But if no matching CA has a valid time, one with an invalid time is accepted anyway. So like, she's flexible. We love a flexible queen 🙈

⭐ Deprecated Aliases ⭐

These following ones are deprecated aliases implemented as macros — so they're giving old money, but make it legacy:

  • X509_STORE_get_by_subject() — for X509_STORE_CTX_get_by_subject()
  • X509_STORE_get1_certs() — for X509_STORE_CTX_get1_certs()
  • X509_STORE_get1_crls() — for X509_STORE_CTX_get1_crls()

🔥 RETURN VALUES 🔥

Let's talk about what these functions give back when they're done doing their thing.

X509_STORE_CTX_get_by_subject() and X509_STORE_get_by_subject()

They return 1 if a match is found or 0 on failure. And failure isn't just "no match found" — they can also fail due to memory allocation failure. So like, sometimes it's not you, it's the malloc 😭

💀 Oh and with library implementations other than LibreSSL? They might also return negative values for internal errors. So watch out for that.

X509_STORE_CTX_get_obj_by_subject()

Returns the new object, or NULL on failure — in particular if no match is found or if memory allocation fails.

X509_STORE_CTX_get1_certs() and X509_STORE_get1_certs()

They return a newly allocated and populated array of certificates, or NULL on failure. They fail if:

  • No match is found
  • X509_STORE_CTX_get_by_subject() fails
  • Memory allocation fails

X509_STORE_CTX_get1_crls() and X509_STORE_get1_crls()

They return a newly allocated and populated array of CRLs, or NULL on failure. They fail if X509_STORE_CTX_get_by_subject() finds no new match — even if the associated X509_STORE already contains matching CRLs — or if memory allocation fails.

X509_STORE_CTX_get1_issuer()

Returns 1 if a matching issuer CA certificate is found or 0 otherwise.

⚠️ Again, with library implementations other than LibreSSL, it might also return negative values for internal errors. Just so you know 💅

🌈 SEE ALSO 🌈

Go check these out, bestie — they're all related and honestly iconic in their own right:

🦋 HISTORY 🦋

Okay so like, a little herstory lesson because these functions have been around for a minute:

  • X509_STORE_get_by_subject() first appeared in SSLeay 0.8.0 and has been available since OpenBSD 2.4.
  • X509_STORE_CTX_get1_issuer() first appeared in OpenSSL 0.9.6 and has been available since OpenBSD 2.9.
  • X509_STORE_get1_certs() and X509_STORE_get1_crls() first appeared in OpenSSL 1.0.0 and have been available since OpenBSD 4.9.
  • X509_STORE_CTX_get_by_subject() and X509_STORE_CTX_get_obj_by_subject() first appeared in OpenSSL 1.1.0 and have been available since OpenBSD 7.1.
  • X509_STORE_CTX_get1_certs() and X509_STORE_CTX_get1_crls() first appeared in OpenSSL 1.1.0 and have been available since OpenBSD 7.4.
🫶 And that's the whole page, bestie! This one's from the Debian distribution, dated May 12, 2024, and the manual page itself is titled X509_STORE_GET_BY_SUBJECT(3). Slay. 💖
📦 where this page comes from