diff options
author | Dr. David von Oheimb <David.von.Oheimb@siemens.com> | 2021-02-16 11:17:07 +0100 |
---|---|---|
committer | Dr. David von Oheimb <dev@ddvo.net> | 2021-06-26 15:38:40 +0200 |
commit | 4acda8635ed55ddf831d1bb3dc6086054f01cc61 (patch) | |
tree | f366f096ef49946d775a738463cc7d89f12858e0 /doc/man3 | |
parent | 426005eea5afd64bb76006f0fda69502ab3e008d (diff) |
DOC: Clarify the role of EKUs including defaults for TLS client and server use
Reviewed-by: Paul Dale <pauli@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/14199)
Diffstat (limited to 'doc/man3')
-rw-r--r-- | doc/man3/SSL_CTX_new.pod | 28 | ||||
-rw-r--r-- | doc/man3/SSL_CTX_set_verify.pod | 2 | ||||
-rw-r--r-- | doc/man3/SSL_new.pod | 2 | ||||
-rw-r--r-- | doc/man3/X509_STORE_CTX_new.pod | 5 | ||||
-rw-r--r-- | doc/man3/X509_VERIFY_PARAM_set_flags.pod | 2 | ||||
-rw-r--r-- | doc/man3/X509_check_purpose.pod | 3 |
6 files changed, 32 insertions, 10 deletions
diff --git a/doc/man3/SSL_CTX_new.pod b/doc/man3/SSL_CTX_new.pod index 6bab45631f..61de1a6551 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<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 @@ -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<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 @@ -214,7 +228,9 @@ SSL_CTX_up_ref() returns 1 for success and 0 for failure. =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 diff --git a/doc/man3/SSL_CTX_set_verify.pod b/doc/man3/SSL_CTX_set_verify.pod index b72227c924..5e3ebef8e6 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 c7c5758cb1..02cbd036b5 100644 --- a/doc/man3/SSL_new.pod +++ b/doc/man3/SSL_new.pod @@ -61,7 +61,7 @@ L<SSL_set_tmp_dh_callback(3)>, or L<SSL_set_dh_auto(3)> 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 diff --git a/doc/man3/X509_STORE_CTX_new.pod b/doc/man3/X509_STORE_CTX_new.pod index b982dc9c7e..56a36bfecd 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<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 diff --git a/doc/man3/X509_VERIFY_PARAM_set_flags.pod b/doc/man3/X509_VERIFY_PARAM_set_flags.pod index 2041176d4f..1213627be7 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<flags> in B<param>. 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>. diff --git a/doc/man3/X509_check_purpose.pod b/doc/man3/X509_check_purpose.pod index e0f1353842..619ed7831a 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 |