18.2. ssl – обёртка TLS/SSL для объектов сокетов¶ssl – TLS/SSL wrapper for socket objects

18.2.1.1. Создание сокета¶Socket creation

Следующая функция позволяет создать сокет независимо. Начиная с Python 3.2, может быть более гибким использование SSLContext.wrap_socket() вместо этого.

ssl.wrap_socket(sock, keyfile=None, certfile=None, server_side=False, cert_reqs=CERT_NONE, ssl_version={see docs}, ca_certs=None, do_handshake_on_connect=True, suppress_ragged_eofs=True, ciphers=None)¶

Принимает экземпляр sock типа socket.socket и возвращает экземпляр ssl.SSLSocket, подтипа socket.socket, который оборачивает нижележащий сокет в контекст SSL. sock должен быть сокетом SOCK_STREAM; другие типы сокетов не поддерживаются.

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

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

Параметр server_side – это логическое значение, которое определяет, требуется ли от этого сокета поведение серверной или клиентской стороны.

Параметр cert_reqs задаёт, требуется ли сертификат от другой стороны соединения и будет ли он проверен, если предоставлен. Он должен быть одним из трёх значений: CERT_NONE (сертификаты игнорируются), CERT_OPTIONAL (не требуется, но проверяется, если предоставлен) или CERT_REQUIRED (требуется и проверяется). Если значение этого параметра не CERT_NONE, то параметр ca_certs должен указывать на файл с сертификатами ЦС.

Файл ca_certs содержит набор объединённых сертификатов «центров сертификации», которые используются для проверки сертификатов, переданных с другого конца соединения. См. обсуждение Certificates для получения дополнительной информации о том, как организовать сертификаты в этом файле.

Параметр ssl_version определяет, какую версию протокола SSL использовать. Обычно сервер выбирает конкретную версию протокола, а клиент должен подстраиваться под выбор сервера. Большинство версий несовместимы друг с другом. Если параметр не задан, по умолчанию используется PROTOCOL_SSLv23; он обеспечивает наилучшую совместимость с другими версиями.

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

клиент / сервер	SSLv2	SSLv3	SSLv23	TLSv1	TLSv1.1	TLSv1.2
SSLv2	да	нет	да	нет	нет	нет
SSLv3	нет	да	да	нет	нет	нет
SSLv23	нет	да	да	да	да	да
TLSv1	нет	нет	да	да	нет	нет
TLSv1.1	нет	нет	да	нет	да	нет
TLSv1.2	нет	нет	да	нет	нет	да

Примечание

Какие соединения будут успешными, зависит от версии OpenSSL. Например, до OpenSSL 1.0.0 клиент SSLv23 всегда пытался устанавливать соединения SSLv2.

Параметр ciphers задаёт доступные шифры для этого объекта SSL. Он должен быть строкой в формате списка шифров OpenSSL.

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

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

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

18.2.1.2. Создание контекста¶Context creation

Вспомогательная функция помогает создавать объекты SSLContext для типовых задач.

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

Возвращает новый объект SSLContext с настройками по умолчанию для заданного purpose. Настройки выбираются модулем ssl, и обычно обеспечивают более высокий уровень безопасности, чем при прямом вызове конструктора SSLContext.

cafile, capath и cadata представляют необязательные сертификаты ЦС для проверки сертификатов, как в SSLContext.load_verify_locations(). Если все три равны None, эта функция может вместо этого использовать системные сертификаты ЦС по умолчанию.

Используются следующие настройки: PROTOCOL_SSLv23, OP_NO_SSLv2 и OP_NO_SSLv3 с набором шифров высокой надёжности без RC4 и без неаутентифицированных шифров. Передача SERVER_AUTH в качестве purpose устанавливает verify_mode в CERT_REQUIRED и либо загружает сертификаты ЦС (когда задан хотя бы один из cafile, capath или cadata), либо использует SSLContext.load_default_certs() для загрузки сертификатов ЦС по умолчанию.

Примечание

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

Если приложению требуются особые настройки, следует создать SSLContext и применить настройки самостоятельно.

Примечание

Если при использовании SSLContext, созданного этой функцией, некоторые старые клиенты или серверы при попытке подключения выдают ошибку «Несовпадение протокола или набора шифров», возможно, они поддерживают только SSL 3.0, который в этой функции отключён с помощью OP_NO_SSLv3. SSL 3.0 широко считается полностью скомпрометированным. Если всё же требуется продолжать использовать эту функцию, но при этом разрешить подключения по SSL 3.0, его можно снова включить следующим образом:

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

Новое в версии 3.4.

Изменено в версии 3.4.4: RC4 был удалён из строки шифров по умолчанию.

Изменено в версии 3.4.7: ChaCha20/Poly1305 была добавлена в строку шифров по умолчанию.

3DES был удалён из строки шифров по умолчанию.

18.2.1.3. Генерация случайных чисел¶Random generation

ssl.RAND_bytes(num)¶

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

Для большинства приложений предпочтительнее использовать os.urandom().

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

Новое в версии 3.3.

ssl.RAND_pseudo_bytes(num)¶

Возвращает (bytes, is_cryptographic): bytes – это num псевдослучайных байтов, is_cryptographic равно True, если сгенерированные байты являются криптостойкими. Вызывает исключение SSLError, если операция не поддерживается текущим методом RAND.

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

Для большинства приложений предпочтительнее использовать os.urandom().

Новое в версии 3.3.

ssl.RAND_status()¶

Возвращает True, если ГПСЧ SSL был инициализирован «достаточной» энтропией, и False в противном случае. Для увеличения энтропии генератора псевдослучайных чисел можно использовать ssl.RAND_egd() и ssl.RAND_add().

ssl.RAND_egd(path)¶

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

См. http://egd.sourceforge.net/ или http://prngd.sourceforge.net/ для получения исходных текстов демонов сбора энтропии.

ssl.RAND_add(bytes, entropy)¶

Смешивает заданные bytes (байты) с генератором псевдослучайных чисел SSL. Параметр entropy (число с плавающей точкой) задаёт нижнюю границу энтропии, содержащейся в строке (поэтому всегда можно использовать 0.0). См. RFC 1750 для получения дополнительной информации об источниках энтропии.

18.2.1.4. Обработка сертификатов¶Certificate handling

ssl.match_hostname(cert, hostname)¶

Проверяет, что cert (в декодированном формате, возвращённом функцией SSLSocket.getpeercert()) соответствует заданному hostname. Применяются правила проверки идентичности HTTPS-серверов, описанные в RFC 2818 и RFC 6125, за исключением того, что IP-адреса в настоящее время не поддерживаются. Помимо HTTPS, эта функция подходит для проверки идентичности серверов в различных протоколах на основе SSL, таких как FTPS, IMAPS, POPS и другие.

CertificateError возбуждается при неудаче. В случае успеха функция ничего не возвращает:

>>> cert = {'subject': ((('commonName', 'example.com'),),)}
>>> ssl.match_hostname(cert, "example.com")
>>> ssl.match_hostname(cert, "example.org")
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/home/py3k/Lib/ssl.py", line 130, in match_hostname
ssl.CertificateError: hostname 'example.org' doesn't match 'example.com'

Новое в версии 3.2.

Изменено в версии 3.3.3: Теперь функция следует RFC 6125, разделу 6.4.3, и не сопоставляет ни множественные подстановочные символы (например, *.*.com или *a*.example.org), ни подстановочный символ внутри фрагмента интернационализированного доменного имени (IDN). Метки IDN A-типа, такие как www*.xn--pthon-kva.org, по-прежнему поддерживаются, но x*.python.org больше не соответствует xn--tda.python.org.

ssl.cert_time_to_seconds(timestring)¶

Возвращает значение с плавающей запятой, содержащее обычное время в секундах от начала эпохи, для строки времени, представляющей дату “notBefore” или “notAfter” из сертификата.

Вот пример:

>>> import ssl
>>> ssl.cert_time_to_seconds("May  9 00:00:00 2007 GMT")
1178694000.0
>>> import time
>>> time.ctime(ssl.cert_time_to_seconds("May  9 00:00:00 2007 GMT"))
'Wed May  9 00:00:00 2007'

ssl.get_server_certificate(addr, ssl_version=PROTOCOL_SSLv3, ca_certs=None)¶

По заданному адресу addr SSL-защищённого сервера, в виде пары (hostname, port-number), получает сертификат сервера и возвращает его в виде строки в кодировке PEM. Если указан ssl_version, используется эта версия протокола SSL для попытки подключения к серверу. Если указан ca_certs, это должен быть файл, содержащий список корневых сертификатов, в том же формате, который используется для одноимённого параметра в wrap_socket(). Вызов попытается проверить сертификат сервера по этому набору корневых сертификатов, и завершится неудачей, если проверка не пройдёт.

Изменено в версии 3.3: Эта функция теперь совместима с IPv6.

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(). Возвращаемое значение – именованный кортеж DefaultVerifyPaths:

• cafile – разрешённый путь к cafile или None, если файл не существует,
• capath – разрешённый путь к capath или None, если каталог не существует,
• openssl_cafile_env – ключ окружения OpenSSL, указывающий на cafile,
• openssl_cafile – жёстко заданный путь к cafile,
• openssl_capath_env – ключ окружения OpenSSL, указывающий на capath,
• openssl_capath – жёстко заданный путь к каталогу capath

Новое в версии 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 задаёт назначение сертификата как набор OID или именно 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)]

Доступность: Windows.

Новое в версии 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.

Доступность: Windows.

Новое в версии 3.4.

18.2.1.5. Константы¶Constants

ssl.CERT_NONE¶

Возможное значение для SSLContext.verify_mode или параметра cert_reqs для wrap_socket(). В этом режиме (по умолчанию) от другой стороны сокетного соединения не требуется сертификатов. Если сертификат получен от другой стороны, никаких попыток его проверки не предпринимается.

См. обсуждение соображений безопасности ниже.

ssl.CERT_OPTIONAL¶

Возможное значение для SSLContext.verify_mode или параметра cert_reqs для wrap_socket(). В этом режиме от другой стороны сокетного соединения не требуется сертификатов; но если они предоставлены, будет предпринята попытка проверки, и при неудаче будет возбуждено SSLError.

Использование этого параметра требует, чтобы был передан действительный набор сертификатов ЦС – либо в SSLContext.load_verify_locations(), либо в качестве значения параметра ca_certs для wrap_socket().

ssl.CERT_REQUIRED¶

Возможное значение для SSLContext.verify_mode или параметра cert_reqs для wrap_socket(). В этом режиме от другой стороны сокетного соединения требуются сертификаты; SSLError будет возбуждено, если сертификат не предоставлен или его проверка не пройдена.

Использование этого параметра требует передачи корректного набора сертификатов ЦС – либо в SSLContext.load_verify_locations(), либо в качестве значения параметра ca_certs в wrap_socket().

ssl.VERIFY_DEFAULT¶

Возможное значение для SSLContext.verify_flags. В этом режиме списки отзыва сертификатов (CRL) не проверяются. По умолчанию OpenSSL ни требует, ни проверяет CRL.

Новое в версии 3.4.

ssl.VERIFY_CRL_CHECK_LEAF¶

Возможное значение для SSLContext.verify_flags. В этом режиме проверяется только сертификат однорангового узла, но не промежуточные сертификаты ЦС. Режим требует действительного CRL, подписанного эмитентом сертификата однорангового узла (его прямым вышестоящим ЦС). Если подходящий объект не был загружен с помощью SSLContext.load_verify_locations, проверка завершится неудачей.

Новое в версии 3.4.

ssl.VERIFY_CRL_CHECK_CHAIN¶

Возможное значение для SSLContext.verify_flags. В этом режиме проверяются CRL всех сертификатов в цепочке сертификатов однорангового узла.

Новое в версии 3.4.

ssl.VERIFY_X509_STRICT¶

Возможное значение для SSLContext.verify_flags, отключающее обходные решения для повреждённых сертификатов X.509.

Новое в версии 3.4.

ssl.VERIFY_X509_TRUSTED_FIRST¶

Возможное значение для SSLContext.verify_flags. Указывает OpenSSL предпочитать доверенные сертификаты при построении цепочки доверия для проверки сертификата. Этот флаг включён по умолчанию.

Новое в версии 3.4.4.

ssl.PROTOCOL_SSLv23¶

Выбирает самую высокую версию протокола, поддерживаемую как клиентом, так и сервером. Несмотря на название, этот параметр может выбирать протоколы «TLS», а также «SSL».

ssl.PROTOCOL_SSLv2¶

Выбирает SSL версии 2 в качестве протокола шифрования канала.

Этот протокол недоступен, если OpenSSL скомпилирован с флагом OPENSSL_NO_SSL2.

Предупреждение

SSL версии 2 небезопасен. Его использование крайне не рекомендуется.

ssl.PROTOCOL_SSLv3¶

Выбирает SSL версии 3 в качестве протокола шифрования канала.

Этот протокол недоступен, если OpenSSL скомпилирован с флагом OPENSSL_NO_SSLv3.

Предупреждение

SSL версии 3 небезопасен. Его использование крайне не рекомендуется.

ssl.PROTOCOL_TLSv1¶

Выбирает TLS версии 1.0 в качестве протокола шифрования канала.

ssl.PROTOCOL_TLSv1_1¶

Выбирает TLS версии 1.1 в качестве протокола шифрования канала. Доступно только в openssl версии 1.0.1+.

Новое в версии 3.4.

ssl.PROTOCOL_TLSv1_2¶

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

Новое в версии 3.4.

ssl.OP_ALL¶

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

Новое в версии 3.2.

ssl.OP_NO_SSLv2¶

Запрещает соединение SSLv2. Этот параметр применим только в сочетании с PROTOCOL_SSLv23. Он не позволяет одноранговым узлам выбирать SSLv2 в качестве версии протокола.

Новое в версии 3.2.

ssl.OP_NO_SSLv3¶

Запрещает соединение SSLv3. Этот параметр применим только в сочетании с PROTOCOL_SSLv23. Он не позволяет одноранговым узлам выбирать SSLv3 в качестве версии протокола.

Новое в версии 3.2.

ssl.OP_NO_TLSv1¶

Запрещает соединение TLSv1. Этот параметр применим только в сочетании с PROTOCOL_SSLv23. Он не позволяет одноранговым узлам выбирать TLSv1 в качестве версии протокола.

Новое в версии 3.2.

ssl.OP_NO_TLSv1_1¶

Запрещает соединение TLSv1.1. Этот параметр применим только в сочетании с PROTOCOL_SSLv23. Он не позволяет одноранговым узлам выбирать TLSv1.1 в качестве версии протокола. Доступно только в OpenSSL версии 1.0.1 и выше.

Новое в версии 3.4.

ssl.OP_NO_TLSv1_2¶

Запрещает соединение TLSv1.2. Этот параметр применим только в сочетании с PROTOCOL_SSLv23. Он не позволяет одноранговым узлам выбирать TLSv1.2 в качестве версии протокола. Доступно только в OpenSSL версии 1.0.1 и выше.

Новое в версии 3.4.

ssl.OP_CIPHER_SERVER_PREFERENCE¶

Использовать порядок шифров, заданный на сервере, а не на клиенте. Этот параметр не влияет на клиентские сокеты и сокеты сервера SSLv2.

Новое в версии 3.3.

ssl.OP_SINGLE_DH_USE¶

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

Новое в версии 3.3.

ssl.OP_SINGLE_ECDH_USE¶

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

Новое в версии 3.3.

ssl.OP_NO_COMPRESSION¶

Отключает сжатие в SSL-канале. Это полезно, если прикладной протокол поддерживает собственный механизм сжатия.

Эта опция доступна только в OpenSSL 1.0.0 и более поздних версиях.

Новое в версии 3.3.

ssl.HAS_ECDH¶

Определяет, имеет ли библиотека OpenSSL встроенную поддержку обмена ключами Диффи-Хеллмана на основе эллиптических кривых. Должно быть истинно, если только эта возможность не была явно отключена распространителем.

Новое в версии 3.3.

ssl.HAS_SNI¶

Указывает, имеет ли библиотека OpenSSL встроенную поддержку расширения Server Name Indication (как определено в RFC 4366).

Новое в версии 3.2.

ssl.HAS_NPN¶

Поддерживает ли библиотека OpenSSL встроенную поддержку Next Protocol Negotiation, как описано в черновике спецификации NPN. Если значение истинно, можно использовать метод SSLContext.set_npn_protocols() для указания поддерживаемых протоколов.

Новое в версии 3.3.

ssl.CHANNEL_BINDING_TYPES¶

Список поддерживаемых типов привязки каналов TLS. Строки из этого списка можно использовать в качестве аргументов для SSLSocket.get_channel_binding().

Новое в версии 3.3.

ssl.OPENSSL_VERSION¶

Строка с версией библиотеки OpenSSL, загруженной интерпретатором:

>>> ssl.OPENSSL_VERSION
'OpenSSL 0.9.8k 25 Mar 2009'

Новое в версии 3.2.

ssl.OPENSSL_VERSION_INFO¶

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

>>> ssl.OPENSSL_VERSION_INFO
(0, 9, 8, 11, 15)

Новое в версии 3.2.

ssl.OPENSSL_VERSION_NUMBER¶

Сырой номер версии библиотеки OpenSSL в виде целого числа:

>>> ssl.OPENSSL_VERSION_NUMBER
9470143
>>> hex(ssl.OPENSSL_VERSION_NUMBER)
'0x9080bf'

Новое в версии 3.2.

ssl.ALERT_DESCRIPTION_HANDSHAKE_FAILURE¶

ssl.ALERT_DESCRIPTION_INTERNAL_ERROR¶

ALERT_DESCRIPTION_*

Описания предупреждений из RFC 5246 и других источников. Реестр предупреждений TLS IANA содержит этот список и ссылки на RFC, где определено их значение.

Используется как возвращаемое значение функции обратного вызова в SSLContext.set_servername_callback().

Новое в версии 3.4.

Purpose.SERVER_AUTH¶

Параметр для create_default_context() и SSLContext.load_default_certs(). Это значение указывает, что контекст может использоваться для аутентификации веб-серверов (поэтому он будет использоваться для создания клиентских сокетов).

Новое в версии 3.4.

Purpose.CLIENT_AUTH¶

Параметр для create_default_context() и SSLContext.load_default_certs(). Это значение указывает, что контекст может использоваться для аутентификации веб-клиентов (поэтому он будет использоваться для создания серверных сокетов).

Новое в версии 3.4.

18.2.4.1. Цепочки сертификатов¶Certificate chains

The Python files which contain certificates can contain a sequence of certificates, sometimes called a certificate chain. This chain should start with the specific certificate for the principal who “is” the client or server, and then the certificate for the issuer of that certificate, and then the certificate for the issuer of that certificate, and so on up the chain till you get to a certificate which is self-signed, that is, a certificate which has the same subject and issuer, sometimes called a root certificate. The certificates should just be concatenated together in the certificate file. For example, suppose we had a three certificate chain, from our server certificate to the certificate of the certification authority that signed our server certificate, to the root certificate of the agency which issued the certification authority’s 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-----

18.2.4.2. Сертификаты УЦ¶CA certificates

Если требуется проверка сертификата другой стороны соединения, необходимо предоставить файл «CA сертификаты», содержащий цепочки сертификатов для каждого центра сертификации, которому вы доверяете. Этот файл просто содержит эти цепочки, объединённые вместе. Для проверки Python будет использовать первую подходящую цепочку, найденную в файле. Файл сертификатов платформы можно использовать, вызвав SSLContext.load_default_certs(); это делается автоматически с помощью create_default_context().

18.2.4.3. Совмещённый ключ и сертификат¶Combined key and certificate

Часто закрытый ключ хранится в том же файле, что и сертификат; в этом случае нужно передать только параметр certfile в SSLContext.load_cert_chain() и wrap_socket(). Если закрытый ключ хранится вместе с сертификатом, он должен располагаться перед первым сертификатом в цепочке сертификатов:

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

18.2.4.4. Самоподписанные сертификаты¶Self-signed certificates

Если планируется создать сервер, предоставляющий услуги 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
%

Недостаток самоподписанного сертификата в том, что он является собственным корневым сертификатом, и никто другой не будет иметь его в своём кэше известных (и доверенных) корневых сертификатов.

18.2.5.1. Проверка поддержки SSL¶Testing for SSL support

Чтобы проверить наличие поддержки SSL в установке Python, в пользовательском коде следует использовать следующую идиому:

try:
    import ssl
except ImportError:
    pass
else:
    ... # сделать что-то, что требует поддержки SSL

18.2.5.2. Работа на стороне клиента¶Client-side operation

Этот пример создаёт контекст SSL с рекомендуемыми настройками безопасности для клиентских сокетов, включая автоматическую проверку сертификатов:

>>> context = ssl.create_default_context()

Если вы предпочитаете настраивать параметры безопасности самостоятельно, можно создать контекст с нуля (но имейте в виду, что настройки могут оказаться неверными):

>>> context = ssl.SSLContext(ssl.PROTOCOL_SSLv23)
>>> context.verify_mode = ssl.CERT_REQUIRED
>>> context.check_hostname = True
>>> context.load_verify_locations("/etc/ssl/certs/ca-bundle.crt")

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

При использовании контекста для подключения к серверу CERT_REQUIRED проверяет сертификат сервера: он гарантирует, что сертификат сервера был подписан одним из сертификатов ЦС, и проверяет корректность подписи:

>>> 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.python.org'),
                    ('DNS', 'docs.python.org'),
                    ('DNS', 'testpypi.python.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'']

См. обсуждение соображений безопасности ниже.

18.2.5.3. Работа на стороне сервера¶Server-side operation

Для работы сервера обычно нужен сертификат сервера и закрытый ключ, каждый в отдельном файле. Сначала создаётся контекст, содержащий ключ и сертификат, чтобы клиенты могли проверить вашу подлинность. Затем открывается сокет, привязывается к порту, вызывается 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.mydomain.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)
    # пустые данные означают, что клиент закончил работу с нами
    while data:
        if not do_something(connstream, data):
            # будем считать, что do_something возвращает False
            # когда мы закончили с клиентом
            break
        data = connstream.recv(1024)
    # закончили с клиентом

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

18.2.7.1. Наилучшие настройки по умолчанию¶Best defaults

Для использования клиентом, если нет особых требований к политике безопасности, настоятельно рекомендуется использовать функцию 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')

Если для соединения требуется клиентский сертификат, его можно добавить с помощью SSLContext.load_cert_chain().

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

18.2.7.2. Ручная настройка¶Manual settings

context = ssl.SSLContext(ssl.PROTOCOL_SSLv23)
context.options |= ssl.OP_NO_SSLv2
context.options |= ssl.OP_NO_SSLv3

18.2.7.3. Многопроцессность¶Multi-processing

Если этот модуль используется в составе многопроцессного приложения (например, с модулями multiprocessing или concurrent.futures), следует учитывать, что внутренний генератор случайных чисел OpenSSL некорректно обрабатывает порождённые процессы. Приложения должны изменять состояние PRNG родительского процесса, если они используют любые функции SSL с os.fork(). Любой успешный вызов RAND_add(), RAND_bytes() или RAND_pseudo_bytes() считается достаточным.