diff --git a/asab/tls.py b/asab/tls.py index 1f179dd23..e2e1f1e9e 100644 --- a/asab/tls.py +++ b/asab/tls.py @@ -3,6 +3,17 @@ class SSLContextBuilder(Configurable): + """ + Class for creating SSL context from a configuration. + + Examples: + + ```python + ssl_context_builder = asab.tls.SSLContextBuilder(config_section) + ssl_context = ssl_context_builder.build(protocol=ssl.PROTOCOL_TLS_CLIENT) + # ssl_context is later used as a parameter when making HTTP requests + ``` + """ ConfigDefaults = { 'cert': '', # The certfile string must be the path to a PEM file containing the certificate as well as any number of CA certificates needed to establish the certificate’s authenticity. @@ -22,15 +33,19 @@ class SSLContextBuilder(Configurable): 'options': '', } - def build(self, protocol=ssl.PROTOCOL_TLS): - ''' - ## SSL Server - ssl_context = self.SSLContextBuilder.build() + def build(self, protocol=ssl.PROTOCOL_TLS) -> ssl.SSLContext: + """ + Create SSL Context for the specified protocol. + + Allowed `protocol` values: - ## SSL Client + - ssl.PROTOCOL_TLS + - ssl.PROTOCOL_TLS_CLIENT: used for the client + - ssl.PROTOCOL_TLS_SERVER: used for the server - ssl_context = self.SSLContextBuilder.build(ssl.PROTOCOL_TLS_CLIENT) - ''' + Args: + protocol: TLS protocol used for the communication. + """ ctx = ssl.SSLContext(protocol=protocol) ctx.options |= ssl.OP_NO_SSLv2 diff --git a/docs/reference/web/tls.md b/docs/reference/web/tls.md index 1486e26c2..9260b51cf 100644 --- a/docs/reference/web/tls.md +++ b/docs/reference/web/tls.md @@ -1,7 +1,25 @@ # Transport Layer Security +!!! warning + :material-excavator: This part of ASAB is currently under construction. :material-excavator: + **Transport Layer Security** protocol (*TLS*, also known as *"Secure Sockets Layer"*) is a cryptographic protocol that provides communication security over a computer network, so that the web servers can use **HTTPS**. For adding the HTTPS to ASAB web applications, there is a `asab.tls.SSLContextBuilder` class that is connected to [`asab.web.WebContainer`](/reference/web/web-server/#asab.web.WebContainer). +## Configuration options + +| Option | Meaning | +| --- | --- | +| `cert` | Path to a PEM file containing the certificate as well as any number of CA certificates needed to establish the certificate’s authenticity. | +| `key` | Path to a file containing the private key. If not provided, the private key will be taken from the file specified in `cert`.| +| `cafile` | Path to a file containing the CA. | +| `capath` | Path to a directory containing CA certificates. | +| `cadata` | String containing CA certificates in PEM format. | +| `ciphers` | String specifying the allowed SSL/TLS ciphers for the connection. | +| `dh_params` | Path to a file containing Diffie-Hellman parameters for key exchange. | +| `verify_mode` | Control the verification mode for peer certificates. Possible values are `'CERT_NONE'` (no certificate verification), `'CERT_OPTIONAL'` (verification but not required), and `'CERT_REQUIRED'` (verification required). | +| `check_hostname` | :material-excavator: | +| `options` | :material-excavator: | + ::: asab.tls.SSLContextBuilder