X509_GET_PUBKEY(3)

📦 version 4.1.0, in opensuse-leap 16.0

💖 X509_GET_PUBKEY(3) 💖

okay bestie, listen up, because this page is literally about getting and setting public keys on certificates and certificate requests, and it's lowkey iconic. we're talking about the X509_get_pubkey family of functions from the library functions manual, and yes, it's giving main character energy. slay. 🎀

✨ NAME ✨

So the whole squad here is: X509_get_pubkey, X509_get0_pubkey, X509_set_pubkey, X509_get_X509_PUBKEY, X509_get0_pubkey_bitstr, X509_REQ_get_pubkey, X509_REQ_get0_pubkey, X509_REQ_set_pubkey, X509_extract_key, and X509_REQ_extract_key. and what do they all do, you ask? they get or set the public key for a certificate or certificate request. periodt. 👑

🦋 SYNOPSIS 🦋

first things first, you gotta include the header, no cap:

#include <openssl/x509.h>

and here's the whole function lineup, looking all cute and official:

EVP_PKEY *
X509_get_pubkey(X509 *x);

EVP_PKEY *
X509_get0_pubkey(const X509 *x);

int
X509_set_pubkey(X509 *x, EVP_PKEY *pkey);

X509_PUBKEY *
X509_get_X509_PUBKEY(const X509 *x);

ASN1_BIT_STRING *
X509_get0_pubkey_bitstr(const X509 *x);

EVP_PKEY *
X509_REQ_get_pubkey(X509_REQ *req);

EVP_PKEY *
X509_REQ_get0_pubkey(X509_REQ *req);

int
X509_REQ_set_pubkey(X509_REQ *x, EVP_PKEY *pkey);

EVP_PKEY *
X509_extract_key(X509 *x);

EVP_PKEY *
X509_REQ_extract_key(X509_REQ *req);

literally all of them, right there, looking adorable. iykyk. 💅

🌸 DESCRIPTION 🌸

okay so let's break this down function by function, because each one has its own little vibe and you need to know which one to use. no guessing. fr fr.

X509_get_pubkey() — this one attempts to decode the public key for certificate x. if it's successful (slay), it returns the public key as an EVP_PKEY pointer, and here's the important part bestie: it increments the reference count. that means you must free the returned key after use. it's yours, you own it, take care of it. 💖

X509_get0_pubkey() — similar to the one above, but it does not increment the reference count of the returned EVP_PKEY. so what does that mean? it means you must not free it after use. it's borrowed, not given. don't touch the ownership, okay? 🙈

X509_get_X509_PUBKEY() — this returns an internal pointer to the SubjectPublicKeyInfo structure contained in x. internal pointer means: do not free this after use. it's not yours to free, bestie. leave it alone. 🫶

X509_get0_pubkey_bitstr() — another internal pointer situation. this one returns a pointer to just the public key contained in that SubjectPublicKeyInfo structure, without the information about the algorithm used. again, do not free it after use. internal means internal. ✨

X509_set_pubkey() — this one attempts to set the public key for certificate x to pkey. and here's a vibe check: the key pkey should be freed up after use. you're handing it over, but you still gotta clean up your side. 🧚

X509_REQ_get_pubkey(), X509_REQ_get0_pubkey(), and X509_REQ_set_pubkey() — these are all similar, but they operate on certificate request req instead of a certificate. same energy, different object. 💜

now here's a fun little performance note, and it's actually iconic: the first time a public key is decoded, the EVP_PKEY structure is cached in the certificate or certificate request itself. subsequent calls return the cached structure with its reference count incremented to improve performance. so it's fast the second time around. we love efficiency. 🔥

and finally, the deprecated squad: X509_extract_key() and X509_REQ_extract_key() are deprecated aliases for X509_get_pubkey() and X509_REQ_get_pubkey(), respectively, and they're implemented as macros. deprecated means don't use them for new stuff, bestie. they're just hanging around for old code. 💀

👑 RETURN VALUES 👑

okay so what comes back out of these functions? let's get into it:

  • X509_get_pubkey(), X509_get0_pubkey(), X509_get_X509_PUBKEY(), X509_get0_pubkey_bitstr(), X509_REQ_get_pubkey(), X509_REQ_get0_pubkey(), X509_extract_key(), and X509_REQ_extract_key() — these all return a public key, or NULL if an error occurred. simple enough. 🌈
  • X509_set_pubkey() and X509_REQ_set_pubkey() — these return 1 for success or 0 for failure. classic. ⭐

and one more thing: in some cases of failure of X509_get0_pubkey(), X509_set_pubkey(), X509_REQ_get_pubkey(), X509_REQ_get0_pubkey(), and X509_REQ_set_pubkey(), the reason can be determined with ERR_get_error(3). so if something goes wrong, that's your detective tool. 🔍

💀 ERRORS 💀

okay this section is important because some of these functions are lowkey dangerous if you're not careful. not to be dramatic, but a crash is a crash. 😭

X509_get_pubkey(), X509_get0_pubkey(), X509_REQ_get_pubkey(), X509_extract_key(), and X509_REQ_extract_key() — these provide diagnostics as documented for X509_PUBKEY_get(3). but here's the catch: if x or req is NULL or contains no certificate information, they fail without pushing an error onto the stack. so you won't get an error message, it just fails. keep that in mind. 🙈

X509_get_X509_PUBKEY() — this one provides no diagnostics and crashes by accessing a NULL pointer if x is NULL or contains no certificate information. yeah, you read that right. it will literally crash. don't pass it a NULL or an empty certificate. please. for your own sake. 💀

X509_get0_pubkey_bitstr() — this one also provides no diagnostics and fails without pushing an error onto the stack if x is NULL. but here's the wild part: it crashes by accessing a NULL pointer if x contains no certificate information. so it's got two different failure modes depending on what's wrong. iconic in the worst way. 🙈

bestie, please do your NULL checks before calling these. the crash is real and it's not cute. 💔

🌟 SEE ALSO 🌟

if you wanna go deeper (and you should, because knowledge is power), check out these absolute legends:

all bangers, no skips. 💅

📜 STANDARDS 📜

these functions are out here following the rules, and the rules are:

  • RFC 5280, Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile, section 4.1 Basic Certificate Fields
  • RFC 2986: PKCS #10: Certification Request Syntax Specification, section 4.1 CertificationRequestInfo

standards queen behavior. periodt. 👑

🕰️ HISTORY 🕰️

okay so let's take a little trip down memory lane, because these functions have been around for a minute:

  • X509_extract_key() and X509_REQ_extract_key() first appeared in SSLeay 0.5.1, but they returned a pointer to an RSA object before SSLeay 0.6.0. so they've been around since before some of us were born. 💀
  • X509_get_pubkey(), X509_set_pubkey(), X509_REQ_get_pubkey(), and X509_REQ_set_pubkey() first appeared in SSLeay 0.6.5.
  • X509_get_X509_PUBKEY() first appeared in SSLeay 0.8.0.
  • these functions have been available since OpenBSD 2.4.
  • X509_get0_pubkey_bitstr() first appeared in OpenSSL 0.9.7 and has been available since OpenBSD 3.4.
  • X509_get0_pubkey() first appeared in OpenSSL 1.1.0 and has been available since OpenBSD 6.3.
  • X509_REQ_get0_pubkey() first appeared in OpenSSL 1.1.0 and has been available since OpenBSD 7.1.

history really said "let me serve you longevity and relevance." and they did. ✨

and that's the whole page, bestie! this was the Debian version, dated March 31, 2022, and the manual name is X509_GET_PUBKEY(3). go forth and handle your public keys responsibly. mwah! 💖🎀🌸🦋💅

📦 where this page comes from