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(). В предыдущих версиях их можно было создавать напрямую. Это никогда не документировалось и не поддерживалось официально.

Изменено в версии 3.10: Python теперь использует SSL_read_ex и SSL_write_ex внутри. Функции поддерживают чтение и запись данных, больших, чем 2 ГБ. Запись данных нулевой длины больше не приводит к ошибке нарушения протокола.

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 являются кортежами, содержащими последовательность относительных различительных имён (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.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.

Устарело начиная с версии 3.10: NPN был заменён на ALPN

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-контексты

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

class ssl.SSLContext(protocol=None)

Создайте новый 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).

Устарело начиная с версии 3.10: SSLContext без аргумента protocol устарело. В будущем класс контекста будет требовать протокол PROTOCOL_TLS_CLIENT или PROTOCOL_TLS_SERVER.

Изменено в версии 3.10: Наборы шифров по умолчанию теперь включают только безопасные шифры AES и ChaCha20 с защитой от раскрытия ключей и уровнем безопасности 2. RSA и DH-ключи с размером меньше 2048 бит и ECC-ключи с размером меньше 224 бит запрещены. PROTOCOL_TLS, PROTOCOL_TLS_CLIENT и PROTOCOL_TLS_SERVER используют TLS 1.2 как минимальную версию TLS.

Объекты 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)

Загрузка набора сертификатов «уполномоченных центров сертификации» (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()
[{'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'}]

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

SSLContext.set_default_verify_paths()

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

SSLContext.set_ciphers(ciphers)

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

Примечание

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

Шифры 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.

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

SSLContext.set_npn_protocols(protocols)

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

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

Устарело начиная с версии 3.10: NPN был заменён ALPN

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.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 завершится с фатальным предупреждением 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 & Perfect Forward Secrecy

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

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

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

SSLContext.keylog_filename

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

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

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.

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

SSLContext.minimum_version

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

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

SSLContext.num_tickets

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

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

SSLContext.options

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

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

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

Устарело начиная с версии 3.7: Все опции OP_NO_SSL* и OP_NO_TLS* устарели начиная с Python 3.7. Используйте SSLContext.minimum_version и SSLContext.maximum_version вместо них.

SSLContext.post_handshake_auth

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

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

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

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

SSLContext.protocol

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

SSLContext.hostname_checks_common_name

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

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

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

SSLContext.security_level

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

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

SSLContext.verify_flags

Флаги для операций проверки сертификатов. Вы можете установить флаги, такие как VERIFY_CRL_CHECK_LEAF, объединив их с операцией OR. По умолчанию OpenSSL не требует и не проверяет списки отзыва сертификатов (CRL).

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

• Обработка протокола 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.minimum_version = ssl.TLSVersion.TLSv1_3
>>> client_context.maximum_version = ssl.TLSVersion.TLSv1_3

TLS 1.3

Протокол TLS 1.3 немного отличается от предыдущих версий 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-сертификата клиента, настройка алгоритмов подписи и повторное ключевание, пока не поддерживаются.