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

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

import socket
import ssl

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

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

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

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

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

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

SSL-сокеты

class ssl.SSLSocket(socket.socket)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

SSLSocket.write(buf)

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

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

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

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

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

SSLSocket.do_handshake()

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

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

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

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

SSLSocket.getpeercert(binary_form=False)

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

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

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

SSLSocket.cipher()

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

SSLSocket.shared_ciphers()

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

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

SSLSocket.compression()

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

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

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

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

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

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

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

SSLSocket.selected_alpn_protocol()

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

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

SSLSocket.selected_npn_protocol()

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

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

SSLSocket.unwrap()

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

SSLSocket.verify_client_post_handshake()

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

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

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

Примечание

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

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

SSLSocket.version()

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

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

SSLSocket.pending()

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

SSLSocket.context

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

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

SSLSocket.server_side

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

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

SSLSocket.server_hostname

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

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

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

SSLSocket.session

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

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

SSLSocket.session_reused

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

SSL Contexts

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

class ssl.SSLContext(protocol=PROTOCOL_TLS)

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

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

client / server	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. Для только TLS 1.3 нет отдельной константы PROTOCOL.

См. также

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

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

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

SSLContext.cert_store_stats()

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

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

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

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

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

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

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

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

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

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

SSLContext.load_default_certs(purpose=Purpose.SERVER_AUTH)

Загрузить набор стандартных сертификатов «центра сертификации» (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)

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

Примечание

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

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

SSLContext.get_ciphers()

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

Пример:

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

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

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

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

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

SSLContext.set_default_verify_paths()

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

SSLContext.set_ciphers(ciphers)

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

Примечание

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

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

SSLContext.set_alpn_protocols(protocols)

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

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

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

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

SSLContext.set_npn_protocols(protocols)

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

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

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

SSLContext.sni_callback

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

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

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

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

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

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

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

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

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

SSLContext.set_servername_callback(server_name_callback)

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

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

Добавлена в версии 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-процедуры будут читать данные из входящего 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.

Примечание

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

SSLContext.keylog_filename

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

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

Примечание

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

SSLContext.maximum_version

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

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

Примечание

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

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

SSLContext.minimum_version

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

Примечание

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

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

SSLContext.num_tickets

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

Примечание

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

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

SSLContext.options

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

Примечание

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

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

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

SSLContext.post_handshake_auth

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

При включении на стороне клиента сокета клиент сигнализирует серверу о поддержке аутентификации после рукопожатия.

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

Примечание

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

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

SSLContext.protocol

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

SSLContext.hostname_checks_common_name

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

Примечание

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

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

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

SSLContext.verify_flags

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

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

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

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

SSLContext.verify_mode

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

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

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

Сертификаты

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

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

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

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

-----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.mydomain.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
• Сеть IO

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

class ssl.MemoryBIO

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

pending

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

eof

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

read(n=-1)

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

write(buf)

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

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

write_eof()

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

Сессия SSL

class ssl.SSLSession

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

id

time

timeout

ticket_lifetime_hint

has_ticket

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

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

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

TLS 1.3

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

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

Поддержка LibreSSL

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

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