.\"
.\"	$OpenBSD: SSL_CTX_new.3,v 1.2 2014/12/02 14:11:01 jmc Exp $
.\"
.Dd $Mdocdate: December 2 2014 $
.Dt SSL_CTX_NEW 3
.Os
.Sh NAME
.Nm SSL_CTX_new ,
.Nm SSLv3_method ,
.Nm SSLv3_server_method ,
.Nm SSLv3_client_method ,
.Nm TLSv1_method ,
.Nm TLSv1_server_method ,
.Nm TLSv1_client_method ,
.Nm TLSv1_1_method ,
.Nm TLSv1_1_server_method ,
.Nm TLSv1_1_client_method ,
.Nm SSLv23_method ,
.Nm SSLv23_server_method ,
.Nm SSLv23_client_method
.Nd create a new SSL_CTX object as framework for TLS/SSL enabled functions
.Sh SYNOPSIS
.In openssl/ssl.h
.Ft SSL_CTX *
.Fn SSL_CTX_new "const SSL_METHOD *method"
.Sh DESCRIPTION
.Fn SSL_CTX_new
creates a new
.Vt SSL_CTX
object as framework to establish TLS/SSL enabled connections.
.Sh NOTES
The
.Vt SSL_CTX
object uses
.Fa method
as its connection method.
The methods exist in a generic type (for client and server use),
a server only type, and a client only type.
.Fa method
can be of the following types:
.Bl -tag -width Ds
.It Fn SSLv3_method void , Fn SSLv3_server_method void , \
Fn 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.
Importantly, this means that it will not understand SSLv2 client hello messages
which are widely used for compatibility reasons; see
.Fn SSLv23_*_method .
.It Fn TLSv1_method void , Fn TLSv1_server_method void , \
Fn 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.
Importantly, this means that it will not understand SSLv2 client hello messages
which are widely used for compatibility reasons; see
.Fn SSLv23_*_method .
It will also not understand SSLv3 client hello messages.
.It Fn SSLv23_method void , Fn SSLv23_server_method void , \
Fn SSLv23_client_method void
A TLS/SSL connection established with these methods may understand the SSLv3,
TLSv1, TLSv1.1 and TLSv1.2 protocols.
.Pp
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.
.El
.Pp
The list of protocols available can later be limited using the
.Dv SSL_OP_NO_SSLv3 ,
.Dv SSL_OP_NO_TLSv1 ,
.Dv SSL_OP_NO_TLSv1_1 ,
and
.Dv SSL_OP_NO_TLSv1_2
options of the
.Fn SSL_CTX_set_options
or
.Fn SSL_set_options
functions.
Using these options it is possible to choose, for example,
.Fn SSLv23_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.
.Pp
.Fn 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.
.Sh RETURN VALUES
The following return values can occur:
.Bl -tag -width Ds
.It Dv NULL
The creation of a new
.Vt SSL_CTX
object failed.
Check the error stack to find out the reason.
.It Pointer to an SSL_CTX object
The return value points to an allocated
.Vt SSL_CTX
object.
.El
.Sh SEE ALSO
.Xr ssl 3 ,
.Xr SSL_accept 3 ,
.Xr SSL_CTX_free 3 ,
.Xr SSL_set_connect_state 3