X509_CHECK_PURPOSE(3ossl)

💖 X509_CHECK_PURPOSE(3ossl) — bestie's guide to cert purpose checking 💖

okay so this is the 3ossl page for the OpenSSL purpose-checking girlies ✨ — all the X509_PURPOSE_* functions, no cap. It's giving "I need to know what this certificate was literally made for" and honestly? Iconic.

✨ NAME ✨

X509_check_purpose, X509_PURPOSE_get_count, X509_PURPOSE_get_unused_id, X509_PURPOSE_get_by_sname, X509_PURPOSE_get_by_id, X509_PURPOSE_add, X509_PURPOSE_cleanup, X509_PURPOSE_get0, X509_PURPOSE_get_id, X509_PURPOSE_get0_name, X509_PURPOSE_get0_sname, X509_PURPOSE_get_trust, X509_PURPOSE_set — functions related to checking the purpose of a certificate 🎀

🌸 SYNOPSIS 🌸

#include <openssl/x509v3.h>

int X509_check_purpose(X509 *x, int id, int ca);

int X509_PURPOSE_get_count(void);
int X509_PURPOSE_get_unused_id(OSSL_LIB_CTX *libctx);
int X509_PURPOSE_get_by_sname(const char *sname);
int X509_PURPOSE_get_by_id(int id);
int X509_PURPOSE_add(int id, int trust, int flags,
                     int (*ck) (const X509_PURPOSE *, const X509 *, int),
                     const char *name, const char *sname, void *arg);
void X509_PURPOSE_cleanup(void);

X509_PURPOSE *X509_PURPOSE_get0(int idx);
int X509_PURPOSE_get_id(const X509_PURPOSE *);
char *X509_PURPOSE_get0_name(const X509_PURPOSE *xp);
char *X509_PURPOSE_get0_sname(const X509_PURPOSE *xp);
int X509_PURPOSE_get_trust(const X509_PURPOSE *xp);
int X509_PURPOSE_set(int *p, int purpose);

🦋 DESCRIPTION 🦋

💅 the main character: `X509_check_purpose`

X509_check_purpose() checks if certificate x was created with the purpose represented by id. vibe check for certs, basically 🫶

If ca is nonzero, then certificate x is checked to determine if it's a possible CA with various levels of certainty possibly returned. (yes bestie, levels of certainty — we'll get to those numbers in a sec, they're a whole thing 😭)

the certificate x must be a complete certificate, otherwise the function returns an error. no half-finished slay, we need the full look 💀

Below are the potential ID's that can be checked — memorize these, they come up:

# define X509_PURPOSE_SSL_CLIENT        1
# define X509_PURPOSE_SSL_SERVER        2
# define X509_PURPOSE_NS_SSL_SERVER     3
# define X509_PURPOSE_SMIME_SIGN        4
# define X509_PURPOSE_SMIME_ENCRYPT     5
# define X509_PURPOSE_CRL_SIGN          6
# define X509_PURPOSE_ANY               7
# define X509_PURPOSE_OCSP_HELPER       8
# define X509_PURPOSE_TIMESTAMP_SIGN    9
# define X509_PURPOSE_CODE_SIGN        10

The checks performed take into account the X.509 extensions keyUsage, extendedKeyUsage, and basicConstraints. that's the trio, periodt ✨

🌈 the purpose-table management girlies

X509_PURPOSE_get_count() returns the number of currently defined purposes.
X509_PURPOSE_get_unused_id() returns the smallest purpose id not yet used, which is guaranteed to be unique and larger than X509_PURPOSE_MAX. The libctx parameter should be used to provide the library context. It is currently ignored as the purpose mapping table is global. (so yeah, you pass it, and it's like "mmhmm" 🙈)
X509_PURPOSE_get_by_sname() returns the index of the purpose with the given short name or -1 if not found.
X509_PURPOSE_get_by_id() returns the index of the purpose with the given id or -1 if not found.
X509_PURPOSE_add() adds or modifies a purpose entry identified by sname.

Unless the id stays the same for an existing entry, id must be fresh — which can be achieved by using the result of X509_PURPOSE_get_unused_id().

The function also sets in the entry: the trust id trust, the given flags, the purpose (long) name name, the short name sname, the purpose checking funktion ck of type int (*) (const X509_PURPOSE *, const X509 *, int), and its user data arg which may be retrieved via the X509_PURPOSE pointer. (yes, "funktion" with a k — that's what the page says, we don't fix, we respect 💜)

X509_PURPOSE_cleanup() removes all purposes that are not pre-defined. bye bye custom entries 👋

🧚 the getters, aka the "just tell me about this struct" girlies

X509_PURPOSE_get0() returns an X509_PURPOSE pointer or NULL on error.
X509_PURPOSE_get_id() returns the id of the given X509_PURPOSE structure.
X509_PURPOSE_get0_name() returns the (long) name of the given X509_PURPOSE.
X509_PURPOSE_get0_sname() returns the short name of the given X509_PURPOSE.
X509_PURPOSE_get_trust() returns the trust id of the given X509_PURPOSE.

🍓 `X509_PURPOSE_set`

X509_PURPOSE_set() assigns the given purpose id to the location pointed at by p. This resets to the any purpose if purpose is X509_PURPOSE_DEFAULT_ANY. lowkey a little plot twist but okay 💅

🔥 RETURN VALUES 🔥

💖 `X509_check_purpose()` — for non-CA checks

-1 — an error condition has occurred 😭
1 — if the certificate was created to perform the purpose represented by id
0 — if the certificate was not created to perform the purpose represented by id

👑 `X509_check_purpose()` — for CA checks

the below integers could be returned with the following meanings:

-1 — an error condition has occurred
0 — not a CA or does not have the purpose represented by id
1 — is a CA.
2 — Only possible in old versions of openSSL when basicConstraints are absent. New versions will not return this value. May be a CA
3 — basicConstraints absent but self signed V1.
4 — basicConstraints absent but keyUsage present and keyCertSign asserted.
5 — legacy Netscape specific CA Flags present

ngl numbers 2 through 5 are giving "archaeology dig" 🏺 — but they're real return values, so know them.

🌟 everything else

X509_PURPOSE_get_count() returns the number of currently defined purposes.
X509_PURPOSE_get_unused_id() returns the smallest purpose id not yet used.
X509_PURPOSE_get_by_sname() returns the index of the purpose with the given short name or -1 if not found.
X509_PURPOSE_get_by_id() returns the index of the purpose with the given id or -1 if not found.
int X509_PURPOSE_add() returns 1 on success, 0 on error.
X509_PURPOSE_cleanup() does not return anything. it's a void girlie, no receipts 🎀
X509_PURPOSE_get0() returns an X509_PURPOSE pointer or NULL on error.
X509_PURPOSE_get_id() returns the id of the given X509_PURPOSE structure.
X509_PURPOSE_get0_name() returns the (long) name of the given X509_PURPOSE.
X509_PURPOSE_get0_sname() returns the short name of the given X509_PURPOSE.
X509_PURPOSE_get_trust() returns the trust id of the given X509_PURPOSE.
X509_PURPOSE_set() returns 1 on success, 0 on error.

💀 BUGS 💀

The X509_PURPOSE implementation so far is not thread-safe. There may be race conditions retrieving purpose information while X509_PURPOSE_add() or X509_PURPOSE_cleanup(void) is being called.

fr fr, do not read purpose info while someone else is adding or cleaning up purposes. that's the cursed combo 🙈 protect your threads bestie.

⭐ HISTORY ⭐

X509_PURPOSE_get_unused_id() was added in OpensSL 3.5. (yes, "OpensSL" — that's how it's written here, we're not editing the historical record 💜)

🎀 COPYRIGHT 🎀

Licensed under the Apache License 2.0 (the "License"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at <https://www.openssl.org/source/license.html>.

🌈💅 and that's the whole page, bestie — this was X509_CHECK_PURPOSE(3ossl) from OpenSSL 3.5.0, dated 2026-09-25. slay, go check some purposes 🫶✨

📦 where this page comes from

opensuse-leap 16.0: openssl-3-doc 3.5.0-160000.11.1 · Apache-2.0
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms

X509_CHECK_PURPOSE(3ossl)