Lines Matching +full:no +full:- +full:tls
1 :mod:`ssl` --- TLS/SSL wrapper for socket objects
5 :synopsis: TLS/SSL wrapper for socket objects
14 .. index:: TLS, SSL, Transport Layer Security, Secure Sockets Layer
16 --------------
20 sockets, both client-side and server-side. This module uses the OpenSSL
32 Don't use this module without reading the :ref:`ssl-security`. Doing so
38 general information about TLS, SSL, and certificates, the reader is referred to
42 :class:`socket.socket` type, and provides a socket-like wrapper that also
57 OpenSSL 0.9.8, 1.0.0 and 1.0.1 are deprecated and no longer supported.
70 ------------------------------------
81 both inefficient and has no support for server name indication (SNI) and
169 use this function but still allow SSL 3.0 connections you can re-enable
205 problem in the higher-level encryption and authentication layer that's
239 A subclass of :exc:`SSLError` raised by a :ref:`non-blocking SSL socket
240 <ssl-nonblocking>` when trying to read or write data, but more data needs
248 A subclass of :exc:`SSLError` raised by a :ref:`non-blocking SSL socket
249 <ssl-nonblocking>` when trying to read or write data, but more data needs
259 there is no easy way to inspect the original errno number.
299 Return *num* cryptographically strong pseudo-random bytes. Raises an
316 Return (bytes, is_cryptographic): bytes are *num* pseudo-random bytes,
321 Generated pseudo-random byte sequences will be unique if they are of
323 for non-cryptographic purposes and for certain purposes in cryptographic
337 Return ``True`` if the SSL pseudo-random number generator has been seeded
340 the pseudo-random number generator.
344 Mix the given *bytes* into the SSL pseudo-random number generator. The
350 Writable :term:`bytes-like object` is now accepted.
366 various SSL-based protocols such as FTPS, IMAPS, POPS and others.
385 IDN A-labels such as ``www*.xn--pthon-kva.org`` are still supported,
386 but ``x*.python.org`` no longer matches ``xn--tda.python.org``.
393 The function is no longer used to TLS connections. Hostname matching
397 in that segment. Partial wildcards like ``www*.example.com`` are no
419 2018-01-05 09:34:43
426 previously. Return an integer (no fractions of a second in the
432 Given the address ``addr`` of an SSL-protected server, as a (*hostname*,
433 *port-number*) pair, fetches the server's certificate, and returns it as a
434 PEM-encoded string. If ``ssl_version`` is specified, uses that version of
444 This function is now IPv6-compatible.
455 Given a certificate as a DER-encoded blob of bytes, returns a PEM-encoded
460 Given a certificate as an ASCII PEM string, returns a DER-encoded sequence of
470 * :attr:`cafile` - resolved path to cafile or ``None`` if the file doesn't exist,
471 * :attr:`capath` - resolved path to capath or ``None`` if the directory doesn't exist,
472 * :attr:`openssl_cafile_env` - OpenSSL's environment key that points to a cafile,
473 * :attr:`openssl_cafile` - hard coded path to a cafile,
474 * :attr:`openssl_capath_env` - OpenSSL's environment key that points to a capath,
475 * :attr:`openssl_capath` - hard coded path to a capath directory
545 top-level function is limited and creates an insecure client socket
559 it is the default mode. With client-side sockets, just about any
561 are ignored and do not abort the TLS/SSL handshake.
563 In server mode, no certificate is requested from the client, so the client
566 See the discussion of :ref:`ssl-security` below.
573 use :const:`CERT_REQUIRED` for client-side sockets instead.
577 perform TLS client cert authentication. If the client chooses to send
579 the TLS handshake.
590 will be raised if no certificate is provided, or if its validation fails.
597 With server socket, this mode provides mandatory TLS client cert
624 ancestor CA). If no proper CRL has been loaded with
661 accept intermediate CAs in the trust store to be treated as trust-anchors,
662 in the same way as the self-signed root CA certificates. This makes it
678 Despite the name, this option can select both "SSL" and "TLS" protocols.
684 TLS clients and servers require different default settings for secure
685 communication. The generic TLS protocol constant is deprecated in
690 Auto-negotiate the highest protocol version that both the client and
691 server support, and configure the context client-side connections. The
699 Auto-negotiate the highest protocol version that both the client and
700 server support, and configure the context server-side connections.
748 Selects TLS version 1.0 as the channel encryption protocol.
756 Selects TLS version 1.1 as the channel encryption protocol.
767 Selects TLS version 1.2 as the channel encryption protocol.
847 the protocol version. TLS 1.3 is available with OpenSSL 1.1.1 or later.
869 This option has no effect on client sockets and SSLv2 server sockets.
875 Prevents re-use of the same DH key for distinct SSL sessions. This
883 Prevents re-use of the same ECDH key for distinct SSL sessions. This
891 Send dummy Change Cipher Spec (CCS) messages in TLS 1.3 handshake to make
892 a TLS 1.3 connection look more like a TLS 1.2 connection.
917 Ignore unexpected shutdown of TLS connections.
925 Whether the OpenSSL library has built-in support for the *Application-Layer
926 Protocol Negotiation* TLS extension as described in :rfc:`7301`.
932 Whether the OpenSSL library has built-in support not checking subject
940 Whether the OpenSSL library has built-in support for the Elliptic Curve-based
941 Diffie-Hellman key exchange. This should be true unless the feature was
948 Whether the OpenSSL library has built-in support for the *Server Name
955 Whether the OpenSSL library has built-in support for the *Next Protocol
957 Negotiation <https://en.wikipedia.org/wiki/Application-Layer_Protocol_Negotiation>`_.
965 Whether the OpenSSL library has built-in support for the SSL 2.0 protocol.
971 Whether the OpenSSL library has built-in support for the SSL 3.0 protocol.
977 Whether the OpenSSL library has built-in support for the TLS 1.0 protocol.
983 Whether the OpenSSL library has built-in support for the TLS 1.1 protocol.
989 Whether the OpenSSL library has built-in support for the TLS 1.2 protocol.
995 Whether the OpenSSL library has built-in support for the TLS 1.3 protocol.
1001 List of supported TLS channel binding types. Strings in this list
1040 Alert Descriptions from :rfc:`5246` and others. The `IANA TLS Alert Registry
1041 <https://www.iana.org/assignments/tls-parameters/tls-parameters.xml#tls-parameters-6>`_
1060 be used to create client-side sockets).
1069 be used to create server-side sockets).
1081 :class:`enum.IntEnum` collection of SSL and TLS versions for
1089 The minimum or maximum supported SSL or TLS version. These are magic
1091 TLS/SSL versions.
1099 SSL 3.0 to TLS 1.3.
1108 -----------
1112 SSL sockets provide the following methods of :ref:`socket-objects`:
1114 - :meth:`~socket.socket.accept()`
1115 - :meth:`~socket.socket.bind()`
1116 - :meth:`~socket.socket.close()`
1117 - :meth:`~socket.socket.connect()`
1118 - :meth:`~socket.socket.detach()`
1119 - :meth:`~socket.socket.fileno()`
1120 - :meth:`~socket.socket.getpeername()`, :meth:`~socket.socket.getsockname()`
1121 - :meth:`~socket.socket.getsockopt()`, :meth:`~socket.socket.setsockopt()`
1122 - :meth:`~socket.socket.gettimeout()`, :meth:`~socket.socket.settimeout()`,
1124 - :meth:`~socket.socket.listen()`
1125 - :meth:`~socket.socket.makefile()`
1126 - :meth:`~socket.socket.recv()`, :meth:`~socket.socket.recv_into()`
1127 (but passing a non-zero ``flags`` argument is not allowed)
1128 - :meth:`~socket.socket.send()`, :meth:`~socket.socket.sendall()` (with
1130 - :meth:`~socket.socket.sendfile()` (but :mod:`os.sendfile` will be used
1131 for plain-text sockets only, else :meth:`~socket.socket.send()` will be used)
1132 - :meth:`~socket.socket.shutdown()`
1134 However, since the SSL (and TLS) protocol has its own framing atop
1136 the specification of normal, OS-level sockets. See especially the
1137 :ref:`notes on non-blocking sockets <ssl-nonblocking>`.
1163 zero-length data no longer fails with a protocol violation error.
1174 :ref:`non-blocking <ssl-nonblocking>` and the read would block.
1176 As at any time a re-negotiation is possible, a call to :meth:`read` can also
1180 The socket timeout is no more reset each time bytes are received or sent.
1193 :ref:`non-blocking <ssl-nonblocking>` and the write would block.
1195 As at any time a re-negotiation is possible, a call to :meth:`write` can
1199 The socket timeout is no more reset each time bytes are received or sent.
1208 low-level methods that read and write unencrypted, application-level data
1209 and decrypt/encrypt it to encrypted, wire-level data. These methods
1227 The socket timeout is no more reset each time bytes are received or sent.
1232 function :func:`match_hostname` is no longer used. In case OpenSSL
1234 a TLS alert message is send to the peer.
1238 If there is no certificate for the peer on the other end of the connection,
1254 name-value pairs. Here is a real-world example::
1265 'subject': ((('description', '571208-SLe257oHY9fVQ07Z'),),
1281 provided, this method returns the DER-encoded form of the entire certificate
1304 IPv6 address strings no longer have a trailing new line.
1308 Returns a three-value tuple containing the name of the cipher being used, the
1310 bits being used. If no connection has been established, returns ``None``.
1315 entry of the returned list is a three-value tuple containing the name of the
1318 ``None`` if no connection has been established or the socket is a client
1328 If the higher-level protocol supports its own compression mechanism,
1329 you can use :data:`OP_NO_COMPRESSION` to disable SSL-level compression.
1333 .. method:: SSLSocket.get_channel_binding(cb_type="tls-unique")
1340 :data:`CHANNEL_BINDING_TYPES` list. Currently only the 'tls-unique' channel
1348 Return the protocol that was selected during the TLS handshake. If
1358 Return the higher-level protocol that was selected during the TLS/SSL
1371 Performs the SSL shutdown handshake, which removes the TLS layer from the
1379 Requests post-handshake authentication (PHA) from a TLS 1.3 client. PHA
1380 can only be initiated for a TLS 1.3 connection from a server-side socket,
1381 after the initial TLS handshake and with PHA enabled on both sides, see
1384 The method does not perform a cert exchange immediately. The server-side
1388 If any precondition isn't met (e.g. not TLS 1.3, PHA not enabled), an
1392 Only available with OpenSSL 1.1.1 and TLS 1.3 enabled. Without TLS 1.3
1400 as a string, or ``None`` is no secure connection is established.
1423 A boolean which is ``True`` for server-side sockets and ``False`` for
1424 client-side sockets.
1430 Hostname of the server: :class:`str` type, or ``None`` for server-side
1438 A-label form (``"xn--pythn-mua.org"``), rather than the U-label form
1444 for client and server side sockets after the TLS handshake has been
1456 ------------
1460 An SSL context holds various data longer-lived than single SSL connections,
1462 It also manages a cache of SSL sessions for server-side sockets, in order
1482 …*client* / **server** **SSLv2** **SSLv3** **TLS** [3]_ **TLSv1** **TLSv1.1** **TLSv…
1483 …------------------------ ------------ ------------ ------------- --------- ----------- -----…
1484 … *SSLv2* yes no no [1]_ no no no
1485 … *SSLv3* no yes no [2]_ no no no
1486 … *TLS* (*SSLv23*) [3]_ no [1]_ no [2]_ yes yes yes yes
1487 … *TLSv1* no no yes yes no no
1488 … *TLSv1.1* no no yes no yes no
1489 … *TLSv1.2* no no yes no no yes
1495 .. [3] TLS 1.3 protocol will be available with :data:`PROTOCOL_TLS` in
1496 OpenSSL >= 1.1.1. There is no dedicated PROTOCOL constant for just
1497 TLS 1.3.
1511 ciphers, no ``NULL`` ciphers and no ``MD5`` ciphers (except for
1526 :data:`PROTOCOL_TLS_SERVER` use TLS 1.2 as minimum TLS version.
1553 :ref:`ssl-certificates` for more information on how the certificate
1558 encrypted and a password is necessary. It will be called with no arguments,
1560 a string it will be encoded as UTF-8 before using it to decrypt the key.
1563 encrypted and no password is needed.
1566 OpenSSL's built-in password prompting mechanism will be used to
1585 flagged and trusted for TLS web server authentication (client side
1603 :ref:`ssl-certificates` for more information about how to arrange the
1612 PEM-encoded certificates or a :term:`bytes-like object` of DER-encoded
1613 certificates. Like with *capath* extra lines around PEM-encoded
1624 the method returns a list of DER-encoded certificates. The returned list
1646 'auth': 'auth-rsa',
1647 'description': 'ECDHE-RSA-AES256-GCM-SHA384 TLSv1.2 Kx=ECDH Au=RSA '
1651 'kea': 'kx-ecdhe',
1652 'name': 'ECDHE-RSA-AES256-GCM-SHA384',
1655 'symmetric': 'aes-256-gcm'},
1658 'auth': 'auth-rsa',
1659 'description': 'ECDHE-RSA-AES128-GCM-SHA256 TLSv1.2 Kx=ECDH Au=RSA '
1663 'kea': 'kx-ecdhe',
1664 'name': 'ECDHE-RSA-AES128-GCM-SHA256',
1667 'symmetric': 'aes-128-gcm'}]
1675 there's no easy way to know whether this method succeeds: no error is
1676 returned if no certificates are to be found. When the OpenSSL library is
1685 If no cipher can be selected (because compile-time options or other
1693 TLS 1.3 cipher suites cannot be disabled with
1698 Specify which protocols the socket should advertise during the SSL/TLS
1703 return the agreed-upon protocol.
1712 Specify which protocols the socket should advertise during the SSL/TLS
1716 <https://en.wikipedia.org/wiki/Application-Layer_Protocol_Negotiation>`_. After a
1718 return the agreed-upon protocol.
1731 Register a callback function that will be called after the TLS Client Hello
1732 handshake message has been received by the SSL/TLS server when the TLS client
1734 is specified in :rfc:`6066` section 3 - Server Name Indication.
1743 (or :const:`None` if the TLS Client Hello does not contain a server name)
1746 name is an IDN A-label (``"xn--pythn-mua.org"``).
1753 Due to the early negotiation phase of the TLS connection, only limited
1758 the TLS connection has progressed beyond the TLS Client Hello and therefore
1762 TLS negotiation to continue. If a TLS failure is required, a constant
1764 returned. Other return values will result in a TLS fatal error with
1767 If an exception is raised from the *sni_callback* function the TLS
1768 connection will terminate with a fatal TLS alert message
1781 IDN-encoded internationalized domain name, the *server_name_callback*
1782 receives a decoded U-label (``"pythön.org"``).
1784 If there is an decoding error on the server name, the TLS connection will
1785 terminate with an :const:`ALERT_DESCRIPTION_INTERNAL_ERROR` fatal TLS
1792 Load the key generation parameters for Diffie-Hellman (DH) key exchange.
1805 Set the curve name for Elliptic Curve-based Diffie-Hellman (ECDH) key
1808 a well-known elliptic curve, for example ``prime256v1`` for a widely
1819 …`SSL/TLS & Perfect Forward Secrecy <https://vincent.bernat.im/en/blog/2011-ssl-perfect-forward-sec…
1833 server-side or client-side behavior is desired from this socket.
1835 For client-side sockets, the context construction is lazy; if the
1838 server-side sockets, if the socket has no remote peer, it is assumed
1839 to be a listening socket, and the server-side SSL wrapping is
1845 single server to host multiple SSL-based services with distinct certificates,
1874 instead of hard-coded :class:`SSLSocket`.
1900 instead of hard-coded :class:`SSLObject`.
1958 Write TLS keys to a keylog file, whenever key material is generated or
1961 as Wireshark. The log file is opened in append-only mode. Writes are
1969 TLS version. The value defaults to :attr:`TLSVersion.MAXIMUM_SUPPORTED`.
1970 The attribute is read-only for protocols other than :attr:`PROTOCOL_TLS`,
1976 and TLS versions of the context. The implementation does not prevent
1980 will not be able to establish a TLS 1.2 connection.
1993 Control the number of TLS 1.3 session tickets of a
1994 :attr:`PROTOCOL_TLS_SERVER` context. The setting has no impact on TLS
2019 Enable TLS 1.3 post-handshake client authentication. Post-handshake auth
2020 is disabled by default and a server can only request a TLS client
2022 request a TLS client certificate at any time after the handshake.
2024 When enabled on client-side sockets, the client signals the server that
2025 it supports post-handshake authentication.
2027 When enabled on server-side sockets, :attr:`SSLContext.verify_mode` must
2038 is read-only.
2050 The flag had no effect with OpenSSL before version 1.1.1k. Python 3.8.9,
2057 for the context. This attribute is read-only.
2091 .. _ssl-certificates:
2094 ------------
2096 Certificates in general are part of a public-key / private-key system. In this
2098 organization) is assigned a unique two-part encryption key. One part of the key
2125 (see :rfc:`1422`), which is a base-64 encoded form wrapped with a header line
2128 -----BEGIN CERTIFICATE-----
2130 -----END CERTIFICATE-----
2140 you get to a certificate which is *self-signed*, that is, a certificate which
2148 -----BEGIN CERTIFICATE-----
2150 -----END CERTIFICATE-----
2151 -----BEGIN CERTIFICATE-----
2153 -----END CERTIFICATE-----
2154 -----BEGIN CERTIFICATE-----
2156 -----END CERTIFICATE-----
2178 -----BEGIN RSA PRIVATE KEY-----
2180 -----END RSA PRIVATE KEY-----
2181 -----BEGIN CERTIFICATE-----
2183 -----END CERTIFICATE-----
2185 Self-signed certificates
2188 If you are going to create a server that provides SSL-encrypted connection
2191 certification authority. Another common practice is to generate a self-signed
2195 % openssl req -new -x509 -days 365 -nodes -out cert.pem -keyout cert.pem
2200 -----
2207 -----
2209 State or Province Name (full name) [Some-State]:MyState
2217 The disadvantage of a self-signed certificate is that it is its own root
2218 certificate, and no one else will have it in their cache of known (and trusted)
2223 --------
2238 Client-side operation
2251 >>> context.load_verify_locations("/etc/ssl/certs/ca-bundle.crt")
2254 certificates in ``/etc/ssl/certs/ca-bundle.crt``; if not, you'll get an
2282 'crlDistributionPoints': ('http://crl3.digicert.com/sha2-ev-server-g1.crl',
2283 'http://crl4.digicert.com/sha2-ev-server-g1.crl'),
2296 (('postalCode', '03894-4801'),),
2327 b'Content-Type: text/html; charset=utf-8',
2328 b'X-Frame-Options: SAMEORIGIN',
2329 b'Content-Length: 45679',
2330 b'Accept-Ranges: bytes',
2333 b'X-Served-By: cache-lcy1134-LCY',
2334 b'X-Cache: HIT',
2335 b'X-Cache-Hits: 11',
2337 b'Strict-Transport-Security: max-age=63072000; includeSubDomains',
2342 See the discussion of :ref:`ssl-security` below.
2345 Server-side operation
2365 method to create a server-side SSL socket for the connection::
2392 the sockets in :ref:`non-blocking mode <ssl-nonblocking>` and use an event loop).
2395 .. _ssl-nonblocking:
2397 Notes on non-blocking sockets
2398 -----------------------------
2401 non-blocking mode. When working with non-blocking sockets, there are
2404 - Most :class:`SSLSocket` methods will raise either
2420 - Calling :func:`~select.select` tells you that the OS-level socket can be
2427 - Conversely, since the SSL layer has its own framing, a SSL socket may
2436 - The SSL handshake itself will be non-blocking: the
2452 The :mod:`asyncio` module supports :ref:`non-blocking SSL sockets
2453 <ssl-nonblocking>` and provides a
2461 ------------------
2468 - SSL protocol handling
2469 - Network IO
2473 used as a drop-in replacement for a regular socket, making it very easy to add
2487 A reduced-scope variant of :class:`SSLSocket` representing an SSL protocol
2492 This class implements an interface on top of a low-level SSL object as
2497 This class has no public constructor. An :class:`SSLObject` instance
2506 - :attr:`~SSLSocket.context`
2507 - :attr:`~SSLSocket.server_side`
2508 - :attr:`~SSLSocket.server_hostname`
2509 - :attr:`~SSLSocket.session`
2510 - :attr:`~SSLSocket.session_reused`
2511 - :meth:`~SSLSocket.read`
2512 - :meth:`~SSLSocket.write`
2513 - :meth:`~SSLSocket.getpeercert`
2514 - :meth:`~SSLSocket.selected_alpn_protocol`
2515 - :meth:`~SSLSocket.selected_npn_protocol`
2516 - :meth:`~SSLSocket.cipher`
2517 - :meth:`~SSLSocket.shared_ciphers`
2518 - :meth:`~SSLSocket.compression`
2519 - :meth:`~SSLSocket.pending`
2520 - :meth:`~SSLSocket.do_handshake`
2521 - :meth:`~SSLSocket.verify_client_post_handshake`
2522 - :meth:`~SSLSocket.unwrap`
2523 - :meth:`~SSLSocket.get_channel_binding`
2524 - :meth:`~SSLSocket.version`
2529 - Any form of network IO; ``recv()`` and ``send()`` read and write only to
2532 - There is no *do_handshake_on_connect* machinery. You must always manually
2535 - There is no handling of *suppress_ragged_eofs*. All end-of-file conditions
2539 - The method :meth:`~SSLSocket.unwrap` call does not return anything,
2542 - The *server_name_callback* callback passed to
2548 - All IO on an :class:`SSLObject` is :ref:`non-blocking <ssl-nonblocking>`.
2553 - There is no module-level ``wrap_bio()`` call like there is for
2578 A boolean indicating whether the memory BIO is current at the end-of-file
2581 .. method:: MemoryBIO.read(n=-1)
2602 -----------
2617 .. _ssl-security:
2620 -----------------------
2639 (220, b'2.0.0 Ready to start TLS')
2669 Hostname matchings is now performed by OpenSSL. Python no longer uses
2673 (rather than using a higher-level authentication mechanism), you'll also have
2702 If you have advanced security requirements, fine-tuning of the ciphers
2707 …cipher list format <https://www.openssl.org/docs/manmaster/man1/ciphers.html#CIPHER-LIST-FORMAT>`_.
2712 Multi-processing
2715 If using this module as part of a multi-processed application (using,
2724 .. _ssl-tlsv1_3:
2726 TLS 1.3
2727 -------
2731 The TLS 1.3 protocol behaves slightly differently than previous version
2732 of TLS/SSL. Some new TLS 1.3 features are not yet available.
2734 - TLS 1.3 uses a disjunct set of cipher suites. All AES-GCM and
2736 :meth:`SSLContext.set_ciphers` cannot enable or disable any TLS 1.3
2738 - Session tickets are no longer sent as part of the initial handshake and
2740 are not compatible with TLS 1.3.
2741 - Client-side certificates are also no longer verified during the initial
2745 - TLS 1.3 features like early data, deferred TLS client cert request,
2754 …`SSL/TLS Strong Encryption: An Introduction <https://httpd.apache.org/docs/trunk/en/ssl/ssl_intro.…
2757 …:rfc:`RFC 1422: Privacy Enhancement for Internet Electronic Mail: Part II: Certificate-Based Key M…
2766 :rfc:`RFC 5246: The Transport Layer Security (TLS) Protocol Version 1.2 <5246>`
2769 :rfc:`RFC 6066: Transport Layer Security (TLS) Extensions <6066>`
2772 …`IANA TLS: Transport Layer Security (TLS) Parameters <https://www.iana.org/assignments/tls-paramet…
2775 …:rfc:`RFC 7525: Recommendations for Secure Use of Transport Layer Security (TLS) and Datagram Tran…
2778 `Mozilla's Server Side TLS recommendations <https://wiki.mozilla.org/Security/Server_Side_TLS>`_