# Cryptography & Key Management

This page documents the cryptography Flopsar uses to protect data **in transit** and **at rest**, and the operator procedures for managing the keys and secrets the product relies on. It is written to support security review and to give operators the concrete steps they are responsible for.&#x20;

Protecting the confidentiality and integrity of processed data is an essential requirement of the Cyber Resilience Act (Annex I, Part I, points (e) and (f)). This page is the operator-facing description of how Flopsar meets it and what the operator must do to keep it effective.

## What the operator is responsible for

Flopsar implements the cryptographic mechanisms; the operator is responsible for the key material those mechanisms consume. In short:

* Generate and protect the **master key**.
* Provide and rotate the **TLS certificate and private key** for the management interface.
* Distribute and rotate the per-application **agent pre-shared keys (PSKs)**.&#x20;

Each of these is described under Key and secret management.

## Cryptographic inventory

For reviewers, the primitives used are:

* **X25519** — Elliptic-curve Diffie–Hellman key agreement, used with ephemeral keys to establish agent session keys.
* **XChaCha20-Poly1305** — Authenticated encryption with associated data (AEAD), with a 192-bit (24-byte) nonce and a 128-bit authentication tag. Used both for the agent data channel and for sealing secrets at rest.
* **BLAKE2b** (keyed, 256-bit output) — Used as the handshake message authentication code and as the key-derivation function for session keys.
* **scrypt** — Memory-hard password hashing function, used for local user account passwords, with a per-user random salt.
* **TLS 1.2 / 1.3** (via rustls) — Protects the HTTPS management interface and, optionally, the OTLP/gRPC channel.
* **HMAC-SHA-512 (HS512)** — Signs API session tokens (JWT).
* All random values (keys, nonces, salts) are produced by the operating system CSPRNG.

## Data in transit

Flopsar has three network channels. Each is described below; the listening ports themselves are covered in Network Surface & Port Reference.

### Agent ↔ server channel

This is Flopsar's proprietary channel between a monitored JVM's agent and the server. It does not use TLS; it uses an authenticated key-agreement handshake followed by AEAD-protected traffic. **Authentication — pre-shared key.** Each monitored application has its own 32-byte pre-shared key (PSK), generated by the server from the OS CSPRNG and handed to the operator as a hex string to configure on the agent side. The handshake is authenticated in both directions with a BLAKE2b keyed MAC over the PSK, so an agent without the correct PSK cannot complete a handshake, and an agent can detect a server that does not hold the PSK. **Key agreement — ephemeral X25519.** During each handshake:

1. The agent sends its application name, an ephemeral X25519 public key, a random nonce, and a MAC computed over those values with the PSK.
2. The server verifies the MAC, generates its own ephemeral X25519 key pair and nonce, and computes the shared secret via X25519 Diffie–Hellman.
3. Both sides derive **two directional session keys** (agent→server and server→agent) from the shared secret using a BLAKE2b-keyed-MAC key derivation function, salted with both nonces and bound to distinct context labels. The server replies with its public key, its nonce, and a confirming MAC over both public keys and both nonces.
4. The shared secret is wiped from memory once the session keys are derived.&#x20;

Because the X25519 key pairs are generated fresh for every session, a compromise of the long-lived PSK does not retroactively expose the contents of past sessions whose ephemeral keys are gone (**forward secrecy** for the recorded traffic).&#x20;

**Bulk encryption — XChaCha20-Poly1305.** After the handshake, all traffic is encrypted and authenticated with XChaCha20-Poly1305 under the directional session keys, with separate keys per direction.

### Management interface (API and Workstation) — TLS

The HTTPS endpoint that serves the REST API and the Flopsar Workstation is protected with TLS (1.2 / 1.3) provided by rustls. It is enabled by default (`[ui_srv].ssl = true`) and configured with a PEM certificate and private key in the `[ssl]` section; see the Server Configuration Reference.&#x20;

If no certificate is supplied, the server can operate with a generated self-signed certificate to make first start-up possible. **A self-signed certificate is for initial bring-up only**; for any real deployment, install a certificate issued by a CA your clients trust. See certificate rotation.

### OTLP channel

The OTLP/HTTP endpoint carries OpenTelemetry data. The OTLP/gRPC endpoint can be protected with TLS by setting `[otlp.grpc].ssl = true`, using the same certificate material. TLS on OTLP/gRPC is **off by default**; enable it whenever telemetry crosses an untrusted segment, or disable OTLP entirely if unused. See Network Surface & Port Reference and the Hardening Checklist.

## Data at rest

### Agent pre-shared keys

PSKs are not stored in plaintext. Each PSK is sealed with the **master key** using XChaCha20-Poly1305, with the application name bound in as associated data, and stored in that sealed form in the server's database. PSKs are unsealed into memory only while the server is running. This is why the master key must be available to the server and must be protected: it is the key that protects every agent PSK at rest.

### Local account passwords

Passwords for local user accounts are never stored in reversible form. They are hashed with **scrypt**, a memory-hard function, using a unique random salt per user, and stored in the standard PHC string format (which embeds the algorithm, parameters, and salt alongside the hash). Verification is constant-time within the algorithm. Where authentication is delegated to an external directory over LDAP, no password is stored by Flopsar at all; see Authentication.

### API session tokens

API tokens are JSON Web Tokens signed with HMAC-SHA-512. The signing secret is generated randomly at server start-up and held only in memory. A consequence worth planning for: **restarting the server invalidates all existing tokens**, requiring clients and users to re-authenticate.

## Key and secret management

### Master key

The master key is the root secret of the deployment. It seals every agent PSK at rest, so losing it or exposing it has consequences for every monitored application.

* **Form.** 32 bytes. With the `file` provider it is a file containing exactly 32 raw bytes (default `master.key`, resolved under the config `ssl` directory). With the `env` provider it is supplied as 64 hexadecimal characters in an environment variable. See `[master_key]`.
* **Generation.** Generate it from a cryptographic random source. For the file provider, for example:

```bash
$ head -c 32 /dev/urandom > master.key
$ chmod 600 master.key
```

For the env provider, supply 64 hex characters (32 bytes) from a CSPRNG.

* Storage. Restrict the key file to the server's service account (`chmod 600`, correct ownership). When using the env provider, source the value from your secrets manager rather than a shell history or a world-readable unit file.
* Backup. Back the master key up separately from the database. The database alone is useless for recovering PSKs without the master key, and the master key alone is useless without the database — keep both, stored apart, so a single compromised backup does not yield both.
* Rotation. Rotating the master key re-seals the PSK store. Plan it as a maintenance operation and keep the previous key until the new one is confirmed working. If the master key is lost, PSKs must be regenerated and re-distributed to agents (see below).

### TLS certificate and key

* Used for the HTTPS management interface and, when enabled, OTLP/gRPC.
* Configured as PEM files in the `[ssl]` section.
* Rotation. Replace the certificate and key files and restart the server. Protect the private key with restrictive filesystem permissions, the same way as the master key.
* Replace any generated self-signed certificate with a CA-issued one before going to production.

### Agent pre-shared keys (PSKs)

* One PSK per monitored application, generated server-side and distributed to the corresponding agent as a hex string.
* Revocation / rotation. Deleting an application's PSK on the server prevents any agent using it from completing a handshake; generating a new PSK and re-deploying it to the agent rotates it. Rotate a PSK if you suspect the agent host or the key string has been exposed.

<br>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.flopsar.com/7/security/cryptography-and-key-management.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.