diff --git a/doc/man1/openssl-cms.pod.in b/doc/man1/openssl-cms.pod.in index f6b3a4c7d6f45..db8517f94cd88 100644 --- a/doc/man1/openssl-cms.pod.in +++ b/doc/man1/openssl-cms.pod.in @@ -192,6 +192,10 @@ to the output file. Verify signed data. Expects a signed data on input and outputs the signed data. Both clear text and opaque signing is supported. +By default, validation of signer certificates and their chain +is done w.r.t. the S/MIME signing (C) purpose. +For details see L. + =item B<-resign> Resign a message: take an existing message and one or more new signers. diff --git a/doc/man1/openssl-s_client.pod.in b/doc/man1/openssl-s_client.pod.in index 75934e714b385..d2491c8fd93ff 100644 --- a/doc/man1/openssl-s_client.pod.in +++ b/doc/man1/openssl-s_client.pod.in @@ -303,14 +303,21 @@ see L. The verify depth to use. This specifies the maximum length of the server certificate chain and turns on server certificate verification. -Currently the verify operation continues after errors so all the problems +Unless the B<-verify_return_error> option is given, +the verify operation continues after errors so all the problems with a certificate chain can be seen. As a side effect the connection will never fail due to a server certificate verify failure. +By default, validation of server certificates and their chain +is done w.r.t. the (D)TLS Server> (C) purpose. +For details see L. + + =item B<-verify_return_error> -Return verification errors instead of continuing. This will typically -abort the handshake with a fatal error. +Turns on server certificate verification, like with B<-verify>, +but returns verification errors instead of continuing. +This will typically abort the handshake with a fatal error. =item B<-verify_quiet> diff --git a/doc/man1/openssl-s_server.pod.in b/doc/man1/openssl-s_server.pod.in index d683c1a797a53..fa224657d600c 100644 --- a/doc/man1/openssl-s_server.pod.in +++ b/doc/man1/openssl-s_server.pod.in @@ -212,6 +212,10 @@ must supply a certificate or an error occurs. If the cipher suite cannot request a client certificate (for example an anonymous cipher suite or PSK) this option has no effect. +By default, validation of any supplied client certificate and its chain +is done w.r.t. the (D)TLS Client> (C) purpose. +For details see L. + =item B<-cert> I The certificate to use, most servers cipher suites require the use of a diff --git a/doc/man1/openssl-verification-options.pod b/doc/man1/openssl-verification-options.pod index 38ae58d83defd..329a282597638 100644 --- a/doc/man1/openssl-verification-options.pod +++ b/doc/man1/openssl-verification-options.pod @@ -24,8 +24,9 @@ The most important of them are detailed in the following sections. In a nutshell, a valid chain of certificates needs to be built up and verified starting from the I that is to be verified and ending in a certificate that due to some policy is trusted. -Verification is done relative to the given I, which is the intended use -of the target certificate, such as SSL server, or by default for any purpose. +Certificate validation can be performed in the context of a I, which +is a high-level specification of the intended use of the target certificate, +such C for TLS servers, or (by default) for any purpose. The details of how each OpenSSL command handles errors are documented on the specific command page. @@ -150,16 +151,17 @@ the chain components and their links are checked thoroughly. 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 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. +The second step is to check the X.509v3 extensions of every certificate +for consistency with the intended specific purpose, if any. +If the B<-purpose> option is not given then no such checks are done except for +CMS signature checking, where by default C is checked, and SSL/(D)TLS +connection setup, where by default C or C are checked. +The X.509v3 extensions of the target or "leaf" certificate +must be compatible with the specified purpose. +All other certificates down the chain are checked to be valid CA certificates, +and possibly also further non-standard checks are performed. +The precise extensions required are described in detail +in the L section below. The third step is to check the trust settings on the last certificate (which typically is a self-signed root CA certificate). @@ -455,13 +457,16 @@ Set policy variable inhibit-policy-mapping (see RFC5280). =item B<-purpose> I -The intended use for the certificate. -Currently defined purposes are C, C, C, +A high-level specification of the intended use of the target certificate. +Currently predefined purposes are C, 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. +and thus the commands L and L +check for consistency with +TLS server (C) or TLS client use (C), respectively. +By default, CMS signature validation, which can be done via L, +checks for consistency with S/MIME signing use (C). 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 @@ -491,19 +496,20 @@ the subject certificate. =item B<-verify_name> I -Use default verification policies like trust model and required certificate -policies identified by I. +Use a set of verification parameters, also known as verification method, +identified by I. The currently predefined methods are named C, +C, C with alias C, C, and C. +These mimic the combinations of purpose and trust settings used in SSL/(D)TLS, +CMS/PKCS7 (including S/MIME), and code signing. + +The verification parameters include the trust model, various flags that can +partly be set also via other command-line options, and the verification purpose, +which in turn implies certificate key usage and extended key usage requirements. + The trust model determines which auxiliary trust or reject OIDs are applicable to verifying the given certificate chain. They can be given using the B<-addtrust> and B<-addreject> options for L. -Supported policy names include: B, B, B, -B, B. -These mimics the combinations of purpose and trust settings used in SSL, CMS -and S/MIME. -As of OpenSSL 1.1.0, the trust model is inferred from the purpose when not -specified, so the B<-verify_name> options are functionally equivalent to the -corresponding B<-purpose> settings. =back @@ -548,9 +554,8 @@ This option has no effect and is retained for backward compatibility only. =head2 Certificate Extensions -Options like B<-purpose> lead to checking the certificate extensions, -which determine what the target certificate and intermediate CA certificates -can be used for. +Options like B<-purpose> and B<-verify_name> trigger the processing of specific +certificate extensions, which determine what certificates can be used for. =head3 Basic Constraints @@ -574,87 +579,128 @@ keyCertSign bit set if the keyUsage extension is present. =head3 Extended Key Usage -The extKeyUsage (EKU) extension places additional restrictions on the -certificate uses. If this extension is present (whether critical or not) -the key can only be used for the purposes specified. - -A complete description of each check is given below. The comments about +The extKeyUsage (EKU) extension places additional restrictions on +certificate use. If this extension is present (whether critical or not) +in an end-entity certficiate, the key is allowed only for the uses specified, +while the special EKU B allows for all uses. + +Note that according to RFC 5280 section 4.2.1.12, +the Extended Key Usage extension will appear only in end-entity certificates, +and consequently the standard certification path validation described +in its section 6 does not include EKU checks for CA certificates. +The CA/Browser Forum requires for TLS server, S/MIME, and code signing use +the presence of respective EKUs in subordinate CA certificates (while excluding +them for root CA certificates), which is self-contradictory because OTOH they +take over the certificate validity concept and path validation from RFC 5280. + +For historic reasons, OpenSSL has its own way of interpreting and checking +EKU extensions on CA certificates, which may change in the future. +It does not require the presence of EKU extensions in CA certificates, +but in case the verification purpose is +C, C, C, C, or C, +it checks that any present EKU extension (that does not contain +B) contains the respective EKU as detailed below. +Moreover, it does these checks even for trust anchor certificates, +for which the EKU extension (like most other extensions) should be irrelevant. + +=head3 Checks Implied by Specific Predefined Policies + +A specific description of each check is given below. The comments about basicConstraints and keyUsage and X.509v1 certificates above apply to B CA certificates. - =over 4 -=item B +=item B<(D)TLS Client> (C) -The extended key usage extension must be absent or include the "web client -authentication" OID. The keyUsage extension must be absent or it must have the -digitalSignature bit set. The Netscape certificate type must be absent -or it must have the SSL client bit set. +Any given extended key usage extension must allow for C +("TLS WWW client authentication"). -=item B +For target certificates, +the key usage must allow for C and/or C. +The Netscape certificate type must be absent or have the SSL client bit set. -The extended key usage extension must be absent or include the "web client -authentication" OID. -The Netscape certificate type must be absent or it must have the SSL CA bit set. -This is used as a work around if the basicConstraints extension is absent. +For all other certificates the normal CA checks apply. In addition, +the Netscape certificate type must be absent or have the SSL CA bit set. +This is used as a workaround if the basicConstraints extension is absent. -=item B +=item B<(D)TLS Server> (C) -The extended key usage extension must be absent or include the "web server -authentication" and/or one of the SGC OIDs. The keyUsage extension must be -absent or it -must have the digitalSignature, the keyEncipherment set or both bits set. -The Netscape certificate type must be absent or have the SSL server bit set. +Any given extended key usage extension must allow for C +("TLS WWW server authentication") and/or include one of the SGC OIDs. -=item B +For target certificates, the key usage must +allow for C, C, and/or C. +The Netscape certificate type must be absent or have the SSL server bit set. -The extended key usage extension must be absent or include the "web server -authentication" and/or one of the SGC OIDs. The Netscape certificate type must -be absent or the SSL CA bit must be set. -This is used as a work around if the basicConstraints extension is absent. +For all other certificates the normal CA checks apply. In addition, +the Netscape certificate type must be absent or have the SSL CA bit set. +This is used as a workaround if the basicConstraints extension is absent. -=item B +=item B (C) -For Netscape SSL clients to connect to an SSL server it must have the -keyEncipherment bit set if the keyUsage extension is present. This isn't +In addition to what has been described for B, for a Netscape +SSL client to connect to an SSL server, its EE certficate must have the +B bit set if the keyUsage extension is present. This isn't always valid because some cipher suites use the key for digital signing. Otherwise it is the same as a normal SSL server. -=item B +=item B + +Any given extended key usage extension must allow for C. -The extended key usage extension must be absent or include the "email -protection" OID. The Netscape certificate type must be absent or should have the -S/MIME bit set. If the S/MIME bit is not set in the Netscape certificate type +For target certificates, +the Netscape certificate type must be absent or should have the S/MIME bit set. +If the S/MIME bit is not set in the Netscape certificate type then the SSL client bit is tolerated as an alternative but a warning is shown. This is because some Verisign certificates don't set the S/MIME bit. -=item B +For all other certificates the normal CA checks apply. In addition, +the Netscape certificate type must be absent or have the S/MIME CA bit set. +This is used as a workaround if the basicConstraints extension is absent. + +=item B (C) + +In addition to the common S/MIME checks, for target certficiates +the key usage must allow for C and/or B. + +=item B (C) + +In addition to the common S/MIME checks, for target certficiates +the key usage must allow for C. + +=item B (C) + +For target certificates, the key usage must allow for C. + +For all other certifcates the normal CA checks apply. +Except in this case the basicConstraints extension must be present. -In addition to the common S/MIME client tests the digitalSignature bit or -the nonRepudiation bit must be set if the keyUsage extension is present. +=item B (C) -=item B +For target certificates, no checks are performed at this stage, +but special checks apply; see L. -In addition to the common S/MIME tests the keyEncipherment bit must be set -if the keyUsage extension is present. +For all other certifcates the normal CA checks apply. -=item B +=item B (C) -The extended key usage extension must be absent or include the "email -protection" OID. The Netscape certificate type must be absent or must have the -S/MIME CA bit set. -This is used as a work around if the basicConstraints extension is absent. +For target certificates, if the key usage extension is present, it must include +C and/or C and must not include other bits. +The EKU extension must be present and contain C only. +Moreover, it must be marked as critical. -=item B +For all other certifcates the normal CA checks apply. -The keyUsage extension must be absent or it must have the CRL signing bit -set. +=item B (C) -=item B +For target certificates, +the key usage extension must be present and marked critical and +include , but must not include C nor C. +The EKU extension must be present and contain C, +but must not include C nor C. -The normal CA tests apply. Except in this case the basicConstraints extension -must be present. +For all other certifcates the normal CA checks apply. =back @@ -671,6 +717,7 @@ only the first one (in the mentioned order of locations) is recognised. =head1 SEE ALSO L, +L, L, L, L, diff --git a/doc/man3/SSL_CTX_new.pod b/doc/man3/SSL_CTX_new.pod index f467f93659b57..627d9e7f0dc36 100644 --- a/doc/man3/SSL_CTX_new.pod +++ b/doc/man3/SSL_CTX_new.pod @@ -104,10 +104,12 @@ On session establishment, 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 + +The SSL/(D)TLS implementation uses the L +function to prepare checks for B on the client side and B on the server side. +The L function can be used, also in conjunction +with L, to override the default purpose of the session. The SSL_CTX object uses I as the connection method. Three method variants are available: a generic method (for either client or @@ -228,7 +230,7 @@ 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 diff --git a/doc/man3/X509_STORE_CTX_new.pod b/doc/man3/X509_STORE_CTX_new.pod index 50781c0e85198..c219cee9d621c 100644 --- a/doc/man3/X509_STORE_CTX_new.pod +++ b/doc/man3/X509_STORE_CTX_new.pod @@ -85,7 +85,10 @@ If I is NULL nothing is done. X509_STORE_CTX_init() sets up I for a subsequent verification operation. X509_STORE_CTX_init() initializes the internal state and resources of the -X509_STORE_CTX, and must be called before each call to L or +given I. Among others, it sets the verification parameters associcated +with the method name C, which includes the C purpose, +and takes over callback function pointers from I (unless NULL). +It must be called before each call to L or L, i.e., a context is only good for one verification. If you want to verify a further certificate or chain with the same I then you must call X509_STORE_CTX_init() again. @@ -176,12 +179,13 @@ by I to be I. Ownership of the chain is transferred to I, 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 the purpose identifier I. -Currently defined purposes are C, C, C, -C, C, C, C, C, -and C. +X509_STORE_CTX_set_default() looks up and sets the default verification method. +This uses the function X509_VERIFY_PARAM_lookup() to find +the set of parameters associated with the given verification method I. +Among others, the parameters determine the trust model and verification purpose. +More detail, including the list of currently predefined methods, +is described for the B<-verify_name> command-line option +in L. 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/test/recipes/25-test_verify.t b/test/recipes/25-test_verify.t index 1c8fce86fd86a..80e9026556f3e 100644 --- a/test/recipes/25-test_verify.t +++ b/test/recipes/25-test_verify.t @@ -61,7 +61,7 @@ ok(verify("ee-cert-ocsp-nocheck", "", ["root-cert"], ["ca-cert"]), ok(verify("ee-cert", "sslserver", [qw(sroot-cert)], [qw(ca-cert)]), "accept server purpose"); ok(!verify("ee-cert", "sslserver", [qw(croot-cert)], [qw(ca-cert)]), - "fail client purpose"); + "fail client purpose"); # beware, questionable non-standard EKU check on trust anchor ok(verify("ee-cert", "sslserver", [qw(root+serverAuth)], [qw(ca-cert)]), "accept server trust"); ok(verify("ee-cert", "sslserver", [qw(sroot+serverAuth)], [qw(ca-cert)]), @@ -81,7 +81,7 @@ ok(verify("ee-cert", "sslserver", [qw(root-clientAuth)], [qw(ca-cert)]), ok(verify("ee-cert", "sslserver", [qw(sroot-clientAuth)], [qw(ca-cert)]), "accept client mistrust with server purpose"); ok(!verify("ee-cert", "sslserver", [qw(croot-clientAuth)], [qw(ca-cert)]), - "fail client mistrust with client purpose"); + "fail client mistrust with client purpose"); # beware, questionable non-standard EKU check on trust anchor # Inapplicable trust ok(!verify("ee-cert", "sslserver", [qw(root+clientAuth)], [qw(ca-cert)]), "fail client trust"); @@ -150,7 +150,7 @@ ok(!verify("ee-cert", "sslserver", [qw(root-expired)], [qw(ca-cert)]), ok(verify("ee-cert", "sslserver", [qw(sca-cert)], [], "-partial_chain"), "accept partial chain with server purpose"); ok(!verify("ee-cert", "sslserver", [qw(cca-cert)], [], "-partial_chain"), - "fail partial chain with client purpose"); + "fail partial chain with client purpose"); # beware, questionable non-standard EKU check on trust anchor ok(verify("ee-cert", "sslserver", [qw(ca+serverAuth)], [], "-partial_chain"), "accept server trust partial chain"); ok(verify("ee-cert", "sslserver", [qw(cca+serverAuth)], [], "-partial_chain"), @@ -188,7 +188,7 @@ ok(verify("ee-cert", "sslserver", [qw(root-cert cca+serverAuth)], [qw(ca-cert)]) ok(verify("ee-cert", "sslserver", [qw(root-cert cca+anyEKU)], [qw(ca-cert)]), "accept wildcard trust and client purpose"); ok(!verify("ee-cert", "sslserver", [qw(root-cert cca-cert)], [qw(ca-cert)]), - "fail client purpose"); + "fail client purpose intermediate trusted"); # beware, questionable non-standard EKU check on trust anchor ok(!verify("ee-cert", "sslserver", [qw(root-cert ca-anyEKU)], [qw(ca-cert)]), "fail wildcard mistrust"); ok(!verify("ee-cert", "sslserver", [qw(root-cert ca-serverAuth)], [qw(ca-cert)]),