1: =pod
    2: 
    3: =head1 NAME
    4: 
    5: SSL_CTX_new - create a new SSL_CTX object as framework for TLS/SSL enabled functions
    6: 
    7: =head1 SYNOPSIS
    8: 
    9:  #include <openssl/ssl.h>
   10: 
   11:  SSL_CTX *SSL_CTX_new(SSL_METHOD *method);
   12: 
   13: =head1 DESCRIPTION
   14: 
   15: SSL_CTX_new() creates a new B<SSL_CTX> object as framework to establish
   16: TLS/SSL enabled connections.
   17: 
   18: =head1 NOTES
   19: 
   20: The SSL_CTX object uses B<method> as connection method. The methods exist
   21: in a generic type (for client and server use), a server only type, and a
   22: client only type. B<method> can be of the following types:
   23: 
   24: =over 4
   25: 
   26: =item SSLv2_method(void), SSLv2_server_method(void), SSLv2_client_method(void)
   27: 
   28: A TLS/SSL connection established with these methods will only understand
   29: the SSLv2 protocol. A client will send out SSLv2 client hello messages
   30: and will also indicate that it only understand SSLv2. A server will only
   31: understand SSLv2 client hello messages.
   32: 
   33: =item SSLv3_method(void), SSLv3_server_method(void), SSLv3_client_method(void)
   34: 
   35: A TLS/SSL connection established with these methods will only understand the
   36: SSLv3 protocol. A client will send out SSLv3 client hello messages
   37: and will indicate that it only understands SSLv3. A server will only understand
   38: SSLv3 client hello messages. This especially means, that it will
   39: not understand SSLv2 client hello messages which are widely used for
   40: compatibility reasons, see SSLv23_*_method().
   41: 
   42: =item TLSv1_method(void), TLSv1_server_method(void), TLSv1_client_method(void)
   43: 
   44: A TLS/SSL connection established with these methods will only understand the
   45: TLSv1 protocol. A client will send out TLSv1 client hello messages
   46: and will indicate that it only understands TLSv1. A server will only understand
   47: TLSv1 client hello messages. This especially means, that it will
   48: not understand SSLv2 client hello messages which are widely used for
   49: compatibility reasons, see SSLv23_*_method(). It will also not understand
   50: SSLv3 client hello messages.
   51: 
   52: =item SSLv23_method(void), SSLv23_server_method(void), SSLv23_client_method(void)
   53: 
   54: A TLS/SSL connection established with these methods will understand the SSLv2,
   55: SSLv3, and TLSv1 protocol. A client will send out SSLv2 client hello messages
   56: and will indicate that it also understands SSLv3 and TLSv1. A server will
   57: understand SSLv2, SSLv3, and TLSv1 client hello messages. This is the best
   58: choice when compatibility is a concern.
   59: 
   60: =back
   61: 
   62: The list of protocols available can later be limited using the SSL_OP_NO_SSLv2,
   63: SSL_OP_NO_SSLv3, SSL_OP_NO_TLSv1 options of the B<SSL_CTX_set_options()> or
   64: B<SSL_set_options()> functions. Using these options it is possible to choose
   65: e.g. SSLv23_server_method() and be able to negotiate with all possible
   66: clients, but to only allow newer protocols like SSLv3 or TLSv1.
   67: 
   68: SSL_CTX_new() initializes the list of ciphers, the session cache setting,
   69: the callbacks, the keys and certificates, and the options to its default
   70: values.
   71: 
   72: =head1 RETURN VALUES
   73: 
   74: The following return values can occur:
   75: 
   76: =over 4
   77: 
   78: =item NULL
   79: 
   80: The creation of a new SSL_CTX object failed. Check the error stack to
   81: find out the reason.
   82: 
   83: =item Pointer to an SSL_CTX object
   84: 
   85: The return value points to an allocated SSL_CTX object.
   86: 
   87: =back
   88: 
   89: =head1 SEE ALSO
   90: 
   91: L<SSL_CTX_free(3)|SSL_CTX_free(3)>, L<SSL_accept(3)|SSL_accept(3)>,
   92: L<ssl(3)|ssl(3)>,  L<SSL_set_connect_state(3)|SSL_set_connect_state(3)>
   93: 
   94: =cut