ssl — Обёртка TLS/SSL для объектов сокетов

Исходный код: Lib/ssl.py

Этот модуль предоставляет доступ к средствам шифрования Transport Layer Security (часто называемому «Secure Sockets Layer») и аутентификации узлов для сетевых сокетов, как со стороны клиента, так и со стороны сервера. Этот модуль использует библиотеку OpenSSL. Он доступен на всех современных Unix-системах, Windows, Mac OS X и, вероятно, на дополнительных платформах, при условии установки OpenSSL на этой платформе.

В этом разделе документированы объекты и функции в модуле ssl; для получения более общей информации о TLS, SSL и сертификатах, читатель может обратиться к документам в разделе «См. также» внизу.

Этот модуль предоставляет класс ssl.SSLSocket, который наследуется от типа socket.socket и предоставляет обёртку сокета, которая также шифрует и расшифровывает данные, передаваемые по сокету с помощью SSL. Он поддерживает дополнительные методы, такие как getpeercert(), который получает сертификат другой стороны подключения, и cipher(), который получает шифр, используемый для безопасного подключения.

Для более сложных приложений класс ssl.SSLContext помогает управлять настройками и сертификатами, которые затем могут быть унаследованы сокетами SSL, созданными с помощью метода SSLContext.wrap_socket().

Функции, константы и исключения

Создание сокетов

С Python 3.2 и 2.7.9 рекомендуется использовать метод SSLContext.wrap_socket() экземпляра SSLContext для обёртки сокетов в объекты SSLSocket. Вспомогательная функция create_default_context() возвращает новый контекст с безопасными настройками по умолчанию. Старая функция wrap_socket() устарела, так как она неэффективна и не поддерживает указание имени сервера (SNI) и сопоставление имён хостов.

Пример сокета клиента с контекстом по умолчанию и двойным стеком IPv4/IPv6:

import socket
import ssl

hostname = 'www.python.org'
context = ssl.create_default_context()

with socket.create_connection((hostname, 443)) as sock:
    with context.wrap_socket(sock, server_hostname=hostname) as ssock:
        print(ssock.version())

Пример сокета клиента с пользовательским контекстом и IPv4:

hostname = 'www.python.org'
# PROTOCOL_TLS_CLIENT requires valid cert chain and hostname
context = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
context.load_verify_locations('path/to/cabundle.pem')

with socket.socket(socket.AF_INET, socket.SOCK_STREAM, 0) as sock:
    with context.wrap_socket(sock, server_hostname=hostname) as ssock:
        print(ssock.version())

Пример сокета сервера, прослушивающего на localhost IPv4:

context = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER)
context.load_cert_chain('/path/to/certchain.pem', '/path/to/private.key')

with socket.socket(socket.AF_INET, socket.SOCK_STREAM, 0) as sock:
    sock.bind(('127.0.0.1', 8443))
    sock.listen(5)
    with context.wrap_socket(sock, server_side=True) as ssock:
        conn, addr = ssock.accept()
        ...

Создание контекста

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

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

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

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

Настройки: PROTOCOL_TLS, 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, созданному этой функцией, возникает ошибка «Несоответствие протокола или набора шифров», это может означать, что они поддерживают только SSL3.0, который исключён этой функцией с помощью OP_NO_SSLv3. SSL3.0 широко считается полностью небезопасным. Если вы всё ещё хотите продолжить использование этой функции, но всё же разрешить подключения SSL 3.0, вы можете их снова включить с помощью:

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

Добавлена в версии 3.4.

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

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

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

Исключения

exception ssl.SSLError

Вызывается для сигнализации об ошибке в базовой реализации SSL (в настоящее время предоставляется библиотекой OpenSSL). Это указывает на проблему в более высоком уровне шифрования и аутентификации, который накладывается на базовое сетевое соединение. Эта ошибка является подтипом OSError. Код ошибки и сообщение экземпляров SSLError предоставляются библиотекой OpenSSL.

Изменено в версии 3.3: SSLError ранее был подтипом socket.error.

library

Мемоническая строка, обозначающая подмодуль OpenSSL, в котором произошла ошибка, например SSL, PEM или X509. Диапазон возможных значений зависит от версии OpenSSL.

Добавлена в версии 3.3.

reason

Мемоническая строка, обозначающая причину возникновения этой ошибки, например CERTIFICATE_VERIFY_FAILED. Диапазон возможных значений зависит от версии OpenSSL.

Добавлена в версии 3.3.

exception ssl.SSLZeroReturnError

Подкласс SSLError, вызываемый при попытке чтения или записи, когда SSL-соединение было закрыто корректно. Обратите внимание, что это не означает, что базовый транспорт (например, TCP) был закрыт.

Добавлена в версии 3.3.

exception ssl.SSLWantReadError

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

Добавлена в версии 3.3.

exception ssl.SSLWantWriteError

Подкласс SSLError, вызываемый неблокирующим SSL-сокетом при попытке чтения или записи данных, но требуется отправка дополнительных данных на базовый транспорт TCP, прежде чем запрос может быть удовлетворён.

Добавлена в версии 3.3.

exception ssl.SSLSyscallError

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

Добавлена в версии 3.3.

exception ssl.SSLEOFError

Подкласс SSLError, генерируется при внезапном прерывании SSL-соединения. Обычно не следует пытаться повторно использовать базовый транспорт при возникновении этой ошибки.

Добавлена в версии 3.3.

exception ssl.SSLCertVerificationError

Подкласс SSLError, генерируется при ошибке проверки сертификата.

Добавлена в версии 3.7.

verify_code

Числовое значение кода ошибки проверки.

verify_message

Строка, содержащая описание ошибки проверки (для чтения человеком).

exception ssl.CertificateError

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

Изменено в версии 3.7: Исключение теперь является псевдонимом для SSLCertVerificationError.

Генерация случайных чисел

ssl.RAND_bytes(num)

Возвращает num криптографически безопасных псевдослучайных байт. Вызывает SSLError, если генератор псевдослучайных чисел (PRNG) не был достаточно проинициализирован или если операция не поддерживается текущим методом RAND. RAND_status() можно использовать для проверки состояния PRNG, а RAND_add() — для его инициализации.

Для почти всех приложений предпочтительнее использовать os.urandom().

Прочитайте статью в Википедии, Cryptographically secure pseudorandom number generator (CSPRNG), чтобы узнать требования к криптографически стойкому генератору.

Добавлена в версии 3.3.

ssl.RAND_pseudo_bytes(num)

Возвращает (bytes, is_cryptographic): bytes — num псевдослучайных байт, is_cryptographic — True , если сгенерированные байты криптографически безопасны. Вызывает SSLError если операция не поддерживается текущим методом RAND.

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

Для почти всех приложений предпочтительнее использовать os.urandom().

Устарело начиная с версии 3.6: 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 (float) — нижняя граница энтропии, содержащейся в строке (поэтому вы всегда можете использовать 0.0). См. RFC 1750 для получения дополнительной информации о источниках энтропии.

Изменено в версии 3.5: Теперь принимается любое объект, подобный объекту bytes, для записи.

Обработка сертификатов

ssl.match_hostname(cert, hostname)

Проверяет, что cert (в декодированном формате, возвращаемом SSLSocket.getpeercert()) соответствует заданному hostname. Применяются правила проверки подлинности HTTPS-серверов, описанные в RFC 2818, RFC 5280 и RFC 6125. Помимо 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'

Добавлена в версии 3.2.

Изменено в версии 3.3.3: Функция теперь соответствует RFC 6125, раздел 6.4.3 и не сопоставляет несколько символов подстановки (например, *.*.com или *a*.example.org) и символ подстановки внутри фрагмента доменных имен с национальными кодами (IDN). IDN-метки A, такие как www*.xn--pthon-kva.org все еще поддерживаются, но x*.python.org больше не соответствует xn--tda.python.org.

Изменено в версии 3.5: Теперь поддерживается сопоставление IP-адресов, если они присутствуют в поле subjectAltName сертификата.

Изменено в версии 3.7: Функция больше не используется для TLS-соединений. Сопоставление имен хостов теперь выполняется OpenSSL.

Разрешается использование символа подстановки, когда он является левым и единственным символом в этом сегменте. Частичные символы подстановки, такие как www*.example.com больше не поддерживаются.

Устарело начиная с версии 3.7.

ssl.cert_time_to_seconds(cert_time)

Возвращает время в секундах с эпохи, заданное строкой, представляющей дату «notBefore» или «notAfter» из сертификата в формате cert_time (C locale).

Вот пример:

>>> 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» или «notAfter» должны использовать GMT (RFC 5280).

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

ssl.get_server_certificate(addr, ssl_version=PROTOCOL_TLS, ca_certs=None)

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

Изменено в версии 3.3: Функция теперь совместима с IPv6.

Изменено в версии 3.5: Значение по умолчанию ssl_version изменено с PROTOCOL_SSLv3 на PROTOCOL_TLS для максимальной совместимости с современными серверами.

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.

Добавлена в версии 3.4.

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 определяет назначение сертификата как набор OIDS или точно 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.

Добавлена в версии 3.4.

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.

Добавлена в версии 3.4.

ssl.wrap_socket(sock, keyfile=None, certfile=None, server_side=False, cert_reqs=CERT_NONE, ssl_version=PROTOCOL_TLS, 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; другие типы сокетов не поддерживаются.

Внутри функция создаёт SSLContext с протоколом ssl_version и SSLContext.options, установленным в cert_reqs. Если параметры keyfile, certfile, ca_certs или ciphers установлены, значения передаются в SSLContext.load_cert_chain(), SSLContext.load_verify_locations() и SSLContext.set_ciphers().

Аргументы server_side, do_handshake_on_connect и suppress_ragged_eofs имеют то же значение, что и SSLContext.wrap_socket().

Устарело начиная с версии 3.7: С Python 3.2 и 2.7.9 рекомендуется использовать SSLContext.wrap_socket() вместо wrap_socket(). Функция верхнего уровня ограничена и создаёт небезопасный сокет клиента без указания имени сервера или сопоставления имени хоста.

Константы

Все константы теперь являются коллекциями enum.IntEnum или enum.IntFlag.

ssl.CERT_NONE

Возможные значения для SSLContext.verify_mode или параметра cert_reqs к wrap_socket(). За исключением PROTOCOL_TLS_CLIENT, это режим по умолчанию. При использовании сокетов клиента почти любой сертификат принимается. Ошибки проверки, такие как недоверенный или просроченный сертификат, игнорируются и не прерывают рукопожатие TLS/SSL.

В режиме сервера от клиента не запрашивается сертификат, поэтому клиент не отправляет его для аутентификации клиента по сертификату.

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

ssl.CERT_OPTIONAL

Возможные значения для SSLContext.verify_mode или параметра cert_reqs к wrap_socket(). В режиме клиента CERT_OPTIONAL имеет то же значение, что и CERT_REQUIRED. Рекомендуется использовать CERT_REQUIRED для сокетов клиента вместо этого.

В режиме сервера клиенту отправляется запрос на предоставление сертификата. Клиент может либо проигнорировать запрос, либо отправить сертификат, чтобы выполнить аутентификацию клиента по сертификату. Если клиент выбирает отправку сертификата, он проверяется. Любая ошибка проверки сразу же прерывает рукопожатие TLS.

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

ssl.CERT_REQUIRED

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

Для серверного сокета этот режим обеспечивает обязательную аутентификацию клиента по сертификату TLS. Клиенту отправляется запрос на предоставление сертификата, и клиент должен предоставить действительный и надёжный сертификат.

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

class ssl.VerifyMode

Коллекция enum.IntEnum констант CERT_*.

Добавлена в версии 3.6.

ssl.VERIFY_DEFAULT

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

Добавлена в версии 3.4.

ssl.VERIFY_CRL_CHECK_LEAF

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

Введено в версии 3.4.

ssl.VERIFY_CRL_CHECK_CHAIN

Возможное значение для SSLContext.verify_flags. В этом режиме проверяются списки отзывов сертификатов (CRLs) всех сертификатов в цепочке сертификатов клиента.

Введено в версии 3.4.

ssl.VERIFY_X509_STRICT

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

Введено в версии 3.4.

ssl.VERIFY_X509_TRUSTED_FIRST

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

Введено в версии 3.4.4.

class ssl.VerifyFlags

enum.IntFlag коллекция констант VERIFY_*.

Введено в версии 3.6.

ssl.PROTOCOL_TLS

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

Введено в версии 3.6.

ssl.PROTOCOL_TLS_CLIENT

Автоматически переговаривается о самой высокой версии протокола, как и PROTOCOL_TLS, но поддерживает только соединения клиента SSLSocket. Протокол по умолчанию включает CERT_REQUIRED и check_hostname.

Введено в версии 3.6.

ssl.PROTOCOL_TLS_SERVER

Автоматически переговаривается о самой высокой версии протокола, как и PROTOCOL_TLS, но поддерживает только соединения сервера SSLSocket.

Введено в версии 3.6.

ssl.PROTOCOL_SSLv23

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

Устарело начиная с версии 3.6: Используйте PROTOCOL_TLS вместо него.

ssl.PROTOCOL_SSLv2

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

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

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

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

Устарело начиная с версии 3.6: Поддержка SSLv2 была удалена из OpenSSL.

ssl.PROTOCOL_SSLv3

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

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

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

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

Устарело начиная с версии 3.6: OpenSSL устарел все протоколы со специфичными версиями. Используйте протокол по умолчанию PROTOCOL_TLS с флагами, такими как OP_NO_SSLv3 вместо него.

ssl.PROTOCOL_TLSv1

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

Устарело начиная с версии 3.6: OpenSSL устарел все протоколы со специфичными версиями. Используйте протокол по умолчанию PROTOCOL_TLS с флагами, такими как OP_NO_SSLv3 вместо него.

ssl.PROTOCOL_TLSv1_1

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

Введено в версии 3.4.

Устарело начиная с версии 3.6: OpenSSL устарел все протоколы со специфичными версиями. Используйте протокол по умолчанию PROTOCOL_TLS с флагами, такими как OP_NO_SSLv3 вместо него.

ssl.PROTOCOL_TLSv1_2

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

Введено в версии 3.4.

Устарело начиная с версии 3.6: OpenSSL устарел все протоколы со специфичными версиями. Используйте протокол по умолчанию PROTOCOL_TLS с флагами, такими как OP_NO_SSLv3 вместо него.

ssl.OP_ALL

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

Введено в версии 3.2.

ssl.OP_NO_SSLv2

Запрещает подключение SSLv2. Этот параметр применим только в сочетании с PROTOCOL_TLS. Он предотвращает выбор SSLv2 в качестве версии протокола.

Введено в версии 3.2.

Устарело начиная с версии 3.6: SSLv2 устарел

ssl.OP_NO_SSLv3

Запрещает подключение SSLv3. Этот параметр применим только в сочетании с PROTOCOL_TLS. Он предотвращает выбор SSLv3 в качестве версии протокола.

Введено в версии 3.2.

Устарело начиная с версии 3.6: SSLv3 устарел

ssl.OP_NO_TLSv1

Запрещает подключение TLSv1. Этот параметр применим только в сочетании с PROTOCOL_TLS. Он предотвращает выбор TLSv1 в качестве версии протокола.

Введено в версии 3.2.

Устарело начиная с версии 3.7: Параметр устарел начиная с OpenSSL 1.1.0, используйте новые SSLContext.minimum_version и SSLContext.maximum_version вместо него.

ssl.OP_NO_TLSv1_1

Запрещает подключение TLSv1.1. Этот параметр применим только в сочетании с PROTOCOL_TLS. Он предотвращает выбор TLSv1.1 в качестве версии протокола. Доступен только с openssl версией 1.0.1+.

Введено в версии 3.4.

Устарело начиная с версии 3.7: Параметр устарел начиная с OpenSSL 1.1.0.

ssl.OP_NO_TLSv1_2

Запрещает подключение TLSv1.2. Этот параметр применим только в сочетании с PROTOCOL_TLS. Он предотвращает выбор TLSv1.2 в качестве версии протокола. Доступен только с openssl версией 1.0.1+.

Введено в версии 3.4.

Устарело начиная с версии 3.7: Параметр устарел начиная с OpenSSL 1.1.0.

ssl.OP_NO_TLSv1_3

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

Введено в версии 3.7.

Устарело начиная с версии 3.7: Параметр устарел с OpenSSL 1.1.0. Он был добавлен в 2.7.15, 3.6.3 и 3.7.0 для обратной совместимости с OpenSSL 1.0.2.

ssl.OP_NO_RENEGOTIATION

Отключает все повторные переговоры в TLSv1.2 и более ранних версиях. Не отправлять сообщения HelloRequest и игнорировать запросы на повторные переговоры через ClientHello.

Этот параметр доступен только с OpenSSL 1.1.0h и более поздними версиями.

Введено в версии 3.7.

ssl.OP_CIPHER_SERVER_PREFERENCE

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

Введено в версии 3.3.

ssl.OP_SINGLE_DH_USE

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

Введено в версии 3.3.

ssl.OP_SINGLE_ECDH_USE

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

Введено в версии 3.3.

ssl.OP_ENABLE_MIDDLEBOX_COMPAT

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

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

Введено в версии 3.8.

ssl.OP_NO_COMPRESSION

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

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

Введено в версии 3.3.

class ssl.Options

enum.IntFlag коллекция констант OP_*.

ssl.OP_NO_TICKET

Запрещает клиенту запрашивать билет сеанса.

Введено в версии 3.6.

ssl.HAS_ALPN

Поддерживает ли библиотека OpenSSL встроенную поддержку расширения TLS Application-Layer Protocol Negotiation, как описано в RFC 7301.

Введено в версии 3.5.

ssl.HAS_NEVER_CHECK_COMMON_NAME

Поддерживает ли библиотека OpenSSL встроенную поддержку не проверки имени общего субъекта и SSLContext.hostname_checks_common_name является ли записью.

Введено в версии 3.7.

ssl.HAS_ECDH

Поддерживает ли библиотека OpenSSL встроенную поддержку обмена ключами Diffie-Hellman на основе эллиптических кривых. Это должно быть истинно, если функция не была явно отключена дистрибутором.

Введено в версии 3.3.

ssl.HAS_SNI

Поддерживает ли библиотека OpenSSL встроенную поддержку расширения Server Name Indication (как определено в RFC 6066).

Введено в версии 3.2.

ssl.HAS_NPN

Поддерживает ли библиотека OpenSSL встроенную поддержку Next Protocol Negotiation, как описано в Application Layer Protocol Negotiation. В случае истины, вы можете использовать метод SSLContext.set_npn_protocols(), чтобы указать, какие протоколы вы хотите поддерживать.

Введено в версии 3.3.

ssl.HAS_SSLv2

Поддерживает ли библиотека OpenSSL встроенную поддержку протокола SSL 2.0.

Введено в версии 3.7.

ssl.HAS_SSLv3

Поддерживает ли библиотека OpenSSL встроенную поддержку протокола SSL 3.0.

Введено в версии 3.7.

ssl.HAS_TLSv1

Поддерживает ли библиотека OpenSSL встроенную поддержку протокола TLS 1.0.

Введено в версии 3.7.

ssl.HAS_TLSv1_1

Поддерживает ли библиотека OpenSSL встроенную поддержку протокола TLS 1.1.

Введено в версии 3.7.

ssl.HAS_TLSv1_2

Поддерживает ли библиотека OpenSSL встроенную поддержку протокола TLS 1.2.

Введено в версии 3.7.

ssl.HAS_TLSv1_3

Поддерживает ли библиотека OpenSSL встроенную поддержку протокола TLS 1.3.

Введено в версии 3.7.

ssl.CHANNEL_BINDING_TYPES

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

Введено в версии 3.3.

ssl.OPENSSL_VERSION

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

>>> ssl.OPENSSL_VERSION
'OpenSSL 1.0.2k  26 Jan 2017'

Введено в версии 3.2.

ssl.OPENSSL_VERSION_INFO

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

>>> ssl.OPENSSL_VERSION_INFO
(1, 0, 2, 11, 15)

Введено в версии 3.2.

ssl.OPENSSL_VERSION_NUMBER

Необработанное число версии библиотеки OpenSSL, как одно целое число:

>>> ssl.OPENSSL_VERSION_NUMBER
268443839
>>> hex(ssl.OPENSSL_VERSION_NUMBER)
'0x100020bf'

Введено в версии 3.2.

ssl.ALERT_DESCRIPTION_HANDSHAKE_FAILURE

ssl.ALERT_DESCRIPTION_INTERNAL_ERROR

ALERT_DESCRIPTION_*

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

Используется как значение возврата функции обратного вызова в SSLContext.set_servername_callback().

Введено в версии 3.4.

class ssl.AlertDescription

enum.IntEnum коллекция констант ALERT_DESCRIPTION_*.

Введено в версии 3.6.

Purpose.SERVER_AUTH

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

Введено в версии 3.4.

Purpose.CLIENT_AUTH

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

Введено в версии 3.4.

class ssl.SSLErrorNumber

enum.IntEnum коллекция констант SSL_ERROR_*.

Введено в версии 3.6.

class ssl.TLSVersion

enum.IntEnum коллекция версий SSL и TLS для SSLContext.maximum_version и SSLContext.minimum_version.

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

TLSVersion.MINIMUM_SUPPORTED

TLSVersion.MAXIMUM_SUPPORTED

Минимальная или максимальная поддерживаемая версия SSL или TLS. Это магические константы. Их значения не отражают самые низкие и самые высокие доступные версии TLS/SSL.

TLSVersion.SSLv3

TLSVersion.TLSv1

TLSVersion.TLSv1_1

TLSVersion.TLSv1_2

TLSVersion.TLSv1_3

От SSL 3.0 до TLS 1.3.

SSL сокеты

class ssl.SSLSocket(socket.socket)

SSL сокеты предоставляют следующие методы Объектов сокетов:

• accept()
• bind()
• close()
• connect()
• detach()
• fileno()
• getpeername(), getsockname()
• getsockopt(), setsockopt()
• gettimeout(), settimeout(), setblocking()
• listen()
• makefile()
• recv(), recv_into() (но передача ненулевого flags аргумента запрещена)
• send(), sendall() (с тем же ограничением)
• sendfile() (но os.sendfile будет использоваться только для текстовых сокетов, иначе будет использоваться send())
• shutdown()

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

Экземпляры SSLSocket должны создаваться с помощью метода SSLContext.wrap_socket().

Изменено в версии 3.5: Метод sendfile() был добавлен.

Изменено в версии 3.5: Метод shutdown() больше не сбрасывает таймаут сокета каждый раз, когда данные принимаются или отправляются. Теперь таймаут сокета равен максимальной общей продолжительности завершения.

Устарело начиная с версии 3.6: Не рекомендуется создавать экземпляр SSLSocket напрямую. Используйте SSLContext.wrap_socket() для обертывания сокета.

Изменено в версии 3.7: Экземпляры SSLSocket должны создаваться с помощью wrap_socket(). В предыдущих версиях было возможно создавать экземпляры напрямую. Это никогда не документировалось или не поддерживалось официально.

SSL сокеты также имеют следующие дополнительные методы и атрибуты:

SSLSocket.read(len=1024, buffer=None)

Прочитать до len байтов данных из SSL сокета и вернуть результат как bytes экземпляр. Если buffer указан, тогда прочитать в буфер вместо этого и вернуть количество прочитанных байтов.

Вызвать SSLWantReadError или SSLWantWriteError, если сокет неблокирующий и чтение заблокировало бы.

Так как в любое время возможна повторная авторизация, вызов read() также может вызвать операции записи.

Изменено в версии 3.5: Таймаут сокета больше не сбрасывается каждый раз, когда данные принимаются или отправляются. Таймаут сокета теперь равен максимальной общей продолжительности чтения до len байтов.

Устарело начиная с версии 3.6: Используйте recv() вместо read().

SSLSocket.write(buf)

Записать buf в SSL сокет и вернуть количество записанных байтов. Аргумент buf должен быть объектом, поддерживающим интерфейс буфера.

Вызвать SSLWantReadError или SSLWantWriteError, если сокет неблокирующий и запись заблокировала бы.

Так как в любое время возможна повторная авторизация, вызов write() также может вызвать операции чтения.

Изменено в версии 3.5: Таймаут сокета больше не сбрасывается каждый раз, когда данные принимаются или отправляются. Таймаут сокета теперь равен максимальной общей продолжительности записи buf.

Устарело начиная с версии 3.6: Используйте send() вместо write().

SSLSocket.do_handshake()

Выполнить рукопожатие SSL.

Изменено в версии 3.4: Метод рукопожатия также выполняет match_hostname(), когда атрибут check_hostname сокета context имеет значение true.

Изменено в версии 3.5: Таймаут сокета больше не сбрасывается каждый раз при получении или отправке байтов. Теперь таймаут сокета соответствует максимальному общему времени рукопожатия.

Изменено в версии 3.7: Проверка имени хоста или IP-адреса выполняется OpenSSL во время рукопожатия. Функция match_hostname() больше не используется. В случае отказа OpenSSL от имени хоста или IP-адреса, рукопожатие прерывается, и в сторону партнёра отправляется сообщение TLS alert.

SSLSocket.getpeercert(binary_form=False)

Если для партнера по соединению нет сертификата, возвращается None. Если рукопожатие SSL ещё не завершено, генерируется исключение ValueError.

Если параметр binary_form равен False, и от партнера был получен сертификат, этот метод возвращает экземпляр dict. Если сертификат не был проверен, словарь пустой. Если сертификат был проверен, возвращается словарь с несколькими ключами, включая subject (принципал, для которого был выдан сертификат) и issuer (принципал, выпустивший сертификат). Если сертификат содержит экземпляр расширения Subject Alternative Name (см. RFC 3280), в словаре также будет ключ subjectAltName.

Поля subject и issuer представляют собой кортежи, содержащие последовательность относительных отличительных имен (RDN), указанных в структуре данных сертификата для соответствующих полей, и каждое RDN является последовательностью пар имя-значение. Вот пример из реальной жизни:

{'issuer': ((('countryName', 'IL'),),
            (('organizationName', 'StartCom Ltd.'),),
            (('organizationalUnitName',
              'Secure Digital Certificate Signing'),),
            (('commonName',
              'StartCom Class 2 Primary Intermediate Server CA'),)),
 'notAfter': 'Nov 22 08:15:19 2013 GMT',
 'notBefore': 'Nov 21 03:09:52 2011 GMT',
 'serialNumber': '95F0',
 'subject': ((('description', '571208-SLe257oHY9fVQ07Z'),),
             (('countryName', 'US'),),
             (('stateOrProvinceName', 'California'),),
             (('localityName', 'San Francisco'),),
             (('organizationName', 'Electronic Frontier Foundation, Inc.'),),
             (('commonName', '*.eff.org'),),
             (('emailAddress', 'hostmaster@eff.org'),)),
 'subjectAltName': (('DNS', '*.eff.org'), ('DNS', 'eff.org')),
 'version': 3}

Примечание

Для проверки сертификата для определённого сервиса можно использовать функцию match_hostname().

Если параметр binary_form равен True, и сертификат был предоставлен, этот метод возвращает DER-кодированную форму всего сертификата в виде последовательности байтов или None, если партнёр не предоставил сертификат. Предоставление сертификата партнёром зависит от роли сокета SSL:

• для сокета SSL клиента сервер всегда предоставляет сертификат, независимо от того, требовалась ли проверка;
• для сокета SSL сервера клиент предоставит сертификат только по запросу сервера; поэтому getpeercert() вернёт None, если используется CERT_NONE (а не CERT_OPTIONAL или CERT_REQUIRED).

Изменено в версии 3.2: Возвращаемый словарь включает дополнительные элементы, такие как issuer и notBefore.

Изменено в версии 3.4: Исключение ValueError генерируется, когда рукопожатие ещё не завершено. Возвращаемый словарь включает дополнительные элементы расширения X509v3, такие как crlDistributionPoints, caIssuers и OCSP URI.

Изменено в версии 3.7.6: Строки адресов IPv6 больше не содержат символа перевода строки в конце.

SSLSocket.cipher()

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

SSLSocket.shared_ciphers()

Возвращает список шифров, которые разделяет клиент во время рукопожатия. Каждый элемент возвращаемого списка — кортеж из трёх значений: имя шифра, версия протокола SSL, определяющая его использование, и количество секретных битов, используемых шифром. shared_ciphers() возвращает None , если соединение не установлено или сокет является клиентом.

Добавлена в версии 3.5.

SSLSocket.compression()

Возвращает используемый алгоритм сжатия в виде строки или None , если сжатие не используется.

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

Добавлена в версии 3.3.

SSLSocket.get_channel_binding(cb_type="tls-unique")

Получить данные канальной привязки для текущего соединения в виде объекта bytes. Возвращает None , если соединение не установлено или рукопожатие не завершено.

Параметр cb_type позволяет выбрать желаемый тип привязки канала. Допустимые типы канальной привязки перечислены в списке CHANNEL_BINDING_TYPES. В настоящее время поддерживается только канальная привязка 'tls-unique', определённая в RFC 5929. Если запрошен неподдерживаемый тип канальной привязки, генерируется исключение ValueError.

Добавлена в версии 3.3.

SSLSocket.selected_alpn_protocol()

Возвращает протокол, выбранный во время рукопожатия TLS. Если SSLContext.set_alpn_protocols() не вызывался, если другой участник не поддерживает ALPN, если этот сокет не поддерживает ни один из предложенных протоколов клиента или если рукопожатие ещё не произошло, возвращается None.

Добавлена в версии 3.5.

SSLSocket.selected_npn_protocol()

Возвращает протокол верхнего уровня, выбранный во время рукопожатия TLS/SSL. Если SSLContext.set_npn_protocols() не вызывался, или если другой участник не поддерживает NPN, или если рукопожатие ещё не произошло, будет возвращено значение None.

Добавлена в версии 3.3.

SSLSocket.unwrap()

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

SSLSocket.verify_client_post_handshake()

Запрашивает проверку подлинности после рукопожатия (PHA) от клиента TLS 1.3. PHA может быть инициирована только для соединения TLS 1.3 со стороны сервера, после начального рукопожатия TLS и с включённой PHA с обеих сторон, см. SSLContext.post_handshake_auth.

Метод не выполняет обмен сертификатами сразу. Со стороны сервера отправляется CertificateRequest во время следующего события записи, и ожидается, что клиент ответит сертификатом во время следующего события чтения.

Если не соблюдаются какие-либо предварительные условия (например, не TLS 1.3, PHA не включено), генерируется SSLError.

Примечание

Доступно только с OpenSSL 1.1.1 и включённой поддержкой TLS 1.3. Без поддержки TLS 1.3 метод генерирует NotImplementedError.

Добавлена в версии 3.7.1.

SSLSocket.version()

Возвращает фактическую версию протокола SSL, согласованную соединением, в виде строки или None , если защищённое соединение не установлено. На данный момент возможные значения возврата включают "SSLv2", "SSLv3", "TLSv1", "TLSv1.1" и "TLSv1.2". В новых версиях OpenSSL может быть больше значений возврата.

Добавлена в версии 3.5.

SSLSocket.pending()

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

SSLSocket.context

Объект SSLContext, к которому привязан этот сокет SSL. Если сокет SSL был создан с использованием устаревшей функции wrap_socket() (а не SSLContext.wrap_socket()), это пользовательский объект контекста, созданный для этого сокета SSL.

Введено в версии 3.2.

SSLSocket.server_side

Логическое значение, которое равно True для сокетов на стороне сервера и False для сокетов на стороне клиента.

Введено в версии 3.2.

SSLSocket.server_hostname

Имя хоста сервера: тип str, или None для сокета на стороне сервера или если имя хоста не было указано в конструкторе.

Введено в версии 3.2.

Изменено в версии 3.7: Атрибут теперь всегда представляет текст в формате ASCII. Когда server_hostname является международным доменным именем (IDN), этот атрибут теперь хранит форму A-метки ("xn--pythn-mua.org"), а не форму U-метки ("pythön.org").

SSLSocket.session

Объект SSLSession для этого SSL-соединения. Сессия доступна для сокетов на стороне клиента и сервера после выполнения рукопожатия TLS. Для сокетов на стороне клиента сессия может быть установлена до вызова do_handshake() для повторного использования сессии.

Введено в версии 3.6.

SSLSocket.session_reused

Введено в версии 3.6.

SSL-контексты

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

class ssl.SSLContext(protocol=PROTOCOL_TLS)

Создаёт новый SSL-контекст. Вы можете передать protocol, которое должно быть одним из PROTOCOL_* констант, определённых в этом модуле. Параметр указывает, какую версию протокола SSL использовать. Обычно сервер выбирает определённую версию протокола, а клиент должен адаптироваться к выбору сервера. Большинство версий несовместимы с другими версиями. Если не указано, по умолчанию используется PROTOCOL_TLS; она обеспечивает наибольшую совместимость с другими версиями.

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

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

Примечания

1(1,2)

SSLContext отключает SSLv2 с помощью OP_NO_SSLv2 по умолчанию.

2(1,2)

SSLContext отключает SSLv3 с помощью OP_NO_SSLv3 по умолчанию.

3(1,2)

Протокол TLS 1.3 будет доступен с PROTOCOL_TLS в OpenSSL >= 1.1.1. Специальной константы PROTOCOL для только TLS 1.3 нет.

См. также

create_default_context() позволяет модулю ssl выбирать параметры безопасности для данной цели.

Изменено в версии 3.6: Контекст создается с безопасными значениями по умолчанию. Параметры OP_NO_COMPRESSION, OP_CIPHER_SERVER_PREFERENCE, OP_SINGLE_DH_USE, OP_SINGLE_ECDH_USE, OP_NO_SSLv2 (кроме PROTOCOL_SSLv2), и OP_NO_SSLv3 (кроме PROTOCOL_SSLv3) устанавливаются по умолчанию. Изначальный список наборов шифров содержит только HIGH шифры, нет NULL шифров и нет MD5 шифров (кроме PROTOCOL_SSLv2).

Объекты SSLContext имеют следующие методы и атрибуты:

SSLContext.cert_store_stats()

Получить статистику загруженных сертификатов X.509, количество сертификатов X.509, помеченных как сертификаты CA, и списки отзывов о сертификатах как словарь.

Пример для контекста с одним сертификатом CA и одним другим сертификатом:

>>> context.cert_store_stats()
{'crl': 0, 'x509_ca': 1, 'x509': 2}

Введено в версии 3.4.

SSLContext.load_cert_chain(certfile, keyfile=None, password=None)

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

Аргумент password может быть функцией, которую нужно вызвать, чтобы получить пароль для расшифровки закрытого ключа. Он будет вызван только в том случае, если закрытый ключ зашифрован и необходим пароль. Он будет вызван без аргументов, и он должен вернуть строку, байты или массив байтов. Если возвращаемое значение является строкой, оно будет закодировано в UTF-8 перед использованием для расшифровки ключа. В качестве альтернативы, строковое значение, значение байтов или массив байтов могут быть переданы непосредственно в качестве аргумента password. Оно будет проигнорировано, если закрытый ключ не зашифрован и пароль не нужен.

Если аргумент password не указан и необходим пароль, будет использоваться встроенный механизм запроса паролей OpenSSL для интерактивного запроса пароля у пользователя.

Если закрытый ключ не соответствует сертификату, генерируется SSLError.

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

SSLContext.load_default_certs(purpose=Purpose.SERVER_AUTH)

Загрузка набора стандартных сертификатов «удостоверяющего центра» (ЦУ) из стандартных расположений. В Windows загружаются сертификаты ЦУ из системных хранилищ CA и ROOT. В других системах вызывается SSLContext.set_default_verify_paths(). В будущем метод может загружать сертификаты ЦУ и из других расположений.

Флаг purpose указывает, какие типы сертификатов ЦУ загрузить. По умолчанию, значение Purpose.SERVER_AUTH загружает сертификаты, помеченные и доверенные для аутентификации веб-сервера TLS (клиентские сокеты). Purpose.CLIENT_AUTH загружает сертификаты ЦУ для проверки сертификата клиента на стороне сервера.

Новая функция в версии 3.4.

SSLContext.load_verify_locations(cafile=None, capath=None, cadata=None)

Загрузка набора сертификатов «удостоверяющего центра» (ЦУ), используемых для проверки сертификатов других узлов, когда verify_mode отличается от CERT_NONE. Должен быть указан хотя бы один из параметров cafile или capath.

Этот метод также может загружать списки отзыва сертификатов (CRL) в форматах PEM или DER. Для использования CRL необходимо правильно настроить SSLContext.verify_flags.

Строка cafile, если присутствует, — путь к файлу, содержащему конкатенированные сертификаты ЦУ в формате PEM. Более подробную информацию о том, как организовать сертификаты в этом файле, см. в разделе Сертификаты.

Строка capath, если присутствует, — путь к каталогу, содержащему несколько сертификатов ЦУ в формате PEM, с использованием специфичной для OpenSSL структуры расположения.

Объект cadata, если присутствует, — это либо строка ASCII с одним или несколькими кодированными в PEM сертификатами, либо объект-подобный байтам с кодированными в DER сертификатами. Как и в случае с capath, дополнительные строки вокруг кодированных в PEM сертификатов игнорируются, но должен присутствовать хотя бы один сертификат.

Изменено в версии 3.4: Добавлен необязательный аргумент cadata

SSLContext.get_ca_certs(binary_form=False)

Получение списка загруженных сертификатов «удостоверяющего центра» (ЦУ). Если параметр binary_form равен False, каждый элемент списка — это словарь, подобный выводу из SSLSocket.getpeercert(). В противном случае метод возвращает список сертификатов, закодированных в DER. Возвращаемый список не содержит сертификатов из capath, если сертификат не был запрошен и загружен соединением SSL.

Примечание

Сертификаты в каталоге capath не загружаются, если они не были использованы хотя бы один раз.

Новая функция в версии 3.4.

SSLContext.get_ciphers()

Получение списка включенных шифров. Список отсортирован по приоритету шифров. См. SSLContext.set_ciphers().

Пример:

>>> ctx = ssl.SSLContext(ssl.PROTOCOL_SSLv23)
>>> ctx.set_ciphers('ECDHE+AESGCM:!ECDSA')
>>> ctx.get_ciphers()  # OpenSSL 1.0.x
[{'alg_bits': 256,
  'description': 'ECDHE-RSA-AES256-GCM-SHA384 TLSv1.2 Kx=ECDH     Au=RSA  '
                 'Enc=AESGCM(256) Mac=AEAD',
  'id': 50380848,
  'name': 'ECDHE-RSA-AES256-GCM-SHA384',
  'protocol': 'TLSv1/SSLv3',
  'strength_bits': 256},
 {'alg_bits': 128,
  'description': 'ECDHE-RSA-AES128-GCM-SHA256 TLSv1.2 Kx=ECDH     Au=RSA  '
                 'Enc=AESGCM(128) Mac=AEAD',
  'id': 50380847,
  'name': 'ECDHE-RSA-AES128-GCM-SHA256',
  'protocol': 'TLSv1/SSLv3',
  'strength_bits': 128}]

В OpenSSL 1.1 и более поздних версиях словарь шифров содержит дополнительные поля:

>>> ctx.get_ciphers()  # OpenSSL 1.1+
[{'aead': True,
  'alg_bits': 256,
  'auth': 'auth-rsa',
  'description': 'ECDHE-RSA-AES256-GCM-SHA384 TLSv1.2 Kx=ECDH     Au=RSA  '
                 'Enc=AESGCM(256) Mac=AEAD',
  'digest': None,
  'id': 50380848,
  'kea': 'kx-ecdhe',
  'name': 'ECDHE-RSA-AES256-GCM-SHA384',
  'protocol': 'TLSv1.2',
  'strength_bits': 256,
  'symmetric': 'aes-256-gcm'},
 {'aead': True,
  'alg_bits': 128,
  'auth': 'auth-rsa',
  'description': 'ECDHE-RSA-AES128-GCM-SHA256 TLSv1.2 Kx=ECDH     Au=RSA  '
                 'Enc=AESGCM(128) Mac=AEAD',
  'digest': None,
  'id': 50380847,
  'kea': 'kx-ecdhe',
  'name': 'ECDHE-RSA-AES128-GCM-SHA256',
  'protocol': 'TLSv1.2',
  'strength_bits': 128,
  'symmetric': 'aes-128-gcm'}]

Доступность: OpenSSL 1.0.2+.

Новая функция в версии 3.6.

SSLContext.set_default_verify_paths()

Загрузка набора стандартных сертификатов «удостоверяющего центра» (ЦУ) из пути к файловой системе, определённого при построении библиотеки OpenSSL. К сожалению, нет простого способа узнать, успешно ли выполнен этот метод: ошибка не возвращается, если сертификаты не найдены. Однако, если библиотека OpenSSL предоставлена как часть операционной системы, она, скорее всего, настроена должным образом.

SSLContext.set_ciphers(ciphers)

Установка доступных шифров для сокетов, созданных с помощью этого контекста. Это должна быть строка в формате списка шифров OpenSSL . Если ни один шифр не может быть выбран (потому что опции времени компиляции или другая конфигурация запрещают использование всех указанных шифров), будет возбуждено исключение SSLError.

Примечание

после подключения метод SSLSocket.cipher() сокетов SSL вернёт текущий выбранный шифр.

OpenSSL 1.1.1 по умолчанию включает наборы шифров TLS 1.3. Эти наборы не могут быть отключены с помощью set_ciphers().

SSLContext.set_alpn_protocols(protocols)

Указание протоколов, которые сокет должен анонсировать во время рукопожатия SSL/TLS. Это должен быть список строк ASCII, как ['http/1.1', 'spdy/2'], упорядоченный по приоритету. Выбор протокола произойдёт во время рукопожатия и будет осуществляться в соответствии с RFC 7301. После успешного рукопожатия метод SSLSocket.selected_alpn_protocol() вернёт согласованный протокол.

Этот метод возбудит NotImplementedError, если HAS_ALPN равно False.

OpenSSL 1.1.0 до 1.1.0e прервёт рукопожатие и возбудит SSLError, когда обе стороны поддерживают ALPN, но не могут договориться о протоколе. Версии 1.1.0f+ ведут себя как 1.0.2, SSLSocket.selected_alpn_protocol() возвращает None.

Новая функция в версии 3.5.

SSLContext.set_npn_protocols(protocols)

Указание протоколов, которые сокет должен анонсировать во время рукопожатия SSL/TLS. Это должен быть список строк, как ['http/1.1', 'spdy/2'], упорядоченный по приоритету. Выбор протокола произойдёт во время рукопожатия и будет осуществляться в соответствии с Application Layer Protocol Negotiation. После успешного рукопожатия метод SSLSocket.selected_npn_protocol() вернёт согласованный протокол.

Этот метод возбудит NotImplementedError, если HAS_NPN равно False.

Новая функция в версии 3.3.

SSLContext.sni_callback

Зарегистрируйте функцию обратного вызова, которая будет вызвана после получения сообщения рукопожатия TLS Client Hello сервером SSL/TLS, когда клиент TLS указывает указание имени сервера. Механизм указания имени сервера описан в RFC 6066 разделе 3 — Указание имени сервера.

Только один обратный вызов может быть установлен на SSLContext. Если sni_callback установлен в None , то обратный вызов отключён. Вызов этой функции повторно отключит ранее зарегистрированный обратный вызов.

Функция обратного вызова будет вызвана с тремя аргументами; первым будет ssl.SSLSocket, вторым — строка, представляющая имя сервера, с которым клиент намеревается взаимодействовать (или None, если сообщение TLS Client Hello не содержит имени сервера), а третьим — исходный SSLContext. Аргумент имени сервера — текст. Для доменных имён с национальными кодами имя сервера — метка IDN A ("xn--pythn-mua.org").

Типичное использование этого обратного вызова — изменение атрибута ssl.SSLSocket’s SSLSocket.context на новый объект типа SSLContext, представляющий цепочку сертификатов, соответствующую имени сервера.

Из-за ранней фазы согласования соединения TLS доступны только ограниченные методы и атрибуты, такие как SSLSocket.selected_alpn_protocol() и SSLSocket.context. Методы SSLSocket.getpeercert(), SSLSocket.getpeercert(), SSLSocket.cipher() и SSLSocket.compress() требуют, чтобы TLS-соединение продвинулось за пределы TLS Client Hello, и поэтому они не будут содержать осмысленных значений, а также небезопасно вызывать их.

Функция sni_callback должна возвращать None , чтобы продолжить TLS-переговоры. Если требуется ошибка TLS, может быть возвращено значение ALERT_DESCRIPTION_*. Другие возвращаемые значения приведут к ошибке TLS со значением ALERT_DESCRIPTION_INTERNAL_ERROR.

Если в функции sni_callback возникает исключение, TLS-соединение завершится сообщением об ошибке TLS ALERT_DESCRIPTION_HANDSHAKE_FAILURE.

Этот метод поднимет NotImplementedError, если библиотека OpenSSL была скомпилирована с определением OPENSSL_NO_TLSEXT.

Введено в версии 3.7.

SSLContext.set_servername_callback(server_name_callback)

Это API-интерфейс устаревшего типа, сохранённый для обратной совместимости. По возможности используйте sni_callback вместо него. Указанный server_name_callback аналогичен sni_callback, за исключением того, что если имя сервера является кодированным международным доменным именем IDN, server_name_callback получает декодированную метку U ("pythön.org").

Если при декодировании имени сервера возникает ошибка, соединение TLS завершится с сообщением об ошибке TLS ALERT_DESCRIPTION_INTERNAL_ERROR для клиента.

Введено в версии 3.4.

SSLContext.load_dh_params(dhfile)

Загрузите параметры генерации ключей для обмена ключами Диффи-Хеллмана (DH). Использование обмена ключами DH улучшает конфиденциальность вперёд, но за счёт вычислительных ресурсов (как на сервере, так и на клиенте). Параметр dhfile должен быть путём к файлу, содержащему параметры DH в формате PEM.

Эта настройка не применяется к сокетам клиента. Также можно использовать опцию OP_SINGLE_DH_USE для дальнейшего повышения безопасности.

Введено в версии 3.3.

SSLContext.set_ecdh_curve(curve_name)

Установите имя кривой для обмена ключами Диффи-Хеллмана на основе эллиптических кривых (ECDH). ECDH значительно быстрее, чем обычный DH, при том же уровне безопасности. Параметр curve_name должен быть строкой, описывающей известную эллиптическую кривую, например prime256v1 для широко поддерживаемой кривой.

Эта настройка не применяется к сокетам клиента. Также можно использовать опцию OP_SINGLE_ECDH_USE для дальнейшего повышения безопасности.

Этот метод недоступен, если HAS_ECDH равен False.

Введено в версии 3.3.

См. также

SSL/TLS и идеальная конфиденциальность вперёд

Vincent Bernat.

SSLContext.wrap_socket(sock, server_side=False, do_handshake_on_connect=True, suppress_ragged_eofs=True, server_hostname=None, session=None)

Оборачивает существующий сокет Python sock и возвращает экземпляр SSLContext.sslsocket_class (по умолчанию SSLSocket). Возвращаемый SSL-сокет привязан к контексту, его настройкам и сертификатам. sock должен быть сокетом SOCK_STREAM; другие типы сокетов не поддерживаются.

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

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

При клиентских подключениях необязательный параметр server_hostname определяет имя хоста службы, с которой мы подключаемся. Это позволяет одному серверу размещать несколько SSL-служб с различными сертификатами, очень похоже на виртуальные хосты HTTP. Указание server_hostname вызовет ValueError, если server_side равно true.

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

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

session, см. session.

Изменено в версии 3.5: Всегда разрешается передавать server_hostname, даже если в OpenSSL нет SNI.

Изменено в версии 3.6: Добавлен аргумент session.

Изменено в версии 3.7: Метод возвращает экземпляр SSLContext.sslsocket_class вместо жёстко заданного SSLSocket.

SSLContext.sslsocket_class

Тип возвращаемого значения SSLContext.wrap_socket(), по умолчанию SSLSocket. Атрибут может быть переопределён для экземпляра класса, чтобы вернуть пользовательский подкласс SSLSocket.

Введено в версии 3.7.

SSLContext.wrap_bio(incoming, outgoing, server_side=False, server_hostname=None, session=None)

Оборачивает объекты BIO incoming и outgoing и возвращает экземпляр SSLContext.sslobject_class (по умолчанию SSLObject). Процедуры SSL будут считывать входные данные из входного BIO и записывать данные в выходной BIO.

Параметры server_side, server_hostname и session имеют такое же значение, как и в SSLContext.wrap_socket().

Изменено в версии 3.6: Добавлен аргумент session.

Изменено в версии 3.7: Метод возвращает экземпляр SSLContext.sslobject_class вместо жёстко заданного SSLObject.

SSLContext.sslobject_class

Тип возвращаемого значения SSLContext.wrap_bio(), по умолчанию SSLObject. Атрибут можно переопределить для экземпляра класса, чтобы возвращать настраиваемый подкласс SSLObject.

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

SSLContext.session_stats()

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

>>> stats = context.session_stats()
>>> stats['hits'], stats['misses']
(0, 0)

SSLContext.check_hostname

Указывает, нужно ли сопоставлять имя хоста сертифицированного узла с match_hostname() в SSLSocket.do_handshake(). Режим проверки verify_mode должен быть установлен в CERT_OPTIONAL или CERT_REQUIRED, и вы должны передать server_hostname в wrap_socket(), чтобы сопоставить имя хоста. Включение проверки имени хоста автоматически устанавливает verify_mode от CERT_NONE до CERT_REQUIRED. Его нельзя установить обратно в CERT_NONE, пока включена проверка имени хоста. Протокол PROTOCOL_TLS_CLIENT по умолчанию включает проверку имени хоста. При использовании других протоколов проверку имени хоста необходимо включить явно.

Пример:

import socket, ssl

context = ssl.SSLContext(ssl.PROTOCOL_TLSv1_2)
context.verify_mode = ssl.CERT_REQUIRED
context.check_hostname = True
context.load_default_certs()

s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
ssl_sock = context.wrap_socket(s, server_hostname='www.verisign.com')
ssl_sock.connect(('www.verisign.com', 443))

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

Изменено в версии 3.7: verify_mode теперь автоматически меняется на CERT_REQUIRED, когда проверка имени хоста включена, и verify_mode равно CERT_NONE. Ранее такая операция завершалась ошибкой ValueError.

Примечание

Эта функция требует OpenSSL 0.9.8f или более поздней версии.

SSLContext.maximum_version

Элемент перечисления TLSVersion, представляющий самую высокую поддерживаемую версию TLS. Значение по умолчанию — TLSVersion.MAXIMUM_SUPPORTED. Атрибут является только для чтения для протоколов, отличных от PROTOCOL_TLS, PROTOCOL_TLS_CLIENT и PROTOCOL_TLS_SERVER.

Атрибуты maximum_version, minimum_version и SSLContext.options влияют на поддерживаемые версии SSL и TLS контекста. Реализация не предотвращает некорректных комбинаций. Например, контекст с OP_NO_TLSv1_2 в options и maximum_version, установленным на TLSVersion.TLSv1_2, не сможет установить соединение TLS 1.2.

Примечание

Этот атрибут недоступен, если модуль ssl скомпилирован с OpenSSL 1.1.0g или более поздней версией.

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

SSLContext.minimum_version

Аналогично SSLContext.maximum_version, но это самая низкая поддерживаемая версия или TLSVersion.MINIMUM_SUPPORTED.

Примечание

Этот атрибут недоступен, если модуль ssl скомпилирован с OpenSSL 1.1.0g или более поздней версией.

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

SSLContext.options

Целое число, представляющее набор включённых для этого контекста параметров SSL. Значение по умолчанию — OP_ALL, но вы можете указать другие параметры, такие как OP_NO_SSLv2, соединив их с помощью операции OR.

Примечание

В версиях OpenSSL, более ранних чем 0.9.8m, можно только устанавливать параметры, а не очищать их. Попытка очистить параметр (сбросом соответствующих битов) приведёт к ошибке ValueError.

Изменено в версии 3.6: SSLContext.options возвращает флаги Options:

>>> ssl.create_default_context().options  
<Options.OP_ALL|OP_NO_SSLv3|OP_NO_SSLv2|OP_NO_COMPRESSION: 2197947391>

SSLContext.post_handshake_auth

Включение аутентификации клиента TLS 1.3 после рукопожатия. Аутентификация после рукопожатия по умолчанию отключена, и сервер может запросить сертификат клиента TLS только во время начального рукопожатия. При включении сервер может запросить сертификат клиента TLS в любое время после рукопожатия.

При включении в клиенте сокеты сообщают серверу, что они поддерживают аутентификацию после рукопожатия.

При включении в серверных сокетах SSLContext.verify_mode также должен быть установлен в CERT_OPTIONAL или CERT_REQUIRED. Фактический обмен сертификатами клиента откладывается до вызова SSLSocket.verify_client_post_handshake() и выполнения некоторых операций ввода-вывода.

Примечание

Доступно только с OpenSSL 1.1.1 и включённой поддержкой TLS 1.3. Без поддержки TLS 1.3 значение свойства равно None и его нельзя изменить

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

SSLContext.protocol

Версия протокола, выбранная при построении контекста. Этот атрибут является только для чтения.

SSLContext.hostname_checks_common_name

Указывает, будет ли check_hostname проверять общее имя субъекта сертификата в отсутствие расширения альтернативных имён субъекта (значение по умолчанию: true).

Примечание

Можно изменять только с OpenSSL 1.1.0 или выше.

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

SSLContext.verify_flags

Флаги для операций проверки сертификатов. Можно установить флаги, такие как VERIFY_CRL_CHECK_LEAF, объединив их с помощью побитового ИЛИ. По умолчанию OpenSSL не требует и не проверяет списки отозванных сертификатов (CRL). Доступно только с версией openssl 0.9.8+.

Введено в версии 3.4.

Изменено в версии 3.6: SSLContext.verify_flags возвращает флаги VerifyFlags:

>>> ssl.create_default_context().verify_flags  
<VerifyFlags.VERIFY_X509_TRUSTED_FIRST: 32768>

SSLContext.verify_mode

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

Изменено в версии 3.6: SSLContext.verify_mode возвращает перечисление VerifyMode:

>>> ssl.create_default_context().verify_mode
<VerifyMode.CERT_REQUIRED: 2>

Сертификаты

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

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

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

Python использует файлы для хранения сертификатов. Они должны быть отформатированы как «PEM» (см. RFC 1422), что представляет собой кодировку в формате base-64, заключённую в заголовок и футер строки:

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

Цепочки сертификатов

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

-----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 будет использовать первую цепочку в файле, которая соответствует. Файл сертификатов платформы можно использовать, вызвав SSLContext.load_default_certs(), это делается автоматически с create_default_context().

Объединённый ключ и сертификат

Часто закрытый ключ хранится в том же файле, что и сертификат; в этом случае достаточно передать только 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-----

Самоподписанные сертификаты

Если вы собираетесь создать сервер, предоставляющий 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
%

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

Примеры

Проверка поддержки SSL

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

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

Операции со стороны клиента

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

>>> context = ssl.create_default_context()

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

>>> context = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
>>> context.load_verify_locations("/etc/ssl/certs/ca-bundle.crt")

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

Протокол PROTOCOL_TLS_CLIENT настраивает контекст для проверки сертификатов и проверки имени хоста. verify_mode устанавливается в CERT_REQUIRED, а check_hostname устанавливается в True. Все остальные протоколы создают контексты SSL с небезопасными значениями по умолчанию.

При использовании контекста для подключения к серверу, CERT_REQUIRED и check_hostname проверяют сертификат сервера: это гарантирует, что сертификат сервера был подписан одним из сертификатов УЦ, проверяет подпись на правильность и проверяет другие свойства, такие как срок действия и соответствие имени хоста:

>>> 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.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'']

См. обсуждение Учитываемые аспекты безопасности ниже.

Операции со стороны сервера

Для работы сервера обычно потребуется сертификат сервера и закрытый ключ, каждый в отдельном файле. Сначала создаётся контекст, содержащий ключ и сертификат, чтобы клиенты могли проверить вашу подлинность. Затем вы откроете сокет, привяжете его к порту, вызовите 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.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

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

Примечания по неблокирующим сокетам

SSL-сокеты ведут себя немного иначе, чем обычные сокеты в неблокирующем режиме. При работе с неблокирующими сокетами необходимо учитывать несколько моментов:

• Большинство методов SSLSocket будут поднимать либо SSLWantWriteError, либо SSLWantReadError вместо BlockingIOError, если операция ввода-вывода заблокируется. SSLWantReadError будет поднято, если необходима операция чтения из базового сокета, а SSLWantWriteError — для операции записи в базовый сокет. Обратите внимание, что попытки записи в сокет SSL могут потребовать чтения из базового сокета в первую очередь, а попытки чтения из сокета SSL могут потребовать предварительной записи в базовый сокет.

  Изменено в версии 3.5: В более ранних версиях Python метод SSLSocket.send() возвращал ноль вместо повышения SSLWantWriteError или SSLWantReadError.

• Вызов select() сообщает вам, что сокет на уровне ОС можно читать (или записывать), но это не означает, что в верхнем слое SSL достаточно данных. Например, может быть получена только часть кадра SSL. Поэтому вы должны быть готовы обрабатывать ошибки SSLSocket.recv() и SSLSocket.send() и повторно попробовать после нового вызова select().

• И наоборот, так как у слоя SSL есть собственная структура, сокет SSL может по-прежнему содержать доступные данные для чтения, не зная о них select(). Поэтому вы должны сначала вызвать SSLSocket.recv() для сброса потенциально доступных данных, а затем блокировать вызов select() только в случае необходимости.

  (конечно, аналогичные меры применяются при использовании других примитивов, таких как poll(), или тех, что в модуле selectors)

• Сам процесс рукопожатия SSL будет неблокирующим: метод SSLSocket.do_handshake() должен быть повторён до тех пор, пока он не вернётся успешно. Вот сводка с использованием select() для ожидания готовности сокета:

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

Поддержка BIO в памяти

С тех пор, как модуль SSL был представлен в Python 2.6, класс SSLSocket предоставляет две взаимосвязанные, но различные области функциональности:

• Обработка протокола SSL
• Сетевой ввод-вывод

API сетевого ввода-вывода идентичен API, предоставляемому socket.socket, из которого SSLSocket также наследуется. Это позволяет использовать сокет SSL как прямую замену обычного сокета, что значительно упрощает добавление поддержки SSL в существующее приложение.

Совместное использование обработки протокола SSL и сетевого ввода-вывода обычно работает хорошо, но в некоторых случаях это не так. Примером является фреймворк асинхронного ввода-вывода, который хочет использовать другую модель множественного ввода-вывода, отличную от модели «select/poll по дескриптору файла» (основанной на готовности), которая предполагается socket.socket и внутренними процедурами ввода-вывода сокетов OpenSSL. Это в основном актуально для платформ, таких как Windows, где эта модель неэффективна. Для этой цели предоставляется урезанный вариант SSLSocket под названием SSLObject.

class ssl.SSLObject

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

Этот класс реализует интерфейс поверх низкоуровневого объекта SSL, реализованного в OpenSSL. Этот объект фиксирует состояние подключения SSL, но не предоставляет никакого сетевого ввода-вывода. Ввод-вывод должен выполняться через отдельные объекты «BIO», которые представляют собой уровень абстракции ввода-вывода OpenSSL.

У этого класса нет публичного конструктора. Экземпляр SSLObject должен быть создан с помощью метода wrap_bio(). Этот метод создаст экземпляр SSLObject и свяжет его с парой BIO. Входящий BIO используется для передачи данных из Python в экземпляр протокола SSL, а исходящий BIO используется для передачи данных в обратном направлении.

Доступны следующие методы:

• context
• server_side
• server_hostname
• session
• session_reused
• read()
• write()
• getpeercert()
• selected_npn_protocol()
• cipher()
• shared_ciphers()
• compression()
• pending()
• do_handshake()
• unwrap()
• get_channel_binding()

По сравнению с SSLSocket, этому объекту не хватает следующих функций:

• Любой формы сетевого ввода-вывода; recv() и send() читают и записывают только в лежащие в основе буферы MemoryBIO.
• Нет механизма do_handshake_on_connect. Вы всегда должны вручную вызвать do_handshake(), чтобы начать рукопожатие.
• Нет обработки suppress_ragged_eofs. Все условия конца файла, которые нарушают протокол, сообщаются через исключение SSLEOFError.
• Вызов метода unwrap() ничего не возвращает, в отличие от сокета SSL, где он возвращает лежащий в основе сокет.
• Обратный вызов server_name_callback, переданный в SSLContext.set_servername_callback(), получит экземпляр SSLObject вместо экземпляра SSLSocket в качестве своего первого параметра.

Некоторые замечания, связанные с использованием SSLObject:

• Весь ввод-вывод для SSLObject является неблокирующим. Это означает, что, например, read() вызовет SSLWantReadError, если ему требуется больше данных, чем доступно в входящем BIO.
• Нет вызова wrap_bio() на уровне модуля, как есть для wrap_socket(). Экземпляр SSLObject всегда создается с помощью SSLContext.

Изменено в версии 3.7: SSLObject экземпляры должны быть созданы с помощью wrap_bio(). В более ранних версиях было возможно создавать экземпляры напрямую. Это никогда не документировалось или официально не поддерживалось.

SSLObject общается с внешним миром с помощью буферов памяти. Класс MemoryBIO предоставляет буфер памяти, который можно использовать для этой цели. Он оборачивает объект памяти BIO OpenSSL (Basic IO):

class ssl.MemoryBIO

Буфер памяти, который можно использовать для передачи данных между Python и экземпляром протокола SSL.

pending

Возвращает количество байтов, текущие хранящихся в буфере памяти.

eof

Логическое значение, указывающее, находится ли память BIO в текущей позиции конца файла.

read(n=-1)

Считывает до n байтов из буфера памяти. Если n не указано или отрицательно, возвращаются все байты.

write(buf)

Записывает байты из buf в память BIO. Аргумент buf должен быть объектом, поддерживающим протокол буфера.

Возвращаемое значение — количество записанных байтов, которое всегда равно длине buf.

write_eof()

Записывает маркер EOF в память BIO. После вызова этого метода вызов write() запрещен. Атрибут eof станет истинным после того, как все данные, текущие в буфере, будут считаны.

Сессия SSL

class ssl.SSLSession

Объект сессии, используемый методом session.

id

time

timeout

ticket_lifetime_hint

has_ticket

Учет безопасности

Лучшие значения по умолчанию

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

Например, вот как вы можете использовать класс smtplib.SMTP для создания надёжного безопасного подключения к серверу SMTP:

>>> import ssl, smtplib
>>> smtp = smtplib.SMTP("mail.python.org", port=587)
>>> context = ssl.create_default_context()
>>> smtp.starttls(context=context)
(220, b'2.0.0 Ready to start TLS')

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

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

Настройки вручную

Проверка сертификатов

При прямом вызове конструктора SSLContext, значение CERT_NONE используется по умолчанию. Поскольку он не выполняет проверку подлинности другого узла, это может быть небезопасно, особенно в режиме клиента, где обычно требуется подтверждение подлинности сервера, с которым вы общаетесь. Поэтому в режиме клиента настоятельно рекомендуется использовать CERT_REQUIRED. Однако этого недостаточно; также необходимо проверить, соответствует ли сертификат сервера, который можно получить, вызвав SSLSocket.getpeercert(), требуемому сервису. Для многих протоколов и приложений сервис может быть идентифицирован по имени хоста; в этом случае можно использовать функцию match_hostname(). Эта общая проверка выполняется автоматически при включении SSLContext.check_hostname.

В режиме сервера, если вы хотите проверить подлинность клиентов с помощью SSL-слоя (вместо использования механизма проверки подлинности более высокого уровня), вам также необходимо указать CERT_REQUIRED и аналогично проверить сертификат клиента.

Версии протоколов

SSL версии 2 и 3 считаются небезопасными и поэтому небезопасны для использования. Для максимальной совместимости между клиентами и серверами рекомендуется использовать PROTOCOL_TLS_CLIENT или PROTOCOL_TLS_SERVER в качестве версии протокола. SSLv2 и SSLv3 отключены по умолчанию.

>>> client_context = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
>>> client_context.options |= ssl.OP_NO_TLSv1
>>> client_context.options |= ssl.OP_NO_TLSv1_1

Созданный выше SSL-контекст будет допускать только подключения TLSv1.2 и более поздних версий (если поддерживаются вашей системой) к серверу. PROTOCOL_TLS_CLIENT по умолчанию подразумевает проверку сертификата и соответствие имени хоста. Вам необходимо загрузить сертификаты в контекст.

Выбор шифров

Если у вас есть повышенные требования к безопасности, то можно более точно настроить шифры, используемые при установлении SSL-сессии, с помощью метода SSLContext.set_ciphers(). Начиная с Python 3.2.3, модуль ssl отключает некоторые слабые шифры по умолчанию, но вы можете дополнительно ограничить выбор шифров. Обязательно прочитайте документацию OpenSSL о формате списка шифров https://www.openssl.org/docs/manmaster/man1/ciphers.html#CIPHER-LIST-FORMAT. Чтобы проверить, какие шифры включены в данный список шифров, используйте SSLContext.get_ciphers() или команду openssl ciphers на вашей системе.

Многопроцессорность

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

TLS 1.3

Python имеет предварительную и экспериментальную поддержку TLS 1.3 с OpenSSL 1.1.1. Новый протокол ведёт себя немного иначе, чем предыдущие версии TLS/SSL. Некоторые новые возможности TLS 1.3 ещё не доступны.

• TLS 1.3 использует отдельный набор наборов шифров. Все шифры AES-GCM и ChaCha20 включены по умолчанию. Метод SSLContext.set_ciphers() пока не может включать или выключать какие-либо шифры TLS 1.3, но SSLContext.get_ciphers() возвращает их.
• Билеты сеанса больше не отправляются в рамках начального рукопожатия и обрабатываются по-другому. SSLSocket.session и SSLSession несовместимы с TLS 1.3.
• Сертификаты клиента со стороны клиента также больше не проверяются во время начального рукопожатия. Сервер может запросить сертификат в любое время. Клиенты обрабатывают запросы сертификатов во время отправки или получения данных приложения от сервера.
• Функции TLS 1.3, такие как ранние данные, отложенный запрос TLS-сертификата клиента, настройка алгоритмов подписи и переключение ключей, пока не поддерживаются.

Поддержка LibreSSL

LibreSSL — это форк OpenSSL 1.0.1. Модуль ssl имеет ограниченную поддержку LibreSSL. Некоторые функции недоступны, когда модуль ssl скомпилирован с LibreSSL.

• LibreSSL >= 2.6.1 больше не поддерживает NPN. Методы SSLContext.set_npn_protocols() и SSLSocket.selected_npn_protocol() недоступны.
• SSLContext.set_default_verify_paths() игнорирует переменные среды SSL_CERT_FILE и SSL_CERT_PATH, хотя get_default_verify_paths() по-прежнему сообщает о них.