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

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

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

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

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()
        ...

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-ошибка.

SSLSocket.getpeercert(binary_form=False)

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

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

Поля subject и issuer — кортежи, содержащие последовательность относительных distinguished names (RDNs), указанных в структуре данных сертификата для соответствующих полей, причём каждый 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 и URI OCSP.

Изменено в версии 3.9: Строки адресов 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.8.

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 Contexts

Контекст 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 и одним другим сертификатом:

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

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

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

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

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

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

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

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

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

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

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

SSLContext.get_ca_certs(binary_form=False)

Получить список загруженных сертификатов уполномоченных центров сертификации (CA). Если параметр 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()

Загрузить набор стандартных сертификатов уполномоченных центров сертификации (CA) из пути к файловой системе, определённого при построении библиотеки 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'], упорядоченных по приоритету. Выбор протокола произойдёт во время рукопожатия в соответствии с переговорами протоколов прикладного уровня. После успешного рукопожатия метод SSLSocket.selected_npn_protocol() вернёт согласованный протокол.

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

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

SSLContext.sni_callback

Регистрация функции обратного вызова, которая будет вызываться после получения сообщения TLS Client Hello сервером SSL/TLS, когда клиент TLS указывает индикацию имени сервера. Механизм индикации имени сервера описан в RFC 6066 разделе 3 - Server Name Indication.

Только один обратный вызов может быть задан на один 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.cipher() и SSLSocket.compression() требуют, чтобы подключение 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 завершится с ALERT_DESCRIPTION_INTERNAL_ERROR сообщением об ошибке TLS клиенту.

Добавлен в версии 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 и полная передовая секретность

Винсент Бернат.

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, при server_side равном true будет возбуждено исключение ValueError.

Параметр 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 incoming и записывать данные в BIO outgoing.

Параметры 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

Приводить ли в соответствие имя хоста в сертификате удалённого узла во время 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.keylog_filename

Записывать ключи TLS в файл keylog всякий раз, когда генерируется или принимается материал ключа. Файл keylog предназначен только для отладки. Формат файла задаётся NSS и используется многими анализаторами трафика, такими как Wireshark. Лог-файл открывается в режиме добавления. Записи синхронизируются между потоками, но не между процессами.

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

Примечание

Эта функция требует OpenSSL 1.1.1 или новее.

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

Управляет количеством билетов сессий TLS 1.3 для контекста TLS_PROTOCOL_SERVER. Настройки не влияют на соединения TLS 1.0-1.2.

Примечание

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

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

SSLContext.options

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

Примечание

В версиях 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.8.

SSLContext.protocol

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

SSLContext.hostname_checks_common_name

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

Примечание

Изменяется только с OpenSSL 1.1.0 или более поздней версией.

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

Изменено в версии 3.9.3: Флаг не имел эффекта с OpenSSL до версии 1.1.1k. Python 3.8.9, 3.9.3 и 3.10 включают обходные пути для предыдущих версий.

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

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

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

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

Примеры

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

>>> context = ssl.create_default_context()

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

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

>>> cert = conn.getpeercert()

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

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

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.example.com', 10023))
bindsocket.listen(5)

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

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-handshake будет неблокирующим: метод 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 предоставляет две взаимосвязанные, но distinct области функциональности:

• Обработка протокола 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_alpn_protocol()
• selected_npn_protocol()
• cipher()
• shared_ciphers()
• compression()
• pending()
• do_handshake()
• verify_client_post_handshake()
• unwrap()
• get_channel_binding()
• version()

По сравнению с 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 предоставляет буфер памяти, который можно использовать для этой цели. Он оборачивает объект памяти OpenSSL BIO (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

Рекомендации по безопасности

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

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

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() по-прежнему их отображает.