update documentation

docs/source/changelog/TBR_2.1.0.rst

@@ -10,6 +10,13 @@ Certificate Revocation Lists
   :class:`~django_ca.models.CertificateRevocationList` model. This makes CRL functionality more robust, as
   clearing the cache will no longer cause an error.
 
+*******************
+OCSP responder keys
+*******************
+
+* Private keys for OCSP responders are now stored using configurable backends, just like private keys for
+  certificate authorities. See :ref:`ocsp_key_backends` for more information.
+
 **********************
 Command-line utilities
 **********************

docs/source/include/config/settings_default_ca_ocsp_key_backends.py

@@ -0,0 +1,6 @@
+CA_OCSP_KEY_BACKENDS = {
+    "default": {
+        "BACKEND": "django_ca.key_backends.storages.StoragesOCSPBackend",
+        "OPTIONS": {"storage_alias": "django-ca"},
+    },
+}

docs/source/include/config/settings_default_ca_ocsp_key_backends.yaml

@@ -0,0 +1,5 @@
+CA_OCSP_KEY_BACKENDS:
+    default:
+        BACKEND: django_ca.key_backends.storages.StoragesOCSPBackend
+        OPTIONS:
+            storage_alias: django-ca

docs/source/include/config/settings_hsm_ocsp_key_backend.py

@@ -0,0 +1,10 @@
+CA_OCSP_KEY_BACKENDS = {
+    "default": {
+        "BACKEND": "django_ca.key_backends.hsm.HSMOCSPBackend",
+        "OPTIONS": {
+            "library_path": "/usr/lib/softhsm/libsofthsm2.so",
+            "token": "my_token_label",
+            "user_pin": "secret_user_pin",
+        },
+    },
+}

docs/source/include/config/settings_hsm_ocsp_key_backend.yaml

@@ -0,0 +1,7 @@
+CA_OCSP_KEY_BACKENDS:
+    default:
+        BACKEND: django_ca.key_backends.hsm.HSMOCSPBackend
+        OPTIONS:
+            library_path: /usr/lib/softhsm/libsofthsm2.so
+            token: my_token_label
+            user_pin: secret_user_pin

docs/source/include/config/settings_storages_ocsp_key_backend.py

@@ -0,0 +1,13 @@
+CA_OCSP_KEY_BACKENDS = {
+    "default": {
+        "BACKEND": "django_ca.key_backends.storages.StoragesOCSPBackend",
+        "OPTIONS": {
+            "storage_alias": "django-ca",
+            # Store OCSP keys in a sub-path of the configured storage backend.
+            # By default, keys are stored in the "ocsp" subfolder.
+            # "path": "ocsp",
+            # Disable private key encryption
+            # "encrypt_private_key": False,
+        },
+    },
+}

docs/source/include/config/settings_storages_ocsp_key_backend.yaml

@@ -0,0 +1,12 @@
+CA_OCSP_KEY_BACKENDS:
+    default:
+        BACKEND: django_ca.key_backends.storages.StoragesOCSPBackend
+        OPTIONS:
+            storage_alias: django-ca
+
+            # Store OCSP keys in a sub-path of the configured storage backend.
+            # By default, keys are stored in the "ocsp" subfolder.
+            #path: ocsp
+
+            # Disable private key encryption
+            #encrypt_private_key: False

docs/source/key_backends.rst

@@ -164,3 +164,73 @@ default backend):
 .. code-block:: console
 
    user@host:~$ python manage.py init_ca --so-pin=1234 --user-pin="" ...
+
+.. _ocsp_key_backends:
+
+*****************
+OCSP Key backends
+*****************
+
+Just like for certificate authorities, **django-ca** allows you to store private keys for OCSP responder
+certificates using different backends. By default, private keys are stored on the file system, but they can
+also be stored in a Hardware Security Module.
+
+Note that the OCSP key storage method does not have to match the method used for storing the private key of
+the certificate authority.
+
+There are two things fundamentally different about OCSP key backends compared to CA key backends:
+
+1. The *private* key must be accessible by the web server to sign OCSP responses. This might be tricky in
+   setups where the private key of the certificate authority is stored on a different host from the web
+   server.
+2. The web server must be able to use the private key non-interactively. That means that all information to
+   access the private key (including e.g. passwords) must either be in settings or the database.
+
+Configuring the OCSP key backend
+================================
+
+The available key backends can be configured using the :ref:`CA_OCSP_KEY_BACKENDS
+<settings-ca-ocsp-key-backends>` option.
+
+The OCSP key backend that is used for a specific certificate authority can be configured using the admin
+interface or with the `--ocsp-key-backend` option to :command:`manage.py init_ca`,
+:command:`manage.py edit_ca` and :command:`manage.py import_ca`. Note that when you change the backend,
+you must manually regenerate OCSP keys (e.g. using :command:`manage.py regenerate_ocsp_keys`.
+
+:spelling:word:`Storages` OCSP key backend
+==========================================
+
+This backend is equivalent to the :ref:`storages_backend` backend and stores keys on the file system.
+
+By default, private keys are encrypted with a random password before written to the files system, with the
+private key stored in the database. This provides a modest security benefit in some setups.
+
+The backend takes three options: ``storage_alias`` has the same meaning as in the :spelling:word:`storages`
+backend, ``path`` defines a sub-directory where to store keys. The ``encrypt_private_key`` can be set to false
+to disable encryption of private keys with a random password:
+
+.. tab:: Python
+
+   .. literalinclude:: /include/config/settings_storages_ocsp_key_backend.py
+      :language: python
+
+.. tab:: YAML
+
+   .. literalinclude:: /include/config/settings_storages_ocsp_key_backend.yaml
+      :language: YAML
+
+HSM (Hardware Security Module) OCSP key backend
+===============================================
+
+The HSM OCSP key backend is equivalent to the :ref:`hsm_backend`. It takes the same options as the normal
+backend:
+
+.. tab:: Python
+
+   .. literalinclude:: /include/config/settings_hsm_ocsp_key_backend.py
+      :language: python
+
+.. tab:: YAML
+
+   .. literalinclude:: /include/config/settings_hsm_ocsp_key_backend.yaml
+      :language: YAML

docs/source/python/key_backends.rst

@@ -164,4 +164,11 @@ Implementations
 
 .. autoclass:: django_ca.key_backends.hsm.HSMBackend
 
+
+
+OCSP key backends
+=================
+
 .. autoclass:: django_ca.key_backends.storages.StoragesOCSPBackend
+
+.. autoclass:: django_ca.key_backends.hsm.HSMOCSPBackend

docs/source/settings.rst

@@ -405,6 +405,23 @@ CA_OCSP_URLS
 
    Configuration for OCSP responders. See :doc:`/ocsp` for more information.
 
+.. _settings-ca-ocsp-key-backends:
+
+CA_OCSP_KEY_BACKENDS
+   Default:
+
+   .. tab:: Python
+
+      .. literalinclude:: /include/config/settings_default_ca_ocsp_key_backends.py
+         :language: python
+
+   .. tab:: YAML
+
+      .. literalinclude:: /include/config/settings_default_ca_ocsp_key_backends.yaml
+         :language: YAML
+
+    Configuration for storing OCSP keys. See :ref:`ocsp_key_backends` for more information.
+
 .. _settings-ca-ocsp-responder-certificate-renewal:
 
 CA_OCSP_RESPONDER_CERTIFICATE_RENEWAL