X509_NEW(3)

📦 version 4.4.0, in alpine 3.24, arch rolling

💅 X509_NEW(3) — the X.509 certificate object, explained bestie to bestie

okay so this is page X509_NEW(3) from the Library Functions Manual, and it's all about libcrypto's X.509 certificate object — the little diva that holds your public key and all the metadata about who it belongs to. grab a snack, we're going in 🎀

✨ SYNOPSIS ✨

library “libcrypto” #include <openssl/x509.h>

X509 *
X509_new(void);

X509 *
X509_dup(X509 *a);

X509 *
X509_REQ_to_X509(X509_REQ *req, int days, EVP_PKEY *pkey);

void
X509_free(X509 *a);

int
X509_up_ref(X509 *a);

STACK_OF(X509) *
X509_chain_up_ref(STACK_OF(X509) *chain);

🌸 DESCRIPTION 🌸

X509_new() allocates and initializes an empty X509 object with reference count 1. it represents an ASN.1 Certificate structure defined in RFC 5280 section 4.1, and lowkey it's the main character 💅 — it can hold a public key together with info about the person, organization, device, or function that the associated private key belongs to.

X509_dup() creates a deep copy of a using ASN1_item_dup(3), and sets the reference count of the copy to 1. no shared vibes, fully its own thing ✨

X509_REQ_to_X509() is giving glow-up energy — it takes a request and turns it into a whole certificate. specifically it:

  • allocates a new certificate object,
  • copies the public key from req into it,
  • copies the subject name of req to both the subject and issuer names of the new certificate,
  • sets the notBefore field to the current time,
  • sets the notAfter field to the given number of days in the future,
  • and signs the new certificate with X509_sign(3) using pkey and the MD5 algorithm.

and if req contains at least one attribute, the version of the new certificate is set to 2. periodt.

X509_free() decrements the reference count of the X509 structure a and frees it up if the reference count reaches 0. if a is a NULL pointer, no action occurs — nothing happens, we love a safe no-op 🫶

X509_up_ref() increments the reference count of a by 1. this is the iconique move when a certificate structure is being used by several different operations and each of them will free it up after use — this avoids the need to duplicate the entire certificate structure. share the same cert, bestie, just count the refs 💖

X509_chain_up_ref() performs a shallow copy of the given chain using sk_X509_dup() and increments the reference count of each contained certificate by 1. its purpose is similar to X509_up_ref(): the returned chain persists after the original is freed. literally the group-chat equivalent of "everyone's still here even after the original chat got deleted" 😭

⭐ RETURN VALUES ⭐

  • X509_new(), X509_dup(), and X509_REQ_to_X509() return a pointer to the newly allocated object, or NULL if an error occurs. you can grab an error code with ERR_get_error(3).
  • X509_up_ref() returns 1 for success or 0 for failure.
  • X509_chain_up_ref() returns the copy of the chain, or NULL if an error occurs.

🦋 SEE ALSO 🦋

ASIdentifiers_new(3), ASRange_new(3), AUTHORITY_KEYID_new(3), BASIC_CONSTRAINTS_new(3), crypto(3), d2i_X509(3), IPAddressRange_new(3), PKCS8_PRIV_KEY_INFO_new(3), X509_ALGOR_new(3), X509_ATTRIBUTE_new(3), X509_check_ca(3), X509_check_host(3), X509_check_issued(3), X509_check_private_key(3), X509_check_purpose(3), X509_CINF_new(3), X509_cmp(3), X509_CRL_new(3), X509_digest(3), X509_EXTENSION_new(3), X509_find_by_subject(3), X509_get0_notBefore(3), X509_get0_signature(3), X509_get1_email(3), X509_get_ex_new_index(3), X509_get_extension_flags(3), X509_get_pubkey(3), X509_get_pubkey_parameters(3), X509_get_serialNumber(3), X509_get_subject_name(3), X509_get_version(3), X509_INFO_new(3), X509_load_cert_file(3), X509_LOOKUP_hash_dir(3), X509_LOOKUP_new(3), X509_NAME_new(3), X509_OBJECT_new(3), X509_print_ex(3), X509_PUBKEY_new(3), X509_PURPOSE_set(3), X509_REQ_new(3), X509_SIG_new(3), X509_sign(3), X509_STORE_CTX_new(3), X509_STORE_get_by_subject(3), X509_STORE_new(3), X509v3_addr_add_inherit(3), X509v3_addr_get_range(3), X509v3_addr_inherits(3), X509v3_addr_subset(3), X509v3_addr_validate_path(3), X509v3_asid_add_id_or_range(3)

(yes that's a lot of them. they're all linked. go click around, iykyk 🌈)

👑 STANDARDS 👑

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

🧚 HISTORY 🧚

X509_new() and X509_free() appeared in SSLeay 0.4 or earlier, X509_dup() in SSLeay 0.4.4, and X509_REQ_to_X509() in SSLeay 0.6.0. these functions have been available since OpenBSD 2.4. ancient. iconic. still slaying 💀

X509_up_ref() first appeared in OpenSSL 1.1.0 and has been available since OpenBSD 6.1.

X509_chain_up_ref() first appeared in OpenSSL 1.0.2 and has been available since OpenBSD 6.3.

🙈 BUGS 🙈

the X.509 public key infrastructure and its data types contain too many design bugs to list them. not me exaggerating, that's literally the manpage.

for lots of examples, see the classic X.509 Style Guide: https://www.cs.auckland.ac.nz/~pgut001/pubs/x509guide.txt that Peter Gutmann published in 2000. it's giving vintage cursed content and honestly it's required reading 🍓

that's the whole page bestie, no cap, every flag and fact accounted for 💜 this one shipped with Debian, dated July 16, 2025 — mwah, go forth and manage your certificates responsibly ✨🎀

📦 where this page comes from