# :mod:ssl --- TLS/SSL wrapper for socket objects

Source code: :source:Lib/ssl.py

This module provides access to Transport Layer Security (often known as "Secure Sockets Layer") encryption and peer authentication facilities for network sockets, both client-side and server-side. This module uses the OpenSSL library. It is available on all modern Unix systems, Windows, Mac OS X, and probably additional platforms, as long as OpenSSL is installed on that platform.

Note

Some behavior may be platform dependent, since calls are made to the operating system socket APIs. The installed version of OpenSSL may also cause variations in behavior. For example, TLSv1.1 and TLSv1.2 come with openssl version 1.0.1.

This section documents the objects and functions in the ssl module; for more general information about TLS, SSL, and certificates, the reader is referred to the documents in the "See Also" section at the bottom.

This module provides a class, :class:ssl.SSLSocket, which is derived from the :class:socket.socket type, and provides a socket-like wrapper that also encrypts and decrypts the data going over the socket with SSL. It supports additional methods such as :meth:getpeercert, which retrieves the certificate of the other side of the connection, and :meth:cipher,which retrieves the cipher being used for the secure connection.

For more sophisticated applications, the :class:ssl.SSLContext class helps manage settings and certificates, which can then be inherited by SSL sockets created through the :meth:SSLContext.wrap_socket method.

## Functions, Constants, and Exceptions

### Socket creation

The following function allows for standalone socket creation. Starting from Python 3.2, it can be more flexible to use :meth:SSLContext.wrap_socket instead.

## SSL Sockets

SSL sockets provide the following methods of :ref:socket-objects:

However, since the SSL (and TLS) protocol has its own framing atop of TCP, the SSL sockets abstraction can, in certain respects, diverge from the specification of normal, OS-level sockets. See especially the :ref:notes on non-blocking sockets <ssl-nonblocking>.

SSL sockets also have the following additional methods and attributes:

## SSL Contexts

An SSL context holds various data longer-lived than single SSL connections, such as SSL configuration options, certificate(s) and private key(s). It also manages a cache of SSL sessions for server-side sockets, in order to speed up repeated connections from the same clients.

Create a new SSL context. You must pass protocol which must be one of the PROTOCOL_* constants defined in this module. :data:PROTOCOL_SSLv23 is recommended for maximum interoperability.

:class:SSLContext objects have the following methods and attributes:

## Certificates

Certificates in general are part of a public-key / private-key system. In this system, each principal, (which may be a machine, or a person, or an organization) is assigned a unique two-part encryption key. One part of the key is public, and is called the public key; the other part is kept secret, and is called the private key. The two parts are related, in that if you encrypt a message with one of the parts, you can decrypt it with the other part, and only with the other part.

A certificate contains information about two principals. It contains the name of a subject, and the subject's public key. It also contains a statement by a second principal, the issuer, that the subject is who he claims to be, and that this is indeed the subject's public key. The issuer's statement is signed with the issuer's private key, which only the issuer knows. However, anyone can verify the issuer's statement by finding the issuer's public key, decrypting the statement with it, and comparing it to the other information in the certificate. The certificate also contains information about the time period over which it is valid. This is expressed as two fields, called "notBefore" and "notAfter".

In the Python use of certificates, a client or server can use a certificate to prove who they are. The other side of a network connection can also be required to produce a certificate, and that certificate can be validated to the satisfaction of the client or server that requires such validation. The connection attempt can be set to raise an exception if the validation fails. Validation is done automatically, by the underlying OpenSSL framework; the application need not concern itself with its mechanics. But the application does usually need to provide sets of certificates to allow this process to take place.

Python uses files to contain certificates. They should be formatted as "PEM" (see RFC 1422), which is a base-64 encoded form wrapped with a header line and a footer line:

-----BEGIN CERTIFICATE-----
... (certificate in base64 PEM encoding) ...
-----END CERTIFICATE-----


### Certificate chains

The Python files which contain certificates can contain a sequence of certificates, sometimes called a certificate chain. This chain should start with the specific certificate for the principal who "is" the client or server, and then the certificate for the issuer of that certificate, and then the certificate for the issuer of that certificate, and so on up the chain till you get to a certificate which is self-signed, that is, a certificate which has the same subject and issuer, sometimes called a root certificate. The certificates should just be concatenated together in the certificate file. For example, suppose we had a three certificate chain, from our server certificate to the certificate of the certification authority that signed our server certificate, to the root certificate of the agency which issued the certification authority's certificate:

-----BEGIN CERTIFICATE-----
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
... (the certificate for the CA)...
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
... (the root certificate for the CA's issuer)...
-----END CERTIFICATE-----


### CA certificates

If you are going to require validation of the other side of the connection's certificate, you need to provide a "CA certs" file, filled with the certificate chains for each issuer you are willing to trust. Again, this file just contains these chains concatenated together. For validation, Python will use the first chain it finds in the file which matches. Some "standard" root certificates are available from various certification authorities: CACert.org, Thawte, Verisign, Positive SSL (used by python.org), Equifax and GeoTrust.

In general, if you are using SSL3 or TLS1, you don't need to put the full chain in your "CA certs" file; you only need the root certificates, and the remote peer is supposed to furnish the other certificates necessary to chain from its certificate to a root certificate. See RFC 4158 for more discussion of the way in which certification chains can be built.

### Combined key and certificate

Often the private key is stored in the same file as the certificate; in this case, only the certfile parameter to :meth:SSLContext.load_cert_chain and :func:wrap_socket needs to be passed. If the private key is stored with the certificate, it should come before the first certificate in the certificate chain:

-----BEGIN RSA PRIVATE KEY-----
... (private key in base64 encoding) ...
-----END RSA PRIVATE KEY-----
-----BEGIN CERTIFICATE-----
... (certificate in base64 PEM encoding) ...
-----END CERTIFICATE-----


### Self-signed certificates

If you are going to create a server that provides SSL-encrypted connection services, you will need to acquire a certificate for that service. There are many ways of acquiring appropriate certificates, such as buying one from a certification authority. Another common practice is to generate a self-signed certificate. The simplest way to do this is with the OpenSSL package, using something like the following:

% openssl req -new -x509 -days 365 -nodes -out cert.pem -keyout cert.pem
Generating a 1024 bit RSA private key
.......++++++
.............................++++++
writing new private key to 'cert.pem'
-----
You are about to be asked to enter information that will be incorporated
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]:US
State or Province Name (full name) [Some-State]:MyState
Locality Name (eg, city) []:Some City
Organization Name (eg, company) [Internet Widgits Pty Ltd]:My Organization, Inc.
Organizational Unit Name (eg, section) []:My Group
Common Name (eg, YOUR name) []:myserver.mygroup.myorganization.com
%


The disadvantage of a self-signed certificate is that it is its own root certificate, and no one else will have it in their cache of known (and trusted) root certificates.

## Examples

### Testing for SSL support

To test for the presence of SSL support in a Python installation, user code should use the following idiom:

try:
import ssl
except ImportError:
pass
else:
... # do something that requires SSL support


### Client-side operation

This example connects to an SSL server and prints the server's certificate:

import socket, ssl, pprint

s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
# require a certificate from the server
ssl_sock = ssl.wrap_socket(s,
ca_certs="/etc/ca_certs_file",
cert_reqs=ssl.CERT_REQUIRED)
ssl_sock.connect(('www.verisign.com', 443))

pprint.pprint(ssl_sock.getpeercert())
# note that closing the SSLSocket will also close the underlying socket
ssl_sock.close()


As of January 6, 2012, the certificate printed by this program looks like this:

{'issuer': ((('countryName', 'US'),),
(('organizationName', 'VeriSign, Inc.'),),
(('organizationalUnitName', 'VeriSign Trust Network'),),
(('organizationalUnitName',
(('commonName',
'VeriSign Class 3 Extended Validation SSL SGC CA'),)),
'notAfter': 'May 25 23:59:59 2012 GMT',
'notBefore': 'May 26 00:00:00 2010 GMT',
'serialNumber': '53D2BEF924A7245E83CA01E46CAA2477',
'subject': ((('1.3.6.1.4.1.311.60.2.1.3', 'US'),),
(('1.3.6.1.4.1.311.60.2.1.2', 'Delaware'),),
(('serialNumber', '2497886'),),
(('countryName', 'US'),),
(('postalCode', '94043'),),
(('stateOrProvinceName', 'California'),),
(('localityName', 'Mountain View'),),
(('organizationName', 'VeriSign, Inc.'),),
(('organizationalUnitName', ' Production Security Services'),),
(('commonName', 'www.verisign.com'),)),
'subjectAltName': (('DNS', 'www.verisign.com'),
('DNS', 'verisign.com'),
('DNS', 'www.verisign.net'),
('DNS', 'verisign.net'),
('DNS', 'www.verisign.mobi'),
('DNS', 'verisign.mobi'),
('DNS', 'www.verisign.eu'),
('DNS', 'verisign.eu')),
'version': 3}


This other example first creates an SSL context, instructs it to verify certificates sent by peers, and feeds it a set of recognized certificate authorities (CA):

>>> context = ssl.SSLContext(ssl.PROTOCOL_SSLv23)
>>> context.verify_mode = ssl.CERT_REQUIRED


(it is assumed your operating system places a bundle of all CA certificates in /etc/ssl/certs/ca-bundle.crt; if not, you'll get an error and have to adjust the location)

When you use the context to connect to a server, :const:CERT_REQUIRED validates the server certificate: it ensures that the server certificate was signed with one of the CA certificates, and checks the signature for correctness:

>>> conn = context.wrap_socket(socket.socket(socket.AF_INET))
>>> conn.connect(("linuxfr.org", 443))


You should then fetch the certificate and check its fields for conformity:

>>> cert = conn.getpeercert()
>>> ssl.match_hostname(cert, "linuxfr.org")


Visual inspection shows that the certificate does identify the desired service (that is, the HTTPS host linuxfr.org):

>>> pprint.pprint(cert)
{'issuer': ((('organizationName', 'CAcert Inc.'),),
(('organizationalUnitName', 'http://www.CAcert.org'),),
(('commonName', 'CAcert Class 3 Root'),)),
'notAfter': 'Jun  7 21:02:24 2013 GMT',
'notBefore': 'Jun  8 21:02:24 2011 GMT',
'serialNumber': 'D3E9',
'subject': ((('commonName', 'linuxfr.org'),),),
'subjectAltName': (('DNS', 'linuxfr.org'),
('othername', '<unsupported>'),
('DNS', 'linuxfr.org'),
('othername', '<unsupported>'),
('DNS', 'dev.linuxfr.org'),
('othername', '<unsupported>'),
('DNS', 'prod.linuxfr.org'),
('othername', '<unsupported>'),
('DNS', 'alpha.linuxfr.org'),
('othername', '<unsupported>'),
('DNS', '*.linuxfr.org'),
('othername', '<unsupported>')),
'version': 3}


Now that you are assured of its authenticity, you can proceed to talk with the server:

>>> conn.sendall(b"HEAD / HTTP/1.0\r\nHost: linuxfr.org\r\n\r\n")
>>> pprint.pprint(conn.recv(1024).split(b"\r\n"))
[b'HTTP/1.1 302 Found',
b'Date: Sun, 16 May 2010 13:43:28 GMT',
b'Server: Apache/2.2',
b'Location: https://linuxfr.org/pub/',
b'Vary: Accept-Encoding',
b'Connection: close',
b'Content-Type: text/html; charset=iso-8859-1',
b'',
b'']


See the discussion of :ref:ssl-security below.

### Server-side operation

For server operation, typically you'll need to have a server certificate, and private key, each in a file. You'll first create a context holding the key and the certificate, so that clients can check your authenticity. Then you'll open a socket, bind it to a port, call :meth:listen on it, and start waiting for clients to connect:

import socket, ssl

context = ssl.SSLContext(ssl.PROTOCOL_TLSv1)

bindsocket = socket.socket()
bindsocket.listen(5)


When a client connects, you'll call :meth:accept on the socket to get the new socket from the other end, and use the context's :meth:SSLContext.wrap_socket method to create a server-side SSL socket for the connection:

while True:
connstream = context.wrap_socket(newsocket, server_side=True)
try:
deal_with_client(connstream)
finally:
connstream.shutdown(socket.SHUT_RDWR)
connstream.close()


Then you'll read data from the connstream and do something with it till you are finished with the client (or the client is finished with you):

def deal_with_client(connstream):
data = connstream.recv(1024)
# empty data means the client is finished with us
while data:
if not do_something(connstream, data):
# we'll assume do_something returns False
# when we're finished with client
break
data = connstream.recv(1024)
# finished with client


And go back to listening for new client connections (of course, a real server would probably handle each client connection in a separate thread, or put the sockets in non-blocking mode and use an event loop).

## Notes on non-blocking sockets

When working with non-blocking sockets, there are several things you need to be aware of:

• Calling :func:~select.select tells you that the OS-level socket can be read from (or written to), but it does not imply that there is sufficient data at the upper SSL layer. For example, only part of an SSL frame might have arrived. Therefore, you must be ready to handle :meth:SSLSocket.recv and :meth:SSLSocket.send failures, and retry after another call to :func:~select.select.

(of course, similar provisions apply when using other primitives such as :func:~select.poll)

• The SSL handshake itself will be non-blocking: the :meth:SSLSocket.do_handshake method has to be retried until it returns successfully. Here is a synopsis using :func:~select.select to wait for the socket's readiness:

while True:
try:
sock.do_handshake()
break
select.select([sock], [], [])
except ssl.SSLWantWriteError:
select.select([], [sock], [])


## Security considerations

### Verifying certificates

:const:CERT_NONE is the default. Since it does not authenticate the other peer, it can be insecure, especially in client mode where most of time you would like to ensure the authenticity of the server you're talking to. Therefore, when in client mode, it is highly recommended to use :const:CERT_REQUIRED. However, it is in itself not sufficient; you also have to check that the server certificate, which can be obtained by calling :meth:SSLSocket.getpeercert, matches the desired service. For many protocols and applications, the service can be identified by the hostname; in this case, the :func:match_hostname function can be used.

In server mode, if you want to authenticate your clients using the SSL layer (rather than using a higher-level authentication mechanism), you'll also have to specify :const:CERT_REQUIRED and similarly check the client certificate.

Note

In client mode, :const:CERT_OPTIONAL and :const:CERT_REQUIRED are equivalent unless anonymous ciphers are enabled (they are disabled by default).

### Protocol versions

SSL version 2 is considered insecure and is therefore dangerous to use. If you want maximum compatibility between clients and servers, it is recommended to use :const:PROTOCOL_SSLv23 as the protocol version and then disable SSLv2 explicitly using the :data:SSLContext.options attribute:

context = ssl.SSLContext(ssl.PROTOCOL_SSLv23)
context.options |= ssl.OP_NO_SSLv2


The SSL context created above will allow SSLv3 and TLSv1 connections, but not SSLv2.

### Cipher selection

If you have advanced security requirements, fine-tuning of the ciphers enabled when negotiating a SSL session is possible through the :meth:SSLContext.set_ciphers method. Starting from Python 3.2.3, the ssl module disables certain weak ciphers by default, but you may want to further restrict the cipher choice. For example:

context = ssl.SSLContext(ssl.PROTOCOL_TLSv1)
context.set_ciphers('HIGH:!aNULL:!eNULL')


The !aNULL:!eNULL part of the cipher spec is necessary to disable ciphers which don't provide both encryption and authentication. Be sure to read OpenSSL's documentation about the cipher list format. If you want to check which ciphers are enabled by a given cipher list, use the openssl ciphers command on your system.