doc: document new 'gencert' default https cert

Signed-off-by: Joachim Wiberg <troglobit@gmail.com>
2026-07-22 01:13:00 +02:00 · 2026-03-20 16:18:07 +01:00
parent 97c26d36bf
commit 3507cd5601
3 changed files with 105 additions and 6 deletions
@@ -59,6 +59,8 @@ them:
  XPath: `/ietf-system:system/authentication/user/password`
 - **Default SSH and NETCONF hostkey:** `genkey` (regenerated at factory reset)
  XPath: `/ietf-keystore:keystore/asymmetric-keys/asymmetric-key[name='genkey']`
+- **Default HTTPS certificate:** `gencert` (self-signed, regenerated at factory reset)
+  XPath: `/ietf-keystore:keystore/asymmetric-keys/asymmetric-key[name='gencert']`
 - **Hostname format specifiers:**  
  XPath: `/ietf-system:system/hostname`
   - `%i`: OS ID, from `/etc/os-release`, from Menuconfig branding
@@ -219,8 +221,12 @@ Notice how both the public and private keys are left empty here, this
 cause them to be always automatically regenerated after each factory reset.
 Keeping the `factory-config` snippet like this means we can use the same
 file on multiple devices, without risking them sharing the same host
-keys.  Sometimes you may want the same host keys, but that is the easy
-use-case and not documented here.
+keys or TLS certificates.  Sometimes you may want the same keys, but
+that is the easy use-case and not documented here.
+
+The `genkey` entry is the default SSH host key, and `gencert` is the
+default self-signed HTTPS certificate used by the web server (nginx).
+Both are regenerated on factory reset when their keys are empty.

 ```json
  "ietf-keystore:keystore": {
@@ -233,6 +239,18 @@ use-case and not documented here.
          "private-key-format": "ietf-crypto-types:rsa-private-key-format",
          "cleartext-private-key": "",
          "certificates": {}
+        },
+        {
+          "name": "gencert",
+          "public-key-format": "infix-crypto-types:x509-public-key-format",
+          "public-key": "",
+          "private-key-format": "infix-crypto-types:rsa-private-key-format",
+          "cleartext-private-key": "",
+          "certificates": {
+            "certificate": [
+              { "name": "self-signed", "cert-data": "" }
+            ]
+          }
        }
      ]
    }
@@ -292,9 +310,22 @@ use-case and not documented here.
        "port": 22
      }
    ]
+  },
+  "infix-services:web": {
+    "certificate": "gencert",
+    "enabled": true,
+    "console": { "enabled": true },
+    "netbrowse": { "enabled": true },
+    "restconf": { "enabled": true }
  }
 ```

+The `certificate` leaf references an asymmetric key in the keystore
+that has an associated certificate.  The default `gencert` entry uses
+a self-signed certificate.  To use a custom (e.g., CA-signed)
+certificate, create a new keystore entry with
+`x509-public-key-format` and point the web `certificate` leaf to it.
+
 ## Integration

 When integrating your software stack with Infix there may be protocols
@@ -11,6 +11,7 @@ The keystore supports two types of cryptographic keys:

 1. **Asymmetric Keys** — public/private key pairs used for:
    - SSH host authentication (RSA keys)
+    - HTTPS/TLS certificates (X.509 keys)
    - WireGuard VPN tunnels (X25519 keys)

 2. **Symmetric Keys** — shared secrets used for:
@@ -22,10 +23,11 @@ managed via CLI, NETCONF, or RESTCONF.

 ### Supported Formats

-| **Asymmetric Key Format**                                | **Use Case**  | **Key Type** |
-|----------------------------------------------------------|---------------|--------------|
-| `rsa-private-key-format` / `ssh-public-key-format`       | SSH host keys | RSA          |
-| `x25519-private-key-format` / `x25519-public-key-format` | WireGuard VPN | Curve25519   |
+| **Asymmetric Key Format**                                | **Use Case**       | **Key Type** |
+|----------------------------------------------------------|--------------------|--------------|
+| `rsa-private-key-format` / `ssh-public-key-format`       | SSH host keys      | RSA          |
+| `rsa-private-key-format` / `x509-public-key-format`      | TLS certificates   | RSA + X.509  |
+| `x25519-private-key-format` / `x25519-public-key-format` | WireGuard VPN      | Curve25519   |

 | **Symmetric Key Format**        | **Use Case**                          |
 |-----------------------------|-----------------------------------|
@@ -46,6 +48,53 @@ keystore with the name `genkey`.
 See [SSH Management](management.md) for details on generating and importing
 custom SSH host keys.

+### TLS Certificates
+
+TLS certificates are used by the web server (nginx) for HTTPS connections.
+The default certificate is a self-signed certificate automatically generated
+on first boot and stored in the keystore with the name `gencert`.  Like SSH
+host keys, the certificate is regenerated on factory reset when its keys are
+empty.
+
+The web server's `certificate` leaf references which keystore entry to use:
+
+```json
+"infix-services:web": {
+    "certificate": "gencert",
+    "enabled": true
+}
+```
+
+To use a custom (e.g., CA-signed) certificate, create a new asymmetric key
+entry with `x509-public-key-format`, populate it with your certificate and
+private key, then point the web `certificate` leaf to it:
+
+```json
+"ietf-keystore:keystore": {
+    "asymmetric-keys": {
+        "asymmetric-key": [
+            {
+                "name": "my-cert",
+                "public-key-format": "infix-crypto-types:x509-public-key-format",
+                "public-key": "<base64-encoded-cert>",
+                "private-key-format": "infix-crypto-types:rsa-private-key-format",
+                "cleartext-private-key": "<base64-encoded-key>",
+                "certificates": {
+                    "certificate": [
+                        { "name": "ca-signed", "cert-data": "<base64-encoded-cert>" }
+                    ]
+                }
+            }
+        ]
+    }
+}
+```
+
+> [!NOTE]
+> The `public-key` and `cert-data` fields contain base64-encoded PEM data
+> with the `-----BEGIN/END-----` markers stripped.  The system reconstructs
+> the PEM files when writing them to disk for nginx.
+
 ### WireGuard Keys

 WireGuard uses X25519 elliptic curve cryptography for key exchange.  Each
@@ -116,6 +165,7 @@ wg-psk                       octet-string  zYr83O4Ykj9i1gN+/aaosJxQx...
 <span class="title">Asymmetric Keys</span>
 <span class="header">NAME                         TYPE    PUBLIC KEY                         </span>
 genkey                       rsa     MIIBCgKCAQEAnj0YinjhYDgYbEGuh7...
+gencert                      x509    MIIDXTCCAkWgAwIBAgIJAJC1HiIAZA...
 wg-tunnel                    x25519  bN1CwZ1lTP6KsrCwZ1lTP6KsrCwZ1...
 </code></pre>

@@ -136,6 +136,7 @@ the unit's neighbors, collected via mDNS (see
 <pre class="cli"><code>admin@example:/> <b>configure</b>
 admin@example:/config/> <b>edit web</b>
 admin@example:/config/web/> <b>help</b>
+  certificate                       Reference to asymmetric key in central keystore.
  enabled                           Enable or disable on all web services.
  console                           Web console interface.
  netbrowse                         mDNS Network Browser.
@@ -191,6 +192,23 @@ admin@example:/config/web/restconf/> <b>no enabled</b>
 admin@example:/config/web/restconf/>
 </code></pre>

+### HTTPS Certificate
+
+The Web server uses a TLS certificate from the central
+[keystore](keystore.md).  By default it uses `gencert`, a self-signed
+certificate that is automatically generated on first boot.
+
+To use a different certificate, e.g., one signed by a CA, first add
+it to the keystore as an asymmetric key with `x509-public-key-format`,
+then point the web `certificate` leaf to it:
+
+<pre class="cli"><code>admin@example:/config/web/> <b>set certificate my-cert</b>
+admin@example:/config/web/>
+</code></pre>
+
+See [Keystore](keystore.md#tls-certificates) for details on managing
+TLS certificates.
+
 ## System Upgrade

 See [Upgrade & Boot Order](upgrade.md) for information on upgrading.