--- name: "libressl-X509_check_purpose" section: "3" platform: "linux" package: "libressl" version: "4.4.0-1" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/libressl-X509_check_purpose" --- # libressl-X509\_check\_purpose(3) check intended usage of a public key ## NAME **X509\_check\_purpose** – check intended usage of a public key ## SYNOPSIS Crypto Library (libcrypto, -lcrypto) **#include \** *int*\ **X509\_check\_purpose**(*X509 \*certificate*, *int purpose*, *int ca*); ## DESCRIPTION If the *purpose* argument is -1, **X509\_check\_purpose**() ignores the *ca* argument and checks that all the extensions of the *certificate* can be parsed and pass minimal sanity checks, ensuring that no extension occurs more than once. It also makes sure that all extensions are cached in the *X509* object. If the *purpose* argument is not -1 and the *ca* flag is 0, **X509\_check\_purpose**() also checks whether the public key contained in the *certificate* is intended to be used for the given *purpose*, which can be one of the following integer constants. The check succeeds if none of the conditions given in the list below are violated. It always fails if parsing fails for any extension contained in the *certificate*. - X509\_PURPOSE\_SSL\_CLIENT - If the *certificate* contains an Extended Key Usage extension, it contains the RFC 5280 “TLS WWW client authentication” purpose (NID\_client\_auth). - If the *certificate* contains a Key Usage extension, the digitalSignature bit is set. - If the *certificate* contains a Netscape Cert Type extension, the “SSL client certificate” bit is set (NS\_SSL\_CLIENT). - X509\_PURPOSE\_SSL\_SERVER - If the *certificate* contains an Extended Key Usage extension, it contains the RFC 5280 “TLS WWW server authentication” purpose (NID\_server\_auth) or the private “Netscape Server Gated Crypto” (NID\_ns\_sgc) or “Microsoft Server Gated Crypto” (NID\_ms\_sgc) purpose. - If the *certificate* contains a Key Usage extension, at least one of the digitalSignature and keyEncipherment bits is set. - If the *certificate* contains a Netscape Cert Type extension, the “SSL server certificate” bit is set (NS\_SSL\_SERVER) - X509\_PURPOSE\_NS\_SSL\_SERVER This does the same checks as X509\_PURPOSE\_SSL\_SERVER and additionally requires that a Key Usage extension, if present, has the keyEncipherment bit set. - X509\_PURPOSE\_SMIME\_SIGN - If the *certificate* contains an Extended Key Usage extension, it contains the RFC 5280 “Email protection” purpose (NID\_email\_protect). - If the *certificate* contains a Key Usage extension, at least one of the digitalSignature and nonRepudiation bits is set. - If the *certificate* contains a Netscape Cert Type extension, it has the “S/MIME certificate” bit set. If the “SSL client certificate” bit is set but the “S/MIME certificate” bit is not, no decision is made. - X509\_PURPOSE\_SMIME\_ENCRYPT - If the *certificate* contains an Extended Key Usage extension, it contains the RFC 5280 “Email protection” purpose (NID\_email\_protect). - If the *certificate* contains a Key Usage extension, the keyEncipherment bit is set. - If the *certificate* contains a Netscape Cert Type extension, it has the “S/MIME certificate” bit set. If the “SSL client certificate” bit is set but the “S/MIME certificate” bit is not, no decision is made. - X509\_PURPOSE\_CRL\_SIGN - If the *certificate* contains a Key Usage extension, the cRLSign bit is set. - X509\_PURPOSE\_ANY Nothing is required except that, if any extensions are present, parsing them needs to succeed. - X509\_PURPOSE\_OCSP\_HELPER Nothing is required except that, if any extensions are present, parsing them needs to succeed. The application program is expected to do the actual checking by other means. - X509\_PURPOSE\_TIMESTAMP\_SIGN - The *certificate* contains an Extended Key Usage extension containing the RFC 5280 “Time Stamping” purpose and no other purpose. This extension is marked as critical. - If the *certificate* contains a Key Usage extension, at least one of the digitalSignature and nonRepudiation bits is set, and no other bits are set. If the *purpose* argument is not -1 and the *ca* flag is non-zero, **X509\_check\_purpose**() instead checks, in addition to the minimal sanity checks, whether the *certificate* can be used as a certificate authority certificate in the context of the given *purpose*. To succeed, the check always requires that none of the following conditions are violated: - If the *certificate* contains any extensions, parsing them succeeds. - If the *certificate* contains a Key Usage extension, the keyCertSign bit is set. - If the *certificate* contains a Basic Constraints extension, the *cA* field is set. - If the *certificate* is a version 1 certificate, the subject name matches the issuer name and the certificate is self signed. The check succeeds if none of the additional conditions given in the list below are violated. - X509\_PURPOSE\_SSL\_CLIENT - If the *certificate* contains an Extended Key Usage extension, it contains the RFC 5280 “TLS WWW client authentication” purpose (NID\_client\_auth). - If the *certificate* is not a version 1 certificate and does not contain a Basic Constraints extension, it contains a Key Usage extension with the keyCertSign bit set or a Netscape Cert Type extension with the “SSL CA certificate” bit set. - X509\_PURPOSE\_SSL\_SERVER or X509\_PURPOSE\_NS\_SSL\_SERVER - If the *certificate* contains an Extended Key Usage extension, it contains the RFC 5280 “TLS WWW server authentication” purpose (NID\_server\_auth) or the private “Netscape Server Gated Crypto” (NID\_ns\_sgc) or “Microsoft Server Gated Crypto” (NID\_ms\_sgc) purpose. - If the *certificate* is not a version 1 certificate and does not contain a Basic Constraints extension, it contains a Key Usage extension with the keyCertSign bit set or a Netscape Cert Type extension with the “SSL CA certificate” bit set. - X509\_PURPOSE\_SMIME\_SIGN or X509\_PURPOSE\_SMIME\_ENCRYPT - If the *certificate* contains an Extended Key Usage extension, it contains the RFC 5280 “Email protection” purpose (NID\_email\_protect). - If the *certificate* is not a version 1 certificate and does not contain a Basic Constraints extension, it contains a Key Usage extension with the keyCertSign bit set or a Netscape Cert Type extension with the “S/MIME CA certificate” bit set. - X509\_PURPOSE\_CRL\_SIGN, X509\_PURPOSE\_OCSP\_HELPER, or X509\_PURPOSE\_TIMESTAMP\_SIGN - If the *certificate* is not a version 1 certificate and does not contain a Basic Constraints extension, it contains a Key Usage extension with the keyCertSign bit set or a Netscape Cert Type extension with at least one of the “SSL CA certificate”, “S/MIME CA certificate”, or “Object-signing CA certificate” bits set. - X509\_PURPOSE\_ANY Nothing is required except that, if any extensions are present, parsing them needs to succeed. The check even succeeds if the three other common conditions cited above this list are violated. If the function X509\_PURPOSE\_add(3) was called before **X509\_check\_purpose**(), it may have installed different, user-supplied checking functions for some of the standard purposes listed above, or it may have installed additional, user-supplied checking functions for user-defined *purpose* identifiers not listed above. ## RETURN VALUES If the parsing of certificate extensions fails, sanity checks fail or the *purpose* is invalid, **X509\_check\_purpose**() returns -1 to indicate the error. If the *purpose* argument is -1 and parsing and minimal sanity checks succeed, **X509\_check\_purpose**() returns 1 to indicate success. Otherwise, it returns the following values: If *ca* is 0: | | | | | --- | --- | --- | | 0 | Failure | The | | 1 | Success | The | | 2 | Unknown | No decision can be made. | If *ca* is non-zero: | | | | | --- | --- | --- | | 0 | Failure | The | | 1 | Success | The | | 3 | Success | The *certificate* is a version 1 CA. | | 4 | Success | The Key Usage allows keyCertSign. | | 5 | Success | A Netscape Cert Type allows usage as a CA. | ## SEE ALSO BASIC\_CONSTRAINTS\_new(3), EXTENDED\_KEY\_USAGE\_new(3), X509\_new(3), X509\_PURPOSE\_set(3), X509V3\_get\_d2i(3), [x509v3.cnf(5)](/x509v3.cnf/5.md) ## STANDARDS RFC 5280: Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile - section 4.2.1.3: Key Usage - section 4.2.1.9: Basic Constraints - section 4.2.1.12: Extended Key Usage ## HISTORY **X509\_check\_purpose**() first appeared in OpenSSL 0.9.5 and has been available since OpenBSD 2.7.