Security and Encryption - Polystack Documentation

Overview

Ironcore Backup Solution (IBS) provides defence-in-depth: backups are encrypted on the client before they leave the workload, stored as immutable append-only chunks, replicated over TLS 1.3, and accessible only to explicitly-granted identities. This page covers the encryption model, key lifecycle, ransomware protections, and platform hardening.

Prerequisites

Administrator role on the Polystack platform
A documented plan for storing master keys and paperkeys off the backup infrastructure

Encryption Model

Layer	Algorithm	Property
Per-chunk encryption	AES-256-GCM	Authenticated; tamper-evident
IV	96-bit per-chunk random	Unique per chunk
Auth tag	128-bit	Verified on every decryption
Transport	TLS 1.3	Forward secrecy, certificate pinning
Master key wrap	RSA-OAEP-4096	Protects symmetric keys at rest

The backup server never holds the decryption key. It stores authenticated ciphertext. A compromise of the backup server reveals no plaintext.

Key Lifecycle

Stage	Action
Generate	Create a new AES-256-GCM key for client-side encryption
Distribute	Install the keyfile on the backup clients
Wrap	Wrap the AES key under the project master key (RSA)
Paperkey	Print the key as a QR + hex block for offline vaulting
Rotate	Generate a new key; old key remains for past snapshots
Retire	Old key marked retired but kept available for restore

If an encryption key is lost and no paperkey exists, the encrypted snapshots are unrecoverable. The encryption is designed to be cryptographically strong specifically to prevent recovery without the key — there is no backdoor.

Generate a Project Encryption Key

Deployment Console
CLI

Open Encryption Keys

Navigate to Backup Solution > Encryption Keys.

Generate the key

Click Generate Key. Enter:

Name: ibs-prod-key
Algorithm: AES-256-GCM
Scope: project / datastore / namespace

Wrap under master key

Select the existing master key. The new key’s wrapped form is stored in the configuration store; the raw key is never persisted.

Generate the paperkey

Click Generate Paperkey. A PDF downloads.

Print the paperkey, vault it physically, and confirm vault entry. Never store the paperkey on the same infrastructure that holds the backups.

Distribute to clients

Distribute the keyfile to backup clients via your secrets management platform. Do not store the keyfile alongside the backup datastore.

Generate a project encryption key

ironcore-backup key create \
  --name ibs-prod-key \
  --type aes256-gcm \
  --output /etc/ironcore/keys/ibs-prod-key.json

Generate the paperkey

ironcore-backup key paperkey \
  /etc/ironcore/keys/ibs-prod-key.json \
  > ibs-prod-key-paper.pdf

Test encryption with the new key

ironcore-backup backup create \
  --type vm --source-id 12345 \
  --repository ibs-primary --namespace production \
  --keyfile /etc/ironcore/keys/ibs-prod-key.json

Master Key

The master key (RSA-OAEP-4096) wraps every project encryption key. Use a single master key per platform — it allows recovery of any project key by an authorised operator without distributing every project key individually.

Deployment Console
CLI

Open Master Key

Open Backup Solution > Encryption Keys > Master Key.

Generate or import

Either generate a new RSA-4096 keypair or import an existing one. The private half is stored encrypted at rest.

Vault the paper version of the private key

Print the private key in paper format and vault it in two geographically-separated locations.

Configure recovery agents

Designate at least two operators who can perform a master-key restore. Require Mthree-of-N approval for sensitive operations.

Generate the master key

ironcore-backup masterkey create \
  --algorithm rsa-oaep-4096 \
  --output /etc/ironcore/keys/master.pem

Print the paper version

ironcore-backup masterkey paper \
  --input /etc/ironcore/keys/master.pem \
  --output master-paper.pdf

At-Rest Protection

The datastore stores only encrypted chunks. The chunk fingerprint (used for deduplication) is the SHA-256 of the encrypted ciphertext, computed after encryption with deterministic keys derived from the master key. This means:

Two clients with the same project key encrypting the same plaintext produce the same ciphertext and the same fingerprint — deduplication works across clients.
A datastore breach reveals only ciphertext; without the key, the data is unreadable.
A change of one bit in the source produces a completely different ciphertext (avalanche), so partial knowledge of plaintext cannot be inferred.

Append-Only Datastore

Existing chunks are immutable. A backup never modifies a chunk that already exists; it only adds new chunks or references existing ones in a new manifest. This is the foundational property for ransomware protection.

Operation	Affects Chunks
New backup	Adds new chunks only
Prune	Removes manifests only
Garbage collection	Removes orphaned chunks (referenced by no manifest)
Sync	Adds new chunks to destination
Tape archival	Writes copies to tape; source unchanged

Configure the operating system filesystem on the datastore to enforce append-only behaviour (chattr +a) on the chunk directories. Combined with strict role separation between datastore owner and platform admin, this prevents even compromised credentials from modifying historical chunks.

Ransomware Protection

Defensive layers:

Layer	Mechanism
Chunk immutability	Existing chunks are never overwritten
Append-only filesystem	OS-level enforcement of write-once chunks
Role separation	Workload admin cannot prune backups
Time-locked prune	Prune requires N approvers or a delay
Off-site replication	Backup site copy survives Primary compromise
Air-gap (tape)	Yearly tape archives are physically disconnected
MFA on prune / delete	Destructive operations require a second factor

Recovery From a Compromised Primary

TLS and Transport Hardening

All inter-process traffic uses TLS 1.3.

Endpoint	Default Port	Notes
Backup API	TCP/8007	Web UI and API
Client-server data	TCP/8007	Same port; multiplexed
Sync transport	TCP/8007	Same port
Tape worker	Local IPC	Unix socket

Deployment Console
CLI

Navigate to Backup Solution > Certificates. Manage TLS certificates via ACME (Let’s Encrypt and other providers), import a custom CA, or use an external account binding (EAB) for enterprise CAs.

Configure ACME with an enterprise CA

ironcore-backup acme account register \
  --name ent-ca \
  --contact ops@polystack \
  --eab-kid "..." \
  --eab-hmac "..."

ironcore-backup acme cert order \
  --account ent-ca \
  --domains ibs.<your-domain>

Web Interface Hardening

Secure Boot Compatibility

The backup server boots under Secure Boot with signed kernel and modules. Tampered boot media is detected at first start.

Restricted by Default

Newly created users and tokens receive no permissions. Every grant is explicit and auditable.

MFA Required

Enforce MFA on every realm except scoped API tokens. Lockout and recovery codes prevent both brute force and accidental lock-out.

Audit Trail

All authentication, configuration, and permission changes recorded with user, timestamp, source IP, and before/after values.

Verification as Tampering Detection

A scheduled verification run reads every chunk and validates its SHA-256 fingerprint and GCM auth tag. A failure indicates either media corruption or tampering. The verification report flags every affected snapshot and triggers the configured notification group. See Verification and Validation for the operational procedures.

Key Rotation

Rotate project encryption keys periodically (recommended: annually) and after any suspected key exposure.

Generate the replacement key

Create a new project key. Vault its paperkey before proceeding.

Distribute to clients

Push the new keyfile via your secrets management tool. Clients pick up the new key on the next backup run.

Mark old key retired

The old key is preserved for restore of past snapshots. It is no longer used for new backups.

Verify a restore

Restore one snapshot encrypted under the old key and one under the new key to confirm both keys remain functional.

Troubleshooting

Backup fails with `encryption key not registered`

The keyfile on the client does not match a registered key on the server. Confirm the key fingerprint with ironcore-backup key list on both ends.

Restore fails with `decryption error`

Wrong key file. Identify the correct key from the snapshot’s Key fingerprint metadata, then load that key on the restore client.

Master key paperkey scan rejected

The QR or hex transcription has a checksum mismatch. Re-scan with better lighting or transcribe the hex blocks again from the printed paper.

Verification reports CORRUPT chunks

Either disk corruption or tampering. Quarantine the affected datastore immediately. Restore from the Backup site replica.

Next Steps

Access Control

Realms, roles, API tokens, and MFA

Verification and Validation

Schedule integrity verification and recovery drills

Replication and Sync

Cross-site replication encrypted in transit

Architecture

Encryption in the broader backup architecture

​Overview

​Encryption Model

​Key Lifecycle

​Generate a Project Encryption Key

Open Encryption Keys

Generate the key

Wrap under master key

Generate the paperkey

Distribute to clients

​Master Key

Open Master Key

Generate or import

Vault the paper version of the private key

Configure recovery agents

​At-Rest Protection

​Append-Only Datastore

​Ransomware Protection

​Recovery From a Compromised Primary

​TLS and Transport Hardening

​Web Interface Hardening

Secure Boot Compatibility

Restricted by Default

MFA Required

Audit Trail

​Verification as Tampering Detection

​Key Rotation

Generate the replacement key

Distribute to clients

Mark old key retired

Verify a restore

​Troubleshooting

​Next Steps

Access Control

Verification and Validation

Replication and Sync

Architecture

Overview

Encryption Model

Key Lifecycle

Generate a Project Encryption Key

Master Key

At-Rest Protection

Append-Only Datastore

Ransomware Protection

Recovery From a Compromised Primary

TLS and Transport Hardening

Web Interface Hardening

Verification as Tampering Detection

Key Rotation

Troubleshooting

Next Steps