From: tb Date: Sat, 23 Oct 2021 15:41:10 +0000 (+0000) Subject: Import documentation for X509_get_extension_flags, X509_get_key_usage, X-Git-Url: http://artulab.com/gitweb/?a=commitdiff_plain;h=07fa46780d1dc8f106664c8669ba23101f10acce;p=openbsd Import documentation for X509_get_extension_flags, X509_get_key_usage, X509_get_extended_key_usage from OpenSSL. Will be linked to the build after the bump. input/lgtm schwarze --- diff --git a/lib/libcrypto/man/X509_get_extension_flags.3 b/lib/libcrypto/man/X509_get_extension_flags.3 new file mode 100644 index 00000000000..eec4f4ee277 --- /dev/null +++ b/lib/libcrypto/man/X509_get_extension_flags.3 @@ -0,0 +1,211 @@ +.\" $OpenBSD: X509_get_extension_flags.3,v 1.1 2021/10/23 15:41:10 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 . +.\" 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: October 23 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 will return one or +more of the following flags ored 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 will return zero or more of the 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 then +.Dv UINT32_MAX +is returned. +.Pp +.Fn X509_get_extended_key_usage +returns the value of the extended key usage extension. +If extended key usage is present it will return zero or more of the +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 X509_check_purpose 3 , +.Xr X509_get_ext_d2i 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 .