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-сокеты предоставляют следующие методы объекта Socket Objects:

• 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: OpenSSL сопоставляет имя хоста или IP-адрес во время рукопожатия. Функция match_hostname() больше не используется. Если OpenSSL отклоняет имя хоста или IP-адрес, рукопожатие досрочно прерывается, а другой стороне отправляется TLS-сообщение-предупреждение.

SSLSocket.getpeercert(binary_form=False)

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

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

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

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

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

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

См. также SSLContext.check_hostname.

Изменено в версии 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-сокет.

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

SSLSocket.server_side

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

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

SSLSocket.server_hostname

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

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

Изменено в версии 3.7: Теперь атрибут всегда содержит текст в кодировке ASCII. Если server_hostname — интернационализированное доменное имя (IDN), в этом атрибуте теперь хранится форма A-label ("xn--pythn-mua.org"), а не форма U-label ("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	нет	нет	да	нет	нет	да

Сноски

См. также

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

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

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

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

Примечание

SSLContext допускает лишь ограниченные изменения после того, как контекст был использован соединением. Добавлять новые сертификаты во внутреннее хранилище доверенных сертификатов разрешено, но изменение шифров, настроек проверки или сертификатов mTLS может привести к неожиданному поведению.

Примечание

SSLContext предназначен для совместного использования несколькими соединениями. Поэтому он потокобезопасен, если его не перенастраивать после использования соединением.

Объекты 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 может быть функцией, вызываемой для получения пароля, необходимого для расшифровки закрытого ключа. Она будет вызвана, только если закрытый ключ зашифрован и требуется пароль. Функция вызывается без аргументов и должна возвращать строку, bytes или bytearray. Если возвращаемое значение является строкой, перед использованием для расшифровки ключа оно будет закодировано в UTF-8. Также непосредственно в качестве аргумента password можно передать значение типа string, bytes или bytearray. Оно игнорируется, если закрытый ключ не зашифрован и пароль не нужен.

Если аргумент 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, либо объект, подобный bytes, содержащий сертификаты в формате DER. Как и в случае с capath, дополнительные строки вокруг сертификатов в формате PEM игнорируются, но должен присутствовать хотя бы один сертификат.

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

SSLContext.get_ca_certs(binary_form=False)

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

Примечание

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

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

SSLContext.get_ciphers()

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

Пример:

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

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

SSLContext.set_default_verify_paths()

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

SSLContext.set_ciphers(ciphers)

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

Примечание

После установления соединения метод SSLSocket.cipher() SSL-сокетов возвращает выбранный в данный момент шифр.

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

SSLContext.set_alpn_protocols(protocols)

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

Если HAS_ALPN имеет значение False, этот метод возбуждает исключение NotImplementedError.

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

SSLContext.set_npn_protocols(protocols)

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

Если HAS_NPN имеет значение False, этот метод возбуждает исключение NotImplementedError.

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

Устарело с версии 3.10: NPN вытеснен ALPN

SSLContext.sni_callback

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

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

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

Типичное применение этого обработчика — изменение атрибута SSLSocket.context объекта ssl.SSLSocket на новый объект типа 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.

Если при сборке библиотеки OpenSSL была определена константа OPENSSL_NO_TLSEXT, этот метод возбуждает исключение NotImplementedError.

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

SSLContext.set_servername_callback(server_name_callback)

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

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

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

SSLContext.load_dh_params(dhfile)

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

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

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

SSLContext.set_ecdh_curve(curve_name)

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

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

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

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

См. также

SSL/TLS и совершенная прямая секретность

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

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_side имеет значение true, указание server_hostname вызовет исключение ValueError.

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

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

session — см. session.

Чтобы обернуть SSLSocket в другой SSLSocket, используйте SSLContext.wrap_bio().

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

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

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

SSLContext.sslsocket_class

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

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

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

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

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

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

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

SSLContext.sslobject_class

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

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

SSLContext.session_stats()

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

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

SSLContext.check_hostname

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

Пример:

import socket, ssl

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

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

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

Изменено в версии 3.7: Теперь при включении проверки имени узла значение verify_mode автоматически меняется на CERT_REQUIRED, если verify_mode имеет значение CERT_NONE. Ранее та же операция приводила к исключению ValueError.

SSLContext.keylog_filename

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

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

Изменено в версии 3.10: В OpenSSL до версии 1.1.1l этот флаг не действовал. В 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) — это представление в кодировке 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.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-рукопожатие будет неблокирующим: метод SSLSocket.do_handshake() нужно повторять, пока он не завершится успешно. Ниже приведён пример использования select() для ожидания готовности сокета:

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

Поддержка Memory BIO

С момента появления модуля SSL в Python 2.6 класс SSLSocket предоставляет две связанные, но отдельные группы возможностей:

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

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

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

class ssl.SSLObject

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

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

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

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

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

По сравнению с SSLSocket, этому объекту недоступны следующие возможности:

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

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

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

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

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

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, настройка алгоритмов подписи и повторное согласование ключей, пока не поддерживаются.