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

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

import socket
import ssl

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

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

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

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

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

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

Сокеты SSL

class ssl.SSLSocket(socket.socket)

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

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

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

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

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

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

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

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

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

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

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

Читает из сокета SSL до len байт данных и возвращает результат в виде экземпляра bytes. Если указан buffer, данные читаются в буфер, а метод возвращает количество прочитанных байтов.

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

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

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

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

SSLSocket.write(data)

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

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

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

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

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

SSLSocket.do_handshake(block=False)

Выполняет рукопожатие для настройки SSL.

Если block имеет значение true, а тайм-аут, полученный с помощью gettimeout(), равен нулю, сокет переводится в блокирующий режим до завершения рукопожатия.

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

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

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

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

Возвращает проверенную цепочку сертификатов, предоставленную другой стороной SSL-канала, в виде списка DER-кодированных байтов. Если проверка сертификатов отключена, метод работает так же, как get_unverified_chain().

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

SSLSocket.get_unverified_chain()

Возвращает исходную цепочку сертификатов, предоставленную другой стороной SSL-канала, в виде списка DER-кодированных байтов.

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

SSLSocket.cipher()

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

SSLSocket.shared_ciphers()

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

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

SSLSocket.compression()

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

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

Добавлено в версии 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. Возвращается None, если SSLContext.set_alpn_protocols() не был вызван, если другая сторона не поддерживает ALPN, если этот сокет не поддерживает ни один из предложенных клиентом протоколов или если рукопожатие ещё не состоялось.

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

SSLSocket.selected_npn_protocol()

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

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

Устарело с версии 3.10: ALPN пришёл на смену NPN.

SSLSocket.unwrap()

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

SSLSocket.verify_client_post_handshake()

Запрашивает у клиента TLS 1.3 аутентификацию после рукопожатия (PHA). 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 является TLS 1.2.

Примечание

После начала использования в соединении 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 можно напрямую передать строку, 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(alpn_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(npn_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-клиент указал индикацию имени сервера. Механизм индикации имени сервера описан в разделе 3 «Server Name Indication» документа RFC 6066.

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

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

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

Из-за раннего этапа согласования TLS-соединения доступны лишь некоторые методы и атрибуты, например SSLSocket.selected_alpn_protocol() и SSLSocket.context. Методы SSLSocket.getpeercert(), SSLSocket.get_verified_chain(), SSLSocket.get_unverified_chain(), 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-метку ("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. Атрибут можно присвоить экземплярам SSLContext, чтобы возвращался пользовательский подкласс 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_NONE, значение verify_mode теперь автоматически изменяется на CERT_REQUIRED. Ранее такая операция приводила к исключению 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. Реализация не предотвращает использование недопустимых комбинаций. Например, контекст, в котором в options задано OP_NO_TLSv1_2, а 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>

SSLContext.set_psk_client_callback(callback)

Включает аутентификацию TLS-PSK (на основе предварительно заданного ключа) для соединения на стороне клиента.

Как правило, аутентификацию на основе сертификатов следует предпочесть этому методу.

Параметр callback — вызываемый объект со следующей сигнатурой: def callback(hint: str | None) -> tuple[str | None, bytes]. Параметр hint — необязательная подсказка идентификатора, отправляемая сервером. Возвращаемое значение — кортеж вида (идентификатор клиента, psk). Идентификатор клиента — необязательная строка, которую сервер может использовать для выбора соответствующего PSK для клиента. После кодирования в UTF-8 длина строки не должна превышать 256 октетов. PSK — это объект, подобный bytes, представляющий предварительно заданный ключ. Чтобы отклонить соединение, верните PSK нулевой длины.

Установка для callback значения None удаляет имеющийся callback.

Примечание

При использовании TLS 1.3:

• параметр hint всегда равен None.
• идентификатор клиента должен быть непустой строкой.

Пример использования:

context = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
context.check_hostname = False
context.verify_mode = ssl.CERT_NONE
context.maximum_version = ssl.TLSVersion.TLSv1_2
context.set_ciphers('PSK')

# A simple lambda:
psk = bytes.fromhex('c0ffee')
context.set_psk_client_callback(lambda hint: (None, psk))

# A table using the hint from the server:
psk_table = { 'ServerId_1': bytes.fromhex('c0ffee'),
              'ServerId_2': bytes.fromhex('facade')
}
def callback(hint):
    return 'ClientId_1', psk_table.get(hint, b'')
context.set_psk_client_callback(callback)

Этот метод вызывает исключение NotImplementedError, если HAS_PSK имеет значение False.

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

SSLContext.set_psk_server_callback(callback, identity_hint=None)

Включает аутентификацию TLS-PSK (на основе предварительно заданного ключа) для соединения на стороне сервера.

Как правило, аутентификацию на основе сертификатов следует предпочесть этому методу.

Параметр callback — вызываемый объект со следующей сигнатурой: def callback(identity: str | None) -> bytes. Параметр identity — необязательный идентификатор, передаваемый клиентом; его можно использовать для выбора соответствующего PSK. Возвращаемое значение — объект, подобный bytes, представляющий предварительно заданный ключ. Чтобы отклонить соединение, верните PSK нулевой длины.

Установка для callback значения None удаляет имеющийся callback.

Параметр identity_hint — необязательная строка-подсказка для идентификатора, отправляемая клиенту. После кодирования в UTF-8 длина строки не должна превышать 256 октетов.

Примечание

При использовании TLS 1.3 параметр identity_hint клиенту не отправляется.

Пример использования:

context = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER)
context.maximum_version = ssl.TLSVersion.TLSv1_2
context.set_ciphers('PSK')

# A simple lambda:
psk = bytes.fromhex('c0ffee')
context.set_psk_server_callback(lambda identity: psk)

# A table using the identity of the client:
psk_table = { 'ClientId_1': bytes.fromhex('c0ffee'),
              'ClientId_2': bytes.fromhex('facade')
}
def callback(identity):
    return psk_table.get(identity, b'')
context.set_psk_server_callback(callback, 'ServerId_1')

Этот метод вызывает исключение NotImplementedError, если HAS_PSK имеет значение False.

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

Сертификаты

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

Сертификат содержит сведения о двух участниках. В нём указано имя субъекта и открытый ключ субъекта. Кроме того, сертификат содержит утверждение второго участника, издателя, о том, что субъект действительно является тем, за кого себя выдаёт, и что указанный открытый ключ действительно принадлежит субъекту. Утверждение издателя подписывается его закрытым ключом, известным только ему. Однако любой может проверить утверждение издателя, найдя его открытый ключ, расшифровав им утверждение и сравнив результат с остальными сведениями в сертификате. Сертификат также содержит сведения о периоде его действия. Они представлены двумя полями, называемыми «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()
• get_verified_chain()
• get_unverified_chain()
• 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.

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

Объект SSLObject взаимодействует с внешним миром с помощью буферов памяти. Для этого предназначен класс MemoryBIO, предоставляющий буфер памяти. Он оборачивает объект Memory BIO (Basic IO) OpenSSL:

class ssl.MemoryBIO

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

pending

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

eof

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

read(n=-1, /)

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

write(buf, /)

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

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

write_eof()

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

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