1ebfedea0SLionel Sambuc=pod 2ebfedea0SLionel Sambuc 3ebfedea0SLionel Sambuc=head1 NAME 4ebfedea0SLionel Sambuc 5ebfedea0SLionel SambucSSL_CTX_new - create a new SSL_CTX object as framework for TLS/SSL enabled functions 6ebfedea0SLionel Sambuc 7ebfedea0SLionel Sambuc=head1 SYNOPSIS 8ebfedea0SLionel Sambuc 9ebfedea0SLionel Sambuc #include <openssl/ssl.h> 10ebfedea0SLionel Sambuc 11ebfedea0SLionel Sambuc SSL_CTX *SSL_CTX_new(const SSL_METHOD *method); 12ebfedea0SLionel Sambuc 13ebfedea0SLionel Sambuc=head1 DESCRIPTION 14ebfedea0SLionel Sambuc 15ebfedea0SLionel SambucSSL_CTX_new() creates a new B<SSL_CTX> object as framework to establish 16ebfedea0SLionel SambucTLS/SSL enabled connections. 17ebfedea0SLionel Sambuc 18ebfedea0SLionel Sambuc=head1 NOTES 19ebfedea0SLionel Sambuc 20ebfedea0SLionel SambucThe SSL_CTX object uses B<method> as connection method. The methods exist 21ebfedea0SLionel Sambucin a generic type (for client and server use), a server only type, and a 22ebfedea0SLionel Sambucclient only type. B<method> can be of the following types: 23ebfedea0SLionel Sambuc 24ebfedea0SLionel Sambuc=over 4 25ebfedea0SLionel Sambuc 26ebfedea0SLionel Sambuc=item SSLv2_method(void), SSLv2_server_method(void), SSLv2_client_method(void) 27ebfedea0SLionel Sambuc 28ebfedea0SLionel SambucA TLS/SSL connection established with these methods will only understand 29ebfedea0SLionel Sambucthe SSLv2 protocol. A client will send out SSLv2 client hello messages 30ebfedea0SLionel Sambucand will also indicate that it only understand SSLv2. A server will only 31ebfedea0SLionel Sambucunderstand SSLv2 client hello messages. 32ebfedea0SLionel Sambuc 33ebfedea0SLionel Sambuc=item SSLv3_method(void), SSLv3_server_method(void), SSLv3_client_method(void) 34ebfedea0SLionel Sambuc 35ebfedea0SLionel SambucA TLS/SSL connection established with these methods will only understand the 36ebfedea0SLionel SambucSSLv3 protocol. A client will send out SSLv3 client hello messages 37ebfedea0SLionel Sambucand will indicate that it only understands SSLv3. A server will only understand 38ebfedea0SLionel SambucSSLv3 client hello messages. This especially means, that it will 39ebfedea0SLionel Sambucnot understand SSLv2 client hello messages which are widely used for 40ebfedea0SLionel Sambuccompatibility reasons, see SSLv23_*_method(). 41ebfedea0SLionel Sambuc 42ebfedea0SLionel Sambuc=item TLSv1_method(void), TLSv1_server_method(void), TLSv1_client_method(void) 43ebfedea0SLionel Sambuc 44ebfedea0SLionel SambucA TLS/SSL connection established with these methods will only understand the 45ebfedea0SLionel SambucTLSv1 protocol. A client will send out TLSv1 client hello messages 46ebfedea0SLionel Sambucand will indicate that it only understands TLSv1. A server will only understand 47ebfedea0SLionel SambucTLSv1 client hello messages. This especially means, that it will 48ebfedea0SLionel Sambucnot understand SSLv2 client hello messages which are widely used for 49ebfedea0SLionel Sambuccompatibility reasons, see SSLv23_*_method(). It will also not understand 50ebfedea0SLionel SambucSSLv3 client hello messages. 51ebfedea0SLionel Sambuc 52ebfedea0SLionel Sambuc=item SSLv23_method(void), SSLv23_server_method(void), SSLv23_client_method(void) 53ebfedea0SLionel Sambuc 54*0a6a1f1dSLionel SambucA TLS/SSL connection established with these methods may understand the SSLv2, 55*0a6a1f1dSLionel SambucSSLv3, TLSv1, TLSv1.1 and TLSv1.2 protocols. 56*0a6a1f1dSLionel Sambuc 57*0a6a1f1dSLionel SambucIf the cipher list does not contain any SSLv2 ciphersuites (the default 58*0a6a1f1dSLionel Sambuccipher list does not) or extensions are required (for example server name) 59*0a6a1f1dSLionel Sambuca client will send out TLSv1 client hello messages including extensions and 60*0a6a1f1dSLionel Sambucwill indicate that it also understands TLSv1.1, TLSv1.2 and permits a 61*0a6a1f1dSLionel Sambucfallback to SSLv3. A server will support SSLv3, TLSv1, TLSv1.1 and TLSv1.2 62*0a6a1f1dSLionel Sambucprotocols. This is the best choice when compatibility is a concern. 63*0a6a1f1dSLionel Sambuc 64*0a6a1f1dSLionel SambucIf any SSLv2 ciphersuites are included in the cipher list and no extensions 65*0a6a1f1dSLionel Sambucare required then SSLv2 compatible client hellos will be used by clients and 66*0a6a1f1dSLionel SambucSSLv2 will be accepted by servers. This is B<not> recommended due to the 67*0a6a1f1dSLionel Sambucinsecurity of SSLv2 and the limited nature of the SSLv2 client hello 68*0a6a1f1dSLionel Sambucprohibiting the use of extensions. 69ebfedea0SLionel Sambuc 70ebfedea0SLionel Sambuc=back 71ebfedea0SLionel Sambuc 72ebfedea0SLionel SambucThe list of protocols available can later be limited using the SSL_OP_NO_SSLv2, 73*0a6a1f1dSLionel SambucSSL_OP_NO_SSLv3, SSL_OP_NO_TLSv1, SSL_OP_NO_TLSv1_1 and SSL_OP_NO_TLSv1_2 74*0a6a1f1dSLionel Sambucoptions of the SSL_CTX_set_options() or SSL_set_options() functions. 75*0a6a1f1dSLionel SambucUsing these options it is possible to choose e.g. SSLv23_server_method() and 76*0a6a1f1dSLionel Sambucbe able to negotiate with all possible clients, but to only allow newer 77*0a6a1f1dSLionel Sambucprotocols like TLSv1, TLSv1.1 or TLS v1.2. 78*0a6a1f1dSLionel Sambuc 79*0a6a1f1dSLionel SambucApplications which never want to support SSLv2 (even is the cipher string 80*0a6a1f1dSLionel Sambucis configured to use SSLv2 ciphersuites) can set SSL_OP_NO_SSLv2. 81ebfedea0SLionel Sambuc 82ebfedea0SLionel SambucSSL_CTX_new() initializes the list of ciphers, the session cache setting, 83*0a6a1f1dSLionel Sambucthe callbacks, the keys and certificates and the options to its default 84ebfedea0SLionel Sambucvalues. 85ebfedea0SLionel Sambuc 86ebfedea0SLionel Sambuc=head1 RETURN VALUES 87ebfedea0SLionel Sambuc 88ebfedea0SLionel SambucThe following return values can occur: 89ebfedea0SLionel Sambuc 90ebfedea0SLionel Sambuc=over 4 91ebfedea0SLionel Sambuc 92ebfedea0SLionel Sambuc=item NULL 93ebfedea0SLionel Sambuc 94ebfedea0SLionel SambucThe creation of a new SSL_CTX object failed. Check the error stack to 95ebfedea0SLionel Sambucfind out the reason. 96ebfedea0SLionel Sambuc 97ebfedea0SLionel Sambuc=item Pointer to an SSL_CTX object 98ebfedea0SLionel Sambuc 99ebfedea0SLionel SambucThe return value points to an allocated SSL_CTX object. 100ebfedea0SLionel Sambuc 101ebfedea0SLionel Sambuc=back 102ebfedea0SLionel Sambuc 103ebfedea0SLionel Sambuc=head1 SEE ALSO 104ebfedea0SLionel Sambuc 105ebfedea0SLionel SambucL<SSL_CTX_free(3)|SSL_CTX_free(3)>, L<SSL_accept(3)|SSL_accept(3)>, 106ebfedea0SLionel SambucL<ssl(3)|ssl(3)>, L<SSL_set_connect_state(3)|SSL_set_connect_state(3)> 107ebfedea0SLionel Sambuc 108ebfedea0SLionel Sambuc=cut 109