`ssl` — TLS/SSL wrapper for socket objects¶

Вихідний код: Lib/ssl.py

Цей модуль надає доступ до шифрування транспортного рівня безпеки (часто відомого як «рівень захищених сокетів») і засобів автентифікації однорангових мережевих сокетів як на стороні клієнта, так і на стороні сервера. Цей модуль використовує бібліотеку OpenSSL. Він доступний у всіх сучасних системах Unix, Windows, macOS і, ймовірно, на додаткових платформах, якщо на цій платформі встановлено OpenSSL.

Примітка

Some behavior may be platform dependent, since calls are made to the operating system socket APIs. The installed version of OpenSSL may also cause variations in behavior. For example, TLSv1.3 comes with OpenSSL version 1.1.1.

Попередження

Не використовуйте цей модуль, не прочитавши Міркування безпеки. Це може призвести до помилкового відчуття безпеки, оскільки стандартні параметри модуля ssl не обов’язково підходять для вашої програми.

Availability: not WASI.

This module does not work or is not available on WebAssembly. See WebAssembly platforms for more information.

У цьому розділі описано об’єкти та функції модуля ssl; для отримання більш загальної інформації про TLS, SSL і сертифікати, читач буде направлено до документів у розділі «Див. також» внизу.

This module provides a class, ssl.SSLSocket, which is derived from the socket.socket type, and provides a socket-like wrapper that also encrypts and decrypts the data going over the socket with SSL. It supports additional methods such as getpeercert(), which retrieves the certificate of the other side of the connection, cipher(), which retrieves the cipher being used for the secure connection or get_verified_chain(), get_unverified_chain() which retrieves certificate chain.

Для складніших програм клас ssl.SSLContext допомагає керувати налаштуваннями та сертифікатами, які потім можуть бути успадковані сокетами SSL, створеними за допомогою методу SSLContext.wrap_socket().

Змінено в версії 3.5.3: Оновлено для підтримки зв’язування з OpenSSL 1.1.0

Змінено в версії 3.6: OpenSSL 0.9.8, 1.0.0 і 1.0.1 застаріли та більше не підтримуються. У майбутньому модуль ssl потребуватиме принаймні OpenSSL 1.0.2 або 1.1.0.

Змінено в версії 3.10: PEP 644 реалізовано. Модуль ssl вимагає OpenSSL 1.1.1 або новішої версії.

Використання застарілих констант і функцій призводить до попереджень про застаріле.

Функції, константи та винятки¶

Створення розетки¶

Instances of SSLSocket must be created using the SSLContext.wrap_socket() method. The helper function create_default_context() returns a new context with secure default settings.

Приклад клієнтського сокета з контекстом за замовчуванням і подвійним стеком IPv4/IPv6:

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())

Приклад клієнтського сокета з власним контекстом і IPv4:

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())

Приклад серверного сокета, який прослуховує локальний хост IPv4:

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()
        ...

Створення контексту¶

Зручна функція допомагає створювати об’єкти SSLContext для звичайних цілей.

ssl.create_default_context(purpose=Purpose.SERVER_AUTH, cafile=None, capath=None, cadata=None)¶

Повертає новий об’єкт SSLContext із налаштуваннями за замовчуванням для заданої цілі. Параметри вибираються модулем ssl і зазвичай представляють вищий рівень безпеки, ніж під час безпосереднього виклику конструктора SSLContext.

cafile, capath, cadata представляють додаткові сертифікати ЦС, яким можна довіряти для перевірки сертифікатів, як у SSLContext.load_verify_locations(). Якщо всі три параметри None, ця функція може натомість довіряти стандартним сертифікатам ЦС системи.

The settings are: PROTOCOL_TLS_CLIENT or PROTOCOL_TLS_SERVER, OP_NO_SSLv2, and OP_NO_SSLv3 with high encryption cipher suites without RC4 and without unauthenticated cipher suites. Passing SERVER_AUTH as purpose sets verify_mode to CERT_REQUIRED and either loads CA certificates (when at least one of cafile, capath or cadata is given) or uses SSLContext.load_default_certs() to load default CA certificates.

Якщо підтримується keylog_filename і встановлено змінну середовища SSLKEYLOGFILE, create_default_context() вмикає журналювання ключів.

The default settings for this context include VERIFY_X509_PARTIAL_CHAIN and VERIFY_X509_STRICT. These make the underlying OpenSSL implementation behave more like a conforming implementation of RFC 5280, in exchange for a small amount of incompatibility with older X.509 certificates.

Примітка

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

Якщо вашій програмі потрібні певні налаштування, ви повинні створити SSLContext і застосувати налаштування самостійно.

Примітка

Якщо ви виявите, що коли певні старіші клієнти чи сервери намагаються підключитися за допомогою SSLContext, створеного цією функцією, вони отримують помилку «Невідповідність протоколу чи набору шифрів», можливо, вони підтримують лише SSL3.0, який ця функція виключає використання OP_NO_SSLv3. SSL3.0 широко вважається повністю зламаним. Якщо ви все ще бажаєте продовжувати використовувати цю функцію, але все ще дозволяєте підключення SSL 3.0, ви можете повторно ввімкнути їх за допомогою:

ctx = ssl.create_default_context(Purpose.CLIENT_AUTH)
ctx.options &= ~ssl.OP_NO_SSLv3

Примітка

This context enables VERIFY_X509_STRICT by default, which may reject pre-RFC 5280 or malformed certificates that the underlying OpenSSL implementation otherwise would accept. While disabling this is not recommended, you can do so using:

ctx = ssl.create_default_context()
ctx.verify_flags &= ~ssl.VERIFY_X509_STRICT

Added in version 3.4.

Змінено в версії 3.4.4: RC4 було видалено з рядка шифру за замовчуванням.

Змінено в версії 3.6: ChaCha20/Poly1305 додано до рядка шифру за замовчуванням.

3DES було видалено з рядка шифру за замовчуванням.

Змінено в версії 3.8: Додано підтримку реєстрації ключів у SSLKEYLOGFILE.

Змінено в версії 3.10: Контекст тепер використовує протокол PROTOCOL_TLS_CLIENT або PROTOCOL_TLS_SERVER замість загального PROTOCOL_TLS.

Змінено в версії 3.13: The context now uses VERIFY_X509_PARTIAL_CHAIN and VERIFY_X509_STRICT in its default verify flags.

Винятки¶

exception ssl.SSLError¶

Піднято, щоб повідомити про помилку базової реалізації SSL (наразі надається бібліотекою OpenSSL). Це означає певну проблему на рівні шифрування та автентифікації вищого рівня, який накладається на базове мережеве з’єднання. Ця помилка є підтипом OSError. Код помилки та повідомлення екземплярів SSLError надає бібліотека OpenSSL.

Змінено в версії 3.3: SSLError раніше був підтипом socket.error.

library¶: Рядкова мнемоніка, що позначає субмодуль OpenSSL, у якому сталася помилка, наприклад SSL, PEM або X509. Діапазон можливих значень залежить від версії OpenSSL.

Added in version 3.3.

reason¶: Рядок мнемоніки, що вказує причину цієї помилки, наприклад CERTIFICATE_VERIFY_FAILED. Діапазон можливих значень залежить від версії OpenSSL.

Added in version 3.3.

exception ssl.SSLZeroReturnError¶: Підклас SSLError викликається під час спроби читання або запису, а SSL-з’єднання було закрито. Зауважте, що це не означає, що основний транспорт (читай TCP) закрито.

Added in version 3.3.

exception ssl.SSLWantReadError¶: Підклас SSLError, викликаний неблокуючим SSL-сокетом під час спроби прочитати або записати дані, але для виконання запиту потрібно отримати більше даних базовим транспортом TCP.

Added in version 3.3.

exception ssl.SSLWantWriteError¶: Підклас SSLError, викликаний неблокуючим SSL-сокетом під час спроби прочитати або записати дані, але більше даних потрібно надіслати базовим транспортом TCP, перш ніж запит буде виконано.

Added in version 3.3.

exception ssl.SSLSyscallError¶: Підклас SSLError викликається, коли виникла системна помилка під час спроби виконати операцію на SSL-сокеті. На жаль, немає простого способу перевірити оригінальний номер errno.

Added in version 3.3.

exception ssl.SSLEOFError¶: Підклас SSLError викликається, коли з’єднання SSL було раптово розірвано. Як правило, ви не повинні намагатися повторно використовувати базовий транспорт, коли виникає ця помилка.

Added in version 3.3.

exception ssl.SSLCertVerificationError¶

Підклас SSLError викликається, коли не вдається перевірити сертифікат.

Added in version 3.7.

verify_code¶: Числовий номер помилки, який позначає помилку підтвердження.

verify_message¶: Зрозумілий для людини рядок помилки перевірки.

exception ssl.CertificateError¶: Псевдонім для SSLCertVerificationError.

Змінено в версії 3.7: Винятком тепер є псевдонім для SSLCertVerificationError.

Випадкова генерація¶

ssl.RAND_bytes(num)¶

Повертає num криптографічно надійних псевдовипадкових байтів. Викликає SSLError, якщо PRNG не було заповнено достатньою кількістю даних або якщо операція не підтримується поточним методом RAND. RAND_status() можна використовувати для перевірки статусу PRNG, а RAND_add() можна використовувати для заповнення PRNG.

Майже для всіх програм os.urandom() є кращим.

Прочитайте статтю Вікіпедії Криптографічно захищений генератор псевдовипадкових чисел (CSPRNG), щоб дізнатися про вимоги до криптографічно надійного генератора.

Added in version 3.3.

ssl.RAND_status()¶: Повертає True, якщо генератор псевдовипадкових чисел SSL заповнено достатньою випадковістю, і False в іншому випадку. Ви можете використовувати ssl.RAND_egd() і ssl.RAND_add(), щоб збільшити випадковість генератора псевдовипадкових чисел.

ssl.RAND_add(bytes, entropy)¶: Mix the given bytes into the SSL pseudo-random number generator. The parameter entropy (a float) is a lower bound on the entropy contained in string (so you can always use 0.0). See RFC 1750 for more information on sources of entropy.

Змінено в версії 3.5: Записуваний bytes-like object тепер приймається.

Обробка сертифікатів¶

ssl.cert_time_to_seconds(cert_time)¶

Повертає час у секундах з епохи, враховуючи рядок cert_time, що представляє дату «notBefore» або «notAfter» із сертифіката в "%b %d %H:%M:%S %Y %Z" формат strptime (C локаль).

Ось приклад:

>>> import ssl
>>> timestamp = ssl.cert_time_to_seconds("Jan  5 09:34:43 2018 GMT")
>>> timestamp  
1515144883
>>> from datetime import datetime
>>> print(datetime.utcfromtimestamp(timestamp))  
2018-01-05 09:34:43

Дати «notBefore» або «notAfter» мають використовувати GMT (RFC 5280).

Змінено в версії 3.5: Інтерпретуйте введений час як час у UTC, як зазначено часовим поясом «GMT» у вхідному рядку. Раніше використовувався місцевий часовий пояс. Повертає ціле число (без часток секунди у форматі введення)

ssl.get_server_certificate(addr, ssl_version=PROTOCOL_TLS_CLIENT, ca_certs=None[, timeout])¶: Given the address addr of an SSL-protected server, as a (hostname, port-number) pair, fetches the server’s certificate, and returns it as a PEM-encoded string. If ssl_version is specified, uses that version of the SSL protocol to attempt to connect to the server. If ca_certs is specified, it should be a file containing a list of root certificates, the same format as used for the cafile parameter in SSLContext.load_verify_locations(). The call will attempt to validate the server certificate against that set of root certificates, and will fail if the validation attempt fails. A timeout can be specified with the timeout parameter.

Змінено в версії 3.3: Тепер ця функція сумісна з IPv6.

Змінено в версії 3.5: Стандартну ssl_version змінено з PROTOCOL_SSLv3 на PROTOCOL_TLS для максимальної сумісності з сучасними серверами.

Змінено в версії 3.10: Додано параметр timeout.

ssl.DER_cert_to_PEM_cert(DER_cert_bytes)¶: Надано сертифікат як DER-кодований блок байтів, повертає PEM-кодовану рядкову версію того самого сертифіката.

ssl.PEM_cert_to_DER_cert(PEM_cert_string)¶: Надано сертифікат як рядок ASCII PEM, повертає закодовану DER послідовність байтів для того самого сертифіката.

ssl.get_default_verify_paths()¶

Повертає іменований кортеж із шляхами до cafile і capath OpenSSL за замовчуванням. Шляхи такі самі, як і SSLContext.set_default_verify_paths(). Поверненим значенням є named tuple DefaultVerifyPaths:

cafile - визначений шлях до cafile або None, якщо файл не існує,
capath - дозволений шлях до capath або None, якщо каталог не існує,
openssl_cafile_env - ключ середовища OpenSSL, який вказує на cafile,
openssl_cafile - жорстко закодований шлях до cafile,
openssl_capath_env - ключ середовища OpenSSL, який вказує на capath,
openssl_capath - жорстко закодований шлях до каталогу capath

Added in version 3.4.

ssl.enum_certificates(store_name)¶

Отримати сертифікати зі сховища сертифікатів системи Windows. store_name може бути одним із CA, ROOT або MY. Windows також може надавати додаткові сховища сертифікатів.

Функція повертає список кортежів (cert_bytes, encoding_type, trust). Encoding_type визначає кодування cert_bytes. Це або x509_asn для даних X.509 ASN.1, або pkcs_7_asn для даних PKCS#7 ASN.1. Trust визначає призначення сертифіката як набір OIDS або точно True, якщо сертифікат є надійним для всіх цілей.

Приклад:

>>> ssl.enum_certificates("CA")
[(b'data...', 'x509_asn', {'1.3.6.1.5.5.7.3.1', '1.3.6.1.5.5.7.3.2'}),
 (b'data...', 'x509_asn', True)]

Availability: Windows.

Added in version 3.4.

ssl.enum_crls(store_name)¶

Отримати CRL із сховища системних сертифікатів Windows. store_name може бути одним із CA, ROOT або MY. Windows також може надавати додаткові сховища сертифікатів.

Функція повертає список кортежів (cert_bytes, encoding_type, trust). Encoding_type визначає кодування cert_bytes. Це або x509_asn для даних X.509 ASN.1, або pkcs_7_asn для даних PKCS#7 ASN.1.

Availability: Windows.

Added in version 3.4.

Константи¶

Усі константи тепер є колекціями enum.IntEnum або enum.IntFlag.

Added in version 3.6.

ssl.CERT_NONE¶

Possible value for SSLContext.verify_mode. Except for PROTOCOL_TLS_CLIENT, it is the default mode. With client-side sockets, just about any cert is accepted. Validation errors, such as untrusted or expired cert, are ignored and do not abort the TLS/SSL handshake.

У режимі сервера від клієнта не запитується сертифікат, тому клієнт не надсилає жодного сертифіката для автентифікації клієнта.

Дивіться обговорення Міркування безпеки нижче.

ssl.CERT_OPTIONAL¶

Possible value for SSLContext.verify_mode. In client mode, CERT_OPTIONAL has the same meaning as CERT_REQUIRED. It is recommended to use CERT_REQUIRED for client-side sockets instead.

У режимі сервера клієнту надсилається запит на сертифікат клієнта. Клієнт може або проігнорувати запит, або надіслати сертифікат, щоб виконати автентифікацію клієнта за допомогою TLS. Якщо клієнт вирішує надіслати сертифікат, він перевіряється. Будь-яка помилка перевірки негайно перериває рукостискання TLS.

Use of this setting requires a valid set of CA certificates to be passed to SSLContext.load_verify_locations().

ssl.CERT_REQUIRED¶

Possible value for SSLContext.verify_mode. In this mode, certificates are required from the other side of the socket connection; an SSLError will be raised if no certificate is provided, or if its validation fails. This mode is not sufficient to verify a certificate in client mode as it does not match hostnames. check_hostname must be enabled as well to verify the authenticity of a cert. PROTOCOL_TLS_CLIENT uses CERT_REQUIRED and enables check_hostname by default.

З серверним сокетом цей режим забезпечує обов’язкову автентифікацію клієнта за допомогою TLS. Запит на сертифікат клієнта надсилається клієнту, і клієнт повинен надати дійсний і надійний сертифікат.

Use of this setting requires a valid set of CA certificates to be passed to SSLContext.load_verify_locations().

class ssl.VerifyMode¶: enum.IntEnum колекція констант CERT_*.

Added in version 3.6.

ssl.VERIFY_DEFAULT¶: Можливе значення для SSLContext.verify_flags. У цьому режимі списки відкликаних сертифікатів (CRL) не перевіряються. За замовчуванням OpenSSL не вимагає і не перевіряє CRL.

Added in version 3.4.

ssl.VERIFY_CRL_CHECK_LEAF¶: Можливе значення для SSLContext.verify_flags. У цьому режимі перевіряється лише одноранговий сертифікат, але не перевіряються проміжні сертифікати ЦС. Для режиму потрібен дійсний CRL, підписаний видавцем однорангового сертифіката (його прямим предком CA). Якщо не було завантажено відповідний CRL з SSLContext.load_verify_locations, перевірка не вдасться.

Added in version 3.4.

ssl.VERIFY_CRL_CHECK_CHAIN¶: Можливе значення для SSLContext.verify_flags. У цьому режимі перевіряються CRL усіх сертифікатів у ланцюжку однорангових сертифікатів.

Added in version 3.4.

ssl.VERIFY_X509_STRICT¶: Можливе значення для SSLContext.verify_flags для вимкнення обхідних шляхів для пошкоджених сертифікатів X.509.

Added in version 3.4.

ssl.VERIFY_ALLOW_PROXY_CERTS¶: Можливе значення для SSLContext.verify_flags для ввімкнення перевірки сертифіката проксі.

Added in version 3.10.

ssl.VERIFY_X509_TRUSTED_FIRST¶: Можливе значення для SSLContext.verify_flags. Він наказує OpenSSL віддавати перевагу надійним сертифікатам під час побудови ланцюжка довіри для перевірки сертифіката. Цей прапорець увімкнено за замовчуванням.

Added in version 3.4.4.

ssl.VERIFY_X509_PARTIAL_CHAIN¶: Можливе значення для SSLContext.verify_flags. Він наказує OpenSSL приймати проміжні ЦС у довірчому сховищі, щоб вони розглядалися як прив’язки довіри, так само, як і самопідписані кореневі сертифікати ЦС. Це дає змогу довіряти сертифікатам, виданим проміжним ЦС, не довіряючи кореневому ЦС предка.

Added in version 3.10.

class ssl.VerifyFlags¶: enum.IntFlag колекція констант VERIFY_*.

Added in version 3.6.

ssl.PROTOCOL_TLS¶: Вибирає найвищу версію протоколу, яку підтримують як клієнт, так і сервер. Незважаючи на назву, ця опція може вибрати як протоколи «SSL», так і «TLS».

Added in version 3.6.

Застаріло починаючи з версії 3.10: Клієнтам і серверам TLS потрібні різні параметри за замовчуванням для безпечного зв’язку. Загальна константа протоколу TLS застаріла на користь PROTOCOL_TLS_CLIENT і PROTOCOL_TLS_SERVER.

ssl.PROTOCOL_TLS_CLIENT¶: Автоматичне узгодження найвищої версії протоколу, яку підтримують як клієнт, так і сервер, і налаштування контекстних підключень на стороні клієнта. Протокол вмикає CERT_REQUIRED і check_hostname за умовчанням.

Added in version 3.6.

ssl.PROTOCOL_TLS_SERVER¶: Автоматичне узгодження найвищої версії протоколу, яку підтримують як клієнт, так і сервер, і налаштування контекстних підключень на стороні сервера.

Added in version 3.6.

ssl.PROTOCOL_SSLv23¶: Псевдонім для PROTOCOL_TLS.

Застаріло починаючи з версії 3.6: Натомість використовуйте PROTOCOL_TLS.

ssl.PROTOCOL_SSLv3¶

Вибирає SSL версії 3 як протокол шифрування каналу.

Цей протокол недоступний, якщо OpenSSL скомпільовано з опцією no-ssl3.

Попередження

SSL версії 3 небезпечний. Його використання вкрай не рекомендується.

Застаріло починаючи з версії 3.6: OpenSSL не підтримує всі протоколи для окремих версій. Замість цього використовуйте протокол за замовчуванням PROTOCOL_TLS_SERVER або PROTOCOL_TLS_CLIENT з SSLContext.minimum_version і SSLContext.maximum_version.

ssl.PROTOCOL_TLSv1¶: Вибирає TLS версії 1.0 як протокол шифрування каналу.

Застаріло починаючи з версії 3.6: OpenSSL не підтримує всі протоколи для окремих версій.

ssl.PROTOCOL_TLSv1_1¶: Вибирає TLS версії 1.1 як протокол шифрування каналу. Доступно лише з openssl версії 1.0.1+.

Added in version 3.4.

Застаріло починаючи з версії 3.6: OpenSSL не підтримує всі протоколи для окремих версій.

ssl.PROTOCOL_TLSv1_2¶: Вибирає TLS версії 1.2 як протокол шифрування каналу. Доступно лише з openssl версії 1.0.1+.

Added in version 3.4.

Застаріло починаючи з версії 3.6: OpenSSL не підтримує всі протоколи для окремих версій.

ssl.OP_ALL¶: Дозволяє обійти різні помилки, наявні в інших реалізаціях SSL. Ця опція встановлена за замовчуванням. Він не обов’язково встановлює ті самі позначки, що й константа SSL_OP_ALL OpenSSL.

Added in version 3.2.

ssl.OP_NO_SSLv2¶: Запобігає підключенню SSLv2. Цей параметр застосовний лише в поєднанні з PROTOCOL_TLS. Це запобігає вибору одноранговими вузлами SSLv2 як версії протоколу.

Added in version 3.2.

Застаріло починаючи з версії 3.6: SSLv2 застарів

ssl.OP_NO_SSLv3¶: Запобігає підключенню SSLv3. Цей параметр застосовний лише в поєднанні з PROTOCOL_TLS. Це запобігає вибору одноранговими вузлами SSLv3 як версії протоколу.

Added in version 3.2.

Застаріло починаючи з версії 3.6: SSLv3 застарів

ssl.OP_NO_TLSv1¶: Запобігає підключенню TLSv1. Цей параметр застосовний лише в поєднанні з PROTOCOL_TLS. Це запобігає вибору партнерами TLSv1 як версії протоколу.

Added in version 3.2.

Застаріло починаючи з версії 3.7: Опція застаріла з OpenSSL 1.1.0, замість неї використовуйте нові SSLContext.minimum_version і SSSLContext.maximum_version.

ssl.OP_NO_TLSv1_1¶: Запобігає підключенню TLSv1.1. Цей параметр застосовний лише в поєднанні з PROTOCOL_TLS. Це запобігає вибору одноранговими вузлами TLSv1.1 як версії протоколу. Доступно лише з openssl версії 1.0.1+.

Added in version 3.4.

Застаріло починаючи з версії 3.7: Опція застаріла з OpenSSL 1.1.0.

ssl.OP_NO_TLSv1_2¶: Запобігає підключенню TLSv1.2. Цей параметр застосовний лише в поєднанні з PROTOCOL_TLS. Це запобігає вибору одноранговими вузлами TLSv1.2 як версії протоколу. Доступно лише з openssl версії 1.0.1+.

Added in version 3.4.

Застаріло починаючи з версії 3.7: Опція застаріла з OpenSSL 1.1.0.

ssl.OP_NO_TLSv1_3¶: Запобігає підключенню TLSv1.3. Цей параметр застосовний лише в поєднанні з PROTOCOL_TLS. Це запобігає вибору одноранговими вузлами TLSv1.3 як версії протоколу. TLS 1.3 доступний з OpenSSL 1.1.1 або новішої версії. Якщо Python скомпільовано зі старішою версією OpenSSL, прапорець за замовчуванням має значення 0.

Added in version 3.6.3.

Застаріло починаючи з версії 3.7: The option is deprecated since OpenSSL 1.1.0. It was added to 2.7.15 and 3.6.3 for backwards compatibility with OpenSSL 1.0.2.

ssl.OP_NO_RENEGOTIATION¶

Вимкніть усі повторні узгодження в TLSv1.2 і попередніх версіях. Не надсилайте повідомлення HelloRequest і ігноруйте запити на повторне узгодження через ClientHello.

Ця опція доступна лише для OpenSSL 1.1.0h і пізніших версій.

Added in version 3.7.

ssl.OP_CIPHER_SERVER_PREFERENCE¶: Використовуйте параметри впорядкування шифрів сервера, а не клієнта. Цей параметр не впливає на клієнтські сокети та серверні сокети SSLv2.

Added in version 3.3.

ssl.OP_SINGLE_DH_USE¶: Prevents reuse of the same DH key for distinct SSL sessions. This improves forward secrecy but requires more computational resources. This option only applies to server sockets.

Added in version 3.3.

ssl.OP_SINGLE_ECDH_USE¶: Prevents reuse of the same ECDH key for distinct SSL sessions. This improves forward secrecy but requires more computational resources. This option only applies to server sockets.

Added in version 3.3.

ssl.OP_ENABLE_MIDDLEBOX_COMPAT¶

Надсилайте фіктивні повідомлення про зміну шифру (CCS) у рукостисканні TLS 1.3, щоб зробити з’єднання TLS 1.3 більш схожим на з’єднання TLS 1.2.

Ця опція доступна лише з OpenSSL 1.1.1 і новіших версій.

Added in version 3.8.

ssl.OP_NO_COMPRESSION¶: Вимкніть стиснення на каналі SSL. Це корисно, якщо протокол програми підтримує власну схему стиснення.

Added in version 3.3.

class ssl.Options¶: enum.IntFlag колекція констант OP_*.

ssl.OP_NO_TICKET¶: Заборонити стороні клієнта запитувати квиток сеансу.

Added in version 3.6.

ssl.OP_IGNORE_UNEXPECTED_EOF¶

Ігноруйте несподіване завершення з’єднань TLS.

Цей параметр доступний лише з OpenSSL 3.0.0 і пізніших версій.

Added in version 3.10.

ssl.OP_ENABLE_KTLS¶

Enable the use of the kernel TLS. To benefit from the feature, OpenSSL must have been compiled with support for it, and the negotiated cipher suites and extensions must be supported by it (a list of supported ones may vary by platform and kernel version).

Note that with enabled kernel TLS some cryptographic operations are performed by the kernel directly and not via any available OpenSSL Providers. This might be undesirable if, for example, the application requires all cryptographic operations to be performed by the FIPS provider.

Цей параметр доступний лише з OpenSSL 3.0.0 і пізніших версій.

Added in version 3.12.

ssl.OP_LEGACY_SERVER_CONNECT¶: Allow legacy insecure renegotiation between OpenSSL and unpatched servers only.

Added in version 3.12.

ssl.HAS_ALPN¶: Чи має бібліотека OpenSSL вбудовану підтримку розширення TLS Application-Layer Protocol Negotiation, як описано в RFC 7301.

Added in version 3.5.

ssl.HAS_NEVER_CHECK_COMMON_NAME¶: Чи має бібліотека OpenSSL вбудовану підтримку, яка не перевіряє загальне ім’я суб’єкта та SSLContext.hostname_checks_common_name, доступний для запису.

Added in version 3.7.

ssl.HAS_ECDH¶: Чи має бібліотека OpenSSL вбудовану підтримку для обміну ключами Діффі-Хеллмана на основі еліптичної кривої. Це має бути правдою, якщо цю функцію явно не вимкнув розповсюджувач.

Added in version 3.3.

ssl.HAS_SNI¶: Чи має бібліотека OpenSSL вбудовану підтримку розширення Індикація імені сервера (як визначено в RFC 6066).

Added in version 3.2.

ssl.HAS_NPN¶: Чи має бібліотека OpenSSL вбудовану підтримку Узгодження наступного протоколу, як описано в розділі Узгодження протоколу прикладного рівня. Якщо значення true, ви можете використовувати метод SSLContext.set_npn_protocols(), щоб повідомити, які протоколи ви хочете підтримувати.

Added in version 3.3.

ssl.HAS_SSLv2¶: Чи бібліотека OpenSSL має вбудовану підтримку протоколу SSL 2.0.

Added in version 3.7.

ssl.HAS_SSLv3¶: Чи має бібліотека OpenSSL вбудовану підтримку протоколу SSL 3.0.

Added in version 3.7.

ssl.HAS_TLSv1¶: Чи бібліотека OpenSSL має вбудовану підтримку протоколу TLS 1.0.

Added in version 3.7.

ssl.HAS_TLSv1_1¶: Чи має бібліотека OpenSSL вбудовану підтримку протоколу TLS 1.1.

Added in version 3.7.

ssl.HAS_TLSv1_2¶: Чи бібліотека OpenSSL має вбудовану підтримку протоколу TLS 1.2.

Added in version 3.7.

ssl.HAS_TLSv1_3¶: Чи має бібліотека OpenSSL вбудовану підтримку протоколу TLS 1.3.

Added in version 3.7.

ssl.HAS_PSK¶: Whether the OpenSSL library has built-in support for TLS-PSK.

Added in version 3.13.

ssl.CHANNEL_BINDING_TYPES¶: Список підтримуваних типів прив’язки каналу TLS. Рядки в цьому списку можна використовувати як аргументи для SSLSocket.get_channel_binding().

Added in version 3.3.

ssl.OPENSSL_VERSION¶

Рядок версії бібліотеки OpenSSL, завантажений інтерпретатором:

>>> ssl.OPENSSL_VERSION
'OpenSSL 1.0.2k  26 Jan 2017'

Added in version 3.2.

ssl.OPENSSL_VERSION_INFO¶

Кортеж із п’яти цілих чисел, що представляє інформацію про версію бібліотеки OpenSSL:

>>> ssl.OPENSSL_VERSION_INFO
(1, 0, 2, 11, 15)

Added in version 3.2.

ssl.OPENSSL_VERSION_NUMBER¶

Необроблений номер версії бібліотеки OpenSSL у вигляді одного цілого числа:

>>> ssl.OPENSSL_VERSION_NUMBER
268443839
>>> hex(ssl.OPENSSL_VERSION_NUMBER)
'0x100020bf'

Added in version 3.2.

ssl.ALERT_DESCRIPTION_HANDSHAKE_FAILURE¶

ssl.ALERT_DESCRIPTION_INTERNAL_ERROR¶

ALERT_DESCRIPTION_*

Описи сповіщень від RFC 5246 та інших. Реєстр сповіщень IANA TLS містить цей список і посилання на RFC, де визначено їх значення.

Використовується як значення, що повертається функцією зворотного виклику в SSLContext.set_servername_callback().

Added in version 3.4.

class ssl.AlertDescription¶: enum.IntEnum колекція констант ALERT_DESCRIPTION_*.

Added in version 3.6.

Purpose.SERVER_AUTH¶: Опція для create_default_context() і SSLContext.load_default_certs(). Це значення вказує на те, що контекст можна використовувати для автентифікації веб-серверів (отже, він використовуватиметься для створення сокетів на стороні клієнта).

Added in version 3.4.

Purpose.CLIENT_AUTH¶: Опція для create_default_context() і SSLContext.load_default_certs(). Це значення вказує на те, що контекст можна використовувати для автентифікації веб-клієнтів (отже, він використовуватиметься для створення сокетів на стороні сервера).

Added in version 3.4.

class ssl.SSLErrorNumber¶: enum.IntEnum колекція констант SSL_ERROR_*.

Added in version 3.6.

class ssl.TLSVersion¶: enum.IntEnum колекція версій SSL і TLS для SSLContext.maximum_version і SSLContext.minimum_version.

Added in version 3.7.

TLSVersion.MINIMUM_SUPPORTED¶

TLSVersion.MAXIMUM_SUPPORTED¶: Мінімальна або максимальна підтримувана версія SSL або TLS. Це магічні константи. Їх значення не відображають найнижчу та найвищу доступні версії TLS/SSL.

TLSVersion.SSLv3¶

TLSVersion.TLSv1¶

TLSVersion.TLSv1_1¶

TLSVersion.TLSv1_2¶

TLSVersion.TLSv1_3¶: SSL 3.0 до TLS 1.3.

Застаріло починаючи з версії 3.10: Усі члени TLSVersion, крім TLSVersion.TLSv1_2 і TLSVersion.TLSv1_3, застаріли.

SSL-сокети¶

class ssl.SSLSocket(socket.socket)¶

SSL-сокети надають такі методи Об’єкти Socket:

accept()
bind()
close()
connect()
detach()
fileno()
getpeername(), getsockname()
getsockopt(), setsockopt()
gettimeout(), settimeout(), setblocking()
listen()
makefile()
recv(), recv_into() (but passing a non-zero flags argument is not allowed)
send(), sendall() (with the same limitation)
sendfile() (but os.sendfile will be used for plain-text sockets only, else send() will be used)
shutdown()

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

Примірники SSLSocket повинні бути створені за допомогою методу SSSLContext.wrap_socket().

Змінено в версії 3.5: Додано метод sendfile().

Змінено в версії 3.5: The shutdown() does not reset the socket timeout each time bytes are received or sent. The socket timeout is now the maximum total duration of the shutdown.

Застаріло починаючи з версії 3.6: Безпосереднє створення екземпляра SSLSocket є застарілим, використовуйте SSSLContext.wrap_socket() для упаковки сокета.

Змінено в версії 3.7: SSLSocket екземпляри повинні бути створені за допомогою wrap_socket(). У попередніх версіях можна було створювати екземпляри безпосередньо. Це ніколи не було задокументовано чи офіційно підтверджено.

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

SSL-сокети також мають такі додаткові методи та атрибути:

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

Читайте до len байтів даних із SSL-сокета та повертайте результат як екземпляр bytes. Якщо вказано buffer, то замість цього зчитується в буфер і повертається кількість прочитаних байтів.

Викликайте SSLWantReadError або SSLWantWriteError, якщо сокет неблокує, і читання буде заблоковано.

Оскільки в будь-який час можливе повторне узгодження, виклик read() також може викликати операції запису.

Змінено в версії 3.5: The socket timeout is no longer reset each time bytes are received or sent. The socket timeout is now the maximum total duration to read up to len bytes.

Застаріло починаючи з версії 3.6: Використовуйте recv() замість read().

SSLSocket.write(buf)¶

Запишіть buf у SSL-сокет і поверніть кількість записаних байтів. Аргумент buf має бути об’єктом, що підтримує інтерфейс буфера.

Викликайте SSLWantReadError або SSLWantWriteError, якщо сокет неблокує, і запис буде заблоковано.

Оскільки в будь-який час можливе повторне узгодження, виклик write() також може викликати операції читання.

Змінено в версії 3.5: The socket timeout is no longer reset each time bytes are received or sent. The socket timeout is now the maximum total duration to write buf.

Застаріло починаючи з версії 3.6: Використовуйте send() замість write().

Примітка

Методи read() і write() є низькорівневими методами, які читають і записують незашифровані дані на рівні програми та розшифровують/шифрують їх у зашифровані дані на рівні проводів. Для цих методів потрібне активне з’єднання SSL, тобто рукостискання завершено і SSLSocket.unwrap() не викликано.

Зазвичай замість цих методів слід використовувати такі методи API сокетів, як recv() і send().

SSLSocket.do_handshake()¶: Виконайте рукостискання налаштування SSL.

Змінено в версії 3.4: Метод рукостискання також виконує match_hostname(), якщо атрибут check_hostname context сокета має значення true.

Змінено в версії 3.5: The socket timeout is no longer reset each time bytes are received or sent. The socket timeout is now the maximum total duration of the handshake.

Змінено в версії 3.7: Hostname or IP address is matched by OpenSSL during handshake. The function match_hostname() is no longer used. In case OpenSSL refuses a hostname or IP address, the handshake is aborted early and a TLS alert message is sent to the peer.

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}

Якщо параметр binary_form має значення True і надано сертифікат, цей метод повертає закодовану DER форму всього сертифіката у вигляді послідовності байтів або None, якщо одноранговий сертифікат не надав. Чи надає партнер сертифікат, залежить від ролі SSL-сокета:

для клієнтського SSL-сокета сервер завжди надаватиме сертифікат, незалежно від того, чи була потрібна перевірка;
для серверного SSL-сокета клієнт надасть сертифікат лише за запитом сервера; тому getpeercert() поверне None, якщо ви використали CERT_NONE (а не CERT_OPTIONAL або CERT_REQUIRED).

Контексти SSL¶

Added in version 3.2.

Контекст SSL зберігає різноманітні дані, які живуть довше, ніж окремі з’єднання SSL, наприклад параметри конфігурації SSL, сертифікат(и) і закритий ключ(и). Він також керує кеш-пам’яттю сеансів SSL для сокетів на стороні сервера, щоб пришвидшити повторювані підключення від тих самих клієнтів.

class ssl.SSLContext(protocol=None)¶

Створіть новий контекст SSL. Ви можете передати протокол, який має бути однією з констант 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: The context is created with secure default values. The options OP_NO_COMPRESSION, OP_CIPHER_SERVER_PREFERENCE, OP_SINGLE_DH_USE, OP_SINGLE_ECDH_USE, OP_NO_SSLv2, and OP_NO_SSLv3 (except for PROTOCOL_SSLv3) are set by default. The initial cipher suite list contains only HIGH ciphers, no NULL ciphers and no MD5 ciphers.

Застаріло починаючи з версії 3.10: SSLContext без аргументу протоколу застаріло. У майбутньому клас контексту потребуватиме протоколу PROTOCOL_TLS_CLIENT або PROTOCOL_TLS_SERVER.

Змінено в версії 3.10: Набір шифрів за замовчуванням тепер включає лише захищені шифри AES і ChaCha20 із прямою секретністю та рівнем безпеки 2. Ключі RSA та DH із менш ніж 2048 бітами та ключі ECC із менш ніж 224 бітами заборонені. PROTOCOL_TLS, PROTOCOL_TLS_CLIENT і PROTOCOL_TLS_SERVER використовують TLS 1.2 як мінімальну версію TLS.

Примітка

SSLContext only supports limited mutation once it has been used by a connection. Adding new certificates to the internal trust store is allowed, but changing ciphers, verification settings, or mTLS certificates may result in surprising behavior.

Примітка

SSLContext is designed to be shared and used by multiple connections. Thus, it is thread-safe as long as it is not reconfigured after being used by a connection.

SSLContext об’єкти мають такі методи та атрибути:

SSLContext.cert_store_stats()¶

Отримайте статистичні дані про кількість завантажених сертифікатів X.509, кількість сертифікатів X.509, позначених як сертифікати ЦС, і списки відкликаних сертифікатів як словник.

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

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

Added in version 3.4.

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

Завантажте закритий ключ і відповідний сертифікат. Рядок certfile має бути шляхом до одного файлу у форматі PEM, що містить сертифікат, а також будь-яку кількість сертифікатів ЦС, необхідних для встановлення автентичності сертифіката. Рядок keyfile, якщо він присутній, має вказувати на файл, що містить закритий ключ. Інакше закритий ключ також буде взято з certfile. Перегляньте обговорення Сертифікати для отримання додаткової інформації про те, як сертифікат зберігається у certfile.

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

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

SSLError виникає, якщо закритий ключ не збігається з сертифікатом.

Змінено в версії 3.3: Новий необов’язковий аргумент пароль.

SSLContext.load_default_certs(purpose=Purpose.SERVER_AUTH)¶

Завантажте набір стандартних сертифікатів «центру сертифікації» (CA) із стандартних розташувань. У Windows він завантажує сертифікати ЦС із системних сховищ CA і ROOT. У всіх системах він викликає SSLContext.set_default_verify_paths(). У майбутньому цей метод може також завантажувати сертифікати ЦС з інших місць.

The purpose flag specifies what kind of CA certificates are loaded. The default settings Purpose.SERVER_AUTH loads certificates, that are flagged and trusted for TLS web server authentication (client side sockets). Purpose.CLIENT_AUTH loads CA certificates for client certificate verification on the server side.

Added in version 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, якщо він присутній, є шляхом до файлу об’єднаних сертифікатів ЦС у форматі PEM. Перегляньте обговорення Сертифікати для отримання додаткової інформації про те, як упорядкувати сертифікати в цьому файлі.

The capath string, if present, is the path to a directory containing several CA certificates in PEM format, following an 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, кожен запис у списку є диктофоном, подібним до результату SSLSocket.getpeercert(). В іншому випадку метод повертає список сертифікатів, закодованих DER. Повернений список не містить сертифікатів від capath, якщо тільки сертифікат не було запитано та завантажено через підключення SSL.

Примітка

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

Added in version 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'}]

Added in version 3.6.

SSLContext.set_default_verify_paths()¶: Завантажте набір стандартних сертифікатів «центру сертифікації» (CA) із шляху файлової системи, визначеного під час створення бібліотеки OpenSSL. На жаль, немає простого способу дізнатися, чи цей метод успішний: помилка не повертається, якщо сертифікати не знайдені. Однак, коли бібліотека OpenSSL надається як частина операційної системи, вона, швидше за все, буде налаштована належним чином.

SSLContext.set_ciphers(ciphers)¶: Set the available ciphers for sockets created with this context. It should be a string in the OpenSSL cipher list format. If no cipher can be selected (because compile-time options or other configuration forbids use of all the specified ciphers), an SSLError will be raised.

Примітка

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

Набори шифрів TLS 1.3 не можна вимкнути за допомогою set_ciphers().

SSLContext.set_alpn_protocols(protocols)¶

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

Цей метод викличе NotImplementedError, якщо HAS_ALPN має значення False.

Added in version 3.5.

SSLContext.set_npn_protocols(protocols)¶

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

Цей метод викличе NotImplementedError, якщо HAS_NPN має значення False.

Added in version 3.3.

Застаріло починаючи з версії 3.10: NPN було замінено на ALPN

SSLContext.sni_callback¶

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

Для кожного SSLContext можна встановити лише один зворотний виклик. Якщо sni_callback встановлено на None, тоді зворотний виклик вимкнено. Наступний виклик цієї функції вимкне попередньо зареєстрований зворотний виклик.

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

Типовим використанням цього зворотного виклику є зміна атрибута SSLSocket.context ssl.SSLSocket на новий об’єкт типу SSLContext, який представляє ланцюжок сертифікатів, який відповідає імені сервера .

Due to the early negotiation phase of the TLS connection, only limited methods and attributes are usable like SSLSocket.selected_alpn_protocol() and SSLSocket.context. The SSLSocket.getpeercert(), SSLSocket.get_verified_chain(), SSLSocket.get_unverified_chain() SSLSocket.cipher() and SSLSocket.compression() methods require that the TLS connection has progressed beyond the TLS Client Hello and therefore will not return meaningful values nor can they be called safely.

Функція 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.

Added in version 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").

If there is a decoding error on the server name, the TLS connection will terminate with an ALERT_DESCRIPTION_INTERNAL_ERROR fatal TLS alert message to the client.

Added in version 3.4.

SSLContext.load_dh_params(dhfile)¶

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

Цей параметр не застосовується до клієнтських сокетів. Ви також можете використовувати параметр OP_SINGLE_DH_USE для подальшого покращення безпеки.

Added in version 3.3.

SSLContext.set_ecdh_curve(curve_name)¶

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

Цей параметр не застосовується до клієнтських сокетів. Ви також можете використовувати опцію OP_SINGLE_ECDH_USE для подальшого покращення безпеки.

Цей метод недоступний, якщо HAS_ECDH має значення False.

Added in version 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)¶

Wrap an existing Python socket sock and return an instance of SSLContext.sslsocket_class (default SSLSocket). The returned SSL socket is tied to the context, its settings and certificates. sock must be a SOCK_STREAM socket; other socket types are unsupported.

Параметр server_side є логічним значенням, яке визначає, яка поведінка для цього сокета – серверна чи клієнтська.

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

У клієнтських з’єднаннях необов’язковий параметр server_hostname визначає ім’я хоста служби, до якої ми під’єднуємося. Це дозволяє одному серверу розміщувати кілька служб на основі SSL з окремими сертифікатами, подібно до віртуальних хостів HTTP. Якщо вказати server_hostname, виникне ValueError, якщо server_side має значення true.

Параметр do_handshake_on_connect визначає, чи виконувати SSL-рукостискання автоматично після виконання socket.connect(), чи прикладна програма викличе його явно, викликаючи метод SSLSocket.do_handshake(). Виклик SSLSocket.do_handshake() явно дає програмі контроль над поведінкою блокування вводу-виводу сокета, залученого до рукостискання.

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

сеанс, див. session.

To wrap an SSLSocket in another SSLSocket, use SSLContext.wrap_bio().

Змінено в версії 3.5: Завжди дозволяйте передачу server_hostname, навіть якщо OpenSSL не має SNI.

Змінено в версії 3.6: Додано аргумент сеанс.

Змінено в версії 3.7: The method returns an instance of SSLContext.sslsocket_class instead of hard-coded SSLSocket.

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

Added in version 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: Додано аргумент сеанс.

Змінено в версії 3.7: The method returns an instance of SSLContext.sslobject_class instead of hard-coded SSLObject.

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

Added in version 3.7.

SSLContext.session_stats()¶

Get statistics about the SSL sessions created or managed by this context. A dictionary is returned which maps the names of each piece of information to their numeric values. For example, here is the total number of hits and misses in the session cache since the context was created:

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

Added in version 3.4.

Змінено в версії 3.7: verify_mode тепер автоматично змінюється на CERT_REQUIRED, коли перевірку імені хоста ввімкнено, а verify_mode має значення CERT_NONE. Раніше ця сама операція не виконувалася з помилкою ValueError.

SSLContext.keylog_filename¶: Записуйте ключі TLS у файл клавіатурного журналу щоразу, коли створюється або отримується ключовий матеріал. Файл клавіатурного журналу створено лише для налагодження. Формат файлу визначається NSS і використовується багатьма аналізаторами трафіку, такими як Wireshark. Файл журналу відкривається в режимі лише додавання. Записи синхронізуються між потоками, але не між процесами.

Added in version 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 підключення.

Added in version 3.7.

SSLContext.minimum_version¶: Як SSLContext.maximum_version, за винятком того, що це найнижча підтримувана версія або TLSVersion.MINIMUM_SUPPORTED.

Added in version 3.7.

SSLContext.num_tickets¶: Контролюйте кількість квитків сесії TLS 1.3 контексту PROTOCOL_TLS_SERVER. Параметр не впливає на підключення TLS 1.0 до 1.2.

Added in version 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() і не буде виконано деякий ввід-вивід.

Added in version 3.8.

SSLContext.protocol¶: Версія протоколу, обрана під час побудови контексту. Цей атрибут доступний лише для читання.

SSLContext.hostname_checks_common_name¶: Чи повертається check_hostname для перевірки загальної назви суб’єкта сертифіката за відсутності альтернативного розширення імені суб’єкта (за умовчанням: істина).

Added in version 3.7.

Змінено в версії 3.10: The flag had no effect with OpenSSL before version 1.1.1l. Python 3.8.9, 3.9.3, and 3.10 include workarounds for previous versions.

SSLContext.security_level¶: An integer representing the security level for the context. This attribute is read-only.

Added in version 3.10.

SSLContext.verify_flags¶

Прапори для операцій перевірки сертифіката. Ви можете встановити такі прапорці, як VERIFY_CRL_CHECK_LEAF, об’єднавши їх разом. За замовчуванням OpenSSL не вимагає і не перевіряє списки відкликаних сертифікатів (CRL).

Added in version 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 enum:

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

SSLContext.set_psk_client_callback(callback)¶

Enables TLS-PSK (pre-shared key) authentication on a client-side connection.

In general, certificate based authentication should be preferred over this method.

The parameter callback is a callable object with the signature: def callback(hint: str | None) -> tuple[str | None, bytes]. The hint parameter is an optional identity hint sent by the server. The return value is a tuple in the form (client-identity, psk). Client-identity is an optional string which may be used by the server to select a corresponding PSK for the client. The string must be less than or equal to 256 octets when UTF-8 encoded. PSK is a bytes-like object representing the pre-shared key. Return a zero length PSK to reject the connection.

Setting callback to None removes any existing callback.

Примітка

When using TLS 1.3:

the hint parameter is always None.
client-identity must be a non-empty string.

Приклад використання:

context = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
context.check_hostname = False
context.verify_mode = ssl.CERT_NONE
context.maximum_version = ssl.TLSVersion.TLSv1_2
context.set_ciphers('PSK')

# A simple lambda:
psk = bytes.fromhex('c0ffee')
context.set_psk_client_callback(lambda hint: (None, psk))

# A table using the hint from the server:
psk_table = { 'ServerId_1': bytes.fromhex('c0ffee'),
              'ServerId_2': bytes.fromhex('facade')
}
def callback(hint):
    return 'ClientId_1', psk_table.get(hint, b'')
context.set_psk_client_callback(callback)

This method will raise NotImplementedError if HAS_PSK is False.

Added in version 3.13.

SSLContext.set_psk_server_callback(callback, identity_hint=None)¶

Enables TLS-PSK (pre-shared key) authentication on a server-side connection.

In general, certificate based authentication should be preferred over this method.

The parameter callback is a callable object with the signature: def callback(identity: str | None) -> bytes. The identity parameter is an optional identity sent by the client which can be used to select a corresponding PSK. The return value is a bytes-like object representing the pre-shared key. Return a zero length PSK to reject the connection.

Setting callback to None removes any existing callback.

The parameter identity_hint is an optional identity hint string sent to the client. The string must be less than or equal to 256 octets when UTF-8 encoded.

Примітка

When using TLS 1.3 the identity_hint parameter is not sent to the client.

Приклад використання:

context = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER)
context.maximum_version = ssl.TLSVersion.TLSv1_2
context.set_ciphers('PSK')

# A simple lambda:
psk = bytes.fromhex('c0ffee')
context.set_psk_server_callback(lambda identity: psk)

# A table using the identity of the client:
psk_table = { 'ClientId_1': bytes.fromhex('c0ffee'),
              'ClientId_2': bytes.fromhex('facade')
}
def callback(identity):
    return psk_table.get(identity, b'')
context.set_psk_server_callback(callback, 'ServerId_1')

This method will raise NotImplementedError if HAS_PSK is False.

Added in version 3.13.

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

Загалом сертифікати є частиною системи відкритого/приватного ключа. У цій системі кожному принципалу (яким може бути машина, або особа, або організація) призначається унікальний ключ шифрування, що складається з двох частин. Одна частина ключа є відкритою і називається відкритим ключем; інша частина зберігається в таємниці та називається приватним ключем. Ці дві частини пов’язані між собою, оскільки якщо ви зашифровуєте повідомлення за допомогою однієї з частин, ви можете розшифрувати його за допомогою іншої частини та тільки за допомогою іншої частини.

Сертифікат містить інформацію про двох принципалів. Він містить назву суб’єкта та відкритий ключ суб’єкта. Він також містить заяву другого принципала, емітента, про те, що суб’єкт є тим, за кого себе видає, і що це справді відкритий ключ суб’єкта. Заява емітента підписується закритим ключем емітента, який відомий лише емітенту. Проте будь-хто може перевірити заяву емітента, знайшовши відкритий ключ емітента, розшифрувавши за його допомогою заяву та порівнявши її з іншою інформацією в сертифікаті. Сертифікат також містить інформацію про термін його дії. Це виражається двома полями, які називаються «notBefore» і «notAfter».

При використанні сертифікатів Python клієнт або сервер можуть використовувати сертифікат, щоб підтвердити, ким вони є. Інша сторона мережевого з’єднання також може вимагати створення сертифіката, і цей сертифікат може бути перевірений відповідно до вимог клієнта або сервера, які потребують такої перевірки. Спробу підключення можна налаштувати так, щоб викликати виняток, якщо перевірка не вдається. Перевірка виконується автоматично базовою структурою OpenSSL; програмі не потрібно займатися своєю механікою. Але програмі зазвичай потрібно надати набори сертифікатів, щоб дозволити цей процес.

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

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

Ланцюжки сертифікатів¶

Файли Python, які містять сертифікати, можуть містити послідовність сертифікатів, яку іноді називають ланцюжком сертифікатів. Цей ланцюжок має починатися з конкретного сертифіката для принципала, який «є» клієнтом або сервером, а потім сертифіката для видавця цього сертифіката, а потім сертифіката для видавця цього сертифіката, і так далі вгору по ланцюжку доки ви не дійдете до самопідписаного сертифіката, тобто сертифіката з тим самим суб’єктом і видавцем, який іноді називають кореневим сертифікатом. Сертифікати потрібно просто об’єднати у файлі сертифікатів. Наприклад, припустімо, що ми маємо ланцюжок із трьох сертифікатів: від сертифіката нашого сервера до сертифіката центру сертифікації, який підписав наш сертифікат сервера, до кореневого сертифіката агентства, яке видало сертифікат центру сертифікації:

-----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-----

сертифікати ЦС¶

Якщо ви збираєтеся вимагати підтвердження іншої сторони сертифіката з’єднання, вам потрібно надати файл «сертифікатів ЦС», заповнений ланцюжками сертифікатів для кожного видавця, якому ви готові довіряти. Знову ж таки, цей файл містить ці ланцюжки, об’єднані разом. Для перевірки Python використовуватиме перший ланцюжок, знайдений у файлі, який відповідає. Файл сертифікатів платформи можна використовувати, викликавши SSLContext.load_default_certs(), це робиться автоматично за допомогою create_default_context().

Комбінований ключ і сертифікат¶

Often the private key is stored in the same file as the certificate; in this case, only the certfile parameter to SSLContext.load_cert_chain() needs to be passed. If the private key is stored with the certificate, it should come before the first certificate in the certificate chain:

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

Самопідписані сертифікати¶

Якщо ви збираєтеся створити сервер, який надає послуги з’єднання з шифруванням SSL, вам потрібно буде отримати сертифікат для цієї послуги. Є багато способів отримати відповідні сертифікати, наприклад придбати сертифікат в центрі сертифікації. Іншою поширеною практикою є створення самопідписаного сертифіката. Найпростіший спосіб зробити це за допомогою пакета OpenSSL, використовуючи щось на зразок наступного:

% 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
%

Недоліком самопідписаного сертифіката є те, що це його власний кореневий сертифікат, і ніхто інший не матиме його в кеш-пам’яті відомих (і надійних) кореневих сертифікатів.

Приклади¶

Тестування підтримки SSL¶

Щоб перевірити наявність підтримки SSL у встановленому Python, код користувача має використовувати таку ідіому:

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

Робота на стороні клієнта¶

У цьому прикладі створюється контекст SSL із рекомендованими налаштуваннями безпеки для клієнтських сокетів, включаючи автоматичну перевірку сертифіката:

>>> context = ssl.create_default_context()

Якщо ви бажаєте налаштувати параметри безпеки самостійно, ви можете створити контекст з нуля (але пам’ятайте, що ви можете неправильно встановити параметри):

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

(цей фрагмент припускає, що ваша операційна система розміщує пакет усіх сертифікатів ЦС у /etc/ssl/certs/ca-bundle.crt; якщо ні, ви отримаєте повідомлення про помилку, і вам доведеться змінити розташування)

Протокол PROTOCOL_TLS_CLIENT налаштовує контекст для перевірки сертифіката та перевірки імені хоста. verify_mode встановлено на CERT_REQUIRED, а check_hostname встановлено на True. Усі інші протоколи створюють контексти SSL із незахищеними значеннями за умовчанням.

Коли ви використовуєте контекст для підключення до сервера, CERT_REQUIRED і check_hostname перевіряють сертифікат сервера: це гарантує, що сертифікат сервера було підписано одним із сертифікатів ЦС, перевіряє підпис на коректність і перевіряє інші властивості, такі як дійсність та ідентичність імені хоста:

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

Потім ви можете отримати сертифікат:

>>> cert = conn.getpeercert()

Візуальна перевірка показує, що сертифікат ідентифікує потрібну службу (тобто хост HTTPS www.python.org):

>>> 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}

Тепер SSL-канал встановлено та сертифікат перевірено, ви можете продовжити спілкування з сервером:

>>> 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'']

Дивіться обговорення Міркування безпеки нижче.

Робота на стороні сервера¶

Для роботи сервера зазвичай потрібно мати сертифікат сервера та закритий ключ, кожен у файлі. Спочатку ви створите контекст, що містить ключ і сертифікат, щоб клієнти могли перевірити вашу автентичність. Потім ви відкриєте сокет, прив’яжете його до порту, викличете на ньому listen() і почнете чекати підключення клієнтів:

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)

Коли клієнт підключається, ви викличете accept() для сокета, щоб отримати новий сокет з іншого боку, і використаєте контекстний метод SSLContext.wrap_socket(), щоб створити серверний сокет SSL для зв’язок:

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()

Потім ви будете читати дані з connstream і щось робити з ними, поки не закінчите роботу з клієнтом (або клієнт не закінчить роботу з вами):

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], [])
```

Дивись також

Модуль asyncio підтримує неблокуючі сокети SSL і забезпечує API вищого рівня. Він опитує події за допомогою модуля selectors і обробляє винятки SSLWantWriteError, SSLWantReadError і BlockingIOError. Він також запускає рукостискання SSL асинхронно.

Підтримка BIO пам’яті¶

Added in version 3.5.

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

Обробка протоколу SSL
Мережа IO

Мережевий IO API ідентичний тому, який надає socket.socket, від якого також успадковується SSLSocket. Це дозволяє використовувати сокет SSL як додаткову заміну звичайного сокета, що дозволяє дуже легко додати підтримку SSL до існуючої програми.

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

class ssl.SSLObject¶

Зменшений варіант SSLSocket, що представляє екземпляр протоколу SSL, який не містить жодних мережевих методів введення-виведення. Цей клас зазвичай використовується авторами фреймворків, які хочуть реалізувати асинхронний IO для SSL через буфери пам’яті.

Цей клас реалізує інтерфейс поверх об’єкта SSL низького рівня, реалізованого OpenSSL. Цей об’єкт фіксує стан SSL-з’єднання, але сам не надає мережевий IO. IO потрібно виконувати через окремі об’єкти «BIO», які є рівнем абстракції IO OpenSSL.

Цей клас не має публічного конструктора. Екземпляр SSLObject має бути створений за допомогою методу wrap_bio(). Цей метод створить екземпляр SSLObject і прив’яже його до пари BIO. Вхідний BIO використовується для передачі даних від Python до примірника протоколу SSL, тоді як вихідний BIO використовується для передачі даних навпаки.

Доступні такі методи:

context
сторона_сервера
сервер_hostname
session
session_reused
read()
write()
getpeercert()
get_verified_chain()
get_unverified_chain()
selected_alpn_protocol()
selected_npn_protocol()
cipher()
shared_ciphers()
compression()
очікує()
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:

Усі IO для SSLObject є неблокуючими. Це означає, що, наприклад, read() викличе SSLWantReadError, якщо йому потрібно більше даних, ніж доступно у вхідному BIO.

Змінено в версії 3.7: SSLObject instances must be created with wrap_bio(). In earlier versions, it was possible to create instances directly. This was never documented or officially supported.

SSLObject спілкується із зовнішнім світом за допомогою буферів пам’яті. Клас MemoryBIO забезпечує буфер пам’яті, який можна використовувати для цієї мети. Він обертає об’єкт BIO пам’яті OpenSSL (Basic IO):

class ssl.MemoryBIO¶

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

pending¶: Повертає кількість байтів у буфері пам’яті.

eof¶: Логічне значення, яке вказує, чи є BIO пам’яті поточним у позиції кінця файлу.

read(n=-1)¶: Прочитати до n байт із буфера пам’яті. Якщо n не вказано або має негативне значення, повертаються всі байти.

write(buf)¶

Запишіть байти з buf в пам’ять BIO. Аргумент buf має бути об’єктом, що підтримує протокол буфера.

Поверненим значенням є кількість записаних байтів, яка завжди дорівнює довжині buf.

write_eof()¶: Запишіть маркер EOF в пам’ять BIO. Після виклику цього методу викликати write() заборонено. Атрибут eof стане істинним після того, як усі дані, які зараз знаходяться в буфері, будуть прочитані.

Сеанс SSL¶

Added in version 3.6.

class ssl.SSLSession¶

Об’єкт сеансу, який використовує session.

id¶

time¶

timeout¶

ticket_lifetime_hint¶

has_ticket¶

Міркування безпеки¶

Найкращі параметри за замовчуванням¶

Для користування клієнтом, якщо у вас немає особливих вимог до вашої політики безпеки, настійно рекомендується використовувати функцію create_default_context() для створення контексту SSL. Він завантажить довірені сертифікати ЦС системи, увімкне перевірку сертифіката та перевірку імені хоста, а також спробує вибрати достатньо безпечний протокол і налаштування шифру.

Наприклад, ось як можна використовувати клас smtplib.SMTP для створення надійного безпечного з’єднання з сервером SMTP:

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

Якщо для підключення потрібен сертифікат клієнта, його можна додати за допомогою SSSLContext.load_cert_chain().

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

Ручні налаштування¶

Перевірка сертифікатів¶

When calling the SSLContext constructor directly, CERT_NONE is the default. Since it does not authenticate the other peer, it can be insecure, especially in client mode where most of the time you would like to ensure the authenticity of the server you’re talking to. Therefore, when in client mode, it is highly recommended to use CERT_REQUIRED. However, it is in itself not sufficient; you also have to check that the server certificate, which can be obtained by calling SSLSocket.getpeercert(), matches the desired service. For many protocols and applications, the service can be identified by the hostname. This common check is automatically performed when SSLContext.check_hostname is enabled.

Змінено в версії 3.7: Зіставлення імен хостів тепер виконує OpenSSL. Python більше не використовує match_hostname().

У режимі сервера, якщо ви хочете автентифікувати своїх клієнтів за допомогою рівня SSL (замість використання механізму автентифікації вищого рівня), вам також доведеться вказати CERT_REQUIRED і так само перевірити сертифікат клієнта.

Версії протоколу¶

SSL версії 2 і 3 вважаються небезпечними, тому їх використання небезпечно. Якщо вам потрібна максимальна сумісність між клієнтами та серверами, рекомендується використовувати PROTOCOL_TLS_CLIENT або PROTOCOL_TLS_SERVER як версію протоколу. SSLv2 і SSLv3 вимкнено за замовчуванням.

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

The SSL context created above will only allow TLSv1.3 and later (if supported by your system) connections to a server. PROTOCOL_TLS_CLIENT implies certificate validation and hostname checks by default. You have to load certificates into the context.

Вибір шифру¶

If you have advanced security requirements, fine-tuning of the ciphers enabled when negotiating a SSL session is possible through the SSLContext.set_ciphers() method. Starting from Python 3.2.3, the ssl module disables certain weak ciphers by default, but you may want to further restrict the cipher choice. Be sure to read OpenSSL’s documentation about the cipher list format. If you want to check which ciphers are enabled by a given cipher list, use SSLContext.get_ciphers() or the openssl ciphers command on your system.

Багатопроцесорність¶

If using this module as part of a multi-processed application (using, for example the multiprocessing or concurrent.futures modules), be aware that OpenSSL’s internal random number generator does not properly handle forked processes. Applications must change the PRNG state of the parent process if they use any SSL feature with os.fork(). Any successful call of RAND_add() or RAND_bytes() is sufficient.

TLS 1.3¶

Added in version 3.7.

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

Дивись також

Клас socket.socket: Документація основного класу socket
Надійне шифрування SSL/TLS: Вступ: Введення з документації Apache HTTP Server
RFC 1422: Покращення конфіденційності електронної пошти в Інтернеті: Частина II: Керування ключами на основі сертифікатів: Стів Кент
RFC 4086: Вимоги до випадковості для безпеки: Дональд Е., Джеффрі І. Шиллер
RFC 5280: Сертифікат інфраструктури відкритих ключів Інтернету X.509 і профіль відкликаних сертифікатів (CRL): Д. Купер
RFC 5246: Протокол безпеки транспортного рівня (TLS) версії 1.2: Т. Діркс та ін. al.
RFC 6066: Розширення безпеки транспортного рівня (TLS): Д. Істлейк
IANA TLS: Параметри безпеки транспортного рівня (TLS): IANA
RFC 7525: Рекомендації щодо безпечного використання безпеки транспортного рівня (TLS) і захисту транспортного рівня датаграм (DTLS): IETF
Рекомендації TLS на стороні сервера Mozilla: Mozilla

`ssl` — TLS/SSL wrapper for socket objects¶

Функції, константи та винятки¶

Створення розетки¶

Створення контексту¶

Винятки¶

Випадкова генерація¶

Обробка сертифікатів¶

Константи¶

SSL-сокети¶

Контексти SSL¶

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

Ланцюжки сертифікатів¶

сертифікати ЦС¶

Комбінований ключ і сертифікат¶

Самопідписані сертифікати¶

Приклади¶

Тестування підтримки SSL¶

Робота на стороні клієнта¶

Робота на стороні сервера¶

Примітки щодо неблокуючих розеток¶

Підтримка BIO пам’яті¶

Сеанс SSL¶

Міркування безпеки¶

Найкращі параметри за замовчуванням¶

Ручні налаштування¶

Перевірка сертифікатів¶

Версії протоколу¶

Вибір шифру¶

Багатопроцесорність¶

TLS 1.3¶

Table of Contents

Попередній розділ

Наступна тема

Ця сторінка

ssl — TLS/SSL wrapper for socket objects¶

Функції, константи та винятки¶

Створення розетки¶

Створення контексту¶

Винятки¶

Випадкова генерація¶

Обробка сертифікатів¶

Константи¶

SSL-сокети¶

Контексти SSL¶

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

Ланцюжки сертифікатів¶

сертифікати ЦС¶

Комбінований ключ і сертифікат¶

Самопідписані сертифікати¶

Приклади¶

Тестування підтримки SSL¶

Робота на стороні клієнта¶

Робота на стороні сервера¶

Примітки щодо неблокуючих розеток¶

Підтримка BIO пам’яті¶

Сеанс SSL¶

Міркування безпеки¶

Найкращі параметри за замовчуванням¶

Ручні налаштування¶

Перевірка сертифікатів¶

Версії протоколу¶

Вибір шифру¶

Багатопроцесорність¶

TLS 1.3¶

`ssl` — TLS/SSL wrapper for socket objects¶