X509_PURPOSE_SET(3)

💖 X509_PURPOSE_SET(3) 💖

okay so bestie, this is the X509_PURPOSE_SET(3) page from the Library Functions Manual, and it's all about the libcrypto life. The squad is purpose objects, indices, and identifiers — and the way this page ate? It's giving certificate-purpose realness, and we're obsessed. 🫶 No cap.

---

✨ NAME ✨

X509_PURPOSE_set, X509_PURPOSE_get_by_id, X509_PURPOSE_add, X509_PURPOSE_get_count, X509_PURPOSE_cleanup, X509_PURPOSE_get0, X509_PURPOSE_get_by_sname, X509_PURPOSE_get_id, X509_PURPOSE_get0_name, X509_PURPOSE_get0_sname, X509_PURPOSE_get_trust — purpose objects, indices, and identifiers. That's the whole cast. 👑

---

🦋 SYNOPSIS 🦋

Library is libcrypto, and you're gonna need this include:

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

Here's the function lineup, literally all of it:

int
X509_PURPOSE_set(int *id_out, int id_in);

int
X509_PURPOSE_get_by_id(int identifier);

int
X509_PURPOSE_add(int identifier, int trust, int flags,
    int (*check_purpose)(const X509_PURPOSE *, const X509 *, int),
    const char *name, const char *sname, void *usr_data);

int
X509_PURPOSE_get_count(void);

void
X509_PURPOSE_cleanup(void);

X509_PURPOSE *
X509_PURPOSE_get0(int index);

int
X509_PURPOSE_get_by_sname(const char *sname);

int
X509_PURPOSE_get_id(const X509_PURPOSE *object);

char *
X509_PURPOSE_get0_name(const X509_PURPOSE *object);

char *
X509_PURPOSE_get0_sname(const X509_PURPOSE *object);

int
X509_PURPOSE_get_trust(const X509_PURPOSE *object);

---

💅 DESCRIPTION 💅

The purposes that an X.509 certificate is intended to be used for can be identified in three equivalent ways. Not one, not two — three. 🌈

1. Purpose identifiers — positive integer constants. Standard purpose identifiers lie in the range from X509_PURPOSE_MIN to X509_PURPOSE_MAX, inclusive, and are listed in the X509_check_purpose(3) manual page. User-defined purpose identifiers are larger than X509_PURPOSE_MAX. 🍓
2. Purpose indices — non-negative integer constants, but they differ from the purpose identifiers for the same purpose. Standard purpose indices are smaller than X509_PURPOSE_MAX. User-defined purpose indices are larger than or equal to X509_PURPOSE_MAX. 🎀
3. Purpose objects of the type X509_PURPOSE. Standard purpose objects are available in static storage. User-defined purpose objects can be created with X509_PURPOSE_add(). 🦋

Application programmers cannot choose the way to identify purposes that they like best; depending on the circumstances, all three ways are needed. Be warned that the naming of most functions is misleading. 💀

Most API functions documented outside the present manual page use purpose identifiers rather than purpose indices. iykyk. 👑

🎯 Using purpose identifiers 🎯

• X509_PURPOSE_set() — validates the purpose identifier id_in. If it's valid, it gets copied to *id_out. Otherwise, *id_out remains unchanged. No sneaky overwrite. 💅
• X509_PURPOSE_get_by_id() — converts the purpose identifier to the corresponding purpose index. To find the corresponding purpose object, pass the result to X509_PURPOSE_get0(). 🔁
• X509_PURPOSE_add() — defines a purpose with the given identifier, or modifies its properties if it already exists. The purpose identifier, the trust identifier, the flags, the check_purpose function, the name, the short name sname, and the usr_data pointer are copied into the X509_PURPOSE object. When modifying an existing purpose object, previous values of fields are overwritten and previous name and sname strings are freed if they were dynamically allocated. When creating a new purpose object, it is added to the global array of user-defined purpose objects. 🛠️

Now the flags tea, because this is where it gets spicy. X509_PURPOSE_DYNAMIC and X509_PURPOSE_DYNAMIC_NAME are always ignored in the flags argument. X509_PURPOSE_DYNAMIC is automatically set if the object was created by the user. It is never set for standard objects, not even if they were modified by the user. X509_PURPOSE_DYNAMIC_NAME is automatically set if the object was created or modified by the user. It is only unset for unmodified standard objects. The library does not appear to define any other flags, so the flags argument is probably useless unless users define their own flags and use them in the check_purpose function. 🙈

The third and final argument of the check_purpose function is the ca argument documented in X509_check_purpose(3). 🫶

X509_PURPOSE_get_count() returns the total number of purposes currently defined, including both standard and user-defined purposes. If no user-defined purposes exist, the returned value is X509_PURPOSE_MAX. 📊

X509_PURPOSE_cleanup() deletes all user-defined purpose objects and invalidates their purpose identifiers and purpose indices. If any of the standard purpose objects were modified by the user, those changes are not reverted. 🧹

🔢 Using purpose indices 🔢

• X509_PURPOSE_get0() — converts the purpose index to a pointer to the corresponding purpose object. To find the corresponding purpose identifier, pass the result to X509_PURPOSE_get_id(). 🪄
• X509_PURPOSE_get_by_sname() — returns the lowest index of a purpose with the given short name. Lowkey the lowest. 💅

🧚 Using purpose objects 🧚

• X509_PURPOSE_get_id() — converts a pointer to a purpose object to the corresponding purpose identifier. To find the corresponding purpose index, pass the result to X509_PURPOSE_get_by_id(). 🔄
• X509_PURPOSE_get0_name(), X509_PURPOSE_get0_sname(), and X509_PURPOSE_get_trust() — retrieve the name, short name, and trust identifier from the object, respectively. 📛

---

💖 RETURN VALUES 💖

• X509_PURPOSE_set() — returns 1 if id_in is valid or 0 otherwise. ✅
• X509_PURPOSE_get_by_id() and X509_PURPOSE_get_by_sname() — return the corresponding purpose index or -1 if no matching purpose is found. 🔎
• X509_PURPOSE_add() — returns 1 for success or 0 for failure. 🎯
• X509_PURPOSE_get_count() — returns the total number of purposes currently defined. 📚
• X509_PURPOSE_get0() — returns a standard or user-defined purpose object or NULL if the index is invalid. 🫥
• X509_PURPOSE_get_id() — always returns a valid purpose identifier. 💯
• X509_PURPOSE_get0_name() and X509_PURPOSE_get0_sname() — return pointers to storage owned by the object. 🗝️
• X509_PURPOSE_get_trust() — returns the trust identifier associated with the object. 🤝

---

💀 ERRORS 💀

The following diagnostics can be retrieved with ERR_get_error(3), ERR_GET_REASON(3), and ERR_reason_error_string(3): 🚨

• X509V3_R_INVALID_PURPOSE "invalid purpose" — X509_PURPOSE_set() was called with an invalid id_in argument. 🙅
• X509V3_R_INVALID_NULL_ARGUMENT "invalid null argument" — X509_PURPOSE_add() was called with a name or sname argument of NULL. 🫠
• ERR_R_MALLOC_FAILURE "malloc failure" — X509_PURPOSE_add() failed to allocate memory. 😭

The other functions provide no diagnostics. 🤐

---

🌸 SEE ALSO 🌸

X509_check_purpose(3), X509_new(3), X509_STORE_set_purpose(3), X509_VERIFY_PARAM_set_purpose(3). Go read those next, bestie. 📚

---

🎀 HISTORY 🎀

X509_PURPOSE_set() first appeared in OpenSSL 0.9.7 and has been available since OpenBSD 3.2. 🕰️

The other functions first appeared in OpenSSL 0.9.5 and have been available since OpenBSD 2.7. 🦋

---

⚠️ CAVEATS ⚠️

The difference between purpose identifiers and purpose indices provides an ideal breeding ground for off-by-one bugs. 💀🔪 So keep your indices and identifiers straight, bestie. Not me warning you twice. 🙈

---

🫶 Debian, June 8, 2025 — that's the footer, bestie. X509_PURPOSE_SET(3) out. 💋