Lines Matching +full:- +full:validation +full:- +full:settings
1 :mod:`ssl` --- TLS/SSL wrapper for socket objects
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
33 may lead to a false sense of security, as the default settings of the
36 .. include:: ../includes/wasm-notavail.rst
43 :class:`socket.socket` type, and provides a socket-like wrapper that also
50 helps manage settings and certificates, which can then be inherited
71 ------------------------------------
81 settings. The old :func:`wrap_socket` function is deprecated since it is
131 Return a new :class:`SSLContext` object with default settings for
132 the given *purpose*. The settings are chosen by the :mod:`ssl` module,
142 The settings are: :data:`PROTOCOL_TLS_CLIENT` or
156 The protocol, options, cipher and other settings may change to more
160 If your application needs specific settings, you should create a
161 :class:`SSLContext` and apply the settings yourself.
170 use this function but still allow SSL 3.0 connections you can re-enable
206 problem in the higher-level encryption and authentication layer that's
240 A subclass of :exc:`SSLError` raised by a :ref:`non-blocking SSL socket
241 <ssl-nonblocking>` when trying to read or write data, but more data needs
249 A subclass of :exc:`SSLError` raised by a :ref:`non-blocking SSL socket
250 <ssl-nonblocking>` when trying to read or write data, but more data needs
274 A subclass of :exc:`SSLError` raised when certificate validation has
300 Return *num* cryptographically strong pseudo-random bytes. Raises an
317 Return (bytes, is_cryptographic): bytes are *num* pseudo-random bytes,
322 Generated pseudo-random byte sequences will be unique if they are of
324 for non-cryptographic purposes and for certain purposes in cryptographic
338 Return ``True`` if the SSL pseudo-random number generator has been seeded
341 the pseudo-random number generator.
345 Mix the given *bytes* into the SSL pseudo-random number generator. The
351 Writable :term:`bytes-like object` is now accepted.
367 various SSL-based protocols such as FTPS, IMAPS, POPS and others.
386 IDN A-labels such as ``www*.xn--pthon-kva.org`` are still supported,
387 but ``x*.python.org`` no longer matches ``xn--tda.python.org``.
420 2018-01-05 09:34:43
433 Given the address ``addr`` of an SSL-protected server, as a (*hostname*,
434 *port-number*) pair, fetches the server's certificate, and returns it as a
435 PEM-encoded string. If ``ssl_version`` is specified, uses that version of
441 if the validation attempt fails. A timeout can be specified with the
445 This function is now IPv6-compatible.
456 Given a certificate as a DER-encoded blob of bytes, returns a PEM-encoded
461 Given a certificate as an ASCII PEM string, returns a DER-encoded sequence of
471 * :attr:`cafile` - resolved path to cafile or ``None`` if the file doesn't exist,
472 * :attr:`capath` - resolved path to capath or ``None`` if the directory doesn't exist,
473 * :attr:`openssl_cafile_env` - OpenSSL's environment key that points to a cafile,
474 * :attr:`openssl_cafile` - hard coded path to a cafile,
475 * :attr:`openssl_capath_env` - OpenSSL's environment key that points to a capath,
476 * :attr:`openssl_capath` - hard coded path to a capath directory
543 top-level function is limited and creates an insecure client socket
557 it is the default mode. With client-side sockets, just about any
558 cert is accepted. Validation errors, such as untrusted or expired cert,
564 See the discussion of :ref:`ssl-security` below.
571 use :const:`CERT_REQUIRED` for client-side sockets instead.
588 will be raised if no certificate is provided, or if its validation fails.
623 :attr:`SSLContext.load_verify_locations`, validation will fail.
659 accept intermediate CAs in the trust store to be treated as trust-anchors,
660 in the same way as the self-signed root CA certificates. This makes it
682 TLS clients and servers require different default settings for secure
688 Auto-negotiate the highest protocol version that both the client and
689 server support, and configure the context client-side connections. The
697 Auto-negotiate the highest protocol version that both the client and
698 server support, and configure the context server-side connections.
715 ``no-ssl2`` option.
730 ``no-ssl3`` option.
873 Prevents re-use of the same DH key for distinct SSL sessions. This
881 Prevents re-use of the same ECDH key for distinct SSL sessions. This
923 Whether the OpenSSL library has built-in support for the *Application-Layer
930 Whether the OpenSSL library has built-in support not checking subject
938 Whether the OpenSSL library has built-in support for the Elliptic Curve-based
939 Diffie-Hellman key exchange. This should be true unless the feature was
946 Whether the OpenSSL library has built-in support for the *Server Name
953 Whether the OpenSSL library has built-in support for the *Next Protocol
955 Negotiation <https://en.wikipedia.org/wiki/Application-Layer_Protocol_Negotiation>`_.
963 Whether the OpenSSL library has built-in support for the SSL 2.0 protocol.
969 Whether the OpenSSL library has built-in support for the SSL 3.0 protocol.
975 Whether the OpenSSL library has built-in support for the TLS 1.0 protocol.
981 Whether the OpenSSL library has built-in support for the TLS 1.1 protocol.
987 Whether the OpenSSL library has built-in support for the TLS 1.2 protocol.
993 Whether the OpenSSL library has built-in support for the TLS 1.3 protocol.
1039 <https://www.iana.org/assignments/tls-parameters/tls-parameters.xml#tls-parameters-6>`_
1058 be used to create client-side sockets).
1067 be used to create server-side sockets).
1106 -----------
1110 SSL sockets provide the following methods of :ref:`socket-objects`:
1112 - :meth:`~socket.socket.accept()`
1113 - :meth:`~socket.socket.bind()`
1114 - :meth:`~socket.socket.close()`
1115 - :meth:`~socket.socket.connect()`
1116 - :meth:`~socket.socket.detach()`
1117 - :meth:`~socket.socket.fileno()`
1118 - :meth:`~socket.socket.getpeername()`, :meth:`~socket.socket.getsockname()`
1119 - :meth:`~socket.socket.getsockopt()`, :meth:`~socket.socket.setsockopt()`
1120 - :meth:`~socket.socket.gettimeout()`, :meth:`~socket.socket.settimeout()`,
1122 - :meth:`~socket.socket.listen()`
1123 - :meth:`~socket.socket.makefile()`
1124 - :meth:`~socket.socket.recv()`, :meth:`~socket.socket.recv_into()`
1125 (but passing a non-zero ``flags`` argument is not allowed)
1126 - :meth:`~socket.socket.send()`, :meth:`~socket.socket.sendall()` (with
1128 - :meth:`~socket.socket.sendfile()` (but :mod:`os.sendfile` will be used
1129 for plain-text sockets only, else :meth:`~socket.socket.send()` will be used)
1130 - :meth:`~socket.socket.shutdown()`
1134 the specification of normal, OS-level sockets. See especially the
1135 :ref:`notes on non-blocking sockets <ssl-nonblocking>`.
1161 zero-length data no longer fails with a protocol violation error.
1172 :ref:`non-blocking <ssl-nonblocking>` and the read would block.
1174 As at any time a re-negotiation is possible, a call to :meth:`read` can also
1191 :ref:`non-blocking <ssl-nonblocking>` and the write would block.
1193 As at any time a re-negotiation is possible, a call to :meth:`write` can
1206 low-level methods that read and write unencrypted, application-level data
1207 and decrypt/encrypt it to encrypted, wire-level data. These methods
1252 name-value pairs. Here is a real-world example::
1263 'subject': ((('description', '571208-SLe257oHY9fVQ07Z'),),
1279 provided, this method returns the DER-encoded form of the entire certificate
1285 regardless of whether validation was required;
1306 Returns a three-value tuple containing the name of the cipher being used, the
1313 entry of the returned list is a three-value tuple containing the name of the
1326 If the higher-level protocol supports its own compression mechanism,
1327 you can use :data:`OP_NO_COMPRESSION` to disable SSL-level compression.
1331 .. method:: SSLSocket.get_channel_binding(cb_type="tls-unique")
1338 :data:`CHANNEL_BINDING_TYPES` list. Currently only the 'tls-unique' channel
1356 Return the higher-level protocol that was selected during the TLS/SSL
1377 Requests post-handshake authentication (PHA) from a TLS 1.3 client. PHA
1378 can only be initiated for a TLS 1.3 connection from a server-side socket,
1382 The method does not perform a cert exchange immediately. The server-side
1421 A boolean which is ``True`` for server-side sockets and ``False`` for
1422 client-side sockets.
1428 Hostname of the server: :class:`str` type, or ``None`` for server-side
1436 A-label form (``"xn--pythn-mua.org"``), rather than the U-label form
1454 ------------
1458 An SSL context holds various data longer-lived than single SSL connections,
1460 It also manages a cache of SSL sessions for server-side sockets, in order
1481 …------------------------ ------------ ------------ ------------- --------- ----------- -----…
1499 security settings for a given purpose.
1551 :ref:`ssl-certificates` for more information on how the certificate
1558 a string it will be encoded as UTF-8 before using it to decrypt the key.
1564 OpenSSL's built-in password prompting mechanism will be used to
1582 default settings :data:`Purpose.SERVER_AUTH` loads certificates, that are
1601 :ref:`ssl-certificates` for more information about how to arrange the
1610 PEM-encoded certificates or a :term:`bytes-like object` of DER-encoded
1611 certificates. Like with *capath* extra lines around PEM-encoded
1622 the method returns a list of DER-encoded certificates. The returned list
1644 'auth': 'auth-rsa',
1645 'description': 'ECDHE-RSA-AES256-GCM-SHA384 TLSv1.2 Kx=ECDH Au=RSA '
1649 'kea': 'kx-ecdhe',
1650 'name': 'ECDHE-RSA-AES256-GCM-SHA384',
1653 'symmetric': 'aes-256-gcm'},
1656 'auth': 'auth-rsa',
1657 'description': 'ECDHE-RSA-AES128-GCM-SHA256 TLSv1.2 Kx=ECDH Au=RSA '
1661 'kea': 'kx-ecdhe',
1662 'name': 'ECDHE-RSA-AES128-GCM-SHA256',
1665 'symmetric': 'aes-128-gcm'}]
1683 If no cipher can be selected (because compile-time options or other
1701 return the agreed-upon protocol.
1714 <https://en.wikipedia.org/wiki/Application-Layer_Protocol_Negotiation>`_. After a
1716 return the agreed-upon protocol.
1732 is specified in :rfc:`6066` section 3 - Server Name Indication.
1744 name is an IDN A-label (``"xn--pythn-mua.org"``).
1779 IDN-encoded internationalized domain name, the *server_name_callback*
1780 receives a decoded U-label (``"pythön.org"``).
1790 Load the key generation parameters for Diffie-Hellman (DH) key exchange.
1803 Set the curve name for Elliptic Curve-based Diffie-Hellman (ECDH) key
1806 a well-known elliptic curve, for example ``prime256v1`` for a widely
1817 …LS & Perfect Forward Secrecy <https://vincent.bernat.ch/en/blog/2011-ssl-perfect-forward-secrecy>`_
1826 returned SSL socket is tied to the context, its settings and certificates.
1831 server-side or client-side behavior is desired from this socket.
1833 For client-side sockets, the context construction is lazy; if the
1836 server-side sockets, if the socket has no remote peer, it is assumed
1837 to be a listening socket, and the server-side SSL wrapping is
1843 single server to host multiple SSL-based services with distinct certificates,
1872 instead of hard-coded :class:`SSLSocket`.
1898 instead of hard-coded :class:`SSLObject`.
1959 as Wireshark. The log file is opened in append-only mode. Writes are
1968 The attribute is read-only for protocols other than :attr:`PROTOCOL_TLS`,
2017 Enable TLS 1.3 post-handshake client authentication. Post-handshake auth
2022 When enabled on client-side sockets, the client signals the server that
2023 it supports post-handshake authentication.
2025 When enabled on server-side sockets, :attr:`SSLContext.verify_mode` must
2036 is read-only.
2055 for the context. This attribute is read-only.
2089 .. _ssl-certificates:
2092 ------------
2094 Certificates in general are part of a public-key / private-key system. In this
2096 organization) is assigned a unique two-part encryption key. One part of the key
2115 satisfaction of the client or server that requires such validation. The
2116 connection attempt can be set to raise an exception if the validation fails.
2117 Validation is done automatically, by the underlying OpenSSL framework; the
2123 (see :rfc:`1422`), which is a base-64 encoded form wrapped with a header line
2126 -----BEGIN CERTIFICATE-----
2128 -----END CERTIFICATE-----
2138 you get to a certificate which is *self-signed*, that is, a certificate which
2146 -----BEGIN CERTIFICATE-----
2148 -----END CERTIFICATE-----
2149 -----BEGIN CERTIFICATE-----
2151 -----END CERTIFICATE-----
2152 -----BEGIN CERTIFICATE-----
2154 -----END CERTIFICATE-----
2159 If you are going to require validation of the other side of the connection's
2162 these chains concatenated together. For validation, Python will use the first
2176 -----BEGIN RSA PRIVATE KEY-----
2178 -----END RSA PRIVATE KEY-----
2179 -----BEGIN CERTIFICATE-----
2181 -----END CERTIFICATE-----
2183 Self-signed certificates
2186 If you are going to create a server that provides SSL-encrypted connection
2189 certification authority. Another common practice is to generate a self-signed
2193 % openssl req -new -x509 -days 365 -nodes -out cert.pem -keyout cert.pem
2198 -----
2205 -----
2207 State or Province Name (full name) [Some-State]:MyState
2215 The disadvantage of a self-signed certificate is that it is its own root
2221 --------
2236 Client-side operation
2239 This example creates a SSL context with the recommended security settings
2244 If you prefer to tune security settings yourself, you might create
2245 a context from scratch (but beware that you might not get the settings
2249 >>> context.load_verify_locations("/etc/ssl/certs/ca-bundle.crt")
2252 certificates in ``/etc/ssl/certs/ca-bundle.crt``; if not, you'll get an
2256 validation and hostname verification. :attr:`~SSLContext.verify_mode` is
2280 'crlDistributionPoints': ('http://crl3.digicert.com/sha2-ev-server-g1.crl',
2281 'http://crl4.digicert.com/sha2-ev-server-g1.crl'),
2285 (('commonName', 'DigiCert SHA2 Extended Validation Server CA'),)),
2294 (('postalCode', '03894-4801'),),
2325 b'Content-Type: text/html; charset=utf-8',
2326 b'X-Frame-Options: SAMEORIGIN',
2327 b'Content-Length: 45679',
2328 b'Accept-Ranges: bytes',
2331 b'X-Served-By: cache-lcy1134-LCY',
2332 b'X-Cache: HIT',
2333 b'X-Cache-Hits: 11',
2335 b'Strict-Transport-Security: max-age=63072000; includeSubDomains',
2340 See the discussion of :ref:`ssl-security` below.
2343 Server-side operation
2363 method to create a server-side SSL socket for the connection::
2390 the sockets in :ref:`non-blocking mode <ssl-nonblocking>` and use an event loop).
2393 .. _ssl-nonblocking:
2395 Notes on non-blocking sockets
2396 -----------------------------
2399 non-blocking mode. When working with non-blocking sockets, there are
2402 - Most :class:`SSLSocket` methods will raise either
2418 - Calling :func:`~select.select` tells you that the OS-level socket can be
2425 - Conversely, since the SSL layer has its own framing, a SSL socket may
2434 - The SSL handshake itself will be non-blocking: the
2450 The :mod:`asyncio` module supports :ref:`non-blocking SSL sockets
2451 <ssl-nonblocking>` and provides a
2459 ------------------
2466 - SSL protocol handling
2467 - Network IO
2471 used as a drop-in replacement for a regular socket, making it very easy to add
2485 A reduced-scope variant of :class:`SSLSocket` representing an SSL protocol
2490 This class implements an interface on top of a low-level SSL object as
2504 - :attr:`~SSLSocket.context`
2505 - :attr:`~SSLSocket.server_side`
2506 - :attr:`~SSLSocket.server_hostname`
2507 - :attr:`~SSLSocket.session`
2508 - :attr:`~SSLSocket.session_reused`
2509 - :meth:`~SSLSocket.read`
2510 - :meth:`~SSLSocket.write`
2511 - :meth:`~SSLSocket.getpeercert`
2512 - :meth:`~SSLSocket.selected_alpn_protocol`
2513 - :meth:`~SSLSocket.selected_npn_protocol`
2514 - :meth:`~SSLSocket.cipher`
2515 - :meth:`~SSLSocket.shared_ciphers`
2516 - :meth:`~SSLSocket.compression`
2517 - :meth:`~SSLSocket.pending`
2518 - :meth:`~SSLSocket.do_handshake`
2519 - :meth:`~SSLSocket.verify_client_post_handshake`
2520 - :meth:`~SSLSocket.unwrap`
2521 - :meth:`~SSLSocket.get_channel_binding`
2522 - :meth:`~SSLSocket.version`
2527 - Any form of network IO; ``recv()`` and ``send()`` read and write only to
2530 - There is no *do_handshake_on_connect* machinery. You must always manually
2533 - There is no handling of *suppress_ragged_eofs*. All end-of-file conditions
2537 - The method :meth:`~SSLSocket.unwrap` call does not return anything,
2540 - The *server_name_callback* callback passed to
2546 - All IO on an :class:`SSLObject` is :ref:`non-blocking <ssl-nonblocking>`.
2551 - There is no module-level ``wrap_bio()`` call like there is for
2576 A boolean indicating whether the memory BIO is current at the end-of-file
2579 .. method:: MemoryBIO.read(n=-1)
2600 -----------
2615 .. _ssl-security:
2618 -----------------------
2627 validation and hostname checking, and try to choose reasonably secure
2628 protocol and cipher settings.
2643 constructor yourself, it will not have certificate validation nor hostname
2647 Manual settings
2671 (rather than using a higher-level authentication mechanism), you'll also have
2693 implies certificate validation and hostname checks by default. You have to
2700 If you have advanced security requirements, fine-tuning of the ciphers
2705 about the `cipher list format <https://www.openssl.org/docs/man1.1.1/man1/ciphers.html#CIPHER-LIST-…
2710 Multi-processing
2713 If using this module as part of a multi-processed application (using,
2722 .. _ssl-tlsv1_3:
2725 -------
2732 - TLS 1.3 uses a disjunct set of cipher suites. All AES-GCM and
2736 - Session tickets are no longer sent as part of the initial handshake and
2739 - Client-side certificates are also no longer verified during the initial
2743 - TLS 1.3 features like early data, deferred TLS client cert request,
2755 …:rfc:`RFC 1422: Privacy Enhancement for Internet Electronic Mail: Part II: Certificate-Based Key M…
2770 …ayer Security (TLS) Parameters <https://www.iana.org/assignments/tls-parameters/tls-parameters.xml…