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 должен быть объектом, поддерживающим интерфейс buffer.

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

Поскольку в любой момент возможно повторное согласование, вызов 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.

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')¶

Получает данные привязки канала для текущего соединения в виде объекта bytes. Возвращает None, если соединение не установлено или подтверждение связи не было завершено.

Параметр cb_type позволяет выбрать желаемый тип привязки канала. Допустимые типы привязки канала перечислены в списке CHANNEL_BINDING_TYPES. В настоящее время поддерживается только привязка канала «tls-unique», определяемая параметром RFC 5929. ValueError будет поднят, если запрашивается неподдерживаемый тип привязки канала.

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

SSLSocket.selected_alpn_protocol()¶

Возвращает протокол, который был выбран во время подтверждения связи по протоколу TLS. Если SSLContext.set_alpn_protocols() не был вызван, если другая сторона не поддерживает ALPN, если этот сокет не поддерживает ни один из предложенных клиентом протоколов или если подтверждение связи еще не произошло, возвращается None.

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

SSLSocket.selected_npn_protocol()¶

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

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

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

SSLSocket.unwrap()¶

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

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-label ("xn--pythn-mua.org"), вместо формы U-label ("pythön.org").

SSLSocket.session¶

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

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

SSLSocket.session_reused¶

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

Контексты SSL¶

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

class ssl.SSLContext(protocol=None)¶

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

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

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

Сноски

См.также

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

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

Не рекомендуется, начиная с версии 3.10: Аргумент SSLContext без протокола считается устаревшим. В будущем для класса context потребуется либо протокол 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, содержащему сертификат, а также любое количество сертификатов CA, необходимых для установления подлинности сертификата. Строка keyfile, если она присутствует, должна указывать на файл, содержащий закрытый ключ. В противном случае закрытый ключ также будет взят из certfile. Смотрите обсуждение Сертификаты для получения дополнительной информации о том, как сертификат хранится в файле certfile.

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

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

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

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

SSLContext.load_default_certs(purpose=Purpose.SERVER_AUTH)¶

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

Флаг назначение указывает, какие сертификаты 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 specific layout.

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

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

SSLContext.get_ca_certs(binary_form=False)¶

Получите список загруженных сертификатов «центра сертификации» (CA). Если параметр binary_form равен False, то каждая запись в списке представляет собой dict, аналогичный результату 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 cipher list format. Если ни один шифр не может быть выбран (поскольку параметры времени компиляции или другая конфигурация запрещают использование всех указанных шифров), будет поднят SSLError.

Примечание

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

Наборы шифров 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-сервером сообщения Hello handshake от клиента TLS, когда клиент TLS задает указание имени сервера. Механизм указания имени сервера указан в RFC 6066 разделе 3 «Указание имени сервера».

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

Функция обратного вызова будет вызвана с тремя аргументами; первым будет ssl.SSLSocket, вторым - строка, представляющая имя сервера, с которым клиент намеревается связаться (или None, если приветствие клиента TLS не содержит имени сервера). и третий аргумент - это исходный SSLContext. Аргументом имени сервера является текст. Для интернационализированного доменного имени имя сервера представляет собой IDN-метку ("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() для сокета. Для сокетов на стороне сервера, если у сокета нет удаленного однорангового узла, предполагается, что он является прослушивающим сокетом, и для клиентских подключений, принятых с помощью метода accept(), автоматически выполняется передача SSL на стороне сервера. Метод может вызывать 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.

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

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

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

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

SSLContext.sslsocket_class¶

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

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

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

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

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

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

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

SSLContext.sslobject_class¶

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

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

SSLContext.session_stats()¶

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

>>> 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 в файл keylog всякий раз, когда генерируется или принимается информация о ключах. Файл журнала ключей предназначен только для целей отладки. Формат файла определяется NSS и используется многими анализаторами трафика, такими как Wireshark. Файл журнала открывается только в режиме добавления. Записи синхронизируются между потоками, но не между процессами.

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

SSLContext.maximum_version¶

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

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

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

SSLContext.minimum_version¶

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

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

SSLContext.num_tickets¶

Позволяет управлять количеством заявок на сеанс TLS 1.3 в контексте PROTOCOL_TLS_SERVER. Этот параметр не влияет на подключения по протоколам TLS 1.0-1.2.

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

SSLContext.options¶

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

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

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

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

SSLContext.post_handshake_auth¶

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

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

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

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

SSLContext.protocol¶

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

SSLContext.hostname_checks_common_name¶

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

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

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

SSLContext.security_level¶

Целое число, представляющее 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>

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

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

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

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

Python использует файлы для хранения сертификатов. Они должны быть отформатированы как «PEM» (см. RFC 1422), что представляет собой форму в кодировке base64, заключенную в строку верхнего и нижнего колонтитула:

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

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

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

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

Примеры¶

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

>>> context = ssl.create_default_context()

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

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

>>> cert = conn.getpeercert()

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

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

import socket, ssl

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

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

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

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

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

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

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

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

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

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

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

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

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

Биологическая поддержка памяти¶

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

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

• Сетевой ввод-вывод

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 и привяжет его к паре BIOs. Входящий 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, если потребуется больше данных, чем доступно для входящей биографии.

• Здесь нет вызова wrap_bio() на уровне модуля, как для wrap_socket(). SSLObject всегда создается с помощью SSLContext.

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

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

class ssl.MemoryBIO¶

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

pending¶

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

eof¶

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

read(n=-1)¶

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

write(buf)¶

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

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