17.3. ssl – TLS/SSL-обёртка для сокетов¶ssl – TLS/SSL wrapper for socket objects

17.3.1. Функции, константы и исключения¶Functions, Constants, and Exceptions

exception ssl.SSLError¶

Возбуждается для сигнализации об ошибке в базовой реализации SSL. Это указывает на некоторую проблему в вышележащем уровне шифрования и аутентификации, который накладывается на нижележащее сетевое соединение. Эта ошибка является подтипом socket.error, который, в свою очередь, является подтипом IOError.

ssl.wrap_socket(sock, keyfile=None, certfile=None, server_side=False, cert_reqs=CERT_NONE, ssl_version={see docs}, ca_certs=None, do_handshake_on_connect=True, suppress_ragged_eofs=True)¶

Принимает экземпляр sock класса socket.socket и возвращает экземпляр ssl.SSLSocket, подтип socket.socket, который оборачивает базовый сокет в контекст SSL. Для клиентских сокетов построение контекста является отложенным; если базовый сокет ещё не подключён, построение контекста будет выполнено после вызова connect() на сокете. Для серверных сокетов, если у сокета нет удалённого узла, он считается слушающим сокетом, и серверная SSL-обёртка автоматически выполняется для клиентских подключений, принятых через метод accept(). wrap_socket() может возбудить SSLError.

Параметры keyfile и certfile задают необязательные файлы, содержащие сертификат, используемый для идентификации локальной стороны соединения. См. обсуждение Certificates для получения дополнительной информации о том, как сертификат хранится в certfile.

Часто закрытый ключ хранится в том же файле, что и сертификат; в этом случае достаточно передать только параметр certfile. Если закрытый ключ хранится в отдельном файле, необходимо использовать оба параметра. Если закрытый ключ хранится в certfile, он должен предшествовать первому сертификату в цепочке сертификатов:

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

Параметр server_side – это логическое значение, которое определяет, требуется ли от этого сокета поведение серверной или клиентской стороны.

Параметр cert_reqs задаёт, требуется ли сертификат от другой стороны соединения и будет ли он проверен, если предоставлен. Он должен быть одним из трёх значений: CERT_NONE (сертификаты игнорируются), CERT_OPTIONAL (не требуется, но проверяется, если предоставлен) или CERT_REQUIRED (требуется и проверяется). Если значение этого параметра не CERT_NONE, то параметр ca_certs должен указывать на файл с сертификатами ЦС.

Файл ca_certs содержит набор объединённых сертификатов «центров сертификации», которые используются для проверки сертификатов, переданных с другого конца соединения. См. обсуждение Certificates для получения дополнительной информации о том, как организовать сертификаты в этом файле.

Параметр ssl_version определяет, какая версия протокола SSL будет использоваться. Обычно сервер выбирает конкретную версию протокола, а клиент должен подстраиваться под выбор сервера. Большинство версий несовместимы друг с другом. Если параметр не указан, для работы на стороне клиента по умолчанию используется SSLv3; для работы на стороне сервера – SSLv23. Такой выбор версий обеспечивает наибольшую совместимость с другими версиями.

Ниже приведена таблица, показывающая, какие версии на стороне клиента (по вертикали) могут подключаться к каким версиям на стороне сервера (по горизонтали):

клиент / сервер	SSLv2	SSLv3	SSLv23	TLSv1
SSLv2	да	нет	yes*	нет
SSLv3	да	да	да	нет
SSLv23	да	нет	да	нет
TLSv1	нет	нет	да	да

В некоторых старых версиях OpenSSL (например, 0.9.7l на OS X 10.4) клиент SSLv2 не мог подключиться к серверу SSLv23.

Параметр do_handshake_on_connect определяет, выполнять ли квитирование SSL автоматически после вызова socket.connect(), или же программа должна вызывать его явно с помощью метода SSLSocket.do_handshake(). Явный вызов SSLSocket.do_handshake() даёт программе контроль над блокирующим поведением операций ввода-вывода сокета, участвующих в квитировании.

Параметр suppress_ragged_eofs определяет, как метод SSLSocket.read() должен обрабатывать неожиданный EOF с другой стороны соединения. Если указано True (значение по умолчанию), метод возвращает обычный EOF в ответ на ошибки неожиданного EOF, возникающие в нижележащем сокете; если False, исключения будут передаваться обратно вызывающему коду.

ssl.RAND_status()¶

Возвращает True, если SSL-генератор псевдослучайных чисел был инициализирован «достаточным» количеством случайности, и False в противном случае. Для увеличения случайности генератора псевдослучайных чисел можно использовать ssl.RAND_egd() и ssl.RAND_add().

ssl.RAND_egd(path)¶

Если где-то запущен демон сбора энтропии (EGD) и path является именем пути сокетного соединения, открытого к нему, то эта функция прочитает 256 байт случайности из сокета и добавит их в SSL-генератор псевдослучайных чисел для повышения безопасности генерируемых секретных ключей. Обычно это необходимо только в системах без лучших источников случайности.

См. http://egd.sourceforge.net/ или http://prngd.sourceforge.net/ для получения исходных текстов демонов сбора энтропии.

ssl.RAND_add(bytes, entropy)¶

Смешивает заданные bytes с SSL-генератором псевдослучайных чисел. Параметр entropy (число с плавающей запятой) является нижней границей энтропии, содержащейся в строке (поэтому всегда можно использовать 0.0). См. RFC 1750 для получения дополнительной информации об источниках энтропии.

ssl.cert_time_to_seconds(timestring)¶

Возвращает значение с плавающей запятой, содержащее обычное время в секундах от начала эпохи, для строки времени, представляющей дату “notBefore” или “notAfter” из сертификата.

Вот пример:

>>> import ssl
>>> ssl.cert_time_to_seconds("May  9 00:00:00 2007 GMT")
1178694000.0
>>> import time
>>> time.ctime(ssl.cert_time_to_seconds("May  9 00:00:00 2007 GMT"))
'Wed May  9 00:00:00 2007'
>>>

ssl.get_server_certificate(addr, ssl_version=PROTOCOL_SSLv3, ca_certs=None)¶

По заданному адресу addr SSL-защищённого сервера, в виде пары (hostname, port-number), получает сертификат сервера и возвращает его в виде строки в кодировке PEM. Если указан ssl_version, используется эта версия протокола SSL для попытки подключения к серверу. Если указан ca_certs, это должен быть файл, содержащий список корневых сертификатов, в том же формате, который используется для одноимённого параметра в wrap_socket(). Вызов попытается проверить сертификат сервера по этому набору корневых сертификатов, и завершится неудачей, если проверка не пройдёт.

ssl.DER_cert_to_PEM_cert(DER_cert_bytes)¶

Принимая сертификат в виде набора байтов в кодировке DER, возвращает версию того же сертификата в виде строки в кодировке PEM.

ssl.PEM_cert_to_DER_cert(PEM_cert_string)¶

Принимая сертификат в виде строки ASCII в формате PEM, возвращает последовательность байтов в кодировке DER для того же сертификата.

ssl.CERT_NONE¶

Значение, передаваемое параметру cert_reqs функции sslobject(), когда не требуется запрашивать или проверять сертификаты с другой стороны сокетного соединения.

ssl.CERT_OPTIONAL¶

Значение, передаваемое параметру cert_reqs функции sslobject(), когда сертификаты не требуются с другой стороны сокетного соединения, но если они предоставлены, то проверяются. Обратите внимание, что использование этой настройки требует также передачи валидного файла для проверки сертификатов в качестве значения параметра ca_certs.

ssl.CERT_REQUIRED¶

Значение, передаваемое параметру cert_reqs функции sslobject(), когда сертификаты требуются с другой стороны сокетного соединения. Обратите внимание, что использование этой настройки требует также передачи валидного файла для проверки сертификатов в качестве значения параметра ca_certs.

ssl.PROTOCOL_SSLv2¶

Выбирает SSL версии 2 в качестве протокола шифрования канала.

Этот протокол недоступен, если OpenSSL скомпилирован с флагом OPENSSL_NO_SSL2 .

Предупреждение

SSL версии 2 небезопасен. Его использование крайне не рекомендуется.

ssl.PROTOCOL_SSLv23¶

Выбирает SSL версии 2 или 3 в качестве протокола шифрования канала. Это настройка для использования с серверами для максимальной совместимости с другой стороной SSL-соединения, но может привести к выбору довольно низкокачественных шифров для шифрования.

ssl.PROTOCOL_SSLv3¶

Выбирает SSL версии 3 в качестве протокола шифрования канала. Для клиентов это максимально совместимый вариант SSL.

ssl.PROTOCOL_TLSv1¶

Выбирает TLS версии 1 в качестве протокола шифрования канала. Это самая современная версия и, вероятно, лучший выбор для максимальной защиты, если обе стороны её поддерживают.

17.3.2. Объекты SSLSocket¶SSLSocket Objects

SSLSocket.read(nbytes=1024, buffer=None)¶

Reads up to nbytes bytes from the SSL-encrypted channel and returns them. If the buffer is specified, it will attempt to read into the buffer the minimum of the size of the buffer and nbytes, if that is specified. If no buffer is specified, an immutable buffer is allocated and returned with the data read from the socket.

SSLSocket.write(data)¶

Writes the data to the other side of the connection, using the SSL channel to encrypt. Returns the number of bytes written.

SSLSocket.do_handshake()¶

Performs the SSL setup handshake. If the socket is non-blocking, this method may raise SSLError with the value of the exception instance’s args[0] being either SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE, and should be called again until it stops raising those exceptions. Here’s an example of how to do that:

while True:
    try:
        sock.do_handshake()
        break
    except ssl.SSLError as err:
        if err.args[0] == ssl.SSL_ERROR_WANT_READ:
            select.select([sock], [], [])
        elif err.args[0] == ssl.SSL_ERROR_WANT_WRITE:
            select.select([], [sock], [])
        else:
            raise

SSLSocket.getpeercert(binary_form=False)¶

Если на другом конце соединения нет сертификата у удаленной стороны, возвращается None.

If the parameter binary_form is False, and a certificate was received from the peer, this method returns a dict instance. If the certificate was not validated, the dict is empty. If the certificate was validated, it returns a dict with the keys subject (the principal for which the certificate was issued), and notAfter (the time after which the certificate should not be trusted). The certificate was already validated, so the notBefore and issuer fields are not returned. If a certificate contains an instance of the Subject Alternative Name extension (see RFC 3280), there will also be a subjectAltName key in the dictionary.

Поле «subject» представляет собой кортеж, содержащий последовательность относительных отличительных имён (RDN), заданных в структуре данных сертификата для субъекта, и каждый RDN – это последовательность пар «имя-значение»:

{'notAfter': 'Feb 16 16:54:50 2013 GMT',
 'subject': ((('countryName', 'US'),),
             (('stateOrProvinceName', 'Delaware'),),
             (('localityName', 'Wilmington'),),
             (('organizationName', 'Python Software Foundation'),),
             (('organizationalUnitName', 'SSL'),),
             (('commonName', 'somemachine.python.org'),))}

Если параметр binary_form равен True и сертификат был предоставлен, этот метод возвращает полный сертификат в DER-кодировке в виде последовательности байтов или None, если одноранговый узел не предоставил сертификат. Возвращаемое значение не зависит от проверки; если проверка требовалась (CERT_OPTIONAL или CERT_REQUIRED), сертификат будет проверен, но если для установки соединения использовалось CERT_NONE, то сертификат (если он есть) проверен не будет.

SSLSocket.cipher()¶

Возвращает кортеж из трех значений, содержащий название используемого шифра, версию протокола SSL, которая определяет его использование, и количество используемых секретных битов. Если соединение не установлено, возвращает None.

SSLSocket.unwrap()¶

Выполняет рукопожатие завершения SSL, которое удаляет слой TLS из базового сокета и возвращает объект базового сокета. Это можно использовать для перехода от зашифрованной работы по соединению к незашифрованной. Возвращённый сокет всегда следует использовать для дальнейшего обмена данными с другой стороной соединения, а не исходный сокет.

17.3.3. Сертификаты¶Certificates

Сертификаты в целом являются частью системы открытых и закрытых ключей. В этой системе каждому субъекту (которым может быть машина, человек или организация) присваивается уникальный двухчастный ключ шифрования. Одна часть ключа является открытой и называется открытым ключом; другая часть хранится в секрете и называется закрытым ключом. Две части связаны так, что если зашифровать сообщение одной частью, его можно расшифровать только другой частью, и только другой частью.

Сертификат содержит информацию о двух субъектах. Он содержит имя субъекта и его открытый ключ. Также он содержит утверждение второго субъекта, издателя, о том, что субъект является тем, за кого себя выдаёт, и что это действительно открытый ключ субъекта. Утверждение издателя подписано закрытым ключом издателя, который известен только издателю. Однако любой может проверить утверждение издателя, найдя его открытый ключ, расшифровав им утверждение и сравнив его с другой информацией в сертификате. Сертификат также содержит информацию о периоде времени, в течение которого он действителен. Это выражается двумя полями, называемыми «notBefore» и «notAfter».

При использовании сертификатов в Python клиент или сервер может использовать сертификат для подтверждения своей личности. Другая сторона сетевого соединения также может быть обязана предоставить сертификат, и этот сертификат может быть проверен к удовлетворению клиента или сервера, требующего такой проверки. Можно настроить попытку соединения так, чтобы она вызывала исключение, если проверка не удалась. Проверка выполняется автоматически базовым фреймворком OpenSSL; приложению не нужно вникать в её механику. Но приложению обычно необходимо предоставить наборы сертификатов, чтобы этот процесс мог происходить.

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-----

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-----
... (certificate for your server)...
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
... (the certificate for the CA)...
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
... (the root certificate for the CA's issuer)...
-----END CERTIFICATE-----

Если требуется проверка сертификата другой стороны соединения, необходимо предоставить файл «CA certs», содержащий цепочки сертификатов для каждого издателя, которому вы готовы доверять. Этот файл просто содержит эти цепочки, объединённые вместе. Для проверки Python будет использовать первую подходящую цепочку в файле. Некоторые «стандартные» корневые сертификаты доступны от различных центров сертификации: CACert.org, Thawte, Verisign, Positive SSL (используется python.org), Equifax и GeoTrust.

В общем случае, если вы используете SSL3 или TLS1, не нужно помещать полную цепочку в файл «CA certs»; достаточно корневых сертификатов, а удалённый узел должен предоставить остальные сертификаты, необходимые для построения цепочки от своего сертификата до корневого. См. RFC 4158 для более подробного обсуждения способов построения цепочек сертификатов.

Если планируется создать сервер, предоставляющий услуги SSL-защищённого соединения, потребуется приобрести сертификат для этой службы. Существует много способов получения подходящих сертификатов, например покупка в удостоверяющем центре. Ещё одна распространённая практика – сгенерировать самоподписанный сертификат. Самый простой способ сделать это – использовать пакет OpenSSL, примерно следующим образом:

% 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
into your certificate request.
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
Email Address []:ops@myserver.mygroup.myorganization.com
%

Недостаток самоподписанного сертификата в том, что он является собственным корневым сертификатом, и никто другой не будет иметь его в своём кэше известных (и доверенных) корневых сертификатов.

17.3.4. Примеры¶Examples

try:
    import ssl
except ImportError:
    pass
else:
    ... # сделать что-то, что требует поддержки SSL

import socket, ssl, pprint

s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)

# требовать сертификат от сервера
ssl_sock = ssl.wrap_socket(s,
                           ca_certs="/etc/ca_certs_file",
                           cert_reqs=ssl.CERT_REQUIRED)

ssl_sock.connect(('www.verisign.com', 443))

print(repr(ssl_sock.getpeername()))
pprint.pprint(ssl_sock.getpeercert())
print(pprint.pformat(ssl_sock.getpeercert()))

# Установить простой HTTP-запрос – в реальном коде используйте http.client.
ssl_sock.write("""GET / HTTP/1.0\r
Host: www.verisign.com\r\n\r\n""")

# Прочитать порцию данных. Не обязательно
# прочитать все данные, возвращённые сервером.
data = ssl_sock.read()

# закрытие SSLSocket также закроет нижележащий сокет
ssl_sock.close()

{'notAfter': 'May  8 23:59:59 2009 GMT',
 'subject': ((('serialNumber', '2497886'),),
             (('1.3.6.1.4.1.311.60.2.1.3', 'US'),),
             (('1.3.6.1.4.1.311.60.2.1.2', 'Delaware'),),
             (('countryName', 'US'),),
             (('postalCode', '94043'),),
             (('stateOrProvinceName', 'California'),),
             (('localityName', 'Mountain View'),),
             (('streetAddress', '487 East Middlefield Road'),),
             (('organizationName', 'VeriSign, Inc.'),),
             (('organizationalUnitName',
               'Production Security Services'),),
             (('organizationalUnitName',
               'Terms of use at www.verisign.com/rpa (c)06'),),
             (('commonName', 'www.verisign.com'),))}

import socket, ssl

bindsocket = socket.socket()
bindsocket.bind(('myaddr.mydomain.com', 10023))
bindsocket.listen(5)

while True:
    newsocket, fromaddr = bindsocket.accept()
    connstream = ssl.wrap_socket(newsocket,
                                 server_side=True,
                                 certfile="mycertfile",
                                 keyfile="mykeyfile",
                                 ssl_version=ssl.PROTOCOL_TLSv1)
    try:
        deal_with_client(connstream)
    finally:
        connstream.shutdown(socket.SHUT_RDWR)
        connstream.close()

def deal_with_client(connstream):
    data = connstream.read()
    # null-данные означают, что клиент завершил работу с нами
    while data:
        if not do_something(connstream, data):
            # будем считать, что do_something возвращает False
            # когда мы закончили с клиентом
            break
        data = connstream.read()
    # закончили с клиентом