implement support for hardware security modules (HSMs)

.github/workflows/faketime.yml

@@ -10,7 +10,7 @@ jobs:
     name: libfaketime test
     steps:
       - name: Install APT dependencies
-        run: sudo apt-get install -y firefox faketime
+        run: sudo apt-get install -y firefox softhsm2 faketime
 
       - name: Acquire sources
         uses: actions/[email protected]

.github/workflows/tests.yml

@@ -24,7 +24,7 @@ jobs:
     name: Python ${{ matrix.python-version }}, Django ${{ matrix.django-version }}, cryptography ${{ matrix.cryptography-version }}, pydantic ${{ matrix.pydantic-version }}
     steps:
       - name: Install APT dependencies
-        run: sudo apt-get install -y firefox
+        run: sudo apt-get install -y firefox softhsm2
 
       - name: Acquire sources
         uses: actions/[email protected]

Dockerfile

@@ -29,7 +29,7 @@ RUN --mount=type=cache,target=/root/.cache/pip/http \
     pip install --no-warn-script-location --ignore-installed --prefix=/install \
         -r requirements/requirements-docker.txt \
         -r requirements-pinned.txt \
-        -e .[celery,redis,mysql,psycopg3,yaml]
+        -e .[celery,hsm,mysql,psycopg3,redis,yaml]
 
 # Finally, copy sources
 COPY ca/ ca/

README.md

@@ -24,6 +24,7 @@ Documentation is available at https://django-ca.readthedocs.org/.
 1. Set up a secure local certificate authority in just a few minutes.
 2. Certificate revocation via CRLs and OCSP.
 3. Certificate issuance via ACMEv2, command line or web interface.
+4. **Preliminary** support for hardware security modules (HSMs).
 4. Management via command line and/or via Django's admin interface.
 5. Get email notifications about certificates about to expire.
 6. Written in Python 3.9+, Django 4.2+ and cryptography 42+.

ca/ca/test_settings.py

@@ -14,8 +14,12 @@
 """Test settings for the django-ca project."""
 
 import json
+import os
+from datetime import datetime, timezone
 from pathlib import Path
 
+from django.utils.crypto import get_random_string
+
 # Base paths in this project
 BASE_DIR = Path(__file__).resolve().parent.parent  # ca/
 
@@ -186,6 +190,14 @@
     _fixture_data = json.load(stream)
 
 
+# PKCS11 settings
+_timestamp = datetime.now(tz=timezone.utc).strftime("%Y%m%d%H%M%S")
+PKCS11_PATH = os.environ.get("PKCS11_LIBRARY", "/usr/lib/softhsm/libsofthsm2.so")
+PKCS11_TOKEN_LABEL = f"pytest.{_timestamp}.{get_random_string(8)}"
+PKCS11_SO_PIN = "so-pin-1234"
+PKCS11_USER_PIN = "user-pin-1234"
+
+
 CA_KEY_BACKENDS = {
     "default": {
         "BACKEND": "django_ca.key_backends.storages.StoragesBackend",
@@ -195,6 +207,14 @@
         "BACKEND": "django_ca.key_backends.storages.StoragesBackend",
         "OPTIONS": {"storage_alias": "secondary"},
     },
+    "hsm": {
+        "BACKEND": "django_ca.key_backends.hsm.HSMBackend",
+        "OPTIONS": {
+            "library_path": PKCS11_PATH,
+            "token": PKCS11_TOKEN_LABEL,
+            "user_pin": PKCS11_USER_PIN,
+        },
+    },
 }
 
 # Custom settings

ca/django_ca/constants.py

@@ -574,6 +574,18 @@ class ExtendedKeyUsageOID(_ExtendedKeyUsageOID):
     ed448.Ed448PublicKey,
     rsa.RSAPublicKey,
 )
+PUBLIC_KEY_TYPE_MAPPING: MappingProxyType[ParsableKeyType, type[CertificateIssuerPublicKeyTypes]] = (
+    MappingProxyType(
+        {
+            "DSA": dsa.DSAPublicKey,
+            "EC": ec.EllipticCurvePublicKey,
+            "Ed25519": ed25519.Ed25519PublicKey,
+            "Ed448": ed448.Ed448PublicKey,
+            "RSA": rsa.RSAPublicKey,
+        }
+    )
+)
+
 
 #: Tuple of supported private key types.
 PRIVATE_KEY_TYPES: tuple[type[CertificateIssuerPrivateKeyTypes], ...] = (

ca/django_ca/key_backends/base.py

@@ -225,13 +225,12 @@ def get_use_parent_private_key_options(
 
     @abc.abstractmethod
     def get_use_private_key_options(
-        self, ca: Optional["CertificateAuthority"], options: dict[str, Any]
+        self, ca: "CertificateAuthority", options: dict[str, Any]
     ) -> UsePrivateKeyOptionsTypeVar:
         """Get options to use the private key of a certificate authority.
 
         The returned model will be used for the certificate authority `ca`. You can pass it as extra context
-        to influence model validation. If `ca` is ``None``, it indicates that the CA is currently being
-        created via :command:`manage.py init_ca`.
+        to influence model validation.
 
         `options` is the dictionary of arguments to :command:`manage.py init_ca` (including default values).
         The key backend is expected to be able to sign certificates and CRLs using the options provided here.
@@ -285,6 +284,7 @@ def store_private_key(
         self,
         ca: "CertificateAuthority",
         key: CertificateIssuerPrivateKeyTypes,
+        certificate: x509.Certificate,
         options: StorePrivateKeyOptionsTypeVar,
     ) -> None:
         """Store a private key for the certificate authority.

ca/django_ca/key_backends/hsm/__init__.py

@@ -0,0 +1,18 @@
+# This file is part of django-ca (https://github.com/mathiasertl/django-ca).
+#
+# django-ca is free software: you can redistribute it and/or modify it under the terms of the GNU General
+# Public License as published by the Free Software Foundation, either version 3 of the License, or (at your
+# option) any later version.
+#
+# django-ca is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the
+# implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+# for more details.
+#
+# You should have received a copy of the GNU General Public License along with django-ca. If not, see
+# <http://www.gnu.org/licenses/>.
+
+"""HSM backend module."""
+
+from django_ca.key_backends.hsm.backend import HSMBackend
+
+__all__ = ("HSMBackend",)