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

17.3.1.1. Создание сокета¶Socket creation

Следующая функция позволяет создавать сокеты как отдельные объекты. Начиная с Python 2.7.9, для большей гибкости можно использовать SSLContext.wrap_socket().

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, ciphers=None)¶

Принимает экземпляр sock класса socket.socket и возвращает экземпляр ssl.SSLSocket, подтипа socket.socket, который оборачивает базовый сокет в контекст SSL. sock должен быть сокетом SOCK_STREAM; другие типы сокетов не поддерживаются.

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

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

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

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

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

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

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

клиент / сервер	SSLv2	SSLv3	SSLv23	TLSv1	TLSv1.1	TLSv1.2
SSLv2	да	нет	да	нет	нет	нет
SSLv3	нет	да	да	нет	нет	нет
SSLv23 1	нет	да	да	да	да	да
TLSv1	нет	нет	да	да	нет	нет
TLSv1.1	нет	нет	да	нет	да	нет
TLSv1.2	нет	нет	да	нет	нет	да

Сноски

1

Протокол TLS 1.3 будет доступен с PROTOCOL_SSLv23 в OpenSSL >= 1.1.1. Для одного только TLS 1.3 не существует отдельной константы PROTOCOL.

Примечание

Какие соединения будут успешными, зависит от версии OpenSSL. Например, до OpenSSL 1.0.0 клиент SSLv23 всегда пытался устанавливать соединения SSLv2.

Параметр ciphers задаёт доступные шифры для этого объекта SSL. Он должен быть строкой в формате списка шифров OpenSSL.

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

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

Изменено в версии 2.7: Новый необязательный аргумент ciphers.

17.3.1.2. Создание контекста¶Context creation

Вспомогательная функция помогает создавать объекты SSLContext для распространённых целей.

ssl.create_default_context(purpose=Purpose.SERVER_AUTH, cafile=None, capath=None, cadata=None)¶

Возвращает новый объект SSLContext с настройками по умолчанию для указанного назначения. Настройки выбираются модулем ssl и обычно представляют более высокий уровень безопасности, чем при непосредственном вызове конструктора SSLContext.

cafile, capath, cadata представляют необязательные сертификаты ЦС, которым следует доверять при проверке сертификатов, как в SSLContext.load_verify_locations(). Если все три равны None, эта функция может вместо этого доверять системным сертификатам ЦС по умолчанию.

Настройки таковы: PROTOCOL_SSLv23, OP_NO_SSLv2 и OP_NO_SSLv3 с наборами шифров высокого уровня без RC4 и без неаутентифицированных наборов шифров. Передача SERVER_AUTH в качестве purpose устанавливает verify_mode в CERT_REQUIRED и либо загружает сертификаты CA (когда задан хотя бы один из cafile, capath или cadata), либо использует SSLContext.load_default_certs() для загрузки сертификатов CA по умолчанию.

Примечание

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

Если приложению требуются особые настройки, нужно создать SSLContext и применить их самостоятельно.

Примечание

Если при попытке некоторых старых клиентов или серверов подключиться с помощью SSLContext, созданного этой функцией, возникает ошибка «Несовпадение протокола или набора шифров», возможно, они поддерживают только SSL 3.0, который эта функция исключает с помощью OP_NO_SSLv3. SSL 3.0 общепризнанно полностью скомпрометирован. Если всё же необходимо продолжить использование этой функции, но при этом разрешить подключения SSL 3.0, можно снова включить их с помощью:

ctx = ssl.create_default_context(Purpose.CLIENT_AUTH)
ctx.options &= ~ssl.OP_NO_SSLv3

Новое в версии 2.7.9.

Изменено в версии 2.7.10: RC4 был удалён из строки шифров по умолчанию.

Изменено в версии 2.7.13: ChaCha20/Poly1305 добавлен в строку шифров по умолчанию.

3DES был удалён из строки шифров по умолчанию.

ssl._https_verify_certificates(enable=True)¶

Определяет, проверяются ли сертификаты сервера при создании клиентских HTTPS-соединений без указания конкретного SSL-контекста.

Начиная с Python 2.7.9, httplib и модули, которые его используют, такие как urllib2 и xmlrpclib, по умолчанию проверяют сертификаты удалённых серверов, полученные при установке клиентских HTTPS-соединений. Эта проверка по умолчанию удостоверяется, что сертификат подписан центром сертификации из системного хранилища доверенных сертификатов, и что общее имя (или альтернативное имя субъекта) в представленном сертификате соответствует запрошенному хосту.

Присвоение enable значения True гарантирует, что поведение по умолчанию остаётся в силе.

Установка enable в значение False возвращает обработку сертификатов HTTPS по умолчанию к версии Python 2.7.8 и более ранних, разрешая подключения к серверам, использующим самоподписанные сертификаты, серверам с сертификатами, подписанными центром сертификации, отсутствующим в системном хранилище доверенных сертификатов, а также к серверам, где имя хоста не соответствует представленному сертификату.

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

Новое в версии 2.7.12.

См. также

• CVE-2014-9365 – HTTPS-атака «человек посередине» на клиентов Python, использующих настройки по умолчанию

• PEP 476 – Включение проверки сертификатов по умолчанию для HTTPS

• PEP 493 – Инструменты миграции проверки HTTPS для Python 2.7

17.3.1.3. Генерация случайных чисел¶Random generation

Устарело с версии 2.7.13: OpenSSL объявил устаревшим ssl.RAND_pseudo_bytes(), используйте ssl.RAND_bytes() вместо него.

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/ для получения исходных текстов демонов сбора энтропии.

Доступность: недоступно с LibreSSL и OpenSSL > 1.1.0

ssl.RAND_add(bytes, entropy)¶

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

17.3.1.4. Обработка сертификатов¶Certificate handling

ssl.match_hostname(cert, hostname)¶

Проверяет, что cert (в декодированном виде, как возвращается SSLSocket.getpeercert()) соответствует заданному hostname. Применяются правила проверки идентичности HTTPS-серверов, описанные в RFC 2818 и RFC 6125, за исключением того, что IP-адреса в настоящее время не поддерживаются. Помимо HTTPS, эта функция подходит для проверки идентичности серверов в различных протоколах на основе SSL, таких как FTPS, IMAPS, POPS и других.

CertificateError возбуждается при неудаче. При успехе функция не возвращает ничего:

>>> cert = {'subject': ((('commonName', 'example.com'),),)}
>>> ssl.match_hostname(cert, "example.com")
>>> ssl.match_hostname(cert, "example.org")
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/home/py3k/Lib/ssl.py", line 130, in match_hostname
ssl.CertificateError: hostname 'example.org' doesn't match 'example.com'

Новое в версии 2.7.9.

ssl.cert_time_to_seconds(cert_time)¶

Возвращает время в секундах с начала эпохи (Epoch), используя строку cert_time представляющую дату “notBefore” или “notAfter” из сертификата в формате "%b %d %H:%M:%S %Y %Z" strptime (локаль C).

Вот пример:

>>> import ssl
>>> timestamp = ssl.cert_time_to_seconds("Jan  5 09:34:43 2018 GMT")
>>> timestamp
1515144883
>>> from datetime import datetime
>>> print(datetime.utcfromtimestamp(timestamp))
2018-01-05 09:34:43

Даты “notBefore” or “notAfter” должны использовать GMT (RFC 5280).

Изменено в версии 2.7.9: Интерпретирует входное время как время в UTC, как указано часовым поясом 'GMT' во входной строке. Ранее использовался местный часовой пояс. Возвращает целое число (без долей секунды во входном формате).

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

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

Изменено в версии 2.7.9: Эта функция теперь совместима с IPv6, а значение по умолчанию ssl_version изменено с PROTOCOL_SSLv3 на PROTOCOL_SSLv23 для максимальной совместимости с современными серверами.

ssl.DER_cert_to_PEM_cert(DER_cert_bytes)¶

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

ssl.PEM_cert_to_DER_cert(PEM_cert_string)¶

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

ssl.get_default_verify_paths()¶

Возвращает именованный кортеж с путями к файлу cafile и каталогу capath OpenSSL по умолчанию. Эти пути совпадают с используемыми в SSLContext.set_default_verify_paths(). Возвращаемое значение – это именованный кортеж DefaultVerifyPaths:

• cafile – разрешённый (абсолютный) путь к cafile или None, если файл не существует,

• capath – разрешённый путь к capath или None, если каталог не существует,

• openssl_cafile_env – переменная окружения OpenSSL, указывающая на cafile,

• openssl_cafile – жёстко заданный путь к cafile,

• openssl_capath_env – переменная окружения OpenSSL, указывающая на capath,

• openssl_capath – жёстко заданный путь к каталогу capath

Доступность: LibreSSL игнорирует переменные окружения openssl_cafile_env и openssl_capath_env

Новое в версии 2.7.9.

ssl.enum_certificates(store_name)¶

Извлекает сертификаты из системного хранилища сертификатов Windows. store_name может быть одним из CA, ROOT или MY. Windows также может предоставлять дополнительные хранилища сертификатов.

Функция возвращает список кортежей (cert_bytes, encoding_type, trust). Параметр encoding_type задаёт кодировку cert_bytes. Это может быть x509_asn для данных X.509 ASN.1 или pkcs_7_asn для данных PKCS#7 ASN.1. Параметр trust определяет назначение сертификата в виде набора OID или точно True, если сертификат считается надёжным для всех целей.

Пример:

>>> ssl.enum_certificates("CA")
[(b'data...', 'x509_asn', {'1.3.6.1.5.5.7.3.1', '1.3.6.1.5.5.7.3.2'}),
 (b'data...', 'x509_asn', True)]

Доступность: Windows.

Новое в версии 2.7.9.

ssl.enum_crls(store_name)¶

Извлекает CRL из системного хранилища сертификатов Windows. store_name может быть одним из CA, ROOT или MY. Windows также может предоставлять дополнительные хранилища сертификатов.

Функция возвращает список кортежей (cert_bytes, encoding_type, trust). Параметр encoding_type задаёт кодировку cert_bytes. Это может быть x509_asn для данных X.509 ASN.1 или pkcs_7_asn для данных PKCS#7 ASN.1.

Доступность: Windows.

Новое в версии 2.7.9.

17.3.1.5. Константы¶Constants

ssl.CERT_NONE¶

Возможное значение для SSLContext.verify_mode или параметра cert_reqs в wrap_socket(). В этом режиме (по умолчанию) сертификаты не требуются от другой стороны сокетного соединения. Если сертификат получен от другой стороны, попытка его проверки не предпринимается.

См. обсуждение соображений безопасности ниже.

ssl.CERT_OPTIONAL¶

Возможное значение для SSLContext.verify_mode или параметра cert_reqs в wrap_socket(). В этом режиме сертификаты не требуются от другой стороны сокетного соединения; но если они предоставлены, будет предпринята попытка проверки и в случае неудачи будет возбуждено SSLError.

Использование этой настройки требует передачи действительного набора сертификатов ЦС: либо в SSLContext.load_verify_locations(), либо в качестве значения параметра ca_certs для wrap_socket().

ssl.CERT_REQUIRED¶

Возможное значение для SSLContext.verify_mode или параметра cert_reqs в wrap_socket(). В этом режиме сертификаты требуются от другой стороны сокетного соединения; SSLError будет возбуждено, если сертификат не предоставлен или его проверка не удалась.

Использование этой настройки требует передачи действительного набора сертификатов ЦС: либо в SSLContext.load_verify_locations(), либо в качестве значения параметра ca_certs для wrap_socket().

ssl.VERIFY_DEFAULT¶

Возможное значение для SSLContext.verify_flags. В этом режиме списки отзыва сертификатов (CRL) не проверяются. По умолчанию OpenSSL не требует и не проверяет CRL.

Новое в версии 2.7.9.

ssl.VERIFY_CRL_CHECK_LEAF¶

Возможное значение для SSLContext.verify_flags. В этом режиме проверяется только сертификат пира, но ни один из промежуточных сертификатов ЦС. Режим требует действительный CRL, подписанный издателем сертификата пира (его непосредственным вышестоящим ЦС). Если надлежащий не был загружен SSLContext.load_verify_locations, проверка завершится ошибкой.

Новое в версии 2.7.9.

ssl.VERIFY_CRL_CHECK_CHAIN¶

Возможное значение для SSLContext.verify_flags. В этом режиме проверяются CRL всех сертификатов в цепочке сертификата однорангового узла.

Новое в версии 2.7.9.

ssl.VERIFY_X509_STRICT¶

Возможное значение для SSLContext.verify_flags для отключения обходных путей для повреждённых сертификатов X.509.

Новое в версии 2.7.9.

ssl.VERIFY_X509_TRUSTED_FIRST¶

Возможное значение для SSLContext.verify_flags. Оно указывает OpenSSL отдавать предпочтение доверенным сертификатам при построении цепочки доверия для проверки сертификата. Этот флаг включён по умолчанию.

Новое в версии 2.7.10.

ssl.PROTOCOL_TLS¶

Выбирает самую высокую версию протокола, поддерживаемую как клиентом, так и сервером. Несмотря на название, этот параметр может выбирать протоколы «TLS», а также «SSL».

Новое в версии 2.7.13.

ssl.PROTOCOL_SSLv23¶

Псевдоним для PROTOCOL_TLS.

Устарело с версии 2.7.13: Используйте PROTOCOL_TLS вместо этого.

ssl.PROTOCOL_SSLv2¶

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

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

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

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

Устарело с версии 2.7.13: OpenSSL удалил поддержку SSLv2.

ssl.PROTOCOL_SSLv3¶

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

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

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

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

Устарело с версии 2.7.13: OpenSSL объявил устаревшими все протоколы, привязанные к версиям. Используйте протокол по умолчанию с флагами, такими как OP_NO_SSLv3, вместо этого.

ssl.PROTOCOL_TLSv1¶

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

Устарело с версии 2.7.13: OpenSSL объявил устаревшими все протоколы, привязанные к версиям. Используйте протокол по умолчанию с флагами, такими как OP_NO_SSLv3, вместо этого.

ssl.PROTOCOL_TLSv1_1¶

Выбирает TLS версии 1.1 в качестве протокола шифрования канала. Доступно только в openssl версии 1.0.1+.

Новое в версии 2.7.9.

Устарело с версии 2.7.13: OpenSSL объявил устаревшими все протоколы, привязанные к версиям. Используйте протокол по умолчанию с флагами, такими как OP_NO_SSLv3, вместо этого.

ssl.PROTOCOL_TLSv1_2¶

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

Новое в версии 2.7.9.

Устарело с версии 2.7.13: OpenSSL объявил устаревшими все протоколы, привязанные к версиям. Используйте протокол по умолчанию с флагами, такими как OP_NO_SSLv3, вместо этого.

ssl.OP_ALL¶

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

Новое в версии 2.7.9.

ssl.OP_NO_SSLv2¶

Предотвращает подключение по SSLv2. Эта опция применима только в сочетании с PROTOCOL_SSLv23. Она не позволяет сторонам выбирать SSLv2 в качестве версии протокола.

Новое в версии 2.7.9.

ssl.OP_NO_SSLv3¶

Предотвращает подключение по SSLv3. Этот параметр применим только в сочетании с PROTOCOL_SSLv23. Он не позволяет участникам выбирать SSLv3 в качестве версии протокола.

Новое в версии 2.7.9.

ssl.OP_NO_TLSv1¶

Предотвращает подключение по TLSv1. Этот параметр применим только в сочетании с PROTOCOL_SSLv23. Он не позволяет участникам выбирать TLSv1 в качестве версии протокола.

Новое в версии 2.7.9.

ssl.OP_NO_TLSv1_1¶

Предотвращает подключение по TLSv1.1. Этот параметр применим только в сочетании с PROTOCOL_SSLv23. Он не позволяет участникам выбирать TLSv1.1 в качестве версии протокола. Доступно только для OpenSSL версии 1.0.1 и выше.

Новое в версии 2.7.9.

ssl.OP_NO_TLSv1_2¶

Предотвращает подключение по TLSv1.2. Этот параметр применим только в сочетании с PROTOCOL_SSLv23. Он не позволяет участникам выбирать TLSv1.2 в качестве версии протокола. Доступно только для OpenSSL версии 1.0.1 и выше.

Новое в версии 2.7.9.

ssl.OP_NO_TLSv1_3¶

Предотвращает подключение по TLSv1.3. Этот параметр применим только в сочетании с PROTOCOL_TLS. Он не позволяет участникам выбирать TLSv1.3 в качестве версии протокола. TLS 1.3 доступен начиная с OpenSSL 1.1.1. Если Python был собран с более старой версией OpenSSL, этот флаг по умолчанию равен 0.

Новое в версии 2.7.15.

ssl.OP_CIPHER_SERVER_PREFERENCE¶

Использовать порядок шифров, заданный на сервере, а не на клиенте. Этот параметр не влияет на клиентские сокеты и сокеты сервера SSLv2.

Новое в версии 2.7.9.

ssl.OP_SINGLE_DH_USE¶

Предотвращает повторное использование одного и того же DH-ключа для разных SSL-сессий. Это улучшает прямую секретность, но требует больше вычислительных ресурсов. Данная опция применяется только к серверным сокетам.

Новое в версии 2.7.9.

ssl.OP_SINGLE_ECDH_USE¶

Предотвращает повторное использование одного и того же ECDH-ключа для разных SSL-сессий. Это улучшает прямую секретность, но требует больше вычислительных ресурсов. Данная опция применяется только к серверным сокетам.

Новое в версии 2.7.9.

ssl.OP_ENABLE_MIDDLEBOX_COMPAT¶

Отправляет фиктивные сообщения Change Cipher Spec (CCS) в процессе рукопожатия TLS 1.3, чтобы подключение TLS 1.3 выглядело больше как подключение TLS 1.2.

Этот параметр доступен только в OpenSSL 1.1.1 и выше.

Новое в версии 2.7.16.

ssl.OP_NO_COMPRESSION¶

Отключает сжатие в SSL-канале. Это полезно, если прикладной протокол поддерживает собственный механизм сжатия.

Эта опция доступна только в OpenSSL 1.0.0 и более поздних версиях.

Новое в версии 2.7.9.

ssl.HAS_ALPN¶

Указывает, имеет ли библиотека OpenSSL встроенную поддержку расширения TLS Согласование протокола прикладного уровня, как описано в RFC 7301.

Новое в версии 2.7.10.

ssl.HAS_ECDH¶

Определяет, имеет ли библиотека OpenSSL встроенную поддержку обмена ключами Диффи-Хеллмана на основе эллиптических кривых. Должно быть истинно, если только эта возможность не была явно отключена распространителем.

Новое в версии 2.7.9.

ssl.HAS_SNI¶

Указывает, имеет ли библиотека OpenSSL встроенную поддержку расширения Server Name Indication (как определено в RFC 4366).

Новое в версии 2.7.9.

ssl.HAS_NPN¶

Whether the OpenSSL library has built-in support for Next Protocol Negotiation as described in the NPN draft specification. When true, you can use the SSLContext.set_npn_protocols() method to advertise which protocols you want to support.

Новое в версии 2.7.9.

ssl.HAS_TLSv1_3¶

Определяет, поддерживает ли библиотека OpenSSL протокол TLS 1.3 на встроенном уровне.

Новое в версии 2.7.15.

ssl.CHANNEL_BINDING_TYPES¶

Список поддерживаемых типов привязки каналов TLS. Строки из этого списка можно использовать в качестве аргументов для SSLSocket.get_channel_binding().

Новое в версии 2.7.9.

ssl.OPENSSL_VERSION¶

Строка с версией библиотеки OpenSSL, загруженной интерпретатором:

>>> ssl.OPENSSL_VERSION
'OpenSSL 0.9.8k 25 Mar 2009'

Новое в версии 2.7.

ssl.OPENSSL_VERSION_INFO¶

Кортеж из пяти целых чисел, содержащий информацию о версии библиотеки OpenSSL:

>>> ssl.OPENSSL_VERSION_INFO
(0, 9, 8, 11, 15)

Новое в версии 2.7.

ssl.OPENSSL_VERSION_NUMBER¶

Сырой номер версии библиотеки OpenSSL в виде целого числа:

>>> ssl.OPENSSL_VERSION_NUMBER
9470143L
>>> hex(ssl.OPENSSL_VERSION_NUMBER)
'0x9080bfL'

Новое в версии 2.7.

ssl.ALERT_DESCRIPTION_HANDSHAKE_FAILURE¶

ssl.ALERT_DESCRIPTION_INTERNAL_ERROR¶

ALERT_DESCRIPTION_*

Описания предупреждений из RFC 5246 и других источников. Реестр предупреждений TLS IANA содержит этот список и ссылки на RFC, где определено их значение.

Используется как возвращаемое значение колбэка в SSLContext.set_servername_callback().

Новое в версии 2.7.9.

Purpose.SERVER_AUTH¶

Опция для create_default_context() и SSLContext.load_default_certs(). Это значение указывает, что контекст может использоваться для аутентификации веб-серверов (следовательно, он будет использоваться для создания клиентских сокетов).

Новое в версии 2.7.9.

Purpose.CLIENT_AUTH¶

Опция для create_default_context() и SSLContext.load_default_certs(). Это значение указывает, что контекст может использоваться для аутентификации веб-клиентов (поэтому он будет использоваться для создания серверных сокетов).

Новое в версии 2.7.9.

17.3.4.1. Цепочки сертификатов¶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-----
... (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-----

17.3.4.2. Сертификаты CA¶CA certificates

Если требуется проверка сертификата другой стороны соединения, необходимо предоставить файл «CA certs», содержащий цепочки сертификатов для каждого эмитента, которому вы готовы доверять. Этот файл просто содержит эти цепочки, объединённые вместе. Для проверки Python будет использовать первую найденную в файле подходящую цепочку. Файл сертификатов платформы можно использовать, вызвав SSLContext.load_default_certs(); это делается автоматически с помощью create_default_context().

17.3.4.3. Объединенный ключ и сертификат¶Combined key and certificate

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

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

17.3.4.4. Самоподписанные сертификаты¶Self-signed certificates

Если планируется создать сервер, предоставляющий услуги 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.5.1. Проверка поддержки SSL¶Testing for SSL support

Чтобы проверить наличие поддержки SSL в установке Python, в пользовательском коде следует использовать следующую идиому:

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

17.3.5.2. Работа на стороне клиента¶Client-side operation

Этот пример создаёт контекст SSL с рекомендуемыми настройками безопасности для клиентских сокетов, включая автоматическую проверку сертификатов:

>>> context = ssl.create_default_context()

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

>>> context = ssl.SSLContext(ssl.PROTOCOL_TLS)
>>> context.verify_mode = ssl.CERT_REQUIRED
>>> context.check_hostname = True
>>> context.load_verify_locations("/etc/ssl/certs/ca-bundle.crt")

(этот фрагмент предполагает, что ваша операционная система размещает набор всех сертификатов CA в /etc/ssl/certs/ca-bundle.crt; если нет, вы получите ошибку и придётся изменить расположение)

При использовании контекста для подключения к серверу CERT_REQUIRED проверяет сертификат сервера: он удостоверяется, что сертификат сервера был подписан одним из сертификатов CA, и проверяет подпись на корректность:

>>> conn = context.wrap_socket(socket.socket(socket.AF_INET),
...                            server_hostname="www.python.org")
>>> conn.connect(("www.python.org", 443))

Затем можно получить сертификат:

>>> cert = conn.getpeercert()

Визуальная проверка показывает, что сертификат действительно идентифицирует нужный сервис (то есть HTTPS-хост www.python.org):

>>> pprint.pprint(cert)
{'OCSP': ('http://ocsp.digicert.com',),
 'caIssuers': ('http://cacerts.digicert.com/DigiCertSHA2ExtendedValidationServerCA.crt',),
 'crlDistributionPoints': ('http://crl3.digicert.com/sha2-ev-server-g1.crl',
                           'http://crl4.digicert.com/sha2-ev-server-g1.crl'),
 'issuer': ((('countryName', 'US'),),
            (('organizationName', 'DigiCert Inc'),),
            (('organizationalUnitName', 'www.digicert.com'),),
            (('commonName', 'DigiCert SHA2 Extended Validation Server CA'),)),
 'notAfter': 'Sep  9 12:00:00 2016 GMT',
 'notBefore': 'Sep  5 00:00:00 2014 GMT',
 'serialNumber': '01BB6F00122B177F36CAB49CEA8B6B26',
 'subject': ((('businessCategory', 'Private Organization'),),
             (('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', '3359300'),),
             (('streetAddress', '16 Allen Rd'),),
             (('postalCode', '03894-4801'),),
             (('countryName', 'US'),),
             (('stateOrProvinceName', 'NH'),),
             (('localityName', 'Wolfeboro,'),),
             (('organizationName', 'Python Software Foundation'),),
             (('commonName', 'www.python.org'),)),
 'subjectAltName': (('DNS', 'www.python.org'),
                    ('DNS', 'python.org'),
                    ('DNS', 'pypi.org'),
                    ('DNS', 'docs.python.org'),
                    ('DNS', 'testpypi.python.org'),
                    ('DNS', 'bugs.python.org'),
                    ('DNS', 'wiki.python.org'),
                    ('DNS', 'hg.python.org'),
                    ('DNS', 'mail.python.org'),
                    ('DNS', 'packaging.python.org'),
                    ('DNS', 'pythonhosted.org'),
                    ('DNS', 'www.pythonhosted.org'),
                    ('DNS', 'test.pythonhosted.org'),
                    ('DNS', 'us.pycon.org'),
                    ('DNS', 'id.python.org')),
 'version': 3}

Теперь, когда SSL-канал установлен и сертификат проверен, можно продолжить обмен данными с сервером:

>>> 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 200 OK',
 b'Date: Sat, 18 Oct 2014 18:27:20 GMT',
 b'Server: nginx',
 b'Content-Type: text/html; charset=utf-8',
 b'X-Frame-Options: SAMEORIGIN',
 b'Content-Length: 45679',
 b'Accept-Ranges: bytes',
 b'Via: 1.1 varnish',
 b'Age: 2188',
 b'X-Served-By: cache-lcy1134-LCY',
 b'X-Cache: HIT',
 b'X-Cache-Hits: 11',
 b'Vary: Cookie',
 b'Strict-Transport-Security: max-age=63072000; includeSubDomains',
 b'Connection: close',
 b'',
 b'']

См. обсуждение соображений безопасности ниже.

17.3.5.3. Работа на стороне сервера¶Server-side operation

Для работы на стороне сервера обычно нужно иметь сертификат сервера и закрытый ключ, каждый в отдельном файле. Сначала создаётся контекст, содержащий ключ и сертификат, чтобы клиенты могли проверить подлинность. Затем открывается сокет, привязывается к порту, вызывается listen(), и начинается ожидание подключения клиентов:

import socket, ssl

context = ssl.create_default_context(ssl.Purpose.CLIENT_AUTH)
context.load_cert_chain(certfile="mycertfile", keyfile="mykeyfile")

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

Когда клиент подключается, вызывается accept() на сокете, чтобы получить новый сокет с другого конца, и используется метод контекста SSLContext.wrap_socket() для создания серверного SSL-сокета для этого соединения:

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

Затем читаются данные из connstream и что-то с ними делается, пока не будет завершена работа с клиентом (или клиент не завершит работу с вами):

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

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

17.3.7.1. Оптимальные настройки по умолчанию¶Best defaults

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

Если для соединения требуется клиентский сертификат, его можно добавить с помощью SSLContext.load_cert_chain().

Напротив, при создании SSL-контекста через вызов конструктора SSLContext самостоятельно, в нём по умолчанию не будут включены ни проверка сертификатов, ни проверка имени хоста. В этом случае следует прочитать приведённые ниже абзацы, чтобы достичь хорошего уровня безопасности.

17.3.7.2. Ручные настройки¶Manual settings

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

17.3.7.3. Многопроцессорность¶Multi-processing

При использовании этого модуля в составе многопроцессного приложения (с помощью, например, модулей multiprocessing или concurrent.futures) следует учитывать, что внутренний генератор случайных чисел OpenSSL некорректно обрабатывает порождённые процессы. Приложения должны изменять состояние PRNG родительского процесса, если они используют любую функцию SSL с os.fork(). Любого успешного вызова RAND_add(), RAND_bytes() или RAND_pseudo_bytes() достаточно.