Add docstrings and configuration for SSL

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

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