PEP 748: tlslib - configuration

peps/pep-0748.rst

@@ -252,6 +252,9 @@ backwards-compatibility purposes, new fields are only appended to these objects.
 Existing fields will never be removed, renamed, or reordered. They are split
 between client and server to minimize API confusion.
 
+Client Configuration
+^^^^^^^^^^^^^^^^^^^^
+
 The ``TLSClientConfiguration`` class would be defined by the following code:
 
 .. code-block:: python
@@ -273,7 +276,7 @@ The ``TLSClientConfiguration`` class would be defined by the following code:
             inner_protocols: Sequence[NextProtocol | bytes] | None = None,
             lowest_supported_version: TLSVersion | None = None,
             highest_supported_version: TLSVersion | None = None,
-            trust_store: TrustStore | None = None,
+            trust_store: TrustStore = TrustStore.system(),
         ) -> None:
             if inner_protocols is None:
                 inner_protocols = []
@@ -305,12 +308,87 @@ The ``TLSClientConfiguration`` class would be defined by the following code:
         def highest_supported_version(self) -> TLSVersion | None:
             return self._highest_supported_version
 
+        @property
+        def trust_store(self) -> TrustStore:
+            return self._trust_store
+
+A ``trust_store`` is mandatory and is used to validate the server certificates.
+It uses the system's trust store by default. Insecure connections are only
+possible via the :ref:`insecure` module.
+
+When ``certificate_chain`` is set, it is a single signing chain comprising a
+leaf client certificate including its corresponding private key and optionally a
+list of intermediate certificates. These certificates will be offered to the
+server during the handshake if required.
+
+Server Configuration
+^^^^^^^^^^^^^^^^^^^^
+
+The ``TLSServerConfiguration`` class would be defined by the following code:
+
+.. code-block:: python
+
+    class TLSServerConfiguration:
+        __slots__ = (
+            "_certificate_chain",
+            "_ciphers",
+            "_inner_protocols",
+            "_lowest_supported_version",
+            "_highest_supported_version",
+            "_trust_store",
+        )
+
+        def __init__(
+            self,
+            certificate_chain: Sequence[SigningChain],
+            ciphers: Sequence[CipherSuite] | None = None,
+            inner_protocols: Sequence[NextProtocol | bytes] | None = None,
+            lowest_supported_version: TLSVersion | None = None,
+            highest_supported_version: TLSVersion | None = None,
+            trust_store: TrustStore | None = None,
+        ) -> None:
+            if inner_protocols is None:
+                inner_protocols = []
+
+            self._certificate_chain = certificate_chain
+            self._ciphers = ciphers
+            self._inner_protocols = inner_protocols
+            self._lowest_supported_version = lowest_supported_version
+            self._highest_supported_version = highest_supported_version
+            self._trust_store = trust_store
+
+        @property
+        def certificate_chain(self) -> Sequence[SigningChain]:
+            return self._certificate_chain
+
+        @property
+        def ciphers(self) -> Sequence[CipherSuite | int] | None:
+            return self._ciphers
+
+        @property
+        def inner_protocols(self) -> Sequence[NextProtocol | bytes]:
+            return self._inner_protocols
+
+        @property
+        def lowest_supported_version(self) -> TLSVersion | None:
+            return self._lowest_supported_version
+
+        @property
+        def highest_supported_version(self) -> TLSVersion | None:
+            return self._highest_supported_version
+
         @property
         def trust_store(self) -> TrustStore | None:
             return self._trust_store
 
-The ``TLSServerConfiguration`` object is similar to the client one, except that
-it takes a ``Sequence[SigningChain]`` as the ``certificate_chain`` parameter.
+Server authentication is mandatory, at least one signing chain comprising a leaf
+server certificate including its corresponding private key and optionally a list
+of intermediate certificates. It is possible to set more than a single signing
+chain to support multiple virtual hosts.
+
+A ``trust_store`` is optional. Setting one enables client authentication and
+uses the trust store to validate the client certificates. Leaving it ``None``
+disables client authentication.
 
 Context
 ~~~~~~~
@@ -1072,8 +1150,10 @@ The definitions of the errors are below:
 
 
     class ConfigurationError(TLSError):
-        """An special exception that implementations can use when the provided
-        configuration uses features not supported by that implementation."""
+        """A special exception that implementations can use when the provided
+        configuration uses features not supported by that implementation. Do not
+        use this exception when the provided configuration is invalid, use
+        standard exceptions instead."""
 
 
 Certificates
@@ -1440,6 +1520,8 @@ Note that this function only needs to verify that supported constructors were
 used for the certificates, private keys, and trust store. It does not need to
 parse or retrieve the objects to validate them further.
 
+.. _insecure:
+
 Insecure Usage
 --------------