# 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:

```json
{
  "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](examples/security-server.json) and [client template](examples/security-client.json), 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.

| Role | Intended use |
| --- | --- |
| `read_only` | Reads and cluster observations |
| `read_write` | Application reads and mutations |
| `admin` | Operator changes and backup |
| `peer` | Internal replication and coordination |

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:

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

```json
{"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

```sh
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.