[feature] Added X.509 Certificate Generator Templates

docs/developer/extending.rst

@@ -342,6 +342,7 @@ Once you have created the models, add the following to your
     CONFIG_TEMPLATE_MODEL = "sample_config.Template"
     CONFIG_VPN_MODEL = "sample_config.Vpn"
     CONFIG_VPNCLIENT_MODEL = "sample_config.VpnClient"
+    CONFIG_DEVICECERTIFICATE_MODEL = "sample_config.DeviceCertificate"
     CONFIG_ORGANIZATIONCONFIGSETTINGS_MODEL = "sample_config.OrganizationConfigSettings"
     CONFIG_ORGANIZATIONLIMITS_MODEL = "sample_config.OrganizationLimits"
     CONFIG_WHOISINFO_MODEL = "sample_config.WHOISInfo"

docs/index.rst

@@ -37,6 +37,7 @@ the OpenWISP architecture.
     user/intro.rst
     user/device-config-status.rst
     user/templates.rst
+    user/certificate-templates.rst
     user/variables.rst
     user/device-groups.rst
     user/push-operations.rst

docs/user/certificate-templates.rst

@@ -0,0 +1,291 @@
+X.509 Certificate Generator Templates
+=====================================
+
+.. contents:: **Table of Contents**:
+    :depth: 3
+    :local:
+
+Introduction
+------------
+
+A Certificate Template is a specific type of :doc:`Configuration Template
+</controller/user/templates>` that allows OpenWISP to centrally manage and
+automatically provision X.509 client certificates for devices.
+
+Unlike VPN templates, which generate certificates as part of a larger
+tunnel configuration (like OpenVPN or WireGuard), Certificate Templates
+are standalone. They are ideal for use cases where devices need
+cryptographic identities for external services, such as:
+
+- Mutual TLS (mTLS) authentication against internal APIs.
+- Cryptographically signed device identities for 802.1x or captive
+  portals.
+- Secure payload signing.
+
+.. _certificate_templates_setup:
+
+Setting Up a Certificate Template
+---------------------------------
+
+To create a Certificate Template, navigate to the Templates section in the
+OpenWISP admin and set the **Type** to :guilabel:`Certificate generator`
+(``cert``). This will reveal the certificate-specific configuration
+fields.
+
+.. image:: https://raw.githubusercontent.com/openwisp/openwisp-controller/docs/certificate-templates/certificate-template.png
+    :target: https://raw.githubusercontent.com/openwisp/openwisp-controller/docs/certificate-templates/certificate-template.png
+    :alt: Certificate Template admin form
+
+:guilabel:`Certificate Authority` (required)
+    The Certificate Authority that will sign the X.509 certificates
+    generated for each device using the template. The CA must belong to
+    the same organization as the template (or be shared).
+
+:guilabel:`Blueprint Certificate` (optional)
+    An existing, unassigned, non-revoked X.509 certificate that will be
+    used as a *blueprint*. The extensions, key length, digest, and other
+    subject fields of the blueprint are copied to each newly generated
+    certificate. The blueprint must be signed by the selected
+    :guilabel:`Certificate Authority` and must not already be bound to a
+    device.
+
+:guilabel:`Automatic certificate provisioning` (``auto_cert``)
+    When enabled (which is the default behavior), an X.509 certificate is
+    automatically created and signed by the template's CA the moment the
+    template is assigned to a device configuration.
+
+.. _certificate_templates_validation:
+
+Validation Rules
+----------------
+
+To ensure cryptographic integrity and prevent misconfigurations,
+Certificate Templates enforce the following validation rules upon saving:
+
+- A :guilabel:`Certificate Authority` is strictly required.
+- The :guilabel:`Blueprint Certificate` **must** be signed by the selected
+  :guilabel:`Certificate Authority`. Saving with a mismatched pair will
+  fail.
+- The :guilabel:`Blueprint Certificate` must be *unassigned* (it cannot be
+  currently bound to any device). The blueprint dropdown in the admin
+  panel is pre-filtered to show only unassigned, non-revoked certificates.
+- Both the :guilabel:`Certificate Authority` and the :guilabel:`Blueprint
+  Certificate` must belong to the same organization as the template, or be
+  marked as shared.
+
+.. _certificate_templates_lifecycle:
+
+Provisioning and Revocation Lifecycle
+-------------------------------------
+
+Certificate Templates are tightly coupled with the device configuration
+lifecycle to ensure certificates are only valid while the device is
+actively authorized to use them.
+
+**When assigned to a device:** When a Certificate Template is added to a
+device configuration, a ``DeviceCertificate`` relationship is established.
+If ``auto_cert`` is enabled, an X.509 certificate is generated and signed
+in the same database transaction:
+
+- The certificate's subject and extensions are copied from the
+  :guilabel:`Blueprint Certificate` (or the CA defaults).
+- The certificate is augmented with two custom OpenWISP OIDs that
+  cryptographically identify the device (see
+  :ref:`certificate_templates_oid_extensions`).
+- The certificate's :guilabel:`Common Name` is generated using the
+  :ref:`OPENWISP_CONTROLLER_COMMON_NAME_FORMAT
+  <openwisp_controller_common_name_format>` setting, suffixed with a
+  unique slug to prevent collisions.
+
+**When removed from a device:** When the Certificate Template is
+unassigned from a device configuration, the ``DeviceCertificate``
+relationship is deleted. Crucially, the underlying X.509 certificate is
+**automatically revoked** (provided it was created via
+``auto_cert=True``). This ensures that compromised or decommissioned
+devices immediately lose their cryptographic access.
+
+**On certificate renewal:** When an administrator triggers renewal of a
+standalone certificate through the PKI endpoint (e.g.,
+``/api/v1/controller/cert/{id}/renew/``), the ``Cert.renew()`` method
+generates a new serial number, updates the validity dates, and regenerates
+the certificate and private key. The existing ``certificate_updated``
+signal handler (registered in ``config/apps.py``) detects the
+``DeviceCertificate`` relationship and calls
+:meth:`~openwisp_controller.config.base.config.Config.update_status_if_checksum_changed`
+on the associated device configuration, ensuring the device pulls the
+renewed certificate on its next check-in.
+
+**On device property changes :** When a device's **hostname** or **MAC
+address** is modified, OpenWISP automatically detects the change and
+triggers an asynchronous task. The task revokes the existing certificate
+and generates a new one with the updated Common Name and custom OID
+values. A ``generic_message`` notification is sent to the admin informing
+them of the regeneration. This behavior can be disabled by setting
+:ref:`OPENWISP_CONTROLLER_REGENERATE_CERTS_ON_HARDWARE_CHANGE
+<OPENWISP_CONTROLLER_REGENERATE_CERTS_ON_HARDWARE_CHANGE>` to ``False``.
+
+.. _certificate_templates_active_lock:
+
+Active Template Mutation Lock
+-----------------------------
+
+To prevent breaking the cryptographic binding with devices that are
+already using a template, certain destructive changes are blocked while
+the template is assigned to *active* or *activating* device
+configurations.
+
+You **cannot** change the following on an actively used template:
+
+- :guilabel:`Type` (only changing a ``cert`` template to a different type
+  is blocked)
+- :guilabel:`Certificate Authority`
+- :guilabel:`Blueprint Certificate`
+
+If you need to update these core parameters, you must first unassign the
+Certificate Template from all affected device configurations (or
+deactivate the devices), apply your template changes, and then reassign
+them.
+
+.. _certificate_templates_oid_extensions:
+
+Custom Device Identification OIDs
+---------------------------------
+
+To allow external systems to uniquely and securely identify devices by
+parsing their X.509 certificates, every automatically generated
+certificate includes two custom ASN.1 Object Identifiers (OIDs):
+
+- ``1.3.6.1.4.1.65901.1``: Contains the MAC address of the device
+  (``ASN1:UTF8:string:<mac_address>``).
+- ``1.3.6.1.4.1.65901.2``: Contains the UUID of the device
+  (``ASN1:UTF8:string:<device_id>``).
+
+These OIDs are appended securely to the certificate in addition to any
+extensions inherited from the :guilabel:`Blueprint Certificate`.
+
+.. _certificate_templates_context:
+
+Using Certificates in Configuration (Context Injection)
+-------------------------------------------------------
+
+To deploy the certificate to the device, administrators must reference the
+automatically generated variables within the template's JSON configuration
+payload.
+
+To prevent variable collisions when multiple Certificate Templates are
+assigned to a single device, OpenWISP namespaces the Jinja2 variables
+using the template's 32-character hexadecimal UUID (the UUID with dashes
+removed).
+
+The following variables are dynamically injected into the configuration
+context:
+
+- ``{{ cert_<template_uuid_hex>_pem }}``: The public certificate.
+- ``{{ cert_<template_uuid_hex>_key }}``: The private key.
+- ``{{ cert_<template_uuid_hex>_uuid }}``: The UUID of the generated
+  certificate.
+- ``{{ cert_<template_uuid_hex>_path }}``: The file system path where the
+  certificate file will be installed on the device.
+- ``{{ cert_<template_uuid_hex>_key_path }}``: The file system path where
+  the private key file will be installed on the device.
+
+**Workflow Example:**
+
+1. Create a Certificate Template and click **Save and continue editing**
+   to generate its UUID.
+2. Note the UUID from the URL (e.g.,
+   ``d7d20eb8-b3c8-420c-9103-401e7960cfb3``).
+3. Strip the dashes to get the hex string
+   (``d7d20eb8b3c8420c9103401e7960cfb3``).
+4. Add the following JSON payload to write the certificate to the device's
+   filesystem:
+
+.. code-block:: json
+
+    {
+        "files": [
+            {
+                "path": "/etc/ssl/certs/device-cert.pem",
+                "mode": "0600",
+                "contents": "{{ cert_d7d20eb8b3c8420c9103401e7960cfb3_pem }}"
+            },
+            {
+                "path": "/etc/ssl/private/device-key.pem",
+                "mode": "0600",
+                "contents": "{{ cert_d7d20eb8b3c8420c9103401e7960cfb3_key }}"
+            }
+        ]
+    }
+
+When this template is assigned to a device, OpenWISP will automatically
+replace the variables with the exact, unique X.509 certificate and private
+key generated for that specific device.
+
+.. _certificate_templates_api:
+
+Certificate Templates via the REST API
+--------------------------------------
+
+The Certificate Template architecture is fully supported by the
+:doc:`OpenWISP REST API </controller/user/rest-api>`:
+
+- The ``type`` field accepts the ``cert`` enumeration.
+- ``ca`` and ``blueprint_cert`` are writable fields on the
+  ``/api/v1/controller/template/`` endpoint.
+- The ``blueprint_cert`` field is strictly filtered. Attempting to pass
+  the UUID of an already-assigned or revoked certificate will return a
+  ``400 Bad Request``.
+- The Active Mutation Lock is enforced at the serializer level: attempting
+  to patch the ``type``, ``ca``, or ``blueprint_cert`` of an actively
+  deployed template will return a ``400 Bad Request``.
+
+Additionally, you can trigger the automated creation and revocation
+lifecycle by patching the ``config.templates`` array on the ``PATCH
+/api/v1/controller/device/{id}/`` endpoint.
+
+.. _certificate_templates_limitations:
+
+Supported Options and Limitations
+---------------------------------
+
+**Blueprint fields that are cloned**
+
+When a blueprint certificate is specified, the following properties are
+copied to each newly generated certificate:
+
+- ``key_length``
+- ``digest``
+- ``country_code``, ``state``, ``city``
+- ``organization_name``, ``organizational_unit_name``
+- ``email``
+- Extensions (custom OIDs and named extensions like ``nsCertType``)
+
+If no blueprint certificate is provided, these properties fall back to the
+defaults of the selected Certificate Authority.
+
+**Custom OID injection**
+
+Every auto-generated certificate automatically receives two custom ASN.1
+Object Identifiers that uniquely identify the device (see
+:ref:`certificate_templates_oid_extensions`). These are appended in
+addition to any extensions inherited from the blueprint.
+
+**Out of scope**
+
+The following features are **not** managed by certificate templates:
+
+- **Subject Alternative Names (SAN):** SAN extensions are not
+  automatically injected. If a SAN is required, it must be included in the
+  blueprint certificate's extensions and will be copied to generated
+  certificates.
+- **OCSP / CRL distribution points:** These must be configured at the CA
+  level in ``django-x509`` and are not managed per-template.
+- **Let's Encrypt / ACME integration:** Automated ACME or public CA
+  enrollment is not supported. Certificate Templates are designed for
+  private CAs managed within OpenWISP's PKI module.
+- **Certificate expiration management:** Auto-renewal upon expiry is not
+  built in; renewal must be triggered manually through the admin or API
+  endpoint.
+- **Non-``auto_cert`` certificates:** If ``auto_cert`` is disabled, no
+  certificate is automatically generated on template assignment. The
+  administrator is responsible for manual provisioning.

docs/user/intro.rst

@@ -35,6 +35,8 @@ following features:
 - **VPN management**: automatically provision VPN tunnel configurations,
   including cryptographic keys and IP addresses, e.g.: :doc:`OpenVPN
   </user/vpn>`, :doc:`WireGuard <wireguard>`
+- :doc:`Certificate Templates <certificate-templates>`: automatically
+  generate and manage X.509 client certificates for devices
 - :doc:`whois`: display information about the public IP address used by
   devices to communicate with OpenWISP
 - :doc:`import-export`

docs/user/rest-api.rst

@@ -1112,7 +1112,7 @@ You can filter a list of templates based on their backend using the
     GET /api/v1/controller/template/?backend={backend}
 
 You can filter a list of templates based on their type using the ``type``
-(e.g. vpn or generic).
+(e.g. vpn, cert or generic).
 
 .. code-block:: text
 

docs/user/settings.rst

@@ -308,9 +308,9 @@ levels of OpenWISP, see `netjsonconfig context: configuration variables
 The default value of the ``auto_cert`` field for new ``Template`` objects.
 
 The ``auto_cert`` field is valid only for templates which have ``type``
-set to ``VPN`` and indicates whether configuration regarding the VPN
-tunnel is provisioned automatically to each device using the template,
-e.g.:
+set to ``VPN`` or ``cert`` and indicates whether configuration regarding
+the VPN tunnel (or the x509 certificate) is provisioned automatically to
+each device using the template, e.g.:
 
 - when using OpenVPN, new `x509 <https://tools.ietf.org/html/rfc5280>`_
   certificates will be generated automatically using the same CA assigned
@@ -330,6 +330,24 @@ The objects that are automatically created will also be removed when they
 are not needed anymore (e.g.: when the VPN template is removed from a
 configuration object).
 
+``OPENWISP_CONTROLLER_REGENERATE_CERTS_ON_HARDWARE_CHANGE``
+-----------------------------------------------------------
+
+============ ========
+**type**:    ``bool``
+**default**: ``True``
+============ ========
+
+When a device's name or MAC address changes, OpenWISP automatically
+revokes the existing X.509 client certificates and provisions new ones
+with the updated identity attributes. Set this to ``False`` to disable
+this automatic regeneration.
+
+.. note::
+
+    The regeneration only applies to certificates created via Certificate
+    Templates with ``auto_cert`` enabled.
+
 ``OPENWISP_CONTROLLER_CERT_PATH``
 ---------------------------------
 
@@ -350,13 +368,13 @@ default).
 **default**: ``{mac_address}-{name}``
 ============ ========================
 
-Defines the format of the ``common_name`` attribute of VPN client
-certificates that are automatically created when using VPN templates which
-have ``auto_cert`` set to ``True``. A unique slug generated using
-`shortuuid <https://github.com/skorokithakis/shortuuid/>`_ is appended to
-the common name to introduce uniqueness. Therefore, resulting common names
-will have ``{OPENWISP_CONTROLLER_COMMON_NAME_FORMAT}-{unique-slug}``
-format.
+Defines the format of the ``common_name`` attribute of X.509 client
+certificates that are automatically created when using VPN or Certificate
+Templates which have ``auto_cert`` set to ``True``. A unique slug
+generated using `shortuuid <https://github.com/skorokithakis/shortuuid/>`_
+is appended to the common name to introduce uniqueness. Therefore,
+resulting common names will have
+``{OPENWISP_CONTROLLER_COMMON_NAME_FORMAT}-{unique-slug}`` format.
 
 .. note::