diff options
author | Kurt Roeckx <kurt@roeckx.be> | 2015-12-06 17:56:41 +0100 |
---|---|---|
committer | Viktor Dukhovni <openssl-users@dukhovni.org> | 2016-01-02 10:47:52 -0500 |
commit | 7946ab33cecce60afcc00afc8fc18f31f9e66bff (patch) | |
tree | fa178fbc42a649e87e201820cc11796dc3c7d6de /doc/ssl/SSL_CTX_new.pod | |
parent | 1e0784ff95cd69090e26e2205bfec6305038db56 (diff) |
Add support for minimum and maximum protocol version
Reviewed-by: Viktor Dukhovni <viktor@openssl.org>
Diffstat (limited to 'doc/ssl/SSL_CTX_new.pod')
-rw-r--r-- | doc/ssl/SSL_CTX_new.pod | 126 |
1 files changed, 81 insertions, 45 deletions
diff --git a/doc/ssl/SSL_CTX_new.pod b/doc/ssl/SSL_CTX_new.pod index 15011f8fc1..2c2120a647 100644 --- a/doc/ssl/SSL_CTX_new.pod +++ b/doc/ssl/SSL_CTX_new.pod @@ -2,7 +2,7 @@ =head1 NAME -SSL_CTX_new, SSLv3_method, SSLv3_server_method, SSLv3_client_method, TLSv1_method, TLSv1_server_method, TLSv1_client_method, TLSv1_1_method, TLSv1_1_server_method, TLSv1_1_client_method, TLS_method, TLS_server_method, TLS_client_method, SSLv23_method, SSLv23_server_method, SSLv23_client_method - create a new SSL_CTX object as framework for TLS/SSL enabled functions +SSL_CTX_new, SSLv3_method, SSLv3_server_method, SSLv3_client_method, TLSv1_method, TLSv1_server_method, TLSv1_client_method, TLSv1_1_method, TLSv1_1_server_method, TLSv1_1_client_method, TLS_method, TLS_server_method, TLS_client_method, SSLv23_method, SSLv23_server_method, SSLv23_client_method, DTLS_method, DTLS_server_method, DTLS_client_method, DTLSv1_method, DTLSv1_server_method, DTLSv1_client_method, DTLSv1_2_method, DTLSv1_2_server_method, DTLSv1_2_client_method - create a new SSL_CTX object as framework for TLS/SSL or DTLS enabled functions =head1 SYNOPSIS @@ -10,51 +10,77 @@ SSL_CTX_new, SSLv3_method, SSLv3_server_method, SSLv3_client_method, TLSv1_metho SSL_CTX *SSL_CTX_new(const SSL_METHOD *method); + const SSL_METHOD *TLS_method(void); + const SSL_METHOD *TLS_server_method(void); + const SSL_METHOD *TLS_client_method(void); + + #define SSLv23_method TLS_method + #define SSLv23_server_method TLS_server_method + #define SSLv23_client_method TLS_client_method + + #ifndef OPENSSL_NO_SSL3_METHOD + const SSL_METHOD *SSLv3_method(void); + const SSL_METHOD *SSLv3_server_method(void); + const SSL_METHOD *SSLv3_client_method(void); + #endif + + const SSL_METHOD *TLSv1_method(void); + const SSL_METHOD *TLSv1_server_method(void); + const SSL_METHOD *TLSv1_client_method(void); + + const SSL_METHOD *TLSv1_1_method(void); + const SSL_METHOD *TLSv1_1_server_method(void); + const SSL_METHOD *TLSv1_1_client_method(void); + + const SSL_METHOD *TLSv1_2_method(void); + const SSL_METHOD *TLSv1_2_server_method(void); + const SSL_METHOD *TLSv1_2_client_method(void); + + const SSL_METHOD *DTLS_method(void); + const SSL_METHOD *DTLS_server_method(void); + const SSL_METHOD *DTLS_client_method(void); + + const SSL_METHOD *DTLSv1_method(void); + const SSL_METHOD *DTLSv1_server_method(void); + const SSL_METHOD *DTLSv1_client_method(void); + + const SSL_METHOD *DTLSv1_2_method(void); + const SSL_METHOD *DTLSv1_2_server_method(void); + const SSL_METHOD *DTLSv1_2_client_method(void); + =head1 DESCRIPTION -SSL_CTX_new() creates a new B<SSL_CTX> object as framework to establish -TLS/SSL enabled connections. +SSL_CTX_new() creates a new B<SSL_CTX> object as framework to establish TLS/SSL or DTLS enabled connections. =head1 NOTES -The SSL_CTX object uses B<method> as 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 of the following types: +The SSL_CTX object uses B<method> as 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 of the following types: =over 4 -=item SSLv3_method(void), SSLv3_server_method(void), SSLv3_client_method(void) +=item SSLv3_method(), SSLv3_server_method(), SSLv3_client_method() -A TLS/SSL connection established with these methods will only understand the -SSLv3 protocol. A client will send out SSLv3 client hello messages -and will indicate that it only understands SSLv3. A server will only understand -SSLv3 client hello messages. +An SSL connection established with these methods will only understand the SSLv3 protocol. +A client will send out a SSLv3 client hello messages and will indicate that it supports SSLv3. +A server will only understand SSLv3 client hello message and only support the SSLv3 protocol. -=item TLSv1_method(void), TLSv1_server_method(void), TLSv1_client_method(void) +=item TLSv1_method(), TLSv1_server_method(), TLSv1_client_method() -A TLS/SSL connection established with these methods will only understand the -TLSv1 protocol. A client will send out TLSv1 client hello messages -and will indicate that it only understands TLSv1. A server will only understand -TLSv1 client hello messages. +A TLS connection established with these methods will only understand the TLS 1.0 protocol. -=item TLSv1_1_method(void), TLSv1_1_server_method(void), TLSv1_1_client_method(void) +=item TLSv1_1_method(), TLSv1_1_server_method(), TLSv1_1_client_method() -A TLS/SSL connection established with these methods will only understand the -TLSv1.1 protocol. A client will send out TLSv1.1 client hello messages -and will indicate that it only understands TLSv1.1. A server will only -understand TLSv1.1 client hello messages. +A TLS connection established with these methods will only understand the TLS 1.1 protocol. -=item TLSv1_2_method(void), TLSv1_2_server_method(void), TLSv1_2_client_method(void) +=item TLSv1_2_method(), TLSv1_2_server_method(), TLSv1_2_client_method() -A TLS/SSL connection established with these methods will only understand the -TLSv1.2 protocol. A client will send out TLSv1.2 client hello messages -and will indicate that it only understands TLSv1.2. A server will only -understand TLSv1.2 client hello messages. +A TLS connection established with these methods will only understand the TLS 1.2 protocol. -=item TLS_method(void), TLS_server_method(void), TLS_client_method(void) +=item TLS_method(), TLS_server_method(), TLS_client_method() -A TLS/SSL connection established with these methods may understand the -SSLv3, TLSv1, TLSv1.1 and TLSv1.2 protocols. +A TLS/SSL connection established with these methods may understand the SSLv3, TLSv1, TLSv1.1 and TLSv1.2 protocols. If extensions are required (for example server name) a client will send out TLSv1 client hello messages including extensions and @@ -62,26 +88,36 @@ will indicate that it also understands TLSv1.1, TLSv1.2 and permits a fallback to SSLv3. A server will support SSLv3, TLSv1, TLSv1.1 and TLSv1.2 protocols. This is the best choice when compatibility is a concern. -=item SSLv23_method(void), SSLv23_server_method(void), SSLv23_client_method(void) +=item SSLv23_method(), SSLv23_server_method(), SSLv23_client_method() -Use of these functions is deprecated. They have been replaced with TLS_Method(), +Use of these functions is deprecated. They have been replaced with TLS_method(), TLS_server_method() and TLS_client_method() respectively. New code should use those functions instead. +=item DTLS_method(), DTLS_server_method(), DTLS_client_method() + +A DTLS connection established with those methods understands all supported DTLS protocols. +Currently supported protocols are DTLS 1.0 and DTLS 1.2. + +=item DTLSv1_method(), DTLSv1_server_method(), DTLSv1_client_method() + +A DTLS connection established with these methods will only understand the DTLS 1.0 protocol. + +=item DTLSv1_2_method(), DTLSv1_2_server_method(), DTLSv1_2_client_method() + +A DTLS connection established with these methods will only understand the DTLS 1.2 protocol. + =back -The list of protocols available can later be limited using the -SSL_OP_NO_SSLv3, SSL_OP_NO_TLSv1, SSL_OP_NO_TLSv1_1 and SSL_OP_NO_TLSv1_2 -options of the SSL_CTX_set_options() or SSL_set_options() functions. -Using these options it is possible to choose e.g. TLS_server_method() and -be able to negotiate with all possible clients, but to only allow newer -protocols like TLSv1, TLSv1.1 or TLS v1.2. +TLS_method(), TLS_server_method(), TLS_client_method(), DTLS_method(), DTLS_server_method() and DTLS_client_method() are the version flexible methods. +All other methods only support 1 specific protocol version. +It's recommended to use those methods instead of the version specific methods. -Applications which never want to support SSLv3 can set SSL_OP_NO_SSLv3. +If you want to limit the supported protocols for the version flexible methods you can use SSL_CTX_set_min_proto_version(), SSL_set_min_proto_version(), SSL_CTX_set_max_proto_version() and SSL_set_max_proto_version() functions. +They can also be limited using by using an option like SSL_OP_NO_SSLv3 of the SSL_CTX_set_options() or SSL_set_options() functions, but that's not recommended. +Using these functions it is possible to choose e.g. TLS_server_method() and be able to negotiate with all possible clients, but to only allow newer protocols like TLS v1, TLS v1.1 or TLS v1.2. -SSL_CTX_new() initializes the list of ciphers, the session cache setting, -the callbacks, the keys and certificates and the options to its default -values. +SSL_CTX_new() initializes the list of ciphers, the session cache setting, the callbacks, the keys and certificates and the options to its default values. =head1 RETURN VALUES @@ -102,14 +138,14 @@ The return value points to an allocated SSL_CTX object. =head1 HISTORY -SSLv2_method, SSLv2_server_method and SSLv2_client_method where removed in -OpenSSL 1.1.0. SSLv23_method, SSLv23_server_method and SSLv23_client_method were -deprecated and TLS_method, TLS_server_method and TLS_client_method -were introduced in OpenSSL 1.1.0. +SSLv3 +SSLv2_method, SSLv2_server_method and SSLv2_client_method where removed in OpenSSL 1.1.0. +SSLv23_method, SSLv23_server_method and SSLv23_client_method were deprecated and TLS_method, TLS_server_method and TLS_client_method were introduced in OpenSSL 1.1.0. =head1 SEE ALSO L<SSL_CTX_free(3)>, L<SSL_accept(3)>, +L<SSL_CTX_set_min_proto_version(3)>, L<ssl(3)>, L<SSL_set_connect_state(3)> =cut |