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 может в некоторых аспектах отличаться от спецификации обычных сокетов на уровне ОС. См. особенно notes on non-blocking sockets.

Экземпляры 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, если сокет non-blocking и чтение будет блокироваться.

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

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

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

SSLSocket.write(buf)¶

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

Поднимите SSLWantReadError или SSLWantWriteError, если сокет non-blocking и запись будет блокироваться.

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

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

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

SSLSocket.do_handshake()¶

Выполните установочный квиток SSL.

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

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

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

SSLSocket.getpeercert(binary_form=False)¶

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

Если параметр binary_form равен False, и сертификат был получен от сверстника, этот метод возвращает экземпляр dict. Если сертификат не был подтвержден, dict будет пустым. Если сертификат был подтвержден, то возвращается 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}

Примечание

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

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

• для клиентского SSL-сокета, сервер всегда будет предоставлять сертификат, независимо от того, требовалась ли проверка;

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

Изменено в версии 3.2: Возвращаемый словарь включает дополнительные элементы, такие как issuer и notBefore.

Изменено в версии 3.4: ValueError выдается, если квитирование не завершено. Возвращаемый словарь включает дополнительные элементы расширения X509v3, такие как crlDistributionPoints, caIssuers и OCSP URI.

Изменено в версии 3.9: В строках адресов IPv6 больше нет новой строки в конце.

SSLSocket.cipher()¶

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

SSLSocket.shared_ciphers()¶

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

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

SSLSocket.compression()¶

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

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

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

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

Получить данные привязки канала для текущего соединения в виде объекта байтов. Возвращает 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-сокет. Если SSL-сокет был создан с помощью устаревшей функции wrap_socket() (а не SSLContext.wrap_socket()), то это объект пользовательского контекста, созданный для этого SSL-сокета.

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

SSLSocket.server_side¶

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

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

SSLSocket.server_hostname¶

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

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

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

SSLSocket.session¶

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

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

SSLSocket.session_reused¶

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

SSL-контексты¶

Контекст 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	нет	нет	да	нет	нет	да

Сноски

1(1,2)

SSLContext по умолчанию отключает SSLv2 с OP_NO_SSLv2.

2(1,2)

SSLContext по умолчанию отключает SSLv3 с OP_NO_SSLv3.

3(1,2)

Протокол TLS 1.3 будет доступен с PROTOCOL_TLS в OpenSSL >= 1.1.1. Не существует специальной константы PROTOCOL только для TLS 1.3.

См.также

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

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

Не рекомендуется, начиная с версии 3.10: SSLContext без аргумента протокола является устаревшим. В будущем класс контекста будет требовать протокол 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 имеют следующие методы и атрибуты:

SSLContext.cert_store_stats()¶

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

Пример для контекста с одним сертификатом 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, содержащему сертификат, а также любое количество сертификатов ЦС, необходимых для установления подлинности сертификата. Строка keyfile, если она присутствует, должна указывать на файл, содержащий закрытый ключ. В противном случае закрытый ключ также будет взят из certfile. См. обсуждение Сертификаты для получения дополнительной информации о том, как сертификат хранится в certfile.

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

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

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

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

SSLContext.load_default_certs(purpose=Purpose.SERVER_AUTH)¶

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

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

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

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

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

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

Строка cafile, если присутствует, представляет собой путь к файлу с объединенными сертификатами ЦС в формате PEM. См. обсуждение Сертификаты для получения дополнительной информации о том, как расположить сертификаты в этом файле.

Строка capath, если присутствует, представляет собой путь к каталогу, содержащему несколько сертификатов CA в формате PEM, следующий за OpenSSL specific layout.

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

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

SSLContext.get_ca_certs(binary_form=False)¶

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

Примечание

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

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

SSLContext.get_ciphers()¶

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

Пример:

>>> ctx = ssl.SSLContext(ssl.PROTOCOL_SSLv23)
>>> ctx.set_ciphers('ECDHE+AESGCM:!ECDSA')
>>> ctx.get_ciphers()
[{'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()¶

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

SSLContext.set_ciphers(ciphers)¶

Устанавливает доступные шифры для сокетов, созданных с этим контекстом. Это должна быть строка в формате OpenSSL cipher list format. Если ни один шифр не может быть выбран (потому что опции времени компиляции или другая конфигурация запрещают использование всех указанных шифров), будет выдано предупреждение 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'], упорядоченный по предпочтениям. Выбор протокола произойдет во время квитирования и будет происходить в соответствии с Application Layer Protocol Negotiation. После успешного квитирования метод SSLSocket.selected_npn_protocol() вернет согласованный протокол.

Этот метод вызовет ошибку NotImplementedError, если HAS_NPN будет False.

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

Не рекомендуется, начиная с версии 3.10: NPN был заменен на ALPN

SSLContext.sni_callback¶

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

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

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

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

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

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

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

Этот метод вызовет ошибку 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 & Perfect Forward Secrecy

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

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.

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

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

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

SSLContext.sslsocket_class¶

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

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

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

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

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

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

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

SSLContext.sslobject_class¶

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

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

SSLContext.session_stats()¶

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

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

SSLContext.check_hostname¶

Должно ли совпадать имя хоста peer cert в SSLSocket.do_handshake(). В verify_mode контекста должно быть установлено значение CERT_OPTIONAL или CERT_REQUIRED, а в wrap_socket() необходимо передать server_hostname для проверки имени хоста. Включение проверки имени хоста автоматически переводит 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 в файл keylog при генерации или получении ключевого материала. Файл keylog предназначен только для отладочных целей. Формат файла определен NSS и используется многими анализаторами трафика, такими как Wireshark. Файл журнала открывается в режиме append-only. Записи синхронизируются между потоками, но не между процессами.

Добавлено в версии 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, путем их объединения в OR.

Изменено в версии 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. Фактический обмен клиентскими cert задерживается до тех пор, пока не будет вызван SSLSocket.verify_client_post_handshake() и не будет выполнен некоторый ввод/вывод.

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

SSLContext.protocol¶

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

SSLContext.hostname_checks_common_name¶

Будет ли check_hostname возвращаться к проверке общего имени субъекта сертификата при отсутствии расширения альтернативного имени субъекта (по умолчанию: true).

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

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

SSLContext.security_level¶

Целое число, представляющее security level для контекста. Этот атрибут доступен только для чтения.

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

SSLContext.verify_flags¶

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

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

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

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

SSLContext.verify_mode¶

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

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

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

Сертификаты¶

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

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

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

Python использует файлы для хранения сертификатов. Они должны быть отформатированы как «PEM» (см. RFC 1422), что представляет собой форму в кодировке 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 квитирование будет неблокирующим: метод SSLSocket.do_handshake() должен быть повторно запущен до тех пор, пока он не завершится успешно. Вот синопсис с использованием select() для ожидания готовности сокета:

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

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

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

• Обработка протокола SSL

• Сетевой IO

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

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

class ssl.SSLObject¶

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

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

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

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

• context

• server_side

• server_hostname

• session

• session_reused

• read()

• write()

• getpeercert()

• selected_alpn_protocol()

• selected_npn_protocol()

• cipher()

• shared_ciphers()

• compression()

• pending()

• do_handshake()

• verify_client_post_handshake()

• unwrap()

• get_channel_binding()

• version()

По сравнению с SSLSocket у этого объекта отсутствуют следующие характеристики:

• Любая форма сетевого ввода-вывода; recv() и send() читают и записывают только в базовые буферы MemoryBIO.

• Не существует механизма do_handshake_on_connect. Вы всегда должны вручную вызывать do_handshake() для начала квитирования.

• Обработка suppress_ragged_eofs отсутствует. Все условия конца файла, нарушающие протокол, сообщаются через исключение SSLEOFError.

• Вызов метода unwrap() ничего не возвращает, в отличие от SSL-сокета, где он возвращает базовый сокет.

• Обратный вызов server_name_callback, переданный в SSLContext.set_servername_callback(), получит в качестве первого параметра экземпляр SSLObject вместо экземпляра SSLSocket.

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

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

• Вызов wrap_bio() на уровне модуля отсутствует, как в случае с wrap_socket(). SSLObject всегда создается через SSLContext.

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

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

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