.\" $OpenBSD: X509_get_extension_flags.3,v 1.3 2021/11/11 13:58:59 schwarze Exp $ .\" full merge up to: OpenSSL 361136f4 Sep 1 18:56:58 2015 +0100 .\" selective merge up to: OpenSSL 2b2e3106f Feb 16 15:04:45 2021 +0000 .\" .\" This file was written by Dr. Stephen Henson . .\" Copyright (c) 2015 The OpenSSL Project. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in .\" the documentation and/or other materials provided with the .\" distribution. .\" .\" 3. All advertising materials mentioning features or use of this .\" software must display the following acknowledgment: .\" "This product includes software developed by the OpenSSL Project .\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" .\" .\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to .\" endorse or promote products derived from this software without .\" prior written permission. For written permission, please contact .\" openssl-core@openssl.org. .\" .\" 5. Products derived from this software may not be called "OpenSSL" .\" nor may "OpenSSL" appear in their names without prior written .\" permission of the OpenSSL Project. .\" .\" 6. Redistributions of any form whatsoever must retain the following .\" acknowledgment: .\" "This product includes software developed by the OpenSSL Project .\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" .\" .\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY .\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR .\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" .Dd $Mdocdate: November 11 2021 $ .Dt X509_GET_EXTENSION_FLAGS 3 .Os .Sh NAME .Nm X509_get_extension_flags , .Nm X509_get_key_usage , .Nm X509_get_extended_key_usage .Nd retrieve certificate extension data .Sh SYNOPSIS .In openssl/x509v3.h .Ft uint32_t .Fo X509_get_extension_flags .Fa "X509 *x" .Fc .Ft uint32_t .Fo X509_get_key_usage .Fa "X509 *x" .Fc .Ft uint32_t .Fo X509_get_extended_key_usage .Fa "X509 *x" .Fc .Sh DESCRIPTION These functions retrieve information related to commonly used certificate extensions. .Pp .Fn X509_get_extension_flags retrieves general information about a certificate. It returns one or more of the following flags OR'ed together. .Bl -tag -width Ds .It Dv EXFLAG_V1 The certificate is an obsolete version 1 certificate. .It Dv EXFLAG_BCONS The certificate contains a basic constraints extension. .It Dv EXFLAG_CA The certificate contains basic constraints and asserts the CA flag. .It Dv EXFLAG_PROXY The certificate is a valid proxy certificate. .It Dv EXFLAG_SI The certificate is self issued (that is subject and issuer names match). .It Dv EXFLAG_SS The subject and issuer names match and extension values imply it is self signed. .It Dv EXFLAG_FRESHEST The freshest CRL extension is present in the certificate. .It Dv EXFLAG_CRITICAL The certificate contains an unhandled critical extension. .It Dv EXFLAG_INVALID Some certificate extension values are invalid or inconsistent. The certificate should be rejected. 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_NO_FINGERPRINT is not available in LibreSSL. Do we need .\" https://github.com/openssl/openssl/issues/13698 and the fix it fixes? .\".It Dv EXFLAG_NO_FINGERPRINT .\" Failed to compute the internal SHA1 hash value of the certificate. .\" This may be due to malloc failure or because no SHA1 implementation was .\" found. .It Dv EXFLAG_INVALID_POLICY The .Dv NID_certificate_policies certificate extension is invalid or inconsistent. The certificate should be rejected. 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. .It Dv EXFLAG_KUSAGE The certificate contains a key usage extension. The value can be retrieved using .Fn X509_get_key_usage . .It Dv EXFLAG_XKUSAGE The certificate contains an extended key usage extension. The value can be retrieved using .Fn X509_get_extended_key_usage . .El .Pp .Fn X509_get_key_usage returns the value of the key usage extension. If key usage is present, it returns zero or more of these flags: .Dv KU_DIGITAL_SIGNATURE , .Dv KU_NON_REPUDIATION , .Dv KU_KEY_ENCIPHERMENT , .Dv KU_DATA_ENCIPHERMENT , .Dv KU_KEY_AGREEMENT , .Dv KU_KEY_CERT_SIGN , .Dv KU_CRL_SIGN , .Dv KU_ENCIPHER_ONLY , or .Dv KU_DECIPHER_ONLY , corresponding to individual key usage bits. If key usage is absent, .Dv UINT32_MAX is returned. .Pp The following aliases for these flags are defined in .In openssl/x509.h : .Dv X509v3_KU_DIGITAL_SIGNATURE , .Dv X509v3_KU_NON_REPUDIATION , .Dv X509v3_KU_KEY_ENCIPHERMENT , .Dv X509v3_KU_DATA_ENCIPHERMENT , .Dv X509v3_KU_KEY_AGREEMENT , .Dv X509v3_KU_KEY_CERT_SIGN , .Dv X509v3_KU_CRL_SIGN , .Dv X509v3_KU_ENCIPHER_ONLY , and .Dv X509v3_KU_DECIPHER_ONLY . .\" X509v3_KU_UNDEF is intentionally undocumented because nothing uses it. .Pp .Fn X509_get_extended_key_usage returns the value of the extended key usage extension. If extended key usage is present, it returns zero or more of these flags: .Dv XKU_SSL_SERVER , .Dv XKU_SSL_CLIENT , .Dv XKU_SMIME , .Dv XKU_CODE_SIGN .Dv XKU_OCSP_SIGN , .Dv XKU_TIMESTAMP , .Dv XKU_DVCS , or .Dv XKU_ANYEKU . These correspond to the OIDs .Qq id-kp-serverAuth , .Qq id-kp-clientAuth , .Qq id-kp-emailProtection , .Qq id-kp-codeSigning , .Qq id-kp-OCSPSigning , .Qq id-kp-timeStamping , .Qq id-kp-dvcs , and .Qq anyExtendedKeyUsage , respectively. Additionally, .Dv XKU_SGC is set if either Netscape or Microsoft SGC OIDs are present. .Pp The value of the flags correspond to extension values which are cached in the .Vt X509 structure. If the flags returned do not provide sufficient information, an application should examine extension values directly, for example using .Xr X509_get_ext_d2i 3 . .Pp If the key usage or extended key usage extension is absent then typically usage is unrestricted. For this reason .Fn X509_get_key_usage and .Fn X509_get_extended_key_usage return .Dv UINT32_MAX when the corresponding extension is absent. Applications can additionally check the return value of .Fn X509_get_extension_flags and take appropriate action if an extension is absent. .Sh RETURN VALUES .Fn X509_get_extension_flags , .Fn X509_get_key_usage and .Fn X509_get_extended_key_usage return sets of flags corresponding to the certificate extension values. .Sh SEE ALSO .Xr BASIC_CONSTRAINTS_new 3 , .Xr EXTENDED_KEY_USAGE_new 3 , .Xr POLICYINFO_new 3 , .Xr PROXY_CERT_INFO_EXTENSION_new 3 , .Xr X509_check_ca 3 , .Xr X509_check_purpose 3 , .Xr X509_EXTENSION_new 3 , .Xr X509_get_ext_d2i 3 , .Xr X509_get_subject_name 3 , .Xr X509_get_version 3 , .Xr X509_new 3 .Sh HISTORY .Nm X509_get_extension_flags , .Nm X509_get_key_usage , and .Nm X509_get_extended_key_usage first appeared in OpenSSL 1.1.0 and have been available since .Ox 7.1 .