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-адреса рукопожатие прерывается, и в peer отправляется сообщение TLS-сигнала об ошибке.

SSLSocket.getpeercert(binary_form=False)

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

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

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

Устарело начиная с версии 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_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, количестве помеченных как сертификаты 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)

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

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

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

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

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

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

SSLContext.get_ca_certs(binary_form=False)

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

Примечание

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

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

SSLContext.get_ciphers()

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

Пример:

>>> ctx = ssl.SSLContext(ssl.PROTOCOL_SSLv23)
>>> ctx.set_ciphers('ECDHE+AESGCM:!ECDSA')
>>> ctx.get_ciphers()
[{'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()

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

SSLContext.set_ciphers(ciphers)

Установить доступные шифры для сокетов, созданных с этим контекстом. Это должна быть строка в формате списка шифров OpenSSL. Формат списка шифров 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.3.

Устарело начиная с версии 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 (международное доменное имя), закодированном в 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 вызовет 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 будут читать данные ввода из incoming BIO и записывать данные в outgoing 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, объединив их с операцией побитового ИЛИ.

Изменено в версии 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 проверку имени общего сертификата в отсутствии расширения Subject Alternative Name (по умолчанию: 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, объединив их с операцией побитового ИЛИ. По умолчанию 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), что представляет собой кодировку 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
• Сеть IO

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

Комбинирование обработки протокола SSL и сети IO обычно работает хорошо, но в некоторых случаях это не так. Например, в фреймворках асинхронного IO, которые хотят использовать другую модель мультиплексирования IO, отличную от модели «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 клиента, конфигурация алгоритма подписи и переключение ключей, пока не поддерживаются.