From eb8dd9dca1228af0cd132f515509051ecfabf6f6 Mon Sep 17 00:00:00 2001 From: cvs2svn Date: Mon, 14 Apr 2025 17:32:06 +0000 Subject: This commit was manufactured by cvs2git to create tag 'tb_20250414'. --- src/lib/libcrypto/man/X509_check_purpose.3 | 431 ----------------------------- 1 file changed, 431 deletions(-) delete mode 100644 src/lib/libcrypto/man/X509_check_purpose.3 (limited to 'src/lib/libcrypto/man/X509_check_purpose.3') diff --git a/src/lib/libcrypto/man/X509_check_purpose.3 b/src/lib/libcrypto/man/X509_check_purpose.3 deleted file mode 100644 index 8fea6679fc..0000000000 --- a/src/lib/libcrypto/man/X509_check_purpose.3 +++ /dev/null @@ -1,431 +0,0 @@ -.\" $OpenBSD: X509_check_purpose.3,v 1.12 2024/09/02 08:04:32 tb Exp $ -.\" -.\" Copyright (c) 2019, 2021 Ingo Schwarze -.\" -.\" Permission to use, copy, modify, and distribute this software for any -.\" purpose with or without fee is hereby granted, provided that the above -.\" copyright notice and this permission notice appear in all copies. -.\" -.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES -.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF -.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR -.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES -.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN -.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF -.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. -.\" -.Dd $Mdocdate: September 2 2024 $ -.Dt X509_CHECK_PURPOSE 3 -.Os -.Sh NAME -.Nm X509_check_purpose -.Nd check intended usage of a public key -.Sh SYNOPSIS -.In openssl/x509v3.h -.Ft int -.Fo X509_check_purpose -.Fa "X509 *certificate" -.Fa "int purpose" -.Fa "int ca" -.Fc -.Sh DESCRIPTION -If the -.Fa purpose -argument is \-1, -.Fn X509_check_purpose -ignores the -.Fa ca -argument and checks that all the extensions of the -.Fa 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 -.Vt X509 -object. -.Pp -If the -.Fa purpose -argument is not \-1 and the -.Fa ca -flag is 0, -.Fn X509_check_purpose -also checks whether the public key contained in the -.Fa certificate -is intended to be used for the given -.Fa 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 -.Fa certificate . -.Bl -tag -width 1n -.It Dv X509_PURPOSE_SSL_CLIENT -.Bl -dash -width 1n -compact -.It -If the -.Fa certificate -contains an Extended Key Usage extension, it contains the RFC 5280 -.Dq TLS WWW client authentication -purpose -.Pq Dv NID_client_auth . -.It -If the -.Fa certificate -contains a Key Usage extension, the -.Dv digitalSignature -bit is set. -.It -If the -.Fa certificate -contains a Netscape Cert Type extension, the -.Dq SSL client certificate -bit is set -.Pq Dv NS_SSL_CLIENT . -.El -.It Dv X509_PURPOSE_SSL_SERVER -.Bl -dash -width 1n -compact -.It -If the -.Fa certificate -contains an Extended Key Usage extension, it contains the RFC 5280 -.Dq TLS WWW server authentication -purpose -.Pq Dv NID_server_auth -or the private -.Dq Netscape Server Gated Crypto -.Pq Dv NID_ns_sgc -or -.Dq Microsoft Server Gated Crypto -.Pq Dv NID_ms_sgc -purpose. -.It -If the -.Fa certificate -contains a Key Usage extension, at least one of the -.Dv digitalSignature -and -.Dv keyEncipherment -bits is set. -.It -If the -.Fa certificate -contains a Netscape Cert Type extension, the -.Dq SSL server certificate -bit is set -.Pq Dv NS_SSL_SERVER -.El -.It Dv X509_PURPOSE_NS_SSL_SERVER -.\" check_purpose_ns_ssl_server, "Netscape SSL server" -This does the same checks as -.Dv X509_PURPOSE_SSL_SERVER -and additionally requires that a Key Usage extension, if present, -has the -.Dv keyEncipherment -bit set. -.It Dv X509_PURPOSE_SMIME_SIGN -.\" check_purpose_smime_sign, "S/MIME signing" -.Bl -dash -width 1n -compact -.It -If the -.Fa certificate -contains an Extended Key Usage extension, it contains the RFC 5280 -.Dq Email protection -purpose -.Pq Dv NID_email_protect . -.It -If the -.Fa certificate -contains a Key Usage extension, at least one of the -.Dv digitalSignature -and -.Dv nonRepudiation -bits is set. -.It -If the -.Fa certificate -contains a Netscape Cert Type extension, it has the -.Dq S/MIME certificate -bit set. -If the -.Dq SSL client certificate -bit is set but the -.Dq S/MIME certificate -bit is not, no decision is made. -.El -.It Dv X509_PURPOSE_SMIME_ENCRYPT -.\" check_purpose_smime_encrypt, "S/MIME encryption" -.Bl -dash -width 1n -compact -.It -If the -.Fa certificate -contains an Extended Key Usage extension, it contains the RFC 5280 -.Dq Email protection -purpose -.Pq Dv NID_email_protect . -.It -If the -.Fa certificate -contains a Key Usage extension, the -.Dv keyEncipherment -bit is set. -.It -If the -.Fa certificate -contains a Netscape Cert Type extension, it has the -.Dq S/MIME certificate -bit set. -If the -.Dq SSL client certificate -bit is set but the -.Dq S/MIME certificate -bit is not, no decision is made. -.El -.It Dv X509_PURPOSE_CRL_SIGN -.\" check_purpose_crl_sign, "CRL signing" -.Bl -dash -width 1n -compact -.It -If the -.Fa certificate -contains a Key Usage extension, the -.Dv cRLSign -bit is set. -.El -.It Dv X509_PURPOSE_ANY -Nothing is required except that, if any extensions are present, -parsing them needs to succeed. -.It Dv X509_PURPOSE_OCSP_HELPER -.\" ocsp_helper, "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. -.It Dv X509_PURPOSE_TIMESTAMP_SIGN -.\" check_purpose_timestamp_sign, "Time Stamp signing" -.Bl -dash -width 1n -compact -.It -The -.Fa certificate -contains an Extended Key Usage extension containing the RFC 5280 -.Dq Time Stamping -purpose and no other purpose. -This extension is marked as critical. -.It -If the -.Fa certificate -contains a Key Usage extension, at least one of the -.Dv digitalSignature -and -.Dv nonRepudiation -bits is set, and no other bits are set. -.El -.El -.Pp -If the -.Fa purpose -argument is not \-1 and the -.Fa ca -flag is non-zero, -.Fn X509_check_purpose -instead checks, in addition to the minimal sanity checks, whether the -.Fa certificate -can be used as a certificate authority certificate -in the context of the given -.Fa purpose . -To succeed, the check always requires that none of the following -conditions are violated: -.Pp -.Bl -dash -width 1n -compact -.It -If the -.Fa certificate -contains any extensions, parsing them succeeds. -.It -If the -.Fa certificate -contains a Key Usage extension, the -.Dv keyCertSign -bit is set. -.It -If the -.Fa certificate -contains a Basic Constraints extension, the -.Fa cA -field is set. -.It -If the -.Fa certificate -is a version 1 certificate, the subject name matches the issuer name -and the certificate is self signed. -.El -.Pp -The check succeeds if none of the additional conditions given in -the list below are violated. -.Bl -tag -width 1n -.It Dv X509_PURPOSE_SSL_CLIENT -.Bl -dash -width 1n -compact -.It -If the -.Fa certificate -contains an Extended Key Usage extension, it contains the RFC 5280 -.Dq TLS WWW client authentication -purpose -.Pq Dv NID_client_auth . -.It -If the -.Fa certificate -is not a version 1 certificate and does not contain a Basic Constraints -extension, it contains a Key Usage extension with the -.Dv keyCertSign -bit set or a Netscape Cert Type extension with the -.Dq SSL CA certificate -bit set. -.El -.It Dv X509_PURPOSE_SSL_SERVER No or Dv X509_PURPOSE_NS_SSL_SERVER -.Bl -dash -width 1n -compact -.It -If the -.Fa certificate -contains an Extended Key Usage extension, it contains the RFC 5280 -.Dq TLS WWW server authentication -purpose -.Pq Dv NID_server_auth -or the private -.Dq Netscape Server Gated Crypto -.Pq Dv NID_ns_sgc -or -.Dq Microsoft Server Gated Crypto -.Pq Dv NID_ms_sgc -purpose. -.It -If the -.Fa certificate -is not a version 1 certificate and does not contain a Basic Constraints -extension, it contains a Key Usage extension with the -.Dv keyCertSign -bit set or a Netscape Cert Type extension with the -.Dq SSL CA certificate -bit set. -.El -.It Dv X509_PURPOSE_SMIME_SIGN No or Dv X509_PURPOSE_SMIME_ENCRYPT -.Bl -dash -width 1n -compact -.It -If the -.Fa certificate -contains an Extended Key Usage extension, it contains the RFC 5280 -.Dq Email protection -purpose -.Pq Dv NID_email_protect . -.It -If the -.Fa certificate -is not a version 1 certificate and does not contain a Basic Constraints -extension, it contains a Key Usage extension with the -.Dv keyCertSign -bit set or a Netscape Cert Type extension with the -.Dq S/MIME CA certificate -bit set. -.El -.It Xo -.Dv X509_PURPOSE_CRL_SIGN , -.Dv X509_PURPOSE_OCSP_HELPER , -or -.Dv X509_PURPOSE_TIMESTAMP_SIGN -.Xc -.Bl -dash -width 1n -compact -.It -If the -.Fa certificate -is not a version 1 certificate and does not contain a Basic Constraints -extension, it contains a Key Usage extension with the -.Dv keyCertSign -bit set or a Netscape Cert Type extension with at least one of the -.Dq SSL CA certificate , -.Dq S/MIME CA certificate , -or -.Dq Object-signing CA certificate -bits set. -.El -.It Dv 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. -.El -.Pp -If the function -.Xr X509_PURPOSE_add 3 -was called before -.Fn 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 -.Fa purpose -identifiers not listed above. -.Sh RETURN VALUES -If the parsing of certificate extensions fails, sanity checks fail or the -.Fa purpose -is invalid, -.Fn X509_check_purpose -returns \-1 to indicate the error. -.Pp -If the -.Fa purpose -argument is \-1 and parsing and minimal sanity checks succeed, -.Fn X509_check_purpose -returns 1 to indicate success. -.Pp -Otherwise, it returns the following values: -.Pp -If -.Fa ca -is 0: -.Bl -column -1 Failure -compact -.It 0 Ta Failure Ta The -.Fa certificate -cannot be used for the -.Fa purpose . -.It 1 Ta Success Ta The -.Fa certificate -can be used for the -.Fa purpose . -.It 2 Ta Unknown Ta \&No decision can be made. -.El -.Pp -If -.Fa ca -is non-zero: -.Bl -column -1 Failure -compact -.It 0 Ta Failure Ta The -.Fa certificate -cannot be used as a CA for the -.Fa purpose . -.It 1 Ta Success Ta The -.Fa certificate -can be used as a CA for the -.Fa purpose . -.It 3 Ta Success Ta The Fa certificate No is a version 1 CA . -.It 4 Ta Success Ta The Key Usage allows Dv keyCertSign . -.It 5 Ta Success Ta A Netscape Cert Type allows usage as a CA. -.El -.Sh SEE ALSO -.Xr BASIC_CONSTRAINTS_new 3 , -.Xr EXTENDED_KEY_USAGE_new 3 , -.Xr X509_new 3 , -.Xr X509_PURPOSE_set 3 , -.Xr X509V3_get_d2i 3 , -.Xr x509v3.cnf 5 -.Sh STANDARDS -RFC 5280: Internet X.509 Public Key Infrastructure Certificate and -Certificate Revocation List (CRL) Profile -.Bl -dash -offset indent -compact -.It -section 4.2.1.3: Key Usage -.It -section 4.2.1.9: Basic Constraints -.It -section 4.2.1.12: Extended Key Usage -.El -.Sh HISTORY -.Fn X509_check_purpose -first appeared in OpenSSL 0.9.5 and has been available since -.Ox 2.7 . -- cgit v1.2.3-55-g6feb