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

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

import socket
import ssl

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

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

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

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

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

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

Сокеты SSL

class ssl.SSLSocket(socket.socket)

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

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

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

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

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

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

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

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

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

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

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

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

Вызвать SSLWantReadError или SSLWantWriteError, если сокет находится в режиме без ожидания и чтение привело бы к блокировке.

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

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

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

SSLSocket.write(buf)

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

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

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

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

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

SSLSocket.do_handshake()

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

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

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

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

SSLSocket.getpeercert(binary_form=False)

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

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

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

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

Если параметр 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 и OCSP URI.

Изменено в версии 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 если сжатие не используется.

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

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

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

Получить данные связывания каналов для текущего соединения в виде объекта байтов. Возвращает 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-метки ("xn--pythn-mua.org"), а не форму U-метки ("pythön.org").

SSLSocket.session

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

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

SSLSocket.session_reused

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

SSL-контексты

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

class ssl.SSLContext(protocol=None)

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

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

клиент / сервер	SSLv2	SSLv3	TLS [3]	TLSv1	TLSv1.1	TLSv1.2
SSLv2	да	нет	нет [1]	нет	нет	нет
SSLv3	нет	да	нет [2]	нет	нет	нет
TLS (SSLv23) [3]	нет [1]	нет [2]	да	да	да	да
TLSv1	нет	нет	да	да	нет	нет
TLSv1.1	нет	нет	да	нет	да	нет
TLSv1.2	нет	нет	да	нет	нет	да

Примечания

См. также

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

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

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

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

Примечание

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

Примечание

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

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

SSLContext.cert_store_stats()

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

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

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

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

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

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

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

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

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

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

SSLContext.load_default_certs(purpose=Purpose.SERVER_AUTH)

Загрузка набора стандартных сертификатов «центра сертификации» (CA) из стандартных расположений. В Windows загружаются сертификаты CA из системных хранилищ CA и ROOT. На всех системах вызывается SSLContext.set_default_verify_paths(). В будущем метод может загружать сертификаты CA и из других мест.

Флаг purpose указывает, какие сертификаты CA загрузить. По умолчанию Purpose.SERVER_AUTH загружает сертификаты, помеченные и доверенные для аутентификации веб-серверов TLS (сокеты клиента). Purpose.CLIENT_AUTH загружает сертификаты CA для проверки сертификатов клиента на стороне сервера.

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

SSLContext.load_verify_locations(cafile=None, capath=None, cadata=None)

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

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

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

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

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

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

SSLContext.get_ca_certs(binary_form=False)

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

Примечание

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

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

SSLContext.get_ciphers()

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

Пример:

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

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

SSLContext.set_default_verify_paths()

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

SSLContext.set_ciphers(ciphers)

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

Примечание

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

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

SSLContext.set_alpn_protocols(protocols)

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

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

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

SSLContext.set_npn_protocols(protocols)

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

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

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

Устарел начиная с версии 3.10: NPN был заменён на ALPN

SSLContext.sni_callback

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

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

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

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

Из-за ранней фазы согласования TLS доступны только ограниченные методы и атрибуты, такие как SSLSocket.selected_alpn_protocol() и SSLSocket.context. Методы SSLSocket.getpeercert(), SSLSocket.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.

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

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

SSLContext.set_servername_callback(server_name_callback)

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

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

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

SSLContext.load_dh_params(dhfile)

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

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

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

SSLContext.set_ecdh_curve(curve_name)

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

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

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

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

См. также

SSL/TLS и идеальная секретность в будущем

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

SSLContext.wrap_socket(sock, server_side=False, do_handshake_on_connect=True, suppress_ragged_eofs=True, server_hostname=None, session=None)

Оборачивает существующий сокет Python sock и возвращает экземпляр SSLContext.sslsocket_class (по умолчанию SSLSocket). Возвращаемый SSL-сокет привязан к контексту, его настройкам и сертификатам. sock должен быть сокетом SOCK_STREAM; другие типы сокетов не поддерживаются.

Параметр server_side — булево значение, указывающее, требуется ли поведение сокета со стороны сервера или клиента.

Для сокетов клиента создание контекста выполняется лениво; если подлежащий сокет ещё не подключён, создание контекста произойдёт после вызова connect() на сокете. Для сокетов сервера, если сокет не имеет удалённого узла, он предполагается в качестве сокета прослушивания, и SSL-обёртывание со стороны сервера автоматически выполняется при подключении клиентов через метод accept(). Метод может вызвать SSLError.

При подключении к клиенту необязательный параметр server_hostname указывает имя хоста службы, к которой мы подключаемся. Это позволяет одному серверу размещать несколько SSL-служб с различными сертификатами, очень похоже на виртуальные хосты HTTP. Указание server_hostname вызовет ValueError, если server_side равно true.

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

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

session, см. session.

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

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

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

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

SSLContext.sslsocket_class

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

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

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

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

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

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

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

SSLContext.sslobject_class

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

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

SSLContext.session_stats()

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

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

SSLContext.check_hostname

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

Пример:

import socket, ssl

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

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

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

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

SSLContext.keylog_filename

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

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

SSLContext.maximum_version

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

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

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

SSLContext.minimum_version

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

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

SSLContext.num_tickets

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

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

SSLContext.options

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

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

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

Устарело начиная с версии 3.7: Все OP_NO_SSL* и OP_NO_TLS* варианты устарели начиная с Python 3.7. Используйте SSLContext.minimum_version и SSLContext.maximum_version вместо них.

SSLContext.post_handshake_auth

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

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

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

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

SSLContext.protocol

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

SSLContext.hostname_checks_common_name

Определяет, check_hostname отпадает к проверке имени субъекта сертификата в отсутствие расширения Subject Alternative Name (по умолчанию: 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 для клиента. Строка должна быть меньше или равна 256 октетам при кодировании UTF-8. PSK — объект типа байты, представляющий предварительно общие ключ. Возвратите PSK нулевой длины для отклонения соединения.

Установление callback в None удаляет любой существующий обратный вызов.

Примечание

При использовании 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. Возвращаемое значение — объект типа байты, представляющий предварительно общие ключ. Возвратите PSK нулевой длины для отклонения соединения.

Установление callback в None удаляет любой существующий обратный вызов.

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

Примечание

При использовании 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), которая представляет собой кодировку в формате base-64, обернутую заголовком и подвалом:

-----BEGIN CERTIFICATE-----
... (certificate in base64 PEM encoding) ...
-----END CERTIFICATE-----

-----BEGIN CERTIFICATE-----
... (certificate for your server)...
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
... (the certificate for the CA)...
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
... (the root certificate for the CA's issuer)...
-----END CERTIFICATE-----

-----BEGIN RSA PRIVATE KEY-----
... (private key in base64 encoding) ...
-----END RSA PRIVATE KEY-----
-----BEGIN CERTIFICATE-----
... (certificate in base64 PEM encoding) ...
-----END CERTIFICATE-----

% openssl req -new -x509 -days 365 -nodes -out cert.pem -keyout cert.pem
Generating a 1024 bit RSA private key
.......++++++
.............................++++++
writing new private key to 'cert.pem'
-----
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]:US
State or Province Name (full name) [Some-State]:MyState
Locality Name (eg, city) []:Some City
Organization Name (eg, company) [Internet Widgits Pty Ltd]:My Organization, Inc.
Organizational Unit Name (eg, section) []:My Group
Common Name (eg, YOUR name) []:myserver.mygroup.myorganization.com
Email Address []:ops@myserver.mygroup.myorganization.com
%

Примеры

try:
    import ssl
except ImportError:
    pass
else:
    ...  # do something that requires SSL support

>>> context = ssl.create_default_context()

>>> context = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
>>> context.load_verify_locations("/etc/ssl/certs/ca-bundle.crt")

>>> conn = context.wrap_socket(socket.socket(socket.AF_INET),
...                            server_hostname="www.python.org")
>>> conn.connect(("www.python.org", 443))

>>> cert = conn.getpeercert()

>>> pprint.pprint(cert)
{'OCSP': ('http://ocsp.digicert.com',),
 'caIssuers': ('http://cacerts.digicert.com/DigiCertSHA2ExtendedValidationServerCA.crt',),
 'crlDistributionPoints': ('http://crl3.digicert.com/sha2-ev-server-g1.crl',
                           'http://crl4.digicert.com/sha2-ev-server-g1.crl'),
 'issuer': ((('countryName', 'US'),),
            (('organizationName', 'DigiCert Inc'),),
            (('organizationalUnitName', 'www.digicert.com'),),
            (('commonName', 'DigiCert SHA2 Extended Validation Server CA'),)),
 'notAfter': 'Sep  9 12:00:00 2016 GMT',
 'notBefore': 'Sep  5 00:00:00 2014 GMT',
 'serialNumber': '01BB6F00122B177F36CAB49CEA8B6B26',
 'subject': ((('businessCategory', 'Private Organization'),),
             (('1.3.6.1.4.1.311.60.2.1.3', 'US'),),
             (('1.3.6.1.4.1.311.60.2.1.2', 'Delaware'),),
             (('serialNumber', '3359300'),),
             (('streetAddress', '16 Allen Rd'),),
             (('postalCode', '03894-4801'),),
             (('countryName', 'US'),),
             (('stateOrProvinceName', 'NH'),),
             (('localityName', 'Wolfeboro'),),
             (('organizationName', 'Python Software Foundation'),),
             (('commonName', 'www.python.org'),)),
 'subjectAltName': (('DNS', 'www.python.org'),
                    ('DNS', 'python.org'),
                    ('DNS', 'pypi.org'),
                    ('DNS', 'docs.python.org'),
                    ('DNS', 'testpypi.org'),
                    ('DNS', 'bugs.python.org'),
                    ('DNS', 'wiki.python.org'),
                    ('DNS', 'hg.python.org'),
                    ('DNS', 'mail.python.org'),
                    ('DNS', 'packaging.python.org'),
                    ('DNS', 'pythonhosted.org'),
                    ('DNS', 'www.pythonhosted.org'),
                    ('DNS', 'test.pythonhosted.org'),
                    ('DNS', 'us.pycon.org'),
                    ('DNS', 'id.python.org')),
 'version': 3}

>>> conn.sendall(b"HEAD / HTTP/1.0\r\nHost: linuxfr.org\r\n\r\n")
>>> pprint.pprint(conn.recv(1024).split(b"\r\n"))
[b'HTTP/1.1 200 OK',
 b'Date: Sat, 18 Oct 2014 18:27:20 GMT',
 b'Server: nginx',
 b'Content-Type: text/html; charset=utf-8',
 b'X-Frame-Options: SAMEORIGIN',
 b'Content-Length: 45679',
 b'Accept-Ranges: bytes',
 b'Via: 1.1 varnish',
 b'Age: 2188',
 b'X-Served-By: cache-lcy1134-LCY',
 b'X-Cache: HIT',
 b'X-Cache-Hits: 11',
 b'Vary: Cookie',
 b'Strict-Transport-Security: max-age=63072000; includeSubDomains',
 b'Connection: close',
 b'',
 b'']

import socket, ssl

context = ssl.create_default_context(ssl.Purpose.CLIENT_AUTH)
context.load_cert_chain(certfile="mycertfile", keyfile="mykeyfile")

bindsocket = socket.socket()
bindsocket.bind(('myaddr.example.com', 10023))
bindsocket.listen(5)

while True:
    newsocket, fromaddr = bindsocket.accept()
    connstream = context.wrap_socket(newsocket, server_side=True)
    try:
        deal_with_client(connstream)
    finally:
        connstream.shutdown(socket.SHUT_RDWR)
        connstream.close()

def deal_with_client(connstream):
    data = connstream.recv(1024)
    # empty data means the client is finished with us
    while data:
        if not do_something(connstream, data):
            # we'll assume do_something returns False
            # when we're finished with client
            break
        data = connstream.recv(1024)
    # finished with client

Примечания по неблокирующим сокетам

Сокеты SSL ведут себя немного иначе, чем обычные сокеты, в режиме без блокировки. При работе с неблокирующими сокетами необходимо учитывать несколько моментов:

• Большинство методов SSLSocket будут поднимать исключения SSLWantWriteError или SSLWantReadError вместо BlockingIOError, если операция ввода-вывода заблокируется. SSLWantReadError будет поднято, если необходима операция чтения из базового сокета, а SSLWantWriteError — для записи в базовый сокет. Обратите внимание, что попытки записи в сокет SSL могут потребовать чтения из базового сокета, а попытки чтения из сокета SSL могут потребовать предварительной записи в базовый сокет.

  Изменено в версии 3.5: В более ранних версиях Python метод SSLSocket.send() возвращал ноль вместо поднятия SSLWantWriteError или SSLWantReadError.

• Вызов select() указывает, что сокет на уровне ОС можно читать (или записывать), но это не подразумевает, что в верхнем слое SSL имеется достаточное количество данных. Например, может прибыть только часть кадра SSL. Поэтому вы должны быть готовы обрабатывать ошибки SSLSocket.recv() и SSLSocket.send() и повторить попытку после нового вызова select().

• И наоборот, так как у слоя SSL есть собственная структура данных, сокет SSL может иметь доступные для чтения данные, даже если select() об этом не знает. Поэтому вы должны сначала вызвать SSLSocket.recv() для извлечения потенциально доступных данных, а затем блокировать вызов select() только в случае необходимости.

  (конечно, аналогичные положения применяются при использовании других примитивов, таких как poll(), или тех, что в модуле selectors)

• Сам SSL-handshake будет неблокирующим: метод SSLSocket.do_handshake() должен повторяться, пока не вернётся успешно. Вот пример использования select() для ожидания готовности сокета:

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

Поддержка BIO для памяти

С момента введения модуля SSL в Python 2.6, класс SSLSocket предоставляет две взаимосвязанные, но distinct функциональные области:

• Обработка протокола SSL
• Сеть Ввод/Вывод

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()
• и другие

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

class ssl.MemoryBIO

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

pending

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

eof

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

read(n=-1)

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

write(buf)

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

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

write_eof()

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

Сессия SSL

class ssl.SSLSession

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

id

time

timeout

ticket_lifetime_hint

has_ticket

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

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

>>> client_context = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
>>> client_context.minimum_version = ssl.TLSVersion.TLSv1_3
>>> client_context.maximum_version = ssl.TLSVersion.TLSv1_3

TLS 1.3

Протокол TLS 1.3 ведет себя немного иначе, чем предыдущие версии TLS/SSL. Некоторые новые функции TLS 1.3 пока недоступны.

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