diff options
Diffstat (limited to 'Doc/library/ssl.rst')
| -rw-r--r-- | Doc/library/ssl.rst | 285 |
1 files changed, 240 insertions, 45 deletions
diff --git a/Doc/library/ssl.rst b/Doc/library/ssl.rst index a2f008346b..07b97715a9 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 ------------------------------------ @@ -186,16 +192,20 @@ instead. .. table:: - ======================== ========= ========= ========== ========= =========== =========== - *client* / **server** **SSLv2** **SSLv3** **TLS** **TLSv1** **TLSv1.1** **TLSv1.2** - ------------------------ --------- --------- ---------- --------- ----------- ----------- - *SSLv2* yes no yes no no no - *SSLv3* no yes yes no no no - *TLS* (*SSLv23*) no yes yes yes yes yes - *TLSv1* no no yes yes no no - *TLSv1.1* no no yes no yes no - *TLSv1.2* no no yes no no yes - ======================== ========= ========= ========== ========= =========== =========== + ======================== ============ ============ ============= ========= =========== =========== + *client* / **server** **SSLv2** **SSLv3** **TLS** **TLSv1** **TLSv1.1** **TLSv1.2** + ------------------------ ------------ ------------ ------------- --------- ----------- ----------- + *SSLv2* yes no no [1]_ no no no + *SSLv3* no yes no [2]_ no no no + *TLS* (*SSLv23*) no [1]_ no [2]_ yes yes yes yes + *TLSv1* no no yes yes no no + *TLSv1.1* no no yes no yes no + *TLSv1.2* no no yes no no yes + ======================== ============ ============ ============= ========= =========== =========== + + .. rubric:: Footnotes + .. [1] :class:`SSLContext` disables SSLv2 with :data:`OP_NO_SSLv2` by default. + .. [2] :class:`SSLContext` disables SSLv3 with :data:`OP_NO_SSLv3` by default. .. note:: @@ -224,7 +234,6 @@ instead. .. versionchanged:: 3.2 New optional argument *ciphers*. - Context creation ^^^^^^^^^^^^^^^^ @@ -279,7 +288,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 +331,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 +518,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 +555,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,20 +601,42 @@ 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_TLS_CLIENT + + Auto-negotiate the the highest protocol version like :data:`PROTOCOL_SSLv23`, + but only support client-side :class:`SSLSocket` connections. The protocol + enables :data:`CERT_REQUIRED` and :attr:`~SSLContext.check_hostname` by + default. + + .. versionadded:: 3.6 + +.. data:: PROTOCOL_TLS_SERVER + + Auto-negotiate the the highest protocol version like :data:`PROTOCOL_SSLv23`, + but only support server-side :class:`SSLSocket` connections. + + .. versionadded:: 3.6 .. data:: PROTOCOL_SSLv23 Alias for data:`PROTOCOL_TLS`. - .. deprecated:: 3.5.3 + .. deprecated:: 3.6 - Use data:`PROTOCOL_TLS` instead. + Use :data:`PROTOCOL_TLS` instead. .. data:: PROTOCOL_SSLv2 @@ -608,7 +649,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,19 +664,19 @@ 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. + protocol :data:`PROTOCOL_TLS` with flags like :data:`OP_NO_SSLv3` instead. .. data:: PROTOCOL_TLSv1 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. + protocol :data:`PROTOCOL_TLS` with flags like :data:`OP_NO_SSLv3` instead. .. data:: PROTOCOL_TLSv1_1 @@ -644,10 +685,10 @@ 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. + protocol :data:`PROTOCOL_TLS` with flags like :data:`OP_NO_SSLv3` instead. .. data:: PROTOCOL_TLSv1_2 @@ -657,10 +698,10 @@ 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. + protocol :data:`PROTOCOL_TLS` with flags like :data:`OP_NO_SSLv3` instead. .. data:: OP_ALL @@ -678,7 +719,7 @@ Constants .. versionadded:: 3.2 - .. deprecated:: 3.5.3 + .. deprecated:: 3.6 SSLv2 is deprecated @@ -691,7 +732,7 @@ Constants .. versionadded:: 3.2 - .. deprecated:: 3.5.3 + .. deprecated:: 3.6 SSLv3 is deprecated @@ -751,6 +792,16 @@ Constants .. versionadded:: 3.3 +.. class:: Options + + :class:`enum.IntFlag` collection of OP_* constants. + +.. data:: OP_NO_TICKET + + Prevent client side from requesting a session ticket. + + .. versionadded:: 3.6 + .. data:: HAS_ALPN Whether the OpenSSL library has built-in support for the *Application-Layer @@ -833,6 +884,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 +908,12 @@ Constants .. versionadded:: 3.4 +.. class:: SSLErrorNumber + + :class:`enum.IntEnum` collection of SSL_ERROR_* constants. + + .. versionadded:: 3.6 + SSL Sockets ----------- @@ -885,7 +948,7 @@ SSL Sockets :ref:`notes on non-blocking sockets <ssl-nonblocking>`. Usually, :class:`SSLSocket` are not created directly, but using the - :func:`wrap_socket` function or the :meth:`SSLContext.wrap_socket` method. + the :meth:`SSLContext.wrap_socket` method. .. versionchanged:: 3.5 The :meth:`sendfile` method was added. @@ -895,6 +958,10 @@ SSL Sockets are received or sent. The socket timeout is now to maximum total duration of the shutdown. + .. deprecated:: 3.6 + It is deprecated to create a :class:`SSLSocket` instance directly, use + :meth:`SSLContext.wrap_socket` to wrap a socket. + SSL sockets also have the following additional methods and attributes: @@ -915,6 +982,9 @@ SSL sockets also have the following additional methods and attributes: The socket timeout is now to maximum total duration to read up to *len* bytes. + .. deprecated:: 3.6 + Use :meth:`~SSLSocket.recv` instead of :meth:`~SSLSocket.read`. + .. method:: SSLSocket.write(buf) Write *buf* to the SSL socket and return the number of bytes written. The @@ -930,6 +1000,9 @@ SSL sockets also have the following additional methods and attributes: The socket timeout is no more reset each time bytes are received or sent. The socket timeout is now to maximum total duration to write *buf*. + .. deprecated:: 3.6 + Use :meth:`~SSLSocket.send` instead of :meth:`~SSLSocket.write`. + .. note:: The :meth:`~SSLSocket.read` and :meth:`~SSLSocket.write` methods are the @@ -1127,6 +1200,19 @@ SSL sockets also have the following additional methods and attributes: .. versionadded:: 3.2 +.. attribute:: SSLSocket.session + + The :class:`SSLSession` for this SSL connection. The session is available + for client and server side sockets after the TLS handshake has been + performed. For client sockets the session can be set before + :meth:`~SSLSocket.do_handshake` has been called to reuse a session. + + .. versionadded:: 3.6 + +.. attribute:: SSLSocket.session_reused + + .. versionadded:: 3.6 + SSL Contexts ------------ @@ -1149,9 +1235,16 @@ 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. + The context is created with secure default values. The options + :data:`OP_NO_COMPRESSION`, :data:`OP_CIPHER_SERVER_PREFERENCE`, + :data:`OP_SINGLE_DH_USE`, :data:`OP_SINGLE_ECDH_USE`, + :data:`OP_NO_SSLv2` (except for :data:`PROTOCOL_SSLv2`), + and :data:`OP_NO_SSLv3` (except for :data:`PROTOCOL_SSLv3`) are + set by default. The initial cipher suite list contains only ``HIGH`` + ciphers, no ``NULL`` ciphers and no ``MD5`` ciphers (except for + :data:`PROTOCOL_SSLv2`). :class:`SSLContext` objects have the following methods and attributes: @@ -1259,6 +1352,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 @@ -1397,7 +1546,7 @@ to speed up repeated connections from the same clients. .. method:: SSLContext.wrap_socket(sock, server_side=False, \ do_handshake_on_connect=True, suppress_ragged_eofs=True, \ - server_hostname=None) + server_hostname=None, session=None) Wrap an existing Python socket *sock* and return an :class:`SSLSocket` object. *sock* must be a :data:`~socket.SOCK_STREAM` socket; other socket @@ -1414,19 +1563,27 @@ to speed up repeated connections from the same clients. quite similarly to HTTP virtual hosts. Specifying *server_hostname* will raise a :exc:`ValueError` if *server_side* is true. + *session*, see :attr:`~SSLSocket.session`. + .. versionchanged:: 3.5 Always allow a server_hostname to be passed, even if OpenSSL does not have SNI. + .. versionchanged:: 3.6 + *session* argument was added. + .. method:: SSLContext.wrap_bio(incoming, outgoing, server_side=False, \ - server_hostname=None) + server_hostname=None, session=None) Create a new :class:`SSLObject` instance by wrapping the BIO objects *incoming* and *outgoing*. The SSL routines will read input data from the incoming BIO and write data to the outgoing BIO. - The *server_side* and *server_hostname* parameters have the same meaning as - in :meth:`SSLContext.wrap_socket`. + The *server_side*, *server_hostname* and *session* parameters have the + same meaning as in :meth:`SSLContext.wrap_socket`. + + .. versionchanged:: 3.6 + *session* argument was added. .. method:: SSLContext.session_stats() @@ -1478,6 +1635,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 +1655,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 @@ -1916,6 +2090,8 @@ provided. - :attr:`~SSLSocket.context` - :attr:`~SSLSocket.server_side` - :attr:`~SSLSocket.server_hostname` + - :attr:`~SSLSocket.session` + - :attr:`~SSLSocket.session_reused` - :meth:`~SSLSocket.read` - :meth:`~SSLSocket.write` - :meth:`~SSLSocket.getpeercert` @@ -1997,6 +2173,22 @@ purpose. It wraps an OpenSSL memory BIO (Basic IO) object: become true after all data currently in the buffer has been read. +SSL session +----------- + +.. versionadded:: 3.6 + +.. class:: SSLSession + + Session object used by :attr:`~SSLSocket.session`. + + .. attribute:: id + .. attribute:: time + .. attribute:: timeout + .. attribute:: ticket_lifetime_hint + .. attribute:: has_ticket + + .. _ssl-security: Security considerations @@ -2063,18 +2255,20 @@ Protocol versions SSL versions 2 and 3 are considered insecure and are therefore dangerous to use. If you want maximum compatibility between clients and servers, it is -recommended to use :const:`PROTOCOL_TLS` as the protocol version and then -disable SSLv2 and SSLv3 explicitly using the :data:`SSLContext.options` -attribute:: +recommended to use :const:`PROTOCOL_TLS_CLIENT` or +:const:`PROTOCOL_TLS_SERVER` as the protocol version. SSLv2 and SSLv3 are +disabled by default. + + >>> client_context = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT) + >>> client_context.options |= ssl.OP_NO_TLSv1 + >>> client_context.options |= ssl.OP_NO_TLSv1_1 - context = ssl.SSLContext(ssl.PROTOCOL_TLS) - context.options |= ssl.OP_NO_SSLv2 - context.options |= ssl.OP_NO_SSLv3 - context.options |= ssl.OP_NO_TLSv1 - context.options |= ssl.OP_NO_TLSv1_1 The SSL context created above will only allow TLSv1.2 and later (if -supported by your system) connections. +supported by your system) connections to a server. :const:`PROTOCOL_TLS_CLIENT` +implies certificate validation and hostname checks by default. You have to +load certificates into the context. + Cipher selection '''''''''''''''' @@ -2085,8 +2279,9 @@ enabled when negotiating a SSL session is possible through 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 <https://www.openssl.org/docs/apps/ciphers.html#CIPHER-LIST-FORMAT>`_. -If you want to check which ciphers are enabled by a given cipher list, use the -``openssl ciphers`` command on your system. +If you want to check which ciphers are enabled by a given cipher list, use +:meth:`SSLContext.get_ciphers` or the ``openssl ciphers`` command on your +system. Multi-processing ^^^^^^^^^^^^^^^^ |