diff options
Diffstat (limited to 'secure/lib/libssl/man/SSL_CTX_new.3')
| -rw-r--r-- | secure/lib/libssl/man/SSL_CTX_new.3 | 157 |
1 files changed, 102 insertions, 55 deletions
diff --git a/secure/lib/libssl/man/SSL_CTX_new.3 b/secure/lib/libssl/man/SSL_CTX_new.3 index e1b41a0..beeeaec 100644 --- a/secure/lib/libssl/man/SSL_CTX_new.3 +++ b/secure/lib/libssl/man/SSL_CTX_new.3 @@ -133,19 +133,53 @@ .\" ======================================================================== .\" .IX Title "SSL_CTX_new 3" -.TH SSL_CTX_new 3 "2016-01-28" "1.0.1r" "OpenSSL" +.TH SSL_CTX_new 3 "2016-03-01" "1.0.1s" "OpenSSL" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" -SSL_CTX_new \- create a new SSL_CTX object as framework for TLS/SSL enabled functions +SSL_CTX_new, +SSLv23_method, SSLv23_server_method, SSLv23_client_method, +TLSv1_2_method, TLSv1_2_server_method, TLSv1_2_client_method, +TLSv1_1_method, TLSv1_1_server_method, TLSv1_1_client_method, +TLSv1_method, TLSv1_server_method, TLSv1_client_method, +SSLv3_method, SSLv3_server_method, SSLv3_client_method, +SSLv2_method, SSLv2_server_method, SSLv2_client_method, +DTLSv1_method, DTLSv1_server_method, DTLSv1_client_method \- +create a new SSL_CTX object as framework for TLS/SSL enabled functions .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& #include <openssl/ssl.h> \& \& SSL_CTX *SSL_CTX_new(const SSL_METHOD *method); +\& const SSL_METHOD *SSLv23_method(void); +\& const SSL_METHOD *SSLv23_server_method(void); +\& const SSL_METHOD *SSLv23_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 *TLSv1_1_method(void); +\& const SSL_METHOD *TLSv1_1_server_method(void); +\& const SSL_METHOD *TLSv1_1_client_method(void); +\& const SSL_METHOD *TLSv1_method(void); +\& const SSL_METHOD *TLSv1_server_method(void); +\& const SSL_METHOD *TLSv1_client_method(void); +\& #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 +\& #ifndef OPENSSL_NO_SSL2 +\& const SSL_METHOD *SSLv2_method(void); +\& const SSL_METHOD *SSLv2_server_method(void); +\& const SSL_METHOD *SSLv2_client_method(void); +\& #endif +\& +\& const SSL_METHOD *DTLSv1_method(void); +\& const SSL_METHOD *DTLSv1_server_method(void); +\& const SSL_METHOD *DTLSv1_client_method(void); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" @@ -156,71 +190,84 @@ SSL_CTX_new \- create a new SSL_CTX object as framework for TLS/SSL enabled func The \s-1SSL_CTX\s0 object uses \fBmethod\fR as connection method. The methods exist in a generic type (for client and server use), a server only type, and a client only type. \fBmethod\fR can be of the following types: -.IP "SSLv2_method(void), SSLv2_server_method(void), SSLv2_client_method(void)" 4 -.IX Item "SSLv2_method(void), SSLv2_server_method(void), SSLv2_client_method(void)" -A \s-1TLS/SSL\s0 connection established with these methods will only understand -the SSLv2 protocol. A client will send out SSLv2 client hello messages -and will also indicate that it only understand SSLv2. A server will only -understand SSLv2 client hello messages. -.IP "SSLv3_method(void), SSLv3_server_method(void), SSLv3_client_method(void)" 4 -.IX Item "SSLv3_method(void), SSLv3_server_method(void), SSLv3_client_method(void)" -A \s-1TLS/SSL\s0 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. This especially means, that it will -not understand SSLv2 client hello messages which are widely used for -compatibility reasons, see SSLv23_*\fI_method()\fR. -.IP "TLSv1_method(void), TLSv1_server_method(void), TLSv1_client_method(void)" 4 -.IX Item "TLSv1_method(void), TLSv1_server_method(void), TLSv1_client_method(void)" -A \s-1TLS/SSL\s0 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. This especially means, that it will -not understand SSLv2 client hello messages which are widely used for -compatibility reasons, see SSLv23_*\fI_method()\fR. It will also not understand -SSLv3 client hello messages. -.IP "SSLv23_method(void), SSLv23_server_method(void), SSLv23_client_method(void)" 4 -.IX Item "SSLv23_method(void), SSLv23_server_method(void), SSLv23_client_method(void)" -A \s-1TLS/SSL\s0 connection established with these methods may understand the SSLv2, -SSLv3, TLSv1, TLSv1.1 and TLSv1.2 protocols. +.IP "\fISSLv23_method()\fR, \fISSLv23_server_method()\fR, \fISSLv23_client_method()\fR" 4 +.IX Item "SSLv23_method(), SSLv23_server_method(), SSLv23_client_method()" +These are the general-purpose \fIversion-flexible\fR \s-1SSL/TLS\s0 methods. +The actual protocol version used will be negotiated to the highest version +mutually supported by the client and the server. +The supported protocols are SSLv2, SSLv3, TLSv1, TLSv1.1 and TLSv1.2. +Most applications should use these method, and avoid the version specific +methods described below. .Sp -If the cipher list does not contain any SSLv2 ciphersuites (the default -cipher list does not) or extensions are required (for example server name) -a client will send out TLSv1 client hello messages including extensions and -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. +The list of protocols available can be further limited using the +\&\fBSSL_OP_NO_SSLv2\fR, \fBSSL_OP_NO_SSLv3\fR, \fBSSL_OP_NO_TLSv1\fR, +\&\fBSSL_OP_NO_TLSv1_1\fR and \fBSSL_OP_NO_TLSv1_2\fR options of the +\&\fISSL_CTX_set_options\fR\|(3) or \fISSL_set_options\fR\|(3) functions. +Clients should avoid creating \*(L"holes\*(R" in the set of protocols they support, +when disabling a protocol, make sure that you also disable either all previous +or all subsequent protocol versions. +In clients, when a protocol version is disabled without disabling \fIall\fR +previous protocol versions, the effect is to also disable all subsequent +protocol versions. .Sp -If any SSLv2 ciphersuites are included in the cipher list and no extensions -are required then SSLv2 compatible client hellos will be used by clients and -SSLv2 will be accepted by servers. This is \fBnot\fR recommended due to the -insecurity of SSLv2 and the limited nature of the SSLv2 client hello -prohibiting the use of extensions. -.PP -The list of protocols available can later be limited using the SSL_OP_NO_SSLv2, -SSL_OP_NO_SSLv3, SSL_OP_NO_TLSv1, SSL_OP_NO_TLSv1_1 and SSL_OP_NO_TLSv1_2 -options of the \fISSL_CTX_set_options()\fR or \fISSL_set_options()\fR functions. -Using these options it is possible to choose e.g. \fISSLv23_server_method()\fR and -be able to negotiate with all possible clients, but to only allow newer -protocols like TLSv1, TLSv1.1 or \s-1TLS\s0 v1.2. -.PP -Applications which never want to support SSLv2 (even is the cipher string -is configured to use SSLv2 ciphersuites) can set SSL_OP_NO_SSLv2. +The SSLv2 and SSLv3 protocols are deprecated and should generally not be used. +Applications should typically use \fISSL_CTX_set_options\fR\|(3) in combination with +the \fBSSL_OP_NO_SSLv3\fR flag to disable negotiation of SSLv3 via the above +\&\fIversion-flexible\fR \s-1SSL/TLS\s0 methods. +The \fBSSL_OP_NO_SSLv2\fR option is set by default, and would need to be cleared +via \fISSL_CTX_clear_options\fR\|(3) in order to enable negotiation of SSLv2. +.IP "\fITLSv1_2_method()\fR, \fITLSv1_2_server_method()\fR, \fITLSv1_2_client_method()\fR" 4 +.IX Item "TLSv1_2_method(), TLSv1_2_server_method(), TLSv1_2_client_method()" +A \s-1TLS/SSL\s0 connection established with these methods will only understand the +TLSv1.2 protocol. A client will send out TLSv1.2 client hello messages and +will also indicate that it only understand TLSv1.2. A server will only +understand TLSv1.2 client hello messages. +.IP "\fITLSv1_1_method()\fR, \fITLSv1_1_server_method()\fR, \fITLSv1_1_client_method()\fR" 4 +.IX Item "TLSv1_1_method(), TLSv1_1_server_method(), TLSv1_1_client_method()" +A \s-1TLS/SSL\s0 connection established with these methods will only understand the +TLSv1.1 protocol. A client will send out TLSv1.1 client hello messages and +will also indicate that it only understand TLSv1.1. A server will only +understand TLSv1.1 client hello messages. +.IP "\fITLSv1_method()\fR, \fITLSv1_server_method()\fR, \fITLSv1_client_method()\fR" 4 +.IX Item "TLSv1_method(), TLSv1_server_method(), TLSv1_client_method()" +A \s-1TLS/SSL\s0 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. +.IP "\fISSLv3_method()\fR, \fISSLv3_server_method()\fR, \fISSLv3_client_method()\fR" 4 +.IX Item "SSLv3_method(), SSLv3_server_method(), SSLv3_client_method()" +A \s-1TLS/SSL\s0 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. The SSLv3 protocol is deprecated and should not be +used. +.IP "\fISSLv2_method()\fR, \fISSLv2_server_method()\fR, \fISSLv2_client_method()\fR" 4 +.IX Item "SSLv2_method(), SSLv2_server_method(), SSLv2_client_method()" +A \s-1TLS/SSL\s0 connection established with these methods will only understand the +SSLv2 protocol. A client will send out SSLv2 client hello messages and will +also indicate that it only understand SSLv2. A server will only understand +SSLv2 client hello messages. The SSLv2 protocol offers little to no security +and should not be used. +As of OpenSSL 1.0.1s, \s-1EXPORT\s0 ciphers and 56\-bit \s-1DES\s0 are no longer available +with SSLv2. +.IP "\fIDTLSv1_method()\fR, \fIDTLSv1_server_method()\fR, \fIDTLSv1_client_method()\fR" 4 +.IX Item "DTLSv1_method(), DTLSv1_server_method(), DTLSv1_client_method()" +These are the version-specific methods for DTLSv1. .PP -\&\fISSL_CTX_new()\fR initializes the list of ciphers, the session cache setting, -the callbacks, the keys and certificates and the options to its default -values. +\&\fISSL_CTX_new()\fR initializes the list of ciphers, the session cache setting, the +callbacks, the keys and certificates and the options to its default values. .SH "RETURN VALUES" .IX Header "RETURN VALUES" The following return values can occur: .IP "\s-1NULL\s0" 4 .IX Item "NULL" -The creation of a new \s-1SSL_CTX\s0 object failed. Check the error stack to -find out the reason. +The creation of a new \s-1SSL_CTX\s0 object failed. Check the error stack to find out +the reason. .IP "Pointer to an \s-1SSL_CTX\s0 object" 4 .IX Item "Pointer to an SSL_CTX object" The return value points to an allocated \s-1SSL_CTX\s0 object. .SH "SEE ALSO" .IX Header "SEE ALSO" +\&\fISSL_CTX_set_options\fR\|(3), \fISSL_CTX_clear_options\fR\|(3), \fISSL_set_options\fR\|(3), \&\fISSL_CTX_free\fR\|(3), \fISSL_accept\fR\|(3), \&\fIssl\fR\|(3), \fISSL_set_connect_state\fR\|(3) |
