> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polystack.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Security and Encryption

> Client-side AES-256-GCM encryption, master-key handling, append-only datastore semantics, and ransomware protection for Ironcore Backup Solution.

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

<Note>
  **Prerequisites**

  * Administrator role on the Polystack platform
  * A documented plan for storing master keys and paperkeys off the backup
    infrastructure
</Note>

***

## Encryption Model

```mermaid theme={null}
graph LR
    A[Source data] -->|Read on client| B[Per-chunk Zstd compress]
    B -->|AES-256-GCM encrypt| C[Encrypted chunk]
    C -->|TLS 1.3 transport| D[Backup server]
    D -->|Store ciphertext| E[Datastore]
```

| 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

```mermaid theme={null}
stateDiagram-v2
    [*] --> Generated: ironcore-backup key create
    Generated --> Active: Distributed to backup clients
    Active --> Wrapped: Wrapped by master key for safe storage
    Active --> Backed up: Paperkey printed and vaulted
    Active --> Rotated: New key generated
    Rotated --> Retired: Old key still required for past snapshots
    Active --> Lost: ALL ENCRYPTED SNAPSHOTS UNRECOVERABLE
    Lost --> [*]
```

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

<Danger>
  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.
</Danger>

***

## Generate a Project Encryption Key

<Tabs>
  <Tab title="Deployment Console" icon="gauge">
    <Steps titleSize="h3">
      <Step title="Open Encryption Keys" icon="external-link">
        Navigate to **Backup Solution** > **Encryption Keys**.
      </Step>

      <Step title="Generate the key" icon="plus">
        Click **Generate Key**. Enter:

        * **Name**: `ibs-prod-key`
        * **Algorithm**: AES-256-GCM
        * **Scope**: project / datastore / namespace
      </Step>

      <Step title="Wrap under master key" icon="lock">
        Select the existing master key. The new key's wrapped form is stored
        in the configuration store; the raw key is never persisted.
      </Step>

      <Step title="Generate the paperkey" icon="qr-code">
        Click **Generate Paperkey**. A PDF downloads.

        <Warning>Print the paperkey, vault it physically, and confirm vault entry. Never store the paperkey on the same infrastructure that holds the backups.</Warning>
      </Step>

      <Step title="Distribute to clients" icon="copy">
        Distribute the keyfile to backup clients via your secrets management
        platform. Do not store the keyfile alongside the backup datastore.
      </Step>
    </Steps>
  </Tab>

  <Tab title="CLI" icon="terminal">
    ```bash title="Generate a project encryption key" theme={null}
    ironcore-backup key create \
      --name ibs-prod-key \
      --type aes256-gcm \
      --output /etc/ironcore/keys/ibs-prod-key.json
    ```

    ```bash title="Generate the paperkey" theme={null}
    ironcore-backup key paperkey \
      /etc/ironcore/keys/ibs-prod-key.json \
      > ibs-prod-key-paper.pdf
    ```

    ```bash title="Test encryption with the new key" theme={null}
    ironcore-backup backup create \
      --type vm --source-id 12345 \
      --repository ibs-primary --namespace production \
      --keyfile /etc/ironcore/keys/ibs-prod-key.json
    ```
  </Tab>
</Tabs>

***

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

<Tabs>
  <Tab title="Deployment Console" icon="gauge">
    <Steps titleSize="h3">
      <Step title="Open Master Key" icon="key">
        Open **Backup Solution** > **Encryption Keys** > **Master Key**.
      </Step>

      <Step title="Generate or import" icon="plus">
        Either generate a new RSA-4096 keypair or import an existing one. The
        private half is stored encrypted at rest.
      </Step>

      <Step title="Vault the paper version of the private key" icon="qr-code">
        Print the private key in paper format and vault it in two
        geographically-separated locations.
      </Step>

      <Step title="Configure recovery agents" icon="users">
        Designate at least two operators who can perform a master-key restore.
        Require Mthree-of-N approval for sensitive operations.
      </Step>
    </Steps>
  </Tab>

  <Tab title="CLI" icon="terminal">
    ```bash title="Generate the master key" theme={null}
    ironcore-backup masterkey create \
      --algorithm rsa-oaep-4096 \
      --output /etc/ironcore/keys/master.pem
    ```

    ```bash title="Print the paper version" theme={null}
    ironcore-backup masterkey paper \
      --input /etc/ironcore/keys/master.pem \
      --output master-paper.pdf
    ```
  </Tab>
</Tabs>

***

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

<Tip>
  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.
</Tip>

***

## Ransomware Protection

```mermaid theme={null}
graph LR
    A[Ransomware on workload] -->|Encrypts files in place| B[Source data]
    B -->|Next backup picks up changes| C[New chunks added]
    C -.->|Old chunks unchanged| D[Pre-ransomware snapshot]
    D -->|Restore from D| E[Workload recovered]
```

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

```mermaid theme={null}
sequenceDiagram
    participant Op as Operator
    participant Primary as Primary Datastore (compromised)
    participant Backup as Backup Site Datastore
    participant Workload as New Workload Host

    Op->>Backup: Identify pre-compromise snapshot
    Backup-->>Op: Snapshot metadata
    Op->>Backup: Restore snapshot to Workload
    Backup->>Workload: Stream chunks (live-restore)
    Op->>Primary: Quarantine compromised primary
    Op->>Backup: Sync clean primary back from Backup
```

***

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

<Tabs>
  <Tab title="Deployment Console" icon="gauge">
    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.
  </Tab>

  <Tab title="CLI" icon="terminal">
    ```bash title="Configure ACME with an enterprise CA" theme={null}
    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>
    ```
  </Tab>
</Tabs>

***

## Web Interface Hardening

<CardGroup cols={2}>
  <Card title="Secure Boot Compatibility" icon="shield-check" color="#bf9667">
    The backup server boots under Secure Boot with signed kernel and modules.
    Tampered boot media is detected at first start.
  </Card>

  <Card title="Restricted by Default" icon="lock" color="#bf9667">
    Newly created users and tokens receive no permissions. Every grant is
    explicit and auditable.
  </Card>

  <Card title="MFA Required" icon="key" color="#bf9667">
    Enforce MFA on every realm except scoped API tokens. Lockout and recovery
    codes prevent both brute force and accidental lock-out.
  </Card>

  <Card title="Audit Trail" icon="clipboard-check" color="#bf9667">
    All authentication, configuration, and permission changes recorded with
    user, timestamp, source IP, and before/after values.
  </Card>
</CardGroup>

***

## 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](/services/ironcore-backup/admin-guide/verification-validation)
for the operational procedures.

***

## Key Rotation

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

<Steps titleSize="h3">
  <Step title="Generate the replacement key" icon="key">
    Create a new project key. Vault its paperkey before proceeding.
  </Step>

  <Step title="Distribute to clients" icon="copy">
    Push the new keyfile via your secrets management tool. Clients pick up the
    new key on the next backup run.
  </Step>

  <Step title="Mark old key retired" icon="archive">
    The old key is preserved for restore of past snapshots. It is no longer
    used for new backups.
  </Step>

  <Step title="Verify a restore" icon="check">
    Restore one snapshot encrypted under the old key and one under the new key
    to confirm both keys remain functional.
  </Step>
</Steps>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Backup fails with `encryption key not registered`" icon="key">
    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.
  </Accordion>

  <Accordion title="Restore fails with `decryption error`" icon="lock">
    Wrong key file. Identify the correct key from the snapshot's **Key
    fingerprint** metadata, then load that key on the restore client.
  </Accordion>

  <Accordion title="Master key paperkey scan rejected" icon="qr-code">
    The QR or hex transcription has a checksum mismatch. Re-scan with better
    lighting or transcribe the hex blocks again from the printed paper.
  </Accordion>

  <Accordion title="Verification reports CORRUPT chunks" icon="alert-triangle">
    Either disk corruption or tampering. Quarantine the affected datastore
    immediately. Restore from the Backup site replica.
  </Accordion>
</AccordionGroup>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Access Control" icon="lock" href="/services/ironcore-backup/admin-guide/access-control" color="#bf9667">
    Realms, roles, API tokens, and MFA
  </Card>

  <Card title="Verification and Validation" icon="check" href="/services/ironcore-backup/admin-guide/verification-validation" color="#bf9667">
    Schedule integrity verification and recovery drills
  </Card>

  <Card title="Replication and Sync" icon="arrow-left-right" href="/services/ironcore-backup/admin-guide/replication-sync" color="#bf9667">
    Cross-site replication encrypted in transit
  </Card>

  <Card title="Architecture" icon="layers" href="/services/ironcore-backup/admin-guide/architecture" color="#bf9667">
    Encryption in the broader backup architecture
  </Card>
</CardGroup>