Certificate Template Model

A new cert type was added to the existing AbstractTemplate model, exposed in the admin as Certificate generator, together with two new relational fields:

• ca, a required ForeignKey to the pki.Ca model that signs the generated certificates;
• blueprint_cert, an optional ForeignKey to the pki.Cert model whose non-unique properties are copied to every newly generated certificate.

Certificate generator templates always provision certificates automatically, so their auto_cert value is implicitly enabled and is not configurable. A set of validation rules protects the cryptographic integrity of the templates:

• the CA is strictly required for cert templates;
• the blueprint must be signed by the selected CA;
• the blueprint must not already be assigned to a device;
• the CA and the blueprint must belong to the same organization as the template, or be shared.

When the template type is not cert, the two certificate fields are cleared automatically.

A new DeviceCertificate intermediate Many-To-Many model acts as a strict relational bridge between the device configuration, the template and the generated certificate. It stores a config and a template foreign key and a cert one-to-one relationship, and enforces a unique_together constraint on (config, template) so that a single configuration can never generate conflicting certificates from the same template.

Provisioning and Revocation Lifecycle

Certificate generation follows the same lifecycle semantics as the existing OpenVPN client certificates, but for standalone certificates:

• Assignment generates a certificate. When a certificate template is added to a device configuration, a DeviceCertificate relationship is created and an X.509 certificate is generated and signed in the same database transaction. The subject and extensions are copied from the blueprint certificate when one is provided, otherwise they fall back to the CA defaults, and the certificate's common name is built from the OPENWISP_CONTROLLER_COMMON_NAME_FORMAT setting, suffixed with a unique slug to prevent collisions.
• Unassignment revokes the certificate. When the template is removed from a configuration, the DeviceCertificate relationship is deleted and the underlying certificate is automatically revoked, adding it to the CA's Certificate Revocation List, so that relying parties that obtain and check current revocation information can reject the certificate.
• Renewal regenerates the certificate. Renewing a standalone certificate through the PKI endpoint regenerates the certificate and private key, and the dependency registered in Config.get_cache_dependencies() resolves the DeviceCertificate relationship and updates the affected configuration status, so the device pulls the renewed certificate on its next check-in.

Because the private keys and certificates are stored and protected using the existing django-x509 mechanisms, no new encryption scheme, private key download endpoint or permission model was introduced.

Custom Device Identification OIDs

Every automatically generated certificate includes two custom ASN.1 Object Identifiers that cryptographically bind it to the device:

• 1.3.6.1.4.1.65901.1: the MAC address of the device;
• 1.3.6.1.4.1.65901.2: the UUID of the device.

This allows external systems to uniquely and securely identify a device by parsing its certificate. If the blueprint certificate already contains either reserved OpenWISP hardware OID, the inherited value is replaced with the value of the device using the template, so the certificate always reflects the actual hardware.

Certificate Regeneration on Hardware Change

Because the device name and MAC address are bound to the certificate through the common name and the custom OIDs, any change to those hardware properties would otherwise leave the device with a stale and inaccurate identity. A background task now monitors the device's hostname and MAC address and, when a change is detected on a device holding a DeviceCertificate, revokes the outdated certificate and generates a new one with the updated identity attributes. A generic_message notification is sent to the administrator once the regeneration is complete, and the whole behavior can be disabled with the OPENWISP_CONTROLLER_REGENERATE_CERTS_ON_HARDWARE_CHANGE setting.

Context Injection

To make the certificate usable, its payload is exposed to OpenWISP's configuration engine as template variables. The Config.get_context() method was extended to iterate over the device certificates and build a dictionary of variables namespaced with the 32-character hexadecimal UUID of the template, which avoids collisions when multiple certificate templates are assigned to the same device:

• {{ cert_<template_uuid_hex>_pem }}: the public certificate;
• {{ cert_<template_uuid_hex>_key }}: the private key;
• {{ cert_<template_uuid_hex>_id }}: the ID of the generated certificate;
• {{ cert_<template_uuid_hex>_path }}: the path where the certificate file is installed on the device;
• {{ cert_<template_uuid_hex>_key_path }}: the path where the private key file is installed on the device.

Administrators can reference these variables inside the JSON configuration payload of any template, and OpenWISP replaces them with the exact certificate and private key generated for that specific device.

Django Admin and REST API

The Django admin was updated so that certificate templates can actually be configured: the new Certificate generator type appears in the type dropdown, the Certificate Authority and Blueprint Certificate fields are shown or hidden based on the selected type, and both foreign keys use raw_id_fields to stay scalable in large deployments. The blueprint dropdown is filtered to show only unassigned, non-revoked certificates and is scoped to the template's organization. The device admin gained a dedicated certificate tab that lists the certificates generated for a device, and links the template name to its detail page, opening in a new tab.

Because changing the core parameters of a template that is already in use would break the binding with the devices, an Active Template Mutation Lock blocks changes to the type, organization, CA and blueprint of a template while it is assigned to active devices. The lock is enforced both in the admin and at the serializer level, so the same protection applies to the API.

The certificate template type is fully supported by the existing REST API: the type field accepts the cert enumeration, ca and blueprint_cert are writable on /api/v1/controller/template/, and patching the templates array of a device triggers the same creation and revocation lifecycle described above. Requesting an already-assigned or revoked certificate as a blueprint, or attempting a locked mutation, returns a 400 Bad Request.