| =pod |
| |
| =head1 NAME |
| |
| SSL_CTX_new - create a new SSL_CTX object as framework for TLS/SSL enabled functions |
| |
| =head1 SYNOPSIS |
| |
| #include <openssl/ssl.h> |
| |
| SSL_CTX *SSL_CTX_new(SSL_METHOD *method); |
| |
| =head1 DESCRIPTION |
| |
| SSL_CTX_new() creates a new B<SSL_CTX> object as framework to establish |
| TLS/SSL 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: |
| |
| =over 4 |
| |
| =item SSLv2_method(void), SSLv2_server_method(void), SSLv2_client_method(void) |
| |
| A TLS/SSL 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. |
| |
| =item SSLv3_method(void), SSLv3_server_method(void), SSLv3_client_method(void) |
| |
| 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. This especially means, that it will |
| not understand SSLv2 client hello messages which are widely used for |
| compatibility reasons, see SSLv23_*_method(). |
| |
| =item TLSv1_method(void), TLSv1_server_method(void), TLSv1_client_method(void) |
| |
| 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. This especially means, that it will |
| not understand SSLv2 client hello messages which are widely used for |
| compatibility reasons, see SSLv23_*_method(). It will also not understand |
| SSLv3 client hello messages. |
| |
| =item SSLv23_method(void), SSLv23_server_method(void), SSLv23_client_method(void) |
| |
| A TLS/SSL connection established with these methods will understand the SSLv2, |
| SSLv3, and TLSv1 protocol. A client will send out SSLv2 client hello messages |
| and will indicate that it also understands SSLv3 and TLSv1. A server will |
| understand SSLv2, SSLv3, and TLSv1 client hello messages. This is the best |
| choice when compatibility is a concern. |
| |
| =back |
| |
| The list of protocols available can later be limited using the SSL_OP_NO_SSLv2, |
| SSL_OP_NO_SSLv3, SSL_OP_NO_TLSv1 options of the B<SSL_CTX_set_options()> or |
| B<SSL_set_options()> functions. Using these options it is possible to choose |
| e.g. SSLv23_server_method() and be able to negotiate with all possible |
| clients, but to only allow newer protocols like SSLv3 or TLSv1. |
| |
| 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 |
| |
| The following return values can occur: |
| |
| =over 4 |
| |
| =item NULL |
| |
| The creation of a new SSL_CTX object failed. Check the error stack to |
| find out the reason. |
| |
| =item Pointer to an SSL_CTX object |
| |
| The return value points to an allocated SSL_CTX object. |
| |
| =back |
| |
| =head1 SEE ALSO |
| |
| L<SSL_CTX_free(3)|SSL_CTX_free(3)>, L<SSL_accept(3)|SSL_accept(3)>, |
| L<ssl(3)|ssl(3)>, L<SSL_set_connect_state(3)|SSL_set_connect_state(3)> |
| |
| =cut |
