X509_GET_EXTENSION_FLAGS(3ossl)

📦 version 3.5.0, in opensuse-leap 16.0

💅 X509_GET_EXTENSION_FLAGS 💅

okay so bestie, this is the X509_GET_EXTENSION_FLAGS page straight out of the OpenSSL manual (section 3ossl, if you're keeping notes 📝) — and it's literally the cheat sheet for all the certificate extension data you can pull out of an X509 without doing the ASN.1 archaeology yourself. no cap, it's a whole vibe. let's go 🫶

✨ NAME ✨

X509_get0_subject_key_id, X509_get0_authority_key_id, X509_get0_authority_issuer, X509_get0_authority_serial, X509_get_pathlen, X509_get_extension_flags, X509_get_key_usage, X509_get_extended_key_usage, X509_set_proxy_flag, X509_set_proxy_pathlen, X509_get_proxy_pathlen — retrieve certificate extension data 🎀

🦋 SYNOPSIS 🦋

#include <openssl/x509v3.h>

long X509_get_pathlen(X509 *x);
uint32_t X509_get_extension_flags(X509 *x);
uint32_t X509_get_key_usage(X509 *x);
uint32_t X509_get_extended_key_usage(X509 *x);
const ASN1_OCTET_STRING *X509_get0_subject_key_id(X509 *x);
const ASN1_OCTET_STRING *X509_get0_authority_key_id(X509 *x);
const GENERAL_NAMES *X509_get0_authority_issuer(X509 *x);
const ASN1_INTEGER *X509_get0_authority_serial(X509 *x);
void X509_set_proxy_flag(X509 *x);
void X509_set_proxy_pathlen(int l);
long X509_get_proxy_pathlen(X509 *x);

🌸 DESCRIPTION 🌸

okay so all of these functions are out here grabbing info about the certificate extensions that literally everyone uses. it's giving "greatest hits album" 🎵

X509_get_pathlen() snags the path length extension off a certificate. like, this extension is the thing that limits how long a cert chain can be that gets issued from that CA. it's the bouncer checking how long the line can get 💅

X509_get_extension_flags() grabs the general 411 on a certificate. it hands you back one or more of the following flags, ored together (yes, ored, that's a word now):

  • EXFLAG_V1 — the cert is a version 1 certificate, aka obsolete, aka ancient history 👵
  • EXFLAG_BCONS — the cert has a basic constraints extension in it
  • EXFLAG_CA — the cert has basic constraints AND asserts the CA flag. main character CA energy 👑
  • EXFLAG_PROXY — this is a valid proxy certificate
  • EXFLAG_SI — the cert is self issued, meaning the subject and issuer names match (bestie, the cert is issuing itself, iconic)
  • EXFLAG_SS — subject and issuer names match and the extension values imply it's self signed. the full package ✨
  • EXFLAG_FRESHEST — the freshest CRL extension is present in the cert (yes, it's literally called "freshest", we love that for it)
  • EXFLAG_CRITICAL — the cert contains an unhandled critical extension. 🚨
  • EXFLAG_INVALID — some certificate extension values are invalid or inconsistent. the certificate should be rejected. and heads up: this bit may also get raised after an out-of-memory error while processing the X509 object, so it might not even be about the ASN1 object you processed. it's not always the cert's fault, but you still gotta reject it 💀
  • EXFLAG_NO_FINGERPRINT — failed to compute the internal SHA1 hash value of the certificate or CRL. could be a malloc failure, could be that no SHA1 implementation was found at all. either way, no fingerprint for you 🙈
  • EXFLAG_INVALID_POLICY — the NID_certificate_policies certificate extension is invalid or inconsistent. the certificate should be rejected. same caveat as before: this bit may also be raised after an out-of-memory error while processing the X509 object, so it may not be related to the processed ASN1 object itself.
  • EXFLAG_KUSAGE — the cert has a key usage extension, and you can grab the value with X509_get_key_usage()
  • EXFLAG_XKUSAGE — the cert has an extended key usage extension, and the value comes from X509_get_extended_key_usage()

X509_get_key_usage() returns the value of the key usage extension. if key usage is present, it'll give you zero or more of these flags: KU_DIGITAL_SIGNATURE, KU_NON_REPUDIATION, KU_KEY_ENCIPHERMENT, KU_DATA_ENCIPHERMENT, KU_KEY_AGREEMENT, KU_KEY_CERT_SIGN, KU_CRL_SIGN, KU_ENCIPHER_ONLY or KU_DECIPHER_ONLY — each one mapping to an individual key usage bit. but if key usage is absent, you get UINT32_MAX back. not zero. UINT32_MAX. remember that, it's the whole trick 🎯

X509_get_extended_key_usage() returns the value of the extended key usage extension. if extended key usage is present, it'll return zero or more of these: XKU_SSL_SERVER, XKU_SSL_CLIENT, XKU_SMIME, XKU_CODE_SIGN, XKU_OCSP_SIGN, XKU_TIMESTAMP, XKU_DVCS or XKU_ANYEKU. those correspond to the OIDs id-kp-serverAuth, id-kp-clientAuth, id-kp-emailProtection, id-kp-codeSigning, id-kp-OCSPSigning, id-kp-timeStamping, id-kp-dvcs and anyExtendedKeyUsage respectively. oh and bonus: XKU_SGC gets set if either the Netscape or Microsoft SGC OIDs are present 🌈

X509_get0_subject_key_id() hands you an internal pointer to the subject key identifier of x as an ASN1_OCTET_STRING, or NULL if the extension isn't there or can't be parsed.

X509_get0_authority_key_id() — same deal, internal pointer to the authority key identifier of x as an ASN1_OCTET_STRING, or NULL if the extension isn't there or can't be parsed.

X509_get0_authority_issuer() — internal pointer to the authority certificate issuer of x as a stack of GENERAL_NAME structures, or NULL if the extension isn't there or can't be parsed.

X509_get0_authority_serial() — internal pointer to the authority certificate serial number of x as an ASN1_INTEGER, or NULL if the extension isn't there or can't be parsed.

X509_set_proxy_flag() marks the certificate with the EXFLAG_PROXY flag. this one's for the users who need to mark non-RFC3820 proxy certificates as proxy, because OpenSSL only detects the RFC3820-compliant ones on its own. it can't read their minds 🧚

X509_set_proxy_pathlen() sets the proxy certificate path length for the given certificate x. again: for the users who need to mark non-RFC3820 proxy certificates as such, since OpenSSL only detects the RFC3820 compliant ones.

X509_get_proxy_pathlen() returns the proxy certificate path length for the given certificate x — but only if it's a proxy certificate, obviously.

💜 NOTES 💜

the values of those flags correspond to extension values that are cached inside the X509 structure. so if the flags you got back don't give you enough info, an application should go examine the extension values directly — for example using X509_get_ext_d2i().

if the key usage or extended key usage extension is absent, then typically usage is unrestricted. that's literally why X509_get_key_usage() and X509_get_extended_key_usage() return UINT32_MAX when the corresponding extension is absent. it's not an error, it's "no rules, free spirit" 🦋 applications can additionally check the return value of X509_get_extension_flags() and take appropriate action if an extension is absent.

if X509_get0_subject_key_id() returns NULL, then the extension may be absent or malformed — you genuinely can't tell from that alone. applications can determine the precise reason using X509_get_ext_d2i(). iykyk 🔍

⭐ RETURN VALUES ⭐

  • X509_get_pathlen() returns the path length value, or -1 if the extension isn't present.
  • X509_get_extension_flags(), X509_get_key_usage() and X509_get_extended_key_usage() return sets of flags corresponding to the certificate extension values.
  • X509_get0_subject_key_id() returns the subject key identifier as a pointer to an ASN1_OCTET_STRING structure, or NULL if the extension is absent or an error occurred during parsing.
  • X509_get_proxy_pathlen() returns the path length value if the given certificate is a proxy one and has a path length set, and -1 otherwise.
lowkey the -1 and the NULL and the UINT32_MAX are all doing different jobs, don't mix them up bestie 😭

🎀 SEE ALSO 🎀

X509_check_purpose(3)

🔥 HISTORY 🔥

X509_get_pathlen(), X509_set_proxy_flag(), X509_set_proxy_pathlen() and X509_get_proxy_pathlen() were added in OpenSSL 1.1.0. the OGs 🫡

Copyright 2015-2021 The OpenSSL Project Authors. All Rights Reserved.

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>.

okay that's the whole thing, go read your certs 💖 mwah 💋 — this was OpenSSL 3.5.0, dated 2026-09-25, and that's the X509_GET_EXTENSION_FLAGS(3ossl) page, periodt 🌈✨

📦 where this page comes from