X509_GET1_EMAIL(3)

📦 version 4.1.0, in opensuse-leap 16.0

X509_GET1_EMAIL(3): email & OCSP stack utilities, bestie edition 💌

Okay so this is the manual page for X509_get1_email, X509_get1_ocsp, and X509_email_free — the little trio of functions that grab email addresses and OCSP URLs out of certificates and hand you back a stack of strings. Honestly? Super useful. Let's get into it ✨

✨ SYNOPSIS ✨

Like, here's the whole vibe up front:

#include <openssl/x509v3.h>

typedef char *OPENSSL_STRING;

STACK_OF(OPENSSL_STRING) *
X509_get1_email(X509 *certificate);

STACK_OF(OPENSSL_STRING) *
X509_get1_ocsp(X509 *certificate);

void
X509_email_free(STACK_OF(OPENSSL_STRING) *stack);

That typedef char *OPENSSL_STRING; is just the icon it says it is — one string, slaying on its own. Then the real ones:

  • X509_get1_email() — takes a X509 *certificate and gives you back a STACK_OF(OPENSSL_STRING) * full of emails 🎀
  • X509_get1_ocsp() — same deal, takes a X509 *certificate, returns a STACK_OF(OPENSSL_STRING) * but this time with OCSP URLs 🦋
  • X509_email_free() — takes a STACK_OF(OPENSSL_STRING) *stack and frees it, no return value, she's void and she's thriving 💅

🌸 DESCRIPTION 🌸

Okay, lore time:

X509_get1_email() — she pulls all the email addresses out of the subject field, and also out of any Subject Alternative Name extension the certificate might have. Like, everywhere an email could be hiding, she finds it. No cap 🔥

X509_get1_ocsp() — this one's the OCSP girlie. She grabs all the uniform resource identifiers from all the AccessDescription objects that have an accessMethod of OCSP, and those live inside the Authority Information Access extension of the certificate. Yes, that's a whole mouthful, but she ate 💀

X509_email_free() — okay so she frees all the strings stored in the stack, and then the stack itself too. And if stack is a NULL pointer? Nothing happens. No drama, no action, zero fallout 🙈

🫶 RETURN VALUES 🫶

X509_REQ_get1_email() and X509_get1_ocsp() return newly allocated stacks of char * containing copies of the addresses in question. Obsessed with the fact that they're copies, btw — your originals are safe 🥹

And if there are no addresses, or if an error happens? They return NULL. That's it. That's the tea.

Heads up buttercup: the description of this section genuinely says X509_REQ_get1_email() even though the synopsis above is about X509_get1_email(). Not me pointing it out 💀 — just keeping every detail exactly as the page says, fr fr.

💜 SEE ALSO 💜

Go read these next, iykyk:

👑 STANDARDS 👑

RFC 5280: Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile

  • section 4.1: Basic Certificate Fields
  • section 4.1.2.6: Subject
  • section 4.2.1.6: Subject Alternative Name
  • section 4.2.2.1: Authority Information Access

RFC 2985: PKCS #9: Selected Object Classes and Attribute Types

  • section 5.2.1: Electronic-mail address
  • appendix B.3.5: emailAddress

🦋 HISTORY 🦋

X509_get1_email() and X509_email_free() first appeared in OpenSSL 0.9.6, and they've been available since OpenBSD 2.9. Main character energy from day one ⭐

X509_get1_ocsp() first appeared in OpenSSL 0.9.8h, and it's been available since OpenBSD 4.5. A little later to the party, but she showed up and she showed out 🌈

💀 BUGS 💀

Okay this is the part where I have to be completely honest with you:

X509_email_free() is utterly misnamed. Like, the name is giving absolutely nothing correct. She does not operate on any X509 object — not a single one. And she is not in any way restricted to email addresses either. All she actually does is free a stack of strings. That's the whole gig. That's the entire job description. The way her name is just... wrong 😭🙈

And that's the whole page, bestie! This one's from the Debian source, and it's the version dated August 23, 2019. Go off and free those stacks responsibly, and remember: X509_email_free() is a liar but we love her anyway 🍓🧚💖

📦 where this page comes from