|
| 1 | +# Keystore |
| 2 | + |
| 3 | +The Infix keystore is a centralized storage system for cryptographic keys |
| 4 | +used throughout the system. It is based on the IETF standards [RFC 9641][1] |
| 5 | +(Keystore) and [RFC 9640][2] (Cryptographic Types), with Infix extensions |
| 6 | +for WiFi and WireGuard key formats. |
| 7 | + |
| 8 | +## Overview |
| 9 | + |
| 10 | +The keystore supports two types of cryptographic keys: |
| 11 | + |
| 12 | +1. **Asymmetric Keys** — public/private key pairs used for: |
| 13 | + - SSH host authentication (RSA keys) |
| 14 | + - WireGuard VPN tunnels (X25519 keys) |
| 15 | + |
| 16 | +2. **Symmetric Keys** — shared secrets used for: |
| 17 | + - WiFi authentication (WPA2/WPA3 pre-shared keys) |
| 18 | + - WireGuard VPN pre-shared keys |
| 19 | + |
| 20 | +All keys are stored under the `ietf-keystore` configuration path and can be |
| 21 | +managed via CLI, NETCONF, or RESTCONF. |
| 22 | + |
| 23 | +### Supported Formats |
| 24 | + |
| 25 | +| **Asymmetric Key Format** | **Use Case** | **Key Type** | |
| 26 | +|----------------------------------------------------------|---------------|--------------| |
| 27 | +| `rsa-private-key-format` / `ssh-public-key-format` | SSH host keys | RSA | |
| 28 | +| `x25519-private-key-format` / `x25519-public-key-format` | WireGuard VPN | Curve25519 | |
| 29 | + |
| 30 | +| **Symmetric Key Format** | **Use Case** | |
| 31 | +|-----------------------------|-----------------------------------| |
| 32 | +| `passphrase-key-format` | Human-readable passphrases (WiFi) | |
| 33 | +| `octet-string-key-format` | Raw symmetric keys (WireGuard) | |
| 34 | + |
| 35 | +## Asymmetric Keys |
| 36 | + |
| 37 | +Asymmetric keys consist of a public/private key pair. The public key can be |
| 38 | +shared freely, while the private key must be kept secure. |
| 39 | + |
| 40 | +### SSH Host Keys |
| 41 | + |
| 42 | +SSH host keys identify the system during SSH and NETCONF connections. The |
| 43 | +default host key is automatically generated on first boot and stored in the |
| 44 | +keystore with the name `genkey`. |
| 45 | + |
| 46 | +See [SSH Management](management.md) for details on generating and importing |
| 47 | +custom SSH host keys. |
| 48 | + |
| 49 | +### WireGuard Keys |
| 50 | + |
| 51 | +WireGuard uses X25519 elliptic curve cryptography for key exchange. Each |
| 52 | +WireGuard interface requires a public/private key pair stored as an asymmetric |
| 53 | +key in the keystore. Key pairs can be generated directly from the CLI: |
| 54 | + |
| 55 | +<pre class="cli"><code>admin@example:/> <b>wireguard genkey</b> |
| 56 | +Private: aMqBvZqkSP5JrqBvZqkSP5JrqBvZqkSP5JrqBvZqkSP= |
| 57 | +Public: bN1CwZ1lTP6KsrCwZ1lTP6KsrCwZ1lTP6KsrCwZ1lTP= |
| 58 | +</code></pre> |
| 59 | + |
| 60 | +See [WireGuard VPN](vpn-wireguard.md) for key generation and configuration |
| 61 | +examples. |
| 62 | + |
| 63 | +## Symmetric Keys |
| 64 | + |
| 65 | +Symmetric keys are shared secrets where the same key must be configured on |
| 66 | +all systems that need to communicate. |
| 67 | + |
| 68 | +### WiFi Pre-Shared Keys |
| 69 | + |
| 70 | +WiFi networks secured with WPA2 or WPA3 use pre-shared keys stored as |
| 71 | +symmetric keys in the keystore with `passphrase-key-format`. The |
| 72 | +passphrase must be 8-63 printable ASCII characters. |
| 73 | + |
| 74 | +Since symmetric keys are stored as binary (base64-encoded), the CLI |
| 75 | +provides the `change` command to enter passphrases interactively: |
| 76 | + |
| 77 | +<pre class="cli"><code>admin@example:/config/keystore/…/my-wifi-key/> <b>change cleartext-symmetric-key</b> |
| 78 | +Passphrase: ************ |
| 79 | +Retype passphrase: ************ |
| 80 | +</code></pre> |
| 81 | + |
| 82 | +See [WiFi](wifi.md) for complete configuration examples. |
| 83 | + |
| 84 | +### WireGuard Pre-Shared Keys |
| 85 | + |
| 86 | +WireGuard supports optional pre-shared keys (PSK) that add a layer of |
| 87 | +symmetric encryption alongside Curve25519. PSKs use the standard IETF |
| 88 | +`octet-string-key-format` (32 random bytes). This provides defense-in-depth |
| 89 | +against future quantum computers that might break elliptic curve cryptography. |
| 90 | +Note, however, that WireGuard’s authentication and initial key agreement |
| 91 | +remain Curve25519-based, so PSKs only protect the session encryption, |
| 92 | +not the handshake itself. |
| 93 | + |
| 94 | +PSKs can be generated directly from the CLI: |
| 95 | + |
| 96 | +<pre class="cli"><code>admin@example:/> <b>wireguard genpsk</b> |
| 97 | +cO2DxZ2mUQ7LtsrDxZ2mUQ7LtsrDxZ2mUQ7LtsrDxZ2m= |
| 98 | +</code></pre> |
| 99 | + |
| 100 | +See [WireGuard VPN](vpn-wireguard.md) for PSK generation and usage examples. |
| 101 | + |
| 102 | +## Viewing Keys |
| 103 | + |
| 104 | +The `show keystore` command in admin-exec mode gives an overview of all |
| 105 | +keys in the keystore. Passphrases (WiFi passwords) are decoded and shown |
| 106 | +in cleartext, while binary keys (WireGuard PSKs) are shown as base64: |
| 107 | + |
| 108 | +<pre class="cli"><code>admin@example:/> <b>show keystore</b> |
| 109 | +──────────────────────────────────────────────────────────────────────── |
| 110 | +<span class="title">Symmetric Keys</span> |
| 111 | +<span class="header">NAME FORMAT VALUE </span> |
| 112 | +my-wifi-key passphrase MySecretPassword |
| 113 | +wg-psk octet-string zYr83O4Ykj9i1gN+/aaosJxQx... |
| 114 | + |
| 115 | +──────────────────────────────────────────────────────────────────────── |
| 116 | +<span class="title">Asymmetric Keys</span> |
| 117 | +<span class="header">NAME TYPE PUBLIC KEY </span> |
| 118 | +genkey rsa MIIBCgKCAQEAnj0YinjhYDgYbEGuh7... |
| 119 | +wg-tunnel x25519 bN1CwZ1lTP6KsrCwZ1lTP6KsrCwZ1... |
| 120 | +</code></pre> |
| 121 | + |
| 122 | +To see the full (untruncated) details of a specific key, use the |
| 123 | +`symmetric` or `asymmetric` qualifier with the key name: |
| 124 | + |
| 125 | +<pre class="cli"><code>admin@example:/> <b>show keystore symmetric my-wifi-key</b> |
| 126 | +name : my-wifi-key |
| 127 | +format : passphrase |
| 128 | +value : MySecretPassword |
| 129 | + |
| 130 | +admin@example:/> <b>show keystore asymmetric genkey</b> |
| 131 | +name : genkey |
| 132 | +algorithm : rsa |
| 133 | +public key format : ssh-public-key |
| 134 | +public key : MIIBCgKCAQEAnj0YinjhY...full key...IDAQAB |
| 135 | +</code></pre> |
| 136 | + |
| 137 | +> [!NOTE] |
| 138 | +> The `show keystore` command is protected by NACM. Only users in the |
| 139 | +> `admin` group can view keystore data. Operator-level users will see a |
| 140 | +> message indicating that no keystore data is available. |
| 141 | +
|
| 142 | +The full configuration-mode view (including private keys) is still |
| 143 | +available via `configure` and then `show keystore`: |
| 144 | + |
| 145 | +<pre class="cli"><code>admin@example:/config/> <b>show keystore</b> |
| 146 | +</code></pre> |
| 147 | + |
| 148 | +> [!WARNING] |
| 149 | +> The configuration-mode `show keystore` displays private keys in |
| 150 | +> cleartext. Be careful when viewing keys on shared screens or in |
| 151 | +> logged sessions. The admin-exec `show keystore` command never |
| 152 | +> displays private keys. |
| 153 | +
|
| 154 | +## Deleting Keys |
| 155 | + |
| 156 | +<pre class="cli"><code>admin@example:/> <b>configure</b> |
| 157 | +admin@example:/config/> <b>delete keystore asymmetric-key mykey</b> |
| 158 | +admin@example:/config/> <b>leave</b> |
| 159 | +</code></pre> |
| 160 | + |
| 161 | +> [!CAUTION] |
| 162 | +> Deleting a key that is referenced by a service (SSH, WireGuard, WiFi) will |
| 163 | +> cause that service to fail. Verify the key is not in use before deletion. |
| 164 | +
|
| 165 | +## Security Considerations |
| 166 | + |
| 167 | +The keystore is protected by NACM (Network Access Control Model) rules. |
| 168 | +Only users in the `admin` group can view or modify cryptographic keys. |
| 169 | +See [NACM](nacm.md) for details on access control. |
| 170 | + |
| 171 | +Private keys are stored in cleartext in the configuration database. |
| 172 | +Configuration files and backups containing the keystore should be treated |
| 173 | +as sensitive and protected accordingly. |
| 174 | + |
| 175 | +### Key Validation |
| 176 | + |
| 177 | +Symmetric key values are stored as binary (base64-encoded). The system |
| 178 | +validates them based on their declared format: |
| 179 | + |
| 180 | +- `passphrase-key-format`: Used by WiFi, must decode to 8-63 ASCII characters |
| 181 | +- `octet-string-key-format`: Used by Wireguard, must decode to exactly 32 bytes (256 bits) |
| 182 | + |
| 183 | +## References |
| 184 | + |
| 185 | +- [RFC 9641 - A YANG Data Model for a Keystore][1] |
| 186 | +- [RFC 9640 - YANG Data Types and Groupings for Cryptography][2] |
| 187 | +- [WiFi Documentation](wifi.md) |
| 188 | +- [WireGuard VPN Documentation](vpn-wireguard.md) |
| 189 | +- [SSH Management](management.md) |
| 190 | +- [NACM Access Control](nacm.md) |
| 191 | + |
| 192 | +[1]: https://datatracker.ietf.org/doc/html/rfc9641 |
| 193 | +[2]: https://datatracker.ietf.org/doc/html/rfc9640 |
0 commit comments