From: Dr. David von Oheimb Date: Tue, 16 Feb 2021 10:17:07 +0000 (+0100) Subject: DOC: Clarify the role of EKUs including defaults for TLS client and server use X-Git-Tag: openssl-3.0.0-beta2~168 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=4acda8635ed55ddf831d1bb3dc6086054f01cc61;p=thirdparty%2Fopenssl.git DOC: Clarify the role of EKUs including defaults for TLS client and server use Reviewed-by: Paul Dale (Merged from https://github.com/openssl/openssl/pull/14199) --- diff --git a/doc/man1/openssl-verification-options.pod b/doc/man1/openssl-verification-options.pod index 1c91c778529..c634ccae15b 100644 --- a/doc/man1/openssl-verification-options.pod +++ b/doc/man1/openssl-verification-options.pod @@ -151,10 +151,13 @@ The first step is to check that each certificate is well-formed. Part of these checks are enabled only if the B<-x509_strict> option is given. The second step is to check the extensions of every untrusted certificate -for consistency with the given purpose. -If the B<-purpose> option is not included then no such checks are done. -The target certificate must not have an EKU extension that is incompatible with -the given purpose, and all other certificates must be valid CA certificates. +for consistency with the supplied purpose. +If the B<-purpose> option is not given then no such checks are done +except for SSL/TLS connection setup, +where by default C or C, are checked. +The target or "leaf" certificate, as well as any other untrusted certificates, +must have extensions compatible with the specified purpose. +All certificates except the target or "leaf" must also be valid CA certificates. The precise extensions required are described in more detail in L. @@ -452,11 +455,17 @@ Set policy variable inhibit-policy-mapping (see RFC5280). =item B<-purpose> I -The intended use for the certificate. If this option is not specified, this -command will not consider certificate purpose during chain verification. -Currently accepted uses are B, B, B, -B, B, B, B, B, -and . +The intended use for the certificate. +Currently defined purposes are C, C, C, +C, C, C, C, C, +and C. +If peer certificate verification is enabled, by default the TLS implementation +as well as the commands B and B check for consistency +with TLS server or TLS client use, respectively. + +While IETF RFC 5280 says that B and B +are only for WWW use, in practice they are used for all kinds of TLS clients +and servers, and this is what OpenSSL assumes as well. =item B<-verify_depth> I diff --git a/doc/man1/openssl-x509.pod.in b/doc/man1/openssl-x509.pod.in index 0e073d6b058..9c77a216c22 100644 --- a/doc/man1/openssl-x509.pod.in +++ b/doc/man1/openssl-x509.pod.in @@ -551,10 +551,12 @@ Clears all the permitted or trusted uses of the certificate. =item B<-addtrust> I -Adds an allowed trust anchor purpose. -Any object name can be used here but currently only those -listed in L are supported. -Other OpenSSL applications may define additional purposes. +Adds a trusted certificate use. +Any object name can be used here but currently only B, +B, B, and B are defined. +As of OpenSSL 1.1.0, the last of these blocks all purposes when rejected or +enables all purposes when trusted. +Other OpenSSL applications may define additional uses. =item B<-clrreject> diff --git a/doc/man3/SSL_CTX_new.pod b/doc/man3/SSL_CTX_new.pod index 6bab45631fc..61de1a65516 100644 --- a/doc/man3/SSL_CTX_new.pod +++ b/doc/man3/SSL_CTX_new.pod @@ -74,8 +74,11 @@ functions =head1 DESCRIPTION SSL_CTX_new_ex() creates a new B object, which holds various -configuration and data relevant to TLS/SSL or DTLS session establishment. The -library context I (see L) is used to provide the +configuration and data relevant to SSL/TLS or DTLS session establishment. +These are later inherited by the B object representing an active session. +The I parameter specifies whether the context will be used for the +client or server side or both - for details see the L below. +The library context I (see L) is used to provide the cryptographic algorithms needed for the session. Any cryptographic algorithms that are used by any B objects created from this B will be fetched from the I using the property query string I (see @@ -97,10 +100,21 @@ provide serialization of access for these cases. =head1 NOTES +On session estabilishment, by default, no peer credentials verification is done. +This must be explicitly requested, typically using L. +For verifying peer certificates many options can be set using various functions +such as L and L. +The L function can be used, also in conjunction +with L, to set the intended purpose of the session. +The default is B on the client side +and B on the server side. + The SSL_CTX object uses I as the connection method. -The methods exist in a generic type (for client and server use), a server only -type, and a client only type. -B can be one of the following types: +Three method variants are available: a generic method (for either client or +server use), a server-only method, and a client-only method. + +The I parameter of SSL_CTX_new_ex() and SSL_CTX_new() +can be one of the following: =over 4 @@ -214,7 +228,9 @@ SSL_CTX_up_ref() returns 1 for success and 0 for failure. =head1 SEE ALSO -L, L, L, +L, L, +SSL_CTX_set_verify(3), L, L, +L, L, L, L, L =head1 HISTORY diff --git a/doc/man3/SSL_CTX_set_verify.pod b/doc/man3/SSL_CTX_set_verify.pod index b72227c9244..5e3ebef8e68 100644 --- a/doc/man3/SSL_CTX_set_verify.pod +++ b/doc/man3/SSL_CTX_set_verify.pod @@ -9,7 +9,7 @@ SSL_verify_cb, SSL_verify_client_post_handshake, SSL_set_post_handshake_auth, SSL_CTX_set_post_handshake_auth -- set peer certificate verification parameters +- set various SSL/TLS parameters for peer certificate verification =head1 SYNOPSIS diff --git a/doc/man3/SSL_new.pod b/doc/man3/SSL_new.pod index c7c5758cb13..02cbd036b54 100644 --- a/doc/man3/SSL_new.pod +++ b/doc/man3/SSL_new.pod @@ -61,7 +61,7 @@ L, or L L or L (Note: Only from OpenSSL 1.1.1h and above) -=item any Verify mode, callback or depth set via L or +=item any verify mode, callback or depth set via L or L or any configured X509 verification parameters =item any msg callback or info callback set via L or diff --git a/doc/man3/X509_STORE_CTX_new.pod b/doc/man3/X509_STORE_CTX_new.pod index b982dc9c7ea..56a36bfecdc 100644 --- a/doc/man3/X509_STORE_CTX_new.pod +++ b/doc/man3/X509_STORE_CTX_new.pod @@ -138,7 +138,10 @@ and so it should not be free'd by the caller. X509_STORE_CTX_set_default() looks up and sets the default verification method to I. This uses the function X509_VERIFY_PARAM_lookup() to -find an appropriate set of parameters from I. +find an appropriate set of parameters from the purpose identifier I. +Currently defined purposes are C, C, C, +C, C, C, C, C, +and C. X509_STORE_CTX_set_verify() provides the capability for overriding the default verify function. This function is responsible for verifying chain signatures and diff --git a/doc/man3/X509_VERIFY_PARAM_set_flags.pod b/doc/man3/X509_VERIFY_PARAM_set_flags.pod index 2041176d4fa..1213627be7f 100644 --- a/doc/man3/X509_VERIFY_PARAM_set_flags.pod +++ b/doc/man3/X509_VERIFY_PARAM_set_flags.pod @@ -89,7 +89,7 @@ X509_VERIFY_PARAM_clear_flags() clears the flags B in B. X509_VERIFY_PARAM_set_purpose() sets the verification purpose in B to B. This determines the acceptable purpose of the certificate -chain, for example SSL client or SSL server. +chain, for example B. X509_VERIFY_PARAM_set_trust() sets the trust setting in B to B. diff --git a/doc/man3/X509_check_purpose.pod b/doc/man3/X509_check_purpose.pod index e0f1353842a..619ed7831a4 100644 --- a/doc/man3/X509_check_purpose.pod +++ b/doc/man3/X509_check_purpose.pod @@ -29,6 +29,9 @@ Below are the potential ID's that can be checked: # define X509_PURPOSE_OCSP_HELPER 8 # define X509_PURPOSE_TIMESTAMP_SIGN 9 +The checks performed take into account the X.509 extensions +keyUsage, extendedKeyUsage, and basicConstraints. + =head1 RETURN VALUES For non-CA checks diff --git a/doc/man5/x509v3_config.pod b/doc/man5/x509v3_config.pod index f8bc6d0ff19..fb7c3aaff7c 100644 --- a/doc/man5/x509v3_config.pod +++ b/doc/man5/x509v3_config.pod @@ -142,15 +142,15 @@ Examples: =head2 Extended Key Usage This extension consists of a list of values indicating purposes for which -the certificate public key can be used for, Each value can be either a -short text name or an OID. +the certificate public key can be used. +Each value can be either a short text name or an OID. The following text names, and their intended meaning, are known: - Value Meaning - ----- ------- - serverAuth SSL/TLS Web Server Authentication - clientAuth SSL/TLS Web Client Authentication - codeSigning Code signing + Value Meaning according to RFC 5280 etc. + ----- ---------------------------------- + serverAuth SSL/TLS WWW Server Authentication + clientAuth SSL/TLS WWW Client Authentication + codeSigning Code Signing emailProtection E-mail Protection (S/MIME) timeStamping Trusted Timestamping OCSPSigning OCSP Signing @@ -160,6 +160,10 @@ The following text names, and their intended meaning, are known: msCTLSign Microsoft Trust List Signing msEFS Microsoft Encrypted File System +While IETF RFC 5280 says that B and B +are only for WWW use, in practice they are used for all kinds of TLS clients +and servers, and this is what OpenSSL assumes as well. + Examples: extendedKeyUsage = critical, codeSigning, 1.2.3.4