diff options
Diffstat (limited to 'Doc/library/ssl.rst')
| -rw-r--r-- | Doc/library/ssl.rst | 137 |
1 files changed, 125 insertions, 12 deletions
diff --git a/Doc/library/ssl.rst b/Doc/library/ssl.rst index 01d86c8..2285237 100644 --- a/Doc/library/ssl.rst +++ b/Doc/library/ssl.rst @@ -49,6 +49,12 @@ For more sophisticated applications, the :class:`ssl.SSLContext` class helps manage settings and certificates, which can then be inherited by SSL sockets created through the :meth:`SSLContext.wrap_socket` method. +.. versionchanged:: 3.6 + + OpenSSL 0.9.8, 1.0.0 and 1.0.1 are deprecated and no longer supported. + In the future the ssl module will require at least OpenSSL 1.0.2 or + 1.1.0. + Functions, Constants, and Exceptions ------------------------------------ @@ -279,7 +285,7 @@ purposes. RC4 was dropped from the default cipher string. - .. versionchanged:: 3.5.3 + .. versionchanged:: 3.6 ChaCha20/Poly1305 was added to the default cipher string. @@ -322,7 +328,7 @@ Random generation .. versionadded:: 3.3 - .. deprecated:: 3.5.3 + .. deprecated:: 3.6 OpenSSL has deprecated :func:`ssl.RAND_pseudo_bytes`, use :func:`ssl.RAND_bytes` instead. @@ -509,6 +515,10 @@ Certificate handling Constants ^^^^^^^^^ + All constants are now :class:`enum.IntEnum` or :class:`enum.IntFlag` collections. + + .. versionadded:: 3.6 + .. data:: CERT_NONE Possible value for :attr:`SSLContext.verify_mode`, or the ``cert_reqs`` @@ -542,6 +552,12 @@ Constants be passed, either to :meth:`SSLContext.load_verify_locations` or as a value of the ``ca_certs`` parameter to :func:`wrap_socket`. +.. class:: VerifyMode + + :class:`enum.IntEnum` collection of CERT_* constants. + + .. versionadded:: 3.6 + .. data:: VERIFY_DEFAULT Possible value for :attr:`SSLContext.verify_flags`. In this mode, certificate @@ -582,18 +598,24 @@ Constants .. versionadded:: 3.4.4 +.. class:: VerifyFlags + + :class:`enum.IntFlag` collection of VERIFY_* constants. + + .. versionadded:: 3.6 + .. data:: PROTOCOL_TLS Selects the highest protocol version that both the client and server support. Despite the name, this option can select "TLS" protocols as well as "SSL". - .. versionadded:: 3.5.3 + .. versionadded:: 3.6 .. data:: PROTOCOL_SSLv23 Alias for data:`PROTOCOL_TLS`. - .. deprecated:: 3.5.3 + .. deprecated:: 3.6 Use data:`PROTOCOL_TLS` instead. @@ -608,7 +630,7 @@ Constants SSL version 2 is insecure. Its use is highly discouraged. - .. deprecated:: 3.5.3 + .. deprecated:: 3.6 OpenSSL has removed support for SSLv2. @@ -623,7 +645,7 @@ Constants SSL version 3 is insecure. Its use is highly discouraged. - .. deprecated:: 3.5.3 + .. deprecated:: 3.6 OpenSSL has deprecated all version specific protocols. Use the default protocol data:`PROTOCOL_TLS` with flags like data:`OP_NO_SSLv3` instead. @@ -632,7 +654,7 @@ Constants Selects TLS version 1.0 as the channel encryption protocol. - .. deprecated:: 3.5.3 + .. deprecated:: 3.6 OpenSSL has deprecated all version specific protocols. Use the default protocol data:`PROTOCOL_TLS` with flags like data:`OP_NO_SSLv3` instead. @@ -644,7 +666,7 @@ Constants .. versionadded:: 3.4 - .. deprecated:: 3.5.3 + .. deprecated:: 3.6 OpenSSL has deprecated all version specific protocols. Use the default protocol data:`PROTOCOL_TLS` with flags like data:`OP_NO_SSLv3` instead. @@ -657,7 +679,7 @@ Constants .. versionadded:: 3.4 - .. deprecated:: 3.5.3 + .. deprecated:: 3.6 OpenSSL has deprecated all version specific protocols. Use the default protocol data:`PROTOCOL_TLS` with flags like data:`OP_NO_SSLv3` instead. @@ -678,7 +700,7 @@ Constants .. versionadded:: 3.2 - .. deprecated:: 3.5.3 + .. deprecated:: 3.6 SSLv2 is deprecated @@ -691,7 +713,7 @@ Constants .. versionadded:: 3.2 - .. deprecated:: 3.5.3 + .. deprecated:: 3.6 SSLv3 is deprecated @@ -751,6 +773,12 @@ Constants .. versionadded:: 3.3 +.. class:: Options + + :class:`enum.IntFlag` collection of OP_* constants. + + .. versionadded:: 3.6 + .. data:: HAS_ALPN Whether the OpenSSL library has built-in support for the *Application-Layer @@ -833,6 +861,12 @@ Constants .. versionadded:: 3.4 +.. class:: AlertDescription + + :class:`enum.IntEnum` collection of ALERT_DESCRIPTION_* constants. + + .. versionadded:: 3.6 + .. data:: Purpose.SERVER_AUTH Option for :func:`create_default_context` and @@ -851,6 +885,12 @@ Constants .. versionadded:: 3.4 +.. class:: SSLErrorNumber + + :class:`enum.IntEnum` collection of SSL_ERROR_* constants. + + .. versionadded:: 3.6 + SSL Sockets ----------- @@ -1149,7 +1189,7 @@ to speed up repeated connections from the same clients. :func:`create_default_context` lets the :mod:`ssl` module choose security settings for a given purpose. - .. versionchanged:: 3.5.3 + .. versionchanged:: 3.6 :data:`PROTOCOL_TLS` is the default value. @@ -1259,6 +1299,62 @@ to speed up repeated connections from the same clients. .. versionadded:: 3.4 +.. method:: SSLContext.get_ciphers() + + Get a list of enabled ciphers. The list is in order of cipher priority. + See :meth:`SSLContext.set_ciphers`. + + Example:: + + >>> ctx = ssl.SSLContext(ssl.PROTOCOL_SSLv23) + >>> ctx.set_ciphers('ECDHE+AESGCM:!ECDSA') + >>> ctx.get_ciphers() # OpenSSL 1.0.x + [{'alg_bits': 256, + 'description': 'ECDHE-RSA-AES256-GCM-SHA384 TLSv1.2 Kx=ECDH Au=RSA ' + 'Enc=AESGCM(256) Mac=AEAD', + 'id': 50380848, + 'name': 'ECDHE-RSA-AES256-GCM-SHA384', + 'protocol': 'TLSv1/SSLv3', + 'strength_bits': 256}, + {'alg_bits': 128, + 'description': 'ECDHE-RSA-AES128-GCM-SHA256 TLSv1.2 Kx=ECDH Au=RSA ' + 'Enc=AESGCM(128) Mac=AEAD', + 'id': 50380847, + 'name': 'ECDHE-RSA-AES128-GCM-SHA256', + 'protocol': 'TLSv1/SSLv3', + 'strength_bits': 128}] + + On OpenSSL 1.1 and newer the cipher dict contains additional fields:: + >>> ctx.get_ciphers() # OpenSSL 1.1+ + [{'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'}] + + Availability: OpenSSL 1.0.2+ + + .. versionadded:: 3.6 + .. method:: SSLContext.set_default_verify_paths() Load a set of default "certification authority" (CA) certificates from @@ -1478,6 +1574,12 @@ to speed up repeated connections from the same clients. to set options, not to clear them. Attempting to clear an option (by resetting the corresponding bits) will raise a ``ValueError``. + .. versionchanged:: 3.6 + :attr:`SSLContext.options` returns :class:`Options` flags: + + >>> ssl.create_default_context().options + <Options.OP_ALL|OP_NO_SSLv3|OP_NO_SSLv2|OP_NO_COMPRESSION: 2197947391> + .. attribute:: SSLContext.protocol The protocol version chosen when constructing the context. This attribute @@ -1492,12 +1594,23 @@ to speed up repeated connections from the same clients. .. versionadded:: 3.4 + .. versionchanged:: 3.6 + :attr:`SSLContext.verify_flags` returns :class:`VerifyFlags` flags: + + >>> ssl.create_default_context().verify_flags + <VerifyFlags.VERIFY_X509_TRUSTED_FIRST: 32768> + .. attribute:: SSLContext.verify_mode Whether to try to verify other peers' certificates and how to behave if verification fails. This attribute must be one of :data:`CERT_NONE`, :data:`CERT_OPTIONAL` or :data:`CERT_REQUIRED`. + .. versionchanged:: 3.6 + :attr:`SSLContext.verify_mode` returns :class:`VerifyMode` enum: + + >>> ssl.create_default_context().verify_mode + <VerifyMode.CERT_REQUIRED: 2> .. index:: single: certificates |