1.\" $OpenBSD: X509_get_extension_flags.3,v 1.3 2021/11/11 13:58:59 schwarze Exp $ 2.\" full merge up to: OpenSSL 361136f4 Sep 1 18:56:58 2015 +0100 3.\" selective merge up to: OpenSSL 2b2e3106f Feb 16 15:04:45 2021 +0000 4.\" 5.\" This file was written by Dr. Stephen Henson <steve@openssl.org>. 6.\" Copyright (c) 2015 The OpenSSL Project. All rights reserved. 7.\" 8.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: 11.\" 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 15.\" 2. Redistributions in binary form must reproduce the above copyright 16.\" notice, this list of conditions and the following disclaimer in 17.\" the documentation and/or other materials provided with the 18.\" distribution. 19.\" 20.\" 3. All advertising materials mentioning features or use of this 21.\" software must display the following acknowledgment: 22.\" "This product includes software developed by the OpenSSL Project 23.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 24.\" 25.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 26.\" endorse or promote products derived from this software without 27.\" prior written permission. For written permission, please contact 28.\" openssl-core@openssl.org. 29.\" 30.\" 5. Products derived from this software may not be called "OpenSSL" 31.\" nor may "OpenSSL" appear in their names without prior written 32.\" permission of the OpenSSL Project. 33.\" 34.\" 6. Redistributions of any form whatsoever must retain the following 35.\" acknowledgment: 36.\" "This product includes software developed by the OpenSSL Project 37.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 38.\" 39.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 40.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 41.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 42.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 43.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 44.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 45.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 46.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 47.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 48.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 49.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 50.\" OF THE POSSIBILITY OF SUCH DAMAGE. 51.\" 52.Dd $Mdocdate: November 11 2021 $ 53.Dt X509_GET_EXTENSION_FLAGS 3 54.Os 55.Sh NAME 56.Nm X509_get_extension_flags , 57.Nm X509_get_key_usage , 58.Nm X509_get_extended_key_usage 59.Nd retrieve certificate extension data 60.Sh SYNOPSIS 61.In openssl/x509v3.h 62.Ft uint32_t 63.Fo X509_get_extension_flags 64.Fa "X509 *x" 65.Fc 66.Ft uint32_t 67.Fo X509_get_key_usage 68.Fa "X509 *x" 69.Fc 70.Ft uint32_t 71.Fo X509_get_extended_key_usage 72.Fa "X509 *x" 73.Fc 74.Sh DESCRIPTION 75These functions retrieve information related to commonly used 76certificate extensions. 77.Pp 78.Fn X509_get_extension_flags 79retrieves general information about a certificate. 80It returns one or more of the following flags OR'ed together. 81.Bl -tag -width Ds 82.It Dv EXFLAG_V1 83The certificate is an obsolete version 1 certificate. 84.It Dv EXFLAG_BCONS 85The certificate contains a basic constraints extension. 86.It Dv EXFLAG_CA 87The certificate contains basic constraints and asserts the CA flag. 88.It Dv EXFLAG_PROXY 89The certificate is a valid proxy certificate. 90.It Dv EXFLAG_SI 91The certificate is self issued (that is subject and issuer names match). 92.It Dv EXFLAG_SS 93The subject and issuer names match and extension values imply it is self 94signed. 95.It Dv EXFLAG_FRESHEST 96The freshest CRL extension is present in the certificate. 97.It Dv EXFLAG_CRITICAL 98The certificate contains an unhandled critical extension. 99.It Dv EXFLAG_INVALID 100Some certificate extension values are invalid or inconsistent. 101The certificate should be rejected. 102This bit may also be raised after an out-of-memory error while 103processing the X509 object, so it may not be related to the processed 104ASN1 object itself. 105.\" EXFLAG_NO_FINGERPRINT is not available in LibreSSL. Do we need 106.\" https://github.com/openssl/openssl/issues/13698 and the fix it fixes? 107.\".It Dv EXFLAG_NO_FINGERPRINT 108.\" Failed to compute the internal SHA1 hash value of the certificate. 109.\" This may be due to malloc failure or because no SHA1 implementation was 110.\" found. 111.It Dv EXFLAG_INVALID_POLICY 112The 113.Dv NID_certificate_policies 114certificate extension is invalid or inconsistent. 115The certificate should be rejected. 116This bit may also be raised after an out-of-memory error while 117processing the X509 object, so it may not be related to the processed 118ASN1 object itself. 119.It Dv EXFLAG_KUSAGE 120The certificate contains a key usage extension. 121The value can be retrieved using 122.Fn X509_get_key_usage . 123.It Dv EXFLAG_XKUSAGE 124The certificate contains an extended key usage extension. 125The value can be retrieved using 126.Fn X509_get_extended_key_usage . 127.El 128.Pp 129.Fn X509_get_key_usage 130returns the value of the key usage extension. 131If key usage is present, it returns zero or more of these flags: 132.Dv KU_DIGITAL_SIGNATURE , 133.Dv KU_NON_REPUDIATION , 134.Dv KU_KEY_ENCIPHERMENT , 135.Dv KU_DATA_ENCIPHERMENT , 136.Dv KU_KEY_AGREEMENT , 137.Dv KU_KEY_CERT_SIGN , 138.Dv KU_CRL_SIGN , 139.Dv KU_ENCIPHER_ONLY , 140or 141.Dv KU_DECIPHER_ONLY , 142corresponding to individual key usage bits. 143If key usage is absent, 144.Dv UINT32_MAX 145is returned. 146.Pp 147The following aliases for these flags are defined in 148.In openssl/x509.h : 149.Dv X509v3_KU_DIGITAL_SIGNATURE , 150.Dv X509v3_KU_NON_REPUDIATION , 151.Dv X509v3_KU_KEY_ENCIPHERMENT , 152.Dv X509v3_KU_DATA_ENCIPHERMENT , 153.Dv X509v3_KU_KEY_AGREEMENT , 154.Dv X509v3_KU_KEY_CERT_SIGN , 155.Dv X509v3_KU_CRL_SIGN , 156.Dv X509v3_KU_ENCIPHER_ONLY , 157and 158.Dv X509v3_KU_DECIPHER_ONLY . 159.\" X509v3_KU_UNDEF is intentionally undocumented because nothing uses it. 160.Pp 161.Fn X509_get_extended_key_usage 162returns the value of the extended key usage extension. 163If extended key usage is present, it returns zero or more of these 164flags: 165.Dv XKU_SSL_SERVER , 166.Dv XKU_SSL_CLIENT , 167.Dv XKU_SMIME , 168.Dv XKU_CODE_SIGN 169.Dv XKU_OCSP_SIGN , 170.Dv XKU_TIMESTAMP , 171.Dv XKU_DVCS , 172or 173.Dv XKU_ANYEKU . 174These correspond to the OIDs 175.Qq id-kp-serverAuth , 176.Qq id-kp-clientAuth , 177.Qq id-kp-emailProtection , 178.Qq id-kp-codeSigning , 179.Qq id-kp-OCSPSigning , 180.Qq id-kp-timeStamping , 181.Qq id-kp-dvcs , 182and 183.Qq anyExtendedKeyUsage , 184respectively. 185Additionally, 186.Dv XKU_SGC 187is set if either Netscape or Microsoft SGC OIDs are present. 188.Pp 189The value of the flags correspond to extension values which are cached 190in the 191.Vt X509 192structure. 193If the flags returned do not provide sufficient information, 194an application should examine extension values directly, 195for example using 196.Xr X509_get_ext_d2i 3 . 197.Pp 198If the key usage or extended key usage extension is absent then 199typically usage is unrestricted. 200For this reason 201.Fn X509_get_key_usage 202and 203.Fn X509_get_extended_key_usage 204return 205.Dv UINT32_MAX 206when the corresponding extension is absent. 207Applications can additionally check the return value of 208.Fn X509_get_extension_flags 209and take appropriate action if an extension is absent. 210.Sh RETURN VALUES 211.Fn X509_get_extension_flags , 212.Fn X509_get_key_usage 213and 214.Fn X509_get_extended_key_usage 215return sets of flags corresponding to the certificate extension values. 216.Sh SEE ALSO 217.Xr BASIC_CONSTRAINTS_new 3 , 218.Xr EXTENDED_KEY_USAGE_new 3 , 219.Xr POLICYINFO_new 3 , 220.Xr PROXY_CERT_INFO_EXTENSION_new 3 , 221.Xr X509_check_ca 3 , 222.Xr X509_check_purpose 3 , 223.Xr X509_EXTENSION_new 3 , 224.Xr X509_get_ext_d2i 3 , 225.Xr X509_get_subject_name 3 , 226.Xr X509_get_version 3 , 227.Xr X509_new 3 228.Sh HISTORY 229.Nm X509_get_extension_flags , 230.Nm X509_get_key_usage , 231and 232.Nm X509_get_extended_key_usage 233first appeared in OpenSSL 1.1.0 and have been available since 234.Ox 7.1 . 235