set_ssl_option(option,
value)
|
|
Sets a single configuration parameter on this socket. Call once for
each parameter you want to change. The configuration parameters are
listed below.
- SSL_SECURITY (default=True)
- Enables use of security protocol. WARNING: If you turn this option
off, the session will not be an SSL session and will not have
certificate-based authentication, tamper detection, or encryption.
- SSL_REQUEST_CERTIFICATE: (default=False)
- Is a server option that requests a client to authenticate itself.
- SSL_REQUIRE_CERTIFICATE: (default=SSL_REQUIRE_FIRST_HANDSHAKE)
- Is a server option that requires a client to authenticate itself (only
if SSL_REQUEST_CERTIFICATE is also on). If client does not provide
certificate, the connection terminates.
- SSL_HANDSHAKE_AS_CLIENT: (default=False)
- Controls the behavior of SSLSocket.accept(),. If this option is off,
the SSLSocket.accept() configures the SSL socket to handshake as a
server. If it is on, then SSLSocket.accept() configures the SSL socket
to handshake as a client, even though it accepted the connection as a
TCP server.
- SSL_HANDSHAKE_AS_SERVER: (default=False)
- Controls the behavior of SSLSocket.connect(). If this option is off,
then SSLSocket.connect() configures the SSL socket to handshake as a
client. If it is on, then SSLSocket.connect() configures the SSL
socket to handshake as a server, even though it connected as a TCP
client.
- SSL_ENABLE_FDX: (default=False)
Tells the SSL library whether the application will have two threads,
one reading and one writing, or just one thread doing reads and writes
alternately. The factory setting for this option (which is the
default, unless the application changes the default) is off, which
means that the application will not do simultaneous reads and
writes. An application that needs to do simultaneous reads and writes
should set this to True.
In NSS 2.8, the SSL_ENABLE_FDX option only affects the behavior of
nonblocking SSL sockets. See the description below for more
information on this option.
- SSL_ENABLE_SSL3: (default=True)
- Enables the application to communicate with SSL v3. If you turn this
option off, an attempt to establish a connection with a peer that
understands only SSL v3 will fail.
- SSL_ENABLE_SSL2: (default=True)
- Enables the application to communicate with SSL v2. If you turn this
option off, an attempt to establish a connection with a peer that
understands only SSL v2 will fail.
- SSL_ENABLE_TLS: (default=True)
- Is a peer of the SSL_ENABLE_SSL2 and SSL_ENABLE_SSL3 options. The IETF
standard Transport Layer Security (TLS) protocol, RFC 2246, is a
modified version of SSL3. It uses the SSL version number 3.1,
appearing to be a 'minor' revision of SSL3.0. NSS 2.8 supports TLS in
addition to SSL2 and SSL3. You can think of it as 'SSL_ENABLE_SSL3.1.'
See the description below for more information about this option.
- SSL_V2_COMPATIBLE_HELLO: (default=True)
- Tells the SSL library whether or not to send SSL3 client hello
messages in SSL2-compatible format. If set to True, it will;
otherwise, it will not. See the description below for more information
on this option.
- SSL_NO_CACHE: (default=False)
- Disallows use of the session cache. Factory setting is off. If you
turn this option on, this socket will be unable to resume a session
begun by another socket. When this socket's session is finished, no
other socket will be able to resume the session begun by this socket.
- SSL_ROLLBACK_DETECTION: (default=True)
- Disables detection of a rollback attack. Factory setting is on. You
must turn this option off to interoperate with TLS clients ( such as
certain versions of Microsoft Internet Explorer) that do not conform
to the TLS specification regarding rollback attacks. Important:
turning this option off means that your code will not comply with the
TLS 3.1 and SSL 3.0 specifications regarding rollback attack and will
therefore be vulnerable to this form of attack.
Keep the following in mind when deciding on the operating parameters
you want to use with a particular socket.
Turning on SSL_REQUIRE_CERTIFICATE will have no effect unless
SSL_REQUEST_CERTIFICATE is also turned on. If you enable
SSL_REQUEST_CERTIFICATE, then you should explicitly enable or disable
SSL_REQUIRE_CERTIFICATE rather than allowing it to default. Enabling
the SSL_REQUIRE_CERTIFICATE option is not recommended. If the client
has no certificate and this option is enabled, the client's connection
terminates with an error. The user is likely to think something is
wrong with either the client or the server, and is unlikely to realize
that the problem is the lack of a certificate. It is better to allow
the SSL handshake to complete and then return an error message to the
client that informs the user of the need for a certificate.
The SSL protocol is defined to be able to handle simultaneous two-way
communication between applications at each end of an SSL
connection. Two-way simultaneous communication is also known as'Full
Duplex', abbreviated FDX. However, most application protocols that use
SSL are not two-way simultaneous, but two-way alternate, also known as
'Half Dupled'; that is, each end takes turns sending, and each end is
either sending, or receiving, but not both at the same time. For an
application to do full duplex, it would have two threads sharing the
socket; one doing all the reading and the other doing all the writing.
The SSL_ENABLE_FDX option tells the SSL library whether the
application will have two threads, one reading and one writing, or
just one thread doing reads and writes alternately.
If an SSL3 client hello message is sent to a server that only
understands SSL2 and not SSL3, then the server will interpret the SSL3
client hello as a very large message, and the connection will usually
seem to 'hang' while the SSL2 server expects more data that will never
arrive. For this reason, the SSL3 spec allows SSL3 client hellos to be
sent in SSL2 format, and it recommends that SSL3 servers all accept
SSL3 client hellos in SSL2 format. When an SSL2-only server receives
an SSL3 client hello in SSL2 format, it can (and probably will)
negotiate the protocol version correctly, not causing a 'hang'.
Some applications may wish to force SSL3 client hellos to be sent in
SSL3 format, not in SSL2-compatible format. They might wish to do this
if they knew, somehow, that the server does not understand
SSL2-compatible client hello messages.
SSL_V2_COMPATIBLE_HELLO tells the SSL library whether or not to send
SSL3 client hello messages in SSL2-compatible format. Note that
calling SSLSocket.set_ssl_option() to set SSL_V2_COMPATIBLE_HELLO to
False implicitly also sets the SSL_ENABLE_SSL2 option to False for
that SSL socket. Calling SSL_EnableDefault to change the application
default setting for SSL_V2_COMPATIBLE_HELLO to False implicitly also
sets the default value for SSL_ENABLE_SSL2 option to False for that
application.
The options SSL_ENABLE_SSL2, SSL_ENABLE_SSL3, and SSL_ENABLE_TLS can
each be set to True or False independently of each other. NSS 2.8 and
later versions will negotiate the highest protocol version with the
peer application from among the set of protocols that are commonly
enabled in both applications.
Note that SSL3 and TLS share the same set of cipher suites. When both
SSL3 and TLS are enabled, all SSL3/TLS cipher suites that are enabled
are enabled for both SSL3 and TLS.
When an application imports a socket into SSL after the TCP connection
on that socket has already been established, it must call
SSLSocket.reset_handshake() to indicate whether the socket is for a
client or server. At first glance this may seem unnecessary, since
SSLSocket.set_ssl_option() can set SSL_HANDSHAKE_AS_CLIENT or
SSL_HANDSHAKE_AS_SERVER. However, these settings control the behavior
of SSLSocket.connect() and SSLSocket.accept() only; if you don't call
one of those functions after importing a non-SSL socket with
SSL_Import (as in the case of an already established TCP connection),
SSL still needs to know whether the application is functioning as a
client or server.
If a socket file descriptor is imported as an SSL socket before it is
connected, it is implicitly configured to handshake as a client or
handshake as a server when the connection is made. If the application
calls SSLSocket.connect() (connecting as a TCP client), then the SSL
socket is (by default) configured to handshake as an SSL client. If
the application calls SSLSocket.accept() (connecting the socket as a
TCP server) then the SSL socket is (by default) configured to
handshake as an SSL server. SSL_HANDSHAKE_AS_CLIENT and
SSL_HANDSHAKE_AS_SERVER control this implicit configuration. Both
SSL_HANDSHAKE_AS_CLIENT and SSL_HANDSHAKE_AS_SERVER are initially set
to off--that is, the process default for both values is False when the
process begins. The process default can be changed from the initial
values by using SSL_EnableDefault, and the value for a particular
socket can be changed by using SSLSocket.set_ssl_option().
If a socket that is already connected gets imported into SSL after it
has been connected (that is, after SSLSocket.accept() or
SSLSocket.connect() has returned), then no implicit SSL handshake
configuration as a client or server will have been done by
SSLSocket.connect() or SSLSocket.accept() on that socket. In this
case, a call to SSLSocket.reset_handshake() is required to explicitly
configure the socket to handshake as a client or as a server. If
SSLSocket.reset_handshake() is not called to explicitly configure the
socket handshake, a crash is likely to occur when the first I/O
operation is done on the socket after it is imported into SSL.
|