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

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

import socket
import ssl

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

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

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

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

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

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

SSL-сокеты

class ssl.SSLSocket(socket.socket)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

SSLSocket.write(buf)

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

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

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

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

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

SSLSocket.do_handshake()

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

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

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

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

SSLSocket.getpeercert(binary_form=False)

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

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

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

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

Примечание

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

Изменено в версии 3.9: Строки IPv6-адресов больше не содержат завершающий символ новой строки.

SSLSocket.cipher()

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

SSLSocket.shared_ciphers()

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

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

SSLSocket.compression()

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

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

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

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

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

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

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

SSLSocket.selected_alpn_protocol()

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

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

SSLSocket.selected_npn_protocol()

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

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

Устарело с версии 3.10: NPN заменён ALPN

SSLSocket.unwrap()

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

SSLSocket.verify_client_post_handshake()

Запрашивает пострукопожатную аутентификацию (PHA) у клиента TLS 1.3. PHA можно инициировать только для соединения TLS 1.3 с серверного сокета после начального TLS-рукопожатия и при включённой PHA с обеих сторон; см. SSLContext.post_handshake_auth.

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

Если не выполнено какое-либо предварительное условие (например, используется не TLS 1.3 или PHA не включена), вызывается исключение SSLError.

Примечание

Доступно только при использовании OpenSSL 1.1.1 и включённого TLS 1.3. Если TLS 1.3 не поддерживается, метод вызывает NotImplementedError.

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

SSLSocket.version()

Возвращает строку с фактической версией протокола SSL, согласованной для соединения, или None, если защищённое соединение не установлено. На момент написания возможны такие возвращаемые значения: "SSLv2", "SSLv3", "TLSv1", "TLSv1.1" и "TLSv1.2". В новых версиях OpenSSL могут быть определены дополнительные значения.

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

SSLSocket.pending()

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

SSLSocket.context

Объект SSLContext, с которым связан этот SSL-сокет. Если 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 без аргумента protocol устарело. В будущем для класса контекста потребуется протокол PROTOCOL_TLS_CLIENT или PROTOCOL_TLS_SERVER.

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

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

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 может быть функцией, которая вызывается для получения пароля, необходимого для расшифровки закрытого ключа. Она будет вызвана, только если закрытый ключ зашифрован и требуется пароль. Функция вызывается без аргументов и должна возвращать строку, bytes или bytearray. Если возвращаемое значение является строкой, перед использованием для расшифровки ключа оно будет закодировано в UTF-8. Также в качестве аргумента password можно непосредственно передать строку, bytes или bytearray. Аргумент игнорируется, если закрытый ключ не зашифрован и пароль не требуется.

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

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

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

SSLContext.load_default_certs(purpose=Purpose.SERVER_AUTH)

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

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

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

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

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

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

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

Строка capath, если она указана, содержит путь к каталогу с несколькими сертификатами CA в формате PEM, организованными в соответствии со специфичной для OpenSSL структурой.

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

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

SSLContext.get_ca_certs(binary_form=False)

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

Примечание

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

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

SSLContext.get_ciphers()

Возвращает список включённых шифров. Список отсортирован по приоритету шифров. См. SSLContext.set_ciphers().

Пример:

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

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

SSLContext.set_default_verify_paths()

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

SSLContext.set_ciphers(ciphers)

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

Примечание

После установления соединения метод SSLSocket.cipher() SSL-сокетов возвращает выбранный в данный момент шифр.

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

SSLContext.set_alpn_protocols(protocols)

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

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

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

SSLContext.set_npn_protocols(protocols)

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

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

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

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

SSLContext.sni_callback

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

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

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

Обычно эту функцию обратного вызова используют, чтобы заменить атрибут SSLSocket.context объекта ssl.SSLSocket новым объектом типа 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.

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

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

SSLContext.set_servername_callback(server_name_callback)

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

Если при декодировании имени сервера возникает ошибка, TLS-соединение завершится фатальным предупреждением TLS ALERT_DESCRIPTION_INTERNAL_ERROR, отправленным клиенту.

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

SSLContext.load_dh_params(dhfile)

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

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

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

SSLContext.set_ecdh_curve(curve_name)

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

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

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

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

См. также

SSL/TLS и совершенная прямая секретность

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

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

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

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

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

Для клиентских соединений необязательный параметр server_hostname задаёт имя хоста службы, к которой выполняется подключение. Благодаря этому один сервер может обслуживать несколько служб на основе SSL с разными сертификатами — почти так же, как виртуальные хосты HTTP. Если server_side имеет значение true, указание server_hostname вызывает исключение ValueError.

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

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

Параметр session см. в описании session.

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

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

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

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

SSLContext.sslsocket_class

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

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

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

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

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

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

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

SSLContext.sslobject_class

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

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

SSLContext.session_stats()

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

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

SSLContext.check_hostname

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

Пример:

import socket, ssl

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

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

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

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

SSLContext.keylog_filename

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

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

SSLContext.maximum_version

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

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

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

SSLContext.minimum_version

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

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

SSLContext.num_tickets

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

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

SSLContext.options

Целое число, представляющее набор параметров SSL, включенных для этого контекста. По умолчанию установлено значение OP_ALL, но можно указать другие параметры, например OP_NO_SSLv2, объединив их побитовой операцией 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. Фактический обмен сертификатом клиента откладывается до вызова SSLSocket.verify_client_post_handshake() и выполнения операций ввода-вывода.

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

SSLContext.protocol

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

SSLContext.hostname_checks_common_name

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

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

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

SSLContext.security_level

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

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

SSLContext.verify_flags

Флаги операций проверки сертификатов. Можно задать флаги, например VERIFY_CRL_CHECK_LEAF, объединив их побитовой операцией 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) — это кодировка base64, заключенная между строкой заголовка и строкой завершения:

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

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

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

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

Примеры

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

>>> context = ssl.create_default_context()

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

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

>>> cert = conn.getpeercert()

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

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

import socket, ssl

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

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

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

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

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

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

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

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

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

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

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

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

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

Поддержка Memory BIO

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

• обработка протокола SSL
• сетевой ввод-вывод

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

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

class ssl.SSLObject

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

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

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

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

• context
• server_side
• server_hostname
• session
• session_reused
• read()
• write()
• getpeercert()
• 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.
• В отличие от SSL-сокета, вызов метода unwrap() ничего не возвращает; SSL-сокет возвращает базовый сокет.
• В качестве первого параметра обратный вызов server_name_callback, переданный в SSLContext.set_servername_callback(), получает экземпляр SSLObject, а не экземпляр SSLSocket.

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

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

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

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

class ssl.MemoryBIO

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

pending

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

eof

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

read(n=-1)

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

write(buf)

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

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

write_eof()

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

Сеанс SSL

class ssl.SSLSession

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

id

time

timeout

ticket_lifetime_hint

has_ticket

Соображения безопасности

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

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

TLS 1.3

Протокол TLS 1.3 работает несколько иначе, чем предыдущие версии TLS/SSL. Некоторые новые возможности TLS 1.3 пока недоступны.

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