TLS and authentication

Applies to: the development build. Public APT baseline 0.1.0-2 does not provide these transport profiles.

Choose protections independently

SMKV supports plaintext trusted-LAN operation. TLS and authentication are independent options for data, replication, and management; management settings also apply to authority RPC. Omitting a security configuration preserves the plaintext, unauthenticated protocol.

TLS protects the connection and validates the endpoint certificate. Authentication restricts which identities can perform operations. Authentication without TLS sends bearer credentials in cleartext; choose it only where the network policy permits that exposure. Database TLS does not secure Prometheus HTTP or the browser listener.

Configure a profile

All Rust tools accept --security-config /path/security.json or SMKV_SECURITY_CONFIG. The flag wins. Relative file paths resolve beside the JSON file. A selected missing or invalid file fails startup rather than falling back to LAN mode.

A TLS-only data listener can use:

{
  "data": {
    "tls": true,
    "certificate": "server.pem",
    "private_key": "server.key"
  }
}

Its client profile uses {"data":{"tls":true,"ca":"ca.pem"}}. Certificates must contain the endpoint DNS name or IP in their SANs. This example secures only the data listener. For a cluster, use the full node template and client template, configuring replication and management too.

Add identities

A profile's users points to a server-side JSON allowlist. Its credential points to an outgoing identity file. Omitted authentication fields disable authentication; an empty users array denies everyone.

Generate separate random tokens for applications, operators, and each peer. Tokens must be at least 32 printable ASCII bytes. Store only their SHA-256 hashes in server allowlists. Example file structures, with placeholders that must be replaced:

[{"name":"application","token_sha256":"REPLACE_WITH_64_HEX_SHA256","role":"read_write"}]

{"name":"application","token":"REPLACE_WITH_A_CRYPTOGRAPHICALLY_RANDOM_TOKEN"}

Protect raw tokens and private keys with filesystem permissions. Add the necessary peer and admin identities before enabling cluster authentication; an application-only allowlist cannot run internal coordination.

Use credentials safely

smkv --security-config client.json --addr 10.0.0.11:7379 get greeting
smkv-ctl --security-config operator.json --seed 10.0.0.11:7381 info

For systemd dynamic users, root-only files in /etc are not directly readable by the service. Use service-manager credentials or a protected service-readable directory. Do not make secrets world-readable. Keep tokens out of arguments, logs, cluster maps, and browser JavaScript.

Rotate and migrate

Add a new identity, update clients, then remove the old identity. Credential files reload every second; admitted work can finish before revocation takes effect. Server certificates load at startup and require a controlled restart. Static systemd credential copies also require restarting the service to refresh them.

All participants on a connection must agree on TLS and authentication. There is no automatic downgrade or mixed-protocol detection. Changing an existing plaintext cluster to secured transport requires a coordinated maintenance window.