diff --git a/peps/pep-0748.rst b/peps/pep-0748.rst index b3f919f5aa6..333c24fe432 100644 --- a/peps/pep-0748.rst +++ b/peps/pep-0748.rst @@ -94,18 +94,18 @@ provide TLS functionality that is not so strongly tied to OpenSSL. It also proposes to update standard library modules to use only the interface exposed by these protocol classes wherever possible. There are three goals here: -1. To provide a common API surface for both core and third-party developers to +#. To provide a common API surface for both core and third-party developers to target their TLS implementations to. This allows TLS developers to provide interfaces that can be used by most Python code, and allows network developers to have an interface that they can target that will work with a wide range of TLS implementations. -1. To provide an API that has few or no OpenSSL-specific concepts leak through. +#. To provide an API that has few or no OpenSSL-specific concepts leak through. The :mod:`ssl` module today has a number of warts caused by leaking OpenSSL concepts through to the API: the new protocol classes would remove those specific concepts. -1. To provide a path for the core development team to make OpenSSL one of many +#. To provide a path for the core development team to make OpenSSL one of many possible TLS implementations, rather than requiring that it be present on a system in order for Python to have TLS support. @@ -116,37 +116,37 @@ Interfaces There are several interfaces that require standardization. Those interfaces are: -1. Configuring TLS, currently implemented by the :class:`~ssl.SSLContext` class +#. Configuring TLS, currently implemented by the :class:`~ssl.SSLContext` class in the :mod:`ssl` module. -1. Providing an in-memory buffer for doing in-memory encryption or decryption +#. Providing an in-memory buffer for doing in-memory encryption or decryption with no actual I/O (necessary for asynchronous I/O models), currently implemented by the :class:`~ssl.SSLObject` class in the :mod:`ssl` module. -1. Wrapping a socket object, currently implemented by the +#. Wrapping a socket object, currently implemented by the :class:`~ssl.SSLSocket` class in the :mod:`ssl` module. -1. Applying TLS configuration to the wrapping objects in (2) and (3). Currently +#. Applying TLS configuration to the wrapping objects in (2) and (3). Currently this is also implemented by the SSLContext class in the :mod:`ssl` module. -1. Specifying TLS cipher suites. There is currently no code for doing this in +#. Specifying TLS cipher suites. There is currently no code for doing this in the standard library: instead, the standard library uses OpenSSL cipher suite strings. -1. Specifying application-layer protocols that can be negotiated during the TLS +#. Specifying application-layer protocols that can be negotiated during the TLS handshake. -1. Specifying TLS versions. +#. Specifying TLS versions. -1. Reporting errors to the caller, currently implemented by the +#. Reporting errors to the caller, currently implemented by the :class:`~ssl.SSLError` class in the :mod:`ssl` module. -1. Specifying certificates to load, either as client or server certificates. +#. Specifying certificates to load, either as client or server certificates. -1. Specifying which trust database should be used to validate certificates +#. Specifying which trust database should be used to validate certificates presented by a remote peer. -1. Finding a way to get hold of these interfaces at run time. +#. Finding a way to get hold of these interfaces at run time. For the sake of simplicity, this PEP proposes to remove interfaces (3) and (4), and replace them by a simpler interface that returns a socket which ensures that @@ -223,10 +223,10 @@ The ``TLSServerConfiguration`` and ``TLSClientConfiguration`` concrete classes define objects that can hold and manage TLS configuration. The goals of these classes are as follows: -1. To provide a method of specifying TLS configuration that avoids the risk of +#. To provide a method of specifying TLS configuration that avoids the risk of errors in typing (this excludes the use of a simple dictionary). -1. To provide an object that can be safely compared to other configuration +#. To provide an object that can be safely compared to other configuration objects to detect changes in TLS configuration, for use with the SNI callback.