From 3507cd56016f12373d708a300dcb0c602d09b9e0 Mon Sep 17 00:00:00 2001 From: Joachim Wiberg Date: Sat, 14 Feb 2026 11:54:44 +0100 Subject: [PATCH] doc: document new 'gencert' default https cert Signed-off-by: Joachim Wiberg --- doc/branding.md | 35 ++++++++++++++++++++++++++-- doc/keystore.md | 58 +++++++++++++++++++++++++++++++++++++++++++---- doc/management.md | 18 +++++++++++++++ 3 files changed, 105 insertions(+), 6 deletions(-) diff --git a/doc/branding.md b/doc/branding.md index f9894112..7056c95f 100644 --- a/doc/branding.md +++ b/doc/branding.md @@ -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 diff --git a/doc/keystore.md b/doc/keystore.md index 55da5961..79db20de 100644 --- a/doc/keystore.md +++ b/doc/keystore.md @@ -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": "", + "private-key-format": "infix-crypto-types:rsa-private-key-format", + "cleartext-private-key": "", + "certificates": { + "certificate": [ + { "name": "ca-signed", "cert-data": "" } + ] + } + } + ] + } +} +``` + +> [!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... Asymmetric Keys NAME TYPE PUBLIC KEY genkey rsa MIIBCgKCAQEAnj0YinjhYDgYbEGuh7... +gencert x509 MIIDXTCCAkWgAwIBAgIJAJC1HiIAZA... wg-tunnel x25519 bN1CwZ1lTP6KsrCwZ1lTP6KsrCwZ1... diff --git a/doc/management.md b/doc/management.md index 486cd684..2a75214c 100644 --- a/doc/management.md +++ b/doc/management.md @@ -136,6 +136,7 @@ the unit's neighbors, collected via mDNS (see 
admin@example:/> configure
 admin@example:/config/> edit web
 admin@example:/config/web/> help
+  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/> no enabled
 admin@example:/config/web/restconf/>
+### 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: + +
admin@example:/config/web/> set certificate my-cert
+admin@example:/config/web/>
+
+ +See [Keystore](keystore.md#tls-certificates) for details on managing +TLS certificates. + ## System Upgrade See [Upgrade & Boot Order](upgrade.md) for information on upgrading.