gunnar-core 3.0.0

//! Sealing secrets at rest.
//!
//! # The gap this closes
//!
//! `gunnar_store::SecretStore` held the SSH host key as plaintext bytes in
//! `secrets.arrow`. The cold tier format reserves `__gunnar_secrets__` for
//! *already-encrypted* material and `gunnar_store::FoldRequest` therefore
//! carries no secrets at all — the omission was deliberate, so that nobody
//! could close it by accident with a plaintext key. This module is the thing
//! that had to exist first: an encryption layer that makes a secret safe to sit
//! in a file whose whole purpose is to be copied elsewhere.
//!
//! # Where it sits
//!
//! [`SealedSecretStore`] is a **decorator over the trait**, not a fourth
//! backend. `mem`, `arrow_log` and `fs` all gain sealing from one
//! implementation, and there is exactly one place where a secret is encrypted
//! and one where it is decrypted (one implementation). A backend cannot forget to seal,
//! because the backend is not what seals.
//!
//! # The cipher, and why it is not a choice
//!
//! AES-256-GCM out of `aws-lc-rs`. gunnar already links aws-lc-rs statically —
//! russh pulls it, and the stripped appliance binary carries 123 `AWS_LC`
//! strings with zero `PT_INTERP` and zero `DT_NEEDED`. One appliance gets one
//! crypto backend; adding `ring` or a pure-Rust AEAD would mean two
//! implementations of AES in a binary that is meant to be auditable.
//!
//! # The wire format
//!
//! ```text
//! magic  "gsk1"      4 bytes   version, and a marker that tells a sealed value
//!                              from a legacy plaintext one
//! nonce              12 bytes  fresh from the system CSPRNG on every seal
//! ciphertext||tag    n+16      AES-256-GCM
//! ```
//!
//! The **AAD is the secret's key name**. A sealed `ssh/host_ed25519` therefore
//! cannot be lifted out of the log and replayed under a different key: the tag
//! check fails. Without that binding, an attacker who could write the secret log
//! (but not read the KEK) could swap a low-value secret into the host key slot.
//!
//! # Where the key-encrypting key lives — the actual hard question
//!
//! An appliance boots with no operator to type a passphrase. There are four
//! honest places a KEK can live and gunnar takes two of them:
//!
//! 1. **Beside the data, on the appliance's own disk** ([`Kek::from_file`], the
//!    default). A 32-byte file at mode `0600`, in the control directory,
//!    **outside** the Arrow secret log and outside anything a
//!    `gunnar_store::FoldRequest` can reach.
//! 2. **Handed in from outside the machine** ([`Kek::from_env`], `GUNNAR_SECRET_KEK`).
//!    Never written to disk. This is the seam for a KMS, a Kubernetes secret, or
//!    an initramfs that unwraps against a TPM before `exec`ing gunnar.
//! 3. An operator passphrase at boot — rejected, it contradicts unattended boot.
//! 4. A key derived from machine identity (machine-id, disk serial) — rejected,
//!    that is obfuscation wearing a KDF, and calling it encryption is worse than
//!    not encrypting.
//!
//! ## What (1) defeats, and what it does not
//!
//! Say it plainly, because a sealed secret whose unlock key sits beside it is
//! theatre if you claim more than this:
//!
//! **Defeats** — every path by which the *data* leaves the machine without the
//! disk: a cold-tier `.znippy` archive copied to object storage, a backup, an
//! archive handed to a customer, a `secrets.arrow` pulled out of a replica, a
//! log line or a `{:?}` that dumps stored bytes. Those are the realistic
//! exfiltration routes for an appliance whose *design goal* is that its archive
//! be portable, and against all of them the KEK stays behind.
//!
//! **Does not defeat** — an attacker with the appliance's disk, or root on the
//! running appliance, or its memory. The KEK is one `read(2)` away for anyone
//! who has those. Option (1) is **domain separation between the portable
//! artifact and the machine**, not confidentiality against physical possession.
//!
//! Anyone who needs the second property uses option (2), and then the KEK is
//! genuinely not on the disk at all. The design does not pretend option (1) is
//! option (2).
//!
//! # Migration
//!
//! A store written before this existed holds plaintext under the same keys.
//! [`SealedSecretStore::get`] returns such a value unchanged, with a warning, so
//! an in-place upgrade does not brick the host key; and
//! [`SealedSecretStore::get_or_create`] **re-seals it in place**, which closes
//! the migration by construction on the one path the host key actually takes at
//! boot rather than leaving it to a migration nobody runs.
//!
//! ## …and why accepting one has to be asked for
//!
//! Read that migration next to the threat two sections up — *"an attacker who
//! could write the secret log (but not read the KEK) could swap a low-value
//! secret into the host key slot"* — and it undoes it. The AAD binding stops a
//! sealed value being moved between slots, and a magic-less prefix walks past
//! the binding entirely: write `-----BEGIN OPENSSH PRIVATE KEY-----…` into
//! `ssh/host_ed25519`, and a store that accepts any unsealed value serves the
//! attacker's host key. No KEK needed. The warning that says so goes to the
//! journal, where nothing refuses anything.
//!
//! So accepting plaintext is a [`PlaintextPolicy`], it is
//! [`PlaintextPolicy::Refuse`] by default, and the one caller that turns it on
//! does so from a **fact about the disk**: `ServerStores` finds a legacy
//! `secrets.arrow` or it does not, and only on the machine that has one is a
//! plaintext value something gunnar itself could have written. On every
//! installation made after 2026-08-10 there is no such file, nothing under the
//! seal has ever been written in the clear, and an unsealed value is either
//! corruption or somebody else's key.

use std::path::{Path, PathBuf};

use aws_lc_rs::aead::{Aad, LessSafeKey, Nonce, UnboundKey, AES_256_GCM, NONCE_LEN};
use aws_lc_rs::rand::{SecureRandom as _, SystemRandom};
use gunnar_store::{Error as StoreError, Result as StoreResult, SecretStore};
use zeroize::Zeroize as _;

/// Magic and version prefix on every sealed value.
///
/// Four bytes, and its job is to be distinguishable from an OpenSSH private key
/// (`-----BEGIN OPENSSH`) and from anything else a pre-sealing gunnar wrote, so
/// [`is_sealed`] can never mistake a legacy plaintext for ciphertext.
pub const SEAL_MAGIC: &[u8; 4] = b"gsk1";

/// Bytes of a KEK. AES-256, so 32.
pub const KEK_LEN: usize = 32;

/// The GCM authentication tag length, named rather than spelled `16` at the
/// three sites that need it.
const TAG_LEN: usize = 16;

/// The file the on-disk KEK is kept in, relative to the control directory.
pub const KEK_FILE: &str = "secrets.kek";

/// The environment variable that supplies a KEK from outside the machine.
///
/// 64 hex characters. When it is set, nothing writes a KEK to disk.
pub const KEK_ENV: &str = "GUNNAR_SECRET_KEK";

/// A key-encrypting key.
///
/// `Debug` prints nothing but the type name; 32 bytes of key material must not
/// be one `{:?}` away from a log file, exactly as
/// [`crate::host_key::HostKey`] is not.
#[derive(Clone)]
pub struct Kek([u8; KEK_LEN]);

impl std::fmt::Debug for Kek {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str("Kek(<redacted>)")
    }
}

impl Drop for Kek {
    fn drop(&mut self) {
        // `zeroize`, not a hand-rolled `write_volatile`: the workspace forbids
        // `unsafe` (`-F unsafe-code`) and this crate is not the place to make an
        // exception for something a maintained crate already does correctly.
        // It costs no package — aws-lc-rs and curve25519-dalek both already
        // resolve it.
        self.0.zeroize();
    }
}

impl Kek {
    /// A KEK from raw bytes.
    pub fn from_bytes(bytes: [u8; KEK_LEN]) -> Self {
        Kek(bytes)
    }

    /// A fresh KEK from the system CSPRNG.
    pub fn generate() -> crate::Result<Self> {
        let mut bytes = [0u8; KEK_LEN];
        SystemRandom::new()
            .fill(&mut bytes)
            .map_err(|_| crate::Error::Key("the system CSPRNG refused to produce a KEK".into()))?;
        Ok(Kek(bytes))
    }

    /// A KEK from [`KEK_ENV`], if it is set.
    ///
    /// `Ok(None)` when the variable is absent — that is not an error, it is the
    /// normal case. `Err` when it is set and unusable, because silently falling
    /// back to an on-disk KEK after an operator explicitly supplied one would
    /// downgrade the threat model without saying so.
    pub fn from_env() -> crate::Result<Option<Self>> {
        let Ok(hex_text) = std::env::var(KEK_ENV) else {
            return Ok(None);
        };
        let hex_text = hex_text.trim();
        let raw = hex::decode(hex_text)
            .map_err(|err| crate::Error::Key(format!("{KEK_ENV} is not hexadecimal: {err}")))?;
        let bytes: [u8; KEK_LEN] = raw.as_slice().try_into().map_err(|_| {
            crate::Error::Key(format!(
                "{KEK_ENV} decoded to {} bytes; a KEK is {KEK_LEN}",
                raw.len()
            ))
        })?;
        tracing::info!("using the key-encrypting key from {KEK_ENV}; none is written to disk");
        Ok(Some(Kek(bytes)))
    }

    /// The KEK stored at `path`, creating one on first boot.
    ///
    /// Created at mode `0600` and fsynced, then the parent directory is fsynced,
    /// so a KEK that a later boot cannot read is not a way to lose every secret
    /// on the machine.
    pub fn from_file(path: &Path) -> crate::Result<Self> {
        match std::fs::read(path) {
            Ok(raw) => {
                let bytes: [u8; KEK_LEN] = raw.as_slice().try_into().map_err(|_| {
                    crate::Error::Key(format!(
                        "the KEK at {} is {} bytes; a KEK is {KEK_LEN}. Refusing to \
                         guess, because guessing here means every secret on this \
                         machine becomes unreadable",
                        path.display(),
                        raw.len()
                    ))
                })?;
                Ok(Kek(bytes))
            }
            Err(err) if err.kind() == std::io::ErrorKind::NotFound => {
                let kek = Kek::generate()?;
                write_kek_file(path, &kek.0)?;
                tracing::info!(
                    path = %path.display(),
                    "no key-encrypting key found; minted one and sealed the secret store"
                );
                Ok(kek)
            }
            Err(err) => Err(crate::Error::Key(format!(
                "could not read the KEK at {}: {err}",
                path.display()
            ))),
        }
    }

    /// [`Kek::from_env`] if the environment supplies one, else
    /// [`Kek::from_file`] under `control_dir`.
    ///
    /// This is the one call a server should make: the precedence is decided
    /// here, once, rather than at every boot site.
    pub fn for_control_dir(control_dir: &Path) -> crate::Result<Self> {
        if let Some(kek) = Kek::from_env()? {
            return Ok(kek);
        }
        Kek::from_file(&kek_path(control_dir))
    }

    /// Hex, for handing a generated KEK to an operator to put in a vault.
    ///
    /// Deliberately a named method and not `Display`: printing key material must
    /// be something a caller asked for by name.
    pub fn to_hex(&self) -> String {
        hex::encode(self.0)
    }

    fn aead(&self) -> crate::Result<LessSafeKey> {
        UnboundKey::new(&AES_256_GCM, &self.0)
            .map(LessSafeKey::new)
            .map_err(|_| crate::Error::Key("aws-lc-rs rejected the KEK for AES-256-GCM".into()))
    }
}

/// Where [`Kek::for_control_dir`] keeps the on-disk KEK.
pub fn kek_path(control_dir: &Path) -> PathBuf {
    control_dir.join(KEK_FILE)
}

fn write_kek_file(path: &Path, bytes: &[u8; KEK_LEN]) -> crate::Result<()> {
    use std::io::Write as _;

    let io = |err: std::io::Error| {
        crate::Error::Key(format!(
            "could not write the KEK at {}: {err}",
            path.display()
        ))
    };
    if let Some(parent) = path.parent() {
        std::fs::create_dir_all(parent).map_err(io)?;
    }
    let mut options = std::fs::OpenOptions::new();
    options.write(true).create_new(true);
    #[cfg(unix)]
    {
        use std::os::unix::fs::OpenOptionsExt as _;
        options.mode(0o600);
    }
    let mut file = options.open(path).map_err(io)?;
    file.write_all(bytes).map_err(io)?;
    file.sync_all().map_err(io)?;
    drop(file);
    if let Some(parent) = path.parent() {
        // The rename-durability half: a KEK whose directory entry did not reach
        // the disk is a KEK that does not exist after a power cut, and every
        // secret sealed under it is gone.
        if let Ok(dir) = std::fs::File::open(parent) {
            let _ = dir.sync_all();
        }
    }
    Ok(())
}

/// Whether `value` carries the sealed-value magic.
///
/// Public because the migration question — *is this store already sealed?* — is
/// one an operator tool legitimately asks.
pub fn is_sealed(value: &[u8]) -> bool {
    value.len() >= SEAL_MAGIC.len() + NONCE_LEN + TAG_LEN && value.starts_with(SEAL_MAGIC)
}

/// Encrypt `plaintext` for `key_name` under `kek`.
///
/// The key name is the AEAD's associated data, so the result is bound to the
/// slot it was written for.
pub fn seal(kek: &Kek, key_name: &str, plaintext: &[u8]) -> crate::Result<Vec<u8>> {
    let aead = kek.aead()?;
    let mut nonce = [0u8; NONCE_LEN];
    SystemRandom::new()
        .fill(&mut nonce)
        .map_err(|_| crate::Error::Key("the system CSPRNG refused to produce a nonce".into()))?;

    let mut body = plaintext.to_vec();
    aead.seal_in_place_append_tag(
        Nonce::assume_unique_for_key(nonce),
        Aad::from(key_name.as_bytes()),
        &mut body,
    )
    .map_err(|_| crate::Error::Key(format!("could not seal the secret {key_name}")))?;

    let mut out = Vec::with_capacity(SEAL_MAGIC.len() + NONCE_LEN + body.len());
    out.extend_from_slice(SEAL_MAGIC);
    out.extend_from_slice(&nonce);
    out.extend_from_slice(&body);
    Ok(out)
}

/// Decrypt a value produced by [`seal`] for the same `key_name`.
///
/// Fails on a wrong KEK, a wrong key name, or any modified byte — all three are
/// the same GCM tag check, which is the point of using an AEAD rather than a
/// bare cipher.
pub fn unseal(kek: &Kek, key_name: &str, sealed: &[u8]) -> crate::Result<Vec<u8>> {
    if !is_sealed(sealed) {
        return Err(crate::Error::Key(format!(
            "the stored value for {key_name} is not a sealed secret"
        )));
    }
    let aead = kek.aead()?;
    let nonce_start = SEAL_MAGIC.len();
    let body_start = nonce_start + NONCE_LEN;
    let mut nonce = [0u8; NONCE_LEN];
    nonce.copy_from_slice(&sealed[nonce_start..body_start]);

    let mut body = sealed[body_start..].to_vec();
    let plaintext = aead
        .open_in_place(
            Nonce::assume_unique_for_key(nonce),
            Aad::from(key_name.as_bytes()),
            &mut body,
        )
        .map_err(|_| {
            crate::Error::Key(format!(
                "the secret {key_name} did not authenticate: wrong key-encrypting key, wrong \
                 secret name, or modified bytes"
            ))
        })?
        .to_vec();
    Ok(plaintext)
}

/// A [`SecretStore`] that encrypts everything on the way in and decrypts on the
/// way out.
///
/// Wraps any backend. The backend never sees a plaintext secret, so the bytes in
/// `secrets.arrow` — and therefore the bytes any `__gunnar_secrets__` entry
/// would ever carry — are ciphertext.
pub struct SealedSecretStore<S> {
    inner: S,
    kek: Kek,
    plaintext: PlaintextPolicy,
}

/// **What the store does with a value that carries no [`SEAL_MAGIC`].**
///
/// A stored value is either something this decorator sealed or something else,
/// and "something else" has exactly two origins: a gunnar old enough to have
/// written the clear, or a writer who is not gunnar. The KEK tells them apart
/// for every sealed value and tells them apart for no unsealed one — so the
/// answer cannot come from the value, and has to come from the caller, who
/// knows whether this machine has a pre-sealing store on it at all.
///
/// [`Refuse`](PlaintextPolicy::Refuse) is the default for the ordinary reason a
/// default is chosen: the machine that needs the other answer is the rare one,
/// and it is the one that can prove it needs it.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum PlaintextPolicy {
    /// An unsealed value is an error. Nothing under this store's keys was ever
    /// written in the clear, so a value without the magic was not put there by
    /// anything holding the KEK.
    #[default]
    Refuse,
    /// An unsealed value is a pre-sealing gunnar's, is read through, and is
    /// re-sealed by the next `get_or_create`. Only for a store that is
    /// demonstrably backed by one — see [`SealedSecretStore::migrating`].
    SealOnRead,
}

impl<S> std::fmt::Debug for SealedSecretStore<S> {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str("SealedSecretStore")
    }
}

impl<S: SecretStore> SealedSecretStore<S> {
    /// Seal `inner` under `kek`, refusing anything it reads back unsealed.
    pub fn new(inner: S, kek: Kek) -> Self {
        Self {
            inner,
            kek,
            plaintext: PlaintextPolicy::Refuse,
        }
    }

    /// Seal `inner` under `kek`, and read a pre-sealing gunnar's plaintext
    /// through so an in-place upgrade keeps its host key.
    ///
    /// **Only for a store that really is backed by one.** The caller is
    /// asserting a fact about the disk — on the server that is
    /// `legacy_secret_log` having found a `secrets.arrow`, which is the same
    /// file the read-old/write-new [`crate::MigratingSecretStore`] is reading
    /// through. On an installation with no such file this constructor claims a
    /// migration that cannot be happening, and every value it then accepts
    /// unsealed was written by something that did not hold the KEK.
    pub fn migrating(inner: S, kek: Kek) -> Self {
        Self {
            inner,
            kek,
            plaintext: PlaintextPolicy::SealOnRead,
        }
    }

    /// What this store does with an unsealed value.
    pub fn plaintext_policy(&self) -> PlaintextPolicy {
        self.plaintext
    }

    /// The backend, for tests that need to look at what was actually stored.
    pub fn inner(&self) -> &S {
        &self.inner
    }

    fn to_store_err(err: crate::Error) -> StoreError {
        StoreError::backend(err)
    }

    /// Decrypt a value read from the backend, passing a legacy plaintext
    /// through only if this store was told to expect one.
    fn open_value(&self, key: &str, raw: Vec<u8>) -> StoreResult<Vec<u8>> {
        if is_sealed(&raw) {
            return unseal(&self.kek, key, &raw).map_err(Self::to_store_err);
        }
        self.accept_plaintext(key)?;
        tracing::warn!(
            key,
            "read an UNSEALED secret written before sealing existed; it will be sealed on the \
             next get_or_create for this key"
        );
        Ok(raw)
    }

    /// The refusal, in one place because `get` and `get_or_create` must give
    /// the same answer — a store that refuses a read but adopts the same bytes
    /// on the boot path refuses nothing.
    fn accept_plaintext(&self, key: &str) -> StoreResult<()> {
        match self.plaintext {
            PlaintextPolicy::SealOnRead => Ok(()),
            PlaintextPolicy::Refuse => Err(Self::to_store_err(crate::Error::Key(format!(
                "the stored value for {key} carries no seal. Nothing holding the \
                 key-encrypting key wrote it: this store seals on the way in, and there is no \
                 pre-sealing secret log on this machine for it to have come from. Refusing to \
                 use it — an unsealed value in a sealed slot is what an attacker who can write \
                 the store but not read the KEK would leave behind"
            )))),
        }
    }
}

impl<S: SecretStore> SecretStore for SealedSecretStore<S> {
    fn get(&self, key: &str) -> StoreResult<Option<Vec<u8>>> {
        match self.inner.get(key)? {
            Some(raw) => self.open_value(key, raw).map(Some),
            None => Ok(None),
        }
    }

    fn put(&self, key: &str, value: &[u8]) -> StoreResult<()> {
        let sealed = seal(&self.kek, key, value).map_err(Self::to_store_err)?;
        self.inner.put(key, &sealed)
    }

    fn delete(&self, key: &str) -> StoreResult<()> {
        self.inner.delete(key)
    }

    fn get_or_create(
        &self,
        key: &str,
        mk: &mut dyn FnMut() -> StoreResult<Vec<u8>>,
    ) -> StoreResult<Vec<u8>> {
        // The atomicity that matters — exactly one `mk` across racing callers —
        // belongs to the backend and must not be reimplemented here, so this
        // delegates and seals *inside* the callback. Two threads racing on an
        // absent key therefore still mint once, and the loser gets the winner's
        // ciphertext back and decrypts it to the winner's plaintext.
        let stored = self.inner.get_or_create(key, &mut || {
            let plaintext = mk()?;
            seal(&self.kek, key, &plaintext).map_err(Self::to_store_err)
        })?;

        if is_sealed(&stored) {
            return unseal(&self.kek, key, &stored).map_err(Self::to_store_err);
        }

        // A legacy plaintext was already there. Seal it in place — this is the
        // migration, and it runs on the boot path the host key takes rather than
        // in a tool somebody has to remember. Same gate as the read: sealing an
        // injected plaintext in place would not launder it into a secret this
        // machine chose, it would make it permanent.
        self.accept_plaintext(key)?;
        tracing::warn!(
            key,
            "sealing a secret that was stored in the clear by an earlier gunnar"
        );
        let sealed = seal(&self.kek, key, &stored).map_err(Self::to_store_err)?;
        self.inner.put(key, &sealed)?;
        Ok(stored)
    }
}