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<sslserver> or C<sslclient>, 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<openssl-x509(1)/CERTIFICATE EXTENSIONS>.
=item B<-purpose> I<purpose>
-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<sslclient>, B<sslserver>, B<nssslserver>,
-B<smimesign>, B<smimeencrypt>, B<crlsign>, B<ocsphelper>, B<timestampsign>,
-and <any>.
+The intended use for the certificate.
+Currently defined purposes are C<sslclient>, C<sslserver>, C<nssslserver>,
+C<smimesign>, C<smimeencrypt>, C<crlsign>, C<ocsphelper>, C<timestampsign>,
+and C<any>.
+If peer certificate verification is enabled, by default the TLS implementation
+as well as the commands B<s_client> and B<s_server> check for consistency
+with TLS server or TLS client use, respectively.
+
+While IETF RFC 5280 says that B<id-kp-serverAuth> and B<id-kp-clientAuth>
+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<num>
=item B<-addtrust> I<arg>
-Adds an allowed trust anchor purpose.
-Any object name can be used here but currently only those
-listed in L<openssl-verification-options(1)/Trust Anchors> 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<clientAuth>,
+B<serverAuth>, B<emailProtection>, and B<anyExtendedKeyUsage> 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>
=head1 DESCRIPTION
SSL_CTX_new_ex() creates a new B<SSL_CTX> object, which holds various
-configuration and data relevant to TLS/SSL or DTLS session establishment. The
-library context I<libctx> (see L<OSSL_LIB_CTX(3)>) is used to provide the
+configuration and data relevant to SSL/TLS or DTLS session establishment.
+These are later inherited by the B<SSL> object representing an active session.
+The I<method> parameter specifies whether the context will be used for the
+client or server side or both - for details see the L</NOTES> below.
+The library context I<libctx> (see L<OSSL_LIB_CTX(3)>) is used to provide the
cryptographic algorithms needed for the session. Any cryptographic algorithms
that are used by any B<SSL> objects created from this B<SSL_CTX> will be fetched
from the I<libctx> using the property query string I<propq> (see
=head1 NOTES
+On session estabilishment, by default, no peer credentials verification is done.
+This must be explicitly requested, typically using L<SSL_CTX_set_verify(3)>.
+For verifying peer certificates many options can be set using various functions
+such as L<SSL_CTX_load_verify_locations(3)> and L<SSL_CTX_set1_param(3)>.
+The L<X509_VERIFY_PARAM_set_purpose(3)> function can be used, also in conjunction
+with L<SSL_CTX_get0_param(3)>, to set the intended purpose of the session.
+The default is B<X509_PURPOSE_SSL_SERVER> on the client side
+and B<X509_PURPOSE_SSL_CLIENT> on the server side.
+
The SSL_CTX object uses I<method> 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<method> 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<method> parameter of SSL_CTX_new_ex() and SSL_CTX_new()
+can be one of the following:
=over 4
=head1 SEE ALSO
-L<SSL_CTX_set_options(3)>, L<SSL_CTX_free(3)>, L<SSL_accept(3)>,
+L<SSL_CTX_set_options(3)>, L<SSL_CTX_free(3)>,
+SSL_CTX_set_verify(3), L<SSL_CTX_set1_param(3)>, L<SSL_CTX_get0_param(3)>,
+L<SSL_connect(3)>, L<SSL_accept(3)>,
L<SSL_CTX_set_min_proto_version(3)>, L<ssl(7)>, L<SSL_set_connect_state(3)>
=head1 HISTORY
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
L<SSL_set_min_proto_version(3)> or L<SSL_set_max_proto_version(3)> (Note: Only
from OpenSSL 1.1.1h and above)
-=item any Verify mode, callback or depth set via L<SSL_set_verify(3)> or
+=item any verify mode, callback or depth set via L<SSL_set_verify(3)> or
L<SSL_set_verify_depth(3)> or any configured X509 verification parameters
=item any msg callback or info callback set via L<SSL_set_msg_callback(3)> or
X509_STORE_CTX_set_default() looks up and sets the default verification
method to I<name>. This uses the function X509_VERIFY_PARAM_lookup() to
-find an appropriate set of parameters from I<name>.
+find an appropriate set of parameters from the purpose identifier I<name>.
+Currently defined purposes are C<sslclient>, C<sslserver>, C<nssslserver>,
+C<smimesign>, C<smimeencrypt>, C<crlsign>, C<ocsphelper>, C<timestampsign>,
+and C<any>.
X509_STORE_CTX_set_verify() provides the capability for overriding the default
verify function. This function is responsible for verifying chain signatures and
X509_VERIFY_PARAM_set_purpose() sets the verification purpose in B<param>
to B<purpose>. This determines the acceptable purpose of the certificate
-chain, for example SSL client or SSL server.
+chain, for example B<X509_PURPOSE_SSL_CLIENT>.
X509_VERIFY_PARAM_set_trust() sets the trust setting in B<param> to
B<trust>.
# 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
=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
msCTLSign Microsoft Trust List Signing
msEFS Microsoft Encrypted File System
+While IETF RFC 5280 says that B<id-kp-serverAuth> and B<id-kp-clientAuth>
+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
projects / openssl.git / commitdiff