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: Вместо read() используйте recv().

SSLSocket.write(data)

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

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

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

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

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

SSLSocket.do_handshake(block=False)

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

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

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

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

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

SSLSocket.getpeercert(binary_form=False)

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

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

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

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

Если параметр 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. Если 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 является 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_hostname вызовет исключение ValueError, если значение server_side равно true.

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

Параметр suppress_ragged_eofs определяет, как метод SSLSocket.recv() должен сообщать о неожиданном EOF с другого конца соединения. Если задано значение True (по умолчанию), при ошибках неожиданного EOF, возникших в базовом сокете, возвращается обычный EOF (пустой объект 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. Реализация не предотвращает недопустимые сочетания. Например, контекст с OP_NO_TLSv1_2 в options и значением TLSVersion.TLSv1_2 для maximum_version не сможет установить соединение 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 — необязательная подсказка идентификатора, отправляемая сервером. Возвращаемое значение — кортеж вида (client-identity, psk). Client-identity — необязательная строка, которую сервер может использовать для выбора соответствующего PSK для клиента. При кодировании в UTF-8 длина строки должна быть не более 256 октетов. PSK — это объект, подобный bytes, представляющий предварительно установленный ключ. Чтобы отклонить соединение, верните PSK нулевой длины.

Если задать для callback значение None, существующий обратный вызов будет удалён.

Примечание

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

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

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

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, существующий обратный вызов будет удалён.

Параметр 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, предоставляющий буфер памяти. Он оборачивает объект OpenSSL memory BIO (Basic IO):

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 станет истинным после считывания всех данных, находящихся в буфере.

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