libcrypto/man/X509_get_extension_flags.3

.\" $OpenBSD: X509_get_extension_flags.3,v 1.4 2023/04/30 19:40:23 tb 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 <steve@openssl.org>.
.\" 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: April 30 2023 $
.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.
In LibreSSL this flag is never set.
.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 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 .