# Proposal: Cryptography and Key Management

Capability-native abstractions for cryptographic keys and key sources.
Keys are capability objects; key material never crosses cap
boundaries. One interface serves every consumer — volume encryption,
TLS, code signing, instance identity, authenticated backups, per-service
secrets.


## Problem

Nearly every forthcoming capOS subsystem wants cryptography. A
partial list:

- Volume encryption at rest
  ([volume-encryption-proposal.md](volume-encryption-proposal.md)).
- TLS termination in the web text shell gateway
  ([boot-to-shell-proposal.md](boot-to-shell-proposal.md)).
- Inter-service mTLS on a multi-host capability graph
  ([networking-proposal.md](networking-proposal.md)).
- Instance identity tokens (signed JWTs) produced from cloud
  hypervisor metadata
  ([cloud-metadata-proposal.md](cloud-metadata-proposal.md)).
- WebAuthn/passkey public-key verification for login.
- Signed audit logs
  ([system-monitoring-proposal.md](system-monitoring-proposal.md)).
- Signed boot manifests and measured boot
  ([storage-and-naming-proposal.md](storage-and-naming-proposal.md)
  Open Question #5).
- Cloud KMS integration (envelope encryption for volumes and object
  stores).
- Future: signed release artifacts, encrypted swap, session tokens.

Without a shared abstraction each of these invents its own key
interface, its own "where does the key live" story, and its own audit
trail. That is how Linux ended up with `dm-crypt`, `fscrypt`,
`keyctl`, `PKCS#11`, `ssh-agent`, `gpg-agent`, `systemd-creds`, TPM
tools, and cloud-specific SDKs as mutually-unaware silos. capOS is
young enough to avoid that.

## Design Principle: Keys Are Capabilities

In every Unix-lineage system, a key is a byte string — a secret stored
somewhere (keyring, file, memory, HSM handle), protected by a
mechanism orthogonal to the system's main abstractions (syscalls +
files + processes). Every new subsystem therefore invents a new
protection mechanism.

In capOS, a key is a capability object. Holding a `SymmetricKey` or
`PrivateKey` cap means "you may compute with this key." It does not
mean "you may see this key." Key material lives in the address space
of the service that implements the cap; callers reach it by invoking
methods.

Consequences:

- **Attenuation falls out of the capability model.** A decrypt-only
  `SymmetricKey` is a wrapper CapObject that rejects `encrypt`. A
  key bound to a single AAD domain is a wrapper that fixes the `aad`
  argument. A sign-only `PrivateKey` is a wrapper that rejects
  `decrypt`. No new kernel mechanism is needed.
- **Revocation is a cap drop.** Drop the cap, the key is gone from
  that holder's reach. Other holders are unaffected.
- **Audit is intrinsic.** Every method invocation can flow through an
  audit cap. A malicious service granted `decrypt` authority
  generates audit records for every use; it cannot exfiltrate the raw
  key material silently.
- **Hardware isolation composes cleanly.** A TPM-backed key service
  implements the same `PrivateKey` interface as an in-process
  software key service; callers cannot distinguish, and should not
  need to.

A service granted a `SymmetricKey` with both `encrypt` and `decrypt`
can still run arbitrary oracle queries against the key. That is
weaker than "the key material never leaves an HSM" and stronger than
"the key is a byte string in the process heap." When stronger
containment is required, the key service is a thin process sitting on
top of a hardware primitive (TPM, Secure Enclave, cloud KMS).

## Schemas

### Symmetric keys

```capnp
interface SymmetricKey {
    # Authenticated encryption. `aad` is bound into the tag and MUST
    # match on decrypt. Nonce is returned because some constructions
    # generate it internally.
    encrypt @0 (plaintext :Data, aad :Data)
            -> (ciphertext :Data, nonce :Data, tag :Data);
    decrypt @1 (ciphertext :Data, nonce :Data, tag :Data, aad :Data)
            -> (plaintext :Data);

    # HKDF-style subkey derivation. The returned subkey is bound to
    # (label, context); it cannot be used to derive siblings.
    deriveSubkey @2 (label :Data, context :Data, purpose :KeyPurpose)
                 -> (subkey :SymmetricKey);

    # Wrap/unwrap subordinate keys. Used for envelope encryption and
    # for transporting keys between services.
    wrapSymmetric   @3 (subordinate :SymmetricKey) -> (wrapped :Data);
    unwrapSymmetric @4 (wrapped :Data, purpose :KeyPurpose)
                    -> (subordinate :SymmetricKey);
    wrapPrivate     @5 (subordinate :PrivateKey)   -> (wrapped :Data);
    unwrapPrivate   @6 (wrapped :Data, algorithm :AsymmetricAlgorithm)
                    -> (subordinate :PrivateKey);

    # MAC-only modes for keys with `KeyPurpose.integrity`.
    mac    @7 (message :Data) -> (tag :Data);
    verify @8 (message :Data, tag :Data) -> (ok :Bool);

    info @9 () -> (algorithm :SymmetricAlgorithm,
                   purpose :KeyPurpose,
                   identifier :Data);
}

enum SymmetricAlgorithm {
    aes256Gcm         @0;
    aes256GcmSiv      @1;
    xchacha20Poly1305 @2;
    aes256Xts         @3;  # block-device only; no authentication
    hmacSha256        @4;  # mac/verify only
    hmacSha384        @5;
    hmacSha512        @6;
}
```

### Asymmetric keys

```capnp
interface PublicKey {
    verify    @0 (message :Data, signature :Data) -> (ok :Bool);
    # Public-key encryption (e.g. ECIES, RSA-OAEP). For hybrid systems
    # this returns a wrapped ephemeral symmetric key alongside the
    # ciphertext.
    encrypt   @1 (plaintext :Data, aad :Data)
              -> (ciphertext :Data);
    # Export raw public material (SPKI DER, JWK, OpenSSH, PGP) for
    # callers that need to distribute it. Public material is freely
    # shareable; the cap itself is an authority only to invoke
    # methods, not to "own" the public key.
    export    @2 (format :PublicKeyFormat) -> (encoded :Data);
    info      @3 () -> (algorithm :AsymmetricAlgorithm,
                        identifier :Data);
}

interface PrivateKey {
    sign      @0 (message :Data, scheme :SignatureScheme)
              -> (signature :Data);
    decrypt   @1 (ciphertext :Data, aad :Data)
              -> (plaintext :Data);
    # Key agreement (ECDH, X25519).
    agree     @2 (peer :PublicKey, info :Data)
              -> (shared :SymmetricKey);
    public    @3 () -> (pk :PublicKey);
    info      @4 () -> (algorithm :AsymmetricAlgorithm,
                        purpose :KeyPurpose,
                        identifier :Data);
}

enum AsymmetricAlgorithm {
    ed25519      @0;
    x25519       @1;
    p256         @2;
    p384         @3;
    rsa2048      @4;
    rsa3072      @5;
    rsa4096      @6;
    # Post-quantum placeholders; added as capOS ships them.
    mlKem768     @7;  # ML-KEM (Kyber) for KEM
    mlDsa65      @8;  # ML-DSA (Dilithium) for signatures
}

enum SignatureScheme {
    default      @0;  # algorithm's natural default (Ed25519 pure, RSA-PSS, etc.)
    ecdsaSha256  @1;
    ecdsaSha384  @2;
    rsaPssSha256 @3;
    rsaPssSha512 @4;
    rsaPkcs1Sha256 @5;  # for compatibility only
}

enum PublicKeyFormat {
    spkiDer     @0;
    jwk         @1;
    opensshWire @2;
    pgpPacket   @3;
}
```

### Shared metadata

```capnp
enum KeyPurpose {
    generic       @0;
    blockVolume   @1;
    objectStore   @2;
    envelope      @3;   # KEK — only wraps/unwraps
    integrity     @4;   # MAC-only
    tls           @5;
    codeSigning   @6;
    instanceIdentity @7;
    authToken     @8;   # session tokens, JWTs
    webauthn      @9;
    audit         @10;
    oauthClientAssertion @11;  # RFC 7523 private_key_jwt client auth
    oidcIdToken   @12;          # IdP-side ID token signing (LocalIdentityProvider)
    dpopBinding   @13;          # RFC 9449 proof-of-possession keypairs
}
```

`identifier` (bytes in `info()`) is an opaque, stable handle usable
for logging, correlating audit records, and looking up the key in a
`KeyVault`. It is not a secret. It is not a cryptographic hash of the
key (that would let an attacker confirm a guessed key); it is a
random ID chosen at key creation.

### Key sources

A `KeySource` produces keys given some unlock context. Different
implementations realize different trust models.

```capnp
interface KeySource {
    # Produce a key given an unlock context (passphrase bytes, a
    # passkey assertion, a sealed blob, an attestation report, empty
    # for sources that hold keys directly).
    unlockSymmetric @0 (context :Data, purpose :KeyPurpose)
                    -> (key :SymmetricKey);
    unlockPrivate   @1 (context :Data, purpose :KeyPurpose)
                    -> (key :PrivateKey);

    # Seal a key under this source's policy. The returned blob can be
    # stored in the clear; unlock will refuse to produce the key
    # unless its policy is satisfied.
    sealSymmetric @2 (key :SymmetricKey, policy :SealPolicy)
                  -> (blob :Data);
    sealPrivate   @3 (key :PrivateKey, policy :SealPolicy)
                  -> (blob :Data);

    # Rewrap: unseal under current policy, reseal under new policy.
    # Used for KEK rotation without touching the underlying key.
    rewrap @4 (blob :Data, newPolicy :SealPolicy) -> (newBlob :Data);

    info @5 () -> (kind :KeySourceKind, identifier :Data);
}

enum KeySourceKind {
    manifestEmbedded @0;  # dev/CI only
    passphrase       @1;
    passkeyPrf       @2;  # WebAuthn PRF extension
    tpm2             @3;
    secureEnclave    @4;
    cloudKms         @5;
    attestation      @6;  # SEV-SNP / TDX / Nitro
    network          @7;  # Tang/Clevis-style
    softwareStored   @8;  # encrypted-at-rest in a KeyVault
    oidcFederated    @9;  # OIDC AccessToken -> KMS / remote unlock, no baked creds
}

struct SealPolicy {
    union {
        none          @0 :Void;
        pcr           @1 :PcrPolicy;
        kms           @2 :KmsPolicy;
        attested      @3 :AttestationPolicy;
        composite     @4 :List(SealPolicy);  # AND of sub-policies
        tokenExchange @5 :TokenExchangePolicy;  # OIDC/OAuth2-gated unlock
    }
}

struct TokenExchangePolicy {
    # The OIDC issuer whose tokens satisfy this policy.
    issuer          @0 :Text;
    # Required token audience (the KMS / STS endpoint).
    audience        @1 :Text;
    # Required subject predicate. Union allows exact or pattern matches
    # without growing this struct; see oidc-and-oauth2-proposal for the
    # full pattern grammar.
    subjectPattern  @2 :Text;
    # Additional required claims (e.g. `groups`, tenant ID, attestation
    # fields). Values are JSON-encoded bytes.
    requiredClaims  @3 :List(NamedClaim);
    # Acceptable LoA levels mapped from `acr`/`amr`.
    minAuthStrength @4 :UInt8;
}

struct NamedClaim {
    name  @0 :Text;
    value @1 :Data;
}

struct PcrPolicy {
    pcrMask   @0 :UInt32;            # bitmap of PCR indices
    pcrDigest @1 :Data;              # expected composite digest
    bank      @2 :TpmHashBank;
}

struct KmsPolicy {
    provider    @0 :Text;            # "aws", "gcp", "azure", "vault", ...
    keyId       @1 :Text;
    grantTokens @2 :List(Text);
}

struct AttestationPolicy {
    platform        @0 :AttestationPlatform;
    measurement     @1 :Data;
    signerPublicKey @2 :Data;
    allowedVariant  @3 :List(Data);  # e.g. permitted firmware versions
}

enum AttestationPlatform {
    sevSnp @0;
    tdx    @1;
    nitro  @2;
}
```

### Key lifecycle — the `KeyVault`

A `KeyVault` is a stateful service that stores sealed blobs, issues
key handles, handles rotation, and emits audit events. It is distinct
from `KeySource`: a `KeySource` is a *factory* producing keys; a
`KeyVault` is a *registry* tracking the keys a deployment knows
about.

```capnp
interface KeyVault {
    # Generate a fresh key of the given algorithm and purpose. Seals
    # it under `policy` and stores the blob. Returns a handle for
    # later retrieval.
    generateSymmetric @0 (algorithm :SymmetricAlgorithm,
                          purpose :KeyPurpose,
                          policy :SealPolicy)
                      -> (handle :KeyHandle, key :SymmetricKey);
    generatePrivate   @1 (algorithm :AsymmetricAlgorithm,
                          purpose :KeyPurpose,
                          policy :SealPolicy)
                      -> (handle :KeyHandle, key :PrivateKey);

    # Import an externally-generated key. Useful for recovery and for
    # deployments that compute keys elsewhere (e.g. an HSM).
    importSymmetric @2 (material :Data,
                        algorithm :SymmetricAlgorithm,
                        purpose :KeyPurpose,
                        policy :SealPolicy)
                    -> (handle :KeyHandle);
    importPrivate   @3 (material :Data,
                        algorithm :AsymmetricAlgorithm,
                        purpose :KeyPurpose,
                        policy :SealPolicy)
                    -> (handle :KeyHandle);

    # Retrieve a previously-generated or -imported key. The caller
    # must supply the unlock context appropriate to the seal policy.
    openSymmetric @4 (handle :KeyHandle, unlock :Data)
                  -> (key :SymmetricKey);
    openPrivate   @5 (handle :KeyHandle, unlock :Data)
                  -> (key :PrivateKey);

    # Rotate the sealing KEK (cheap; metadata only — re-seals the
    # blob). Rotating the key *material* requires rewriting everywhere
    # it is used and is the caller's responsibility.
    rotateSeal @6 (handle :KeyHandle, newPolicy :SealPolicy) -> ();

    # Delete a key. Subject to policy (audit log retention, legal
    # hold, etc.) — the concrete vault decides.
    destroy @7 (handle :KeyHandle, reason :Text) -> ();

    # List handles matching a filter. Returns only metadata.
    list @8 (filter :KeyFilter) -> (entries :List(KeyEntry));
}

struct KeyHandle {
    identifier @0 :Data;
}

struct KeyEntry {
    handle    @0 :KeyHandle;
    algorithm @1 :KeyAlgorithm;   # union of symmetric/asymmetric
    purpose   @2 :KeyPurpose;
    createdAt @3 :UInt64;
    lastUsed  @4 :UInt64;
    policy    @5 :SealPolicy;
}

struct KeyFilter {
    purpose   @0 :List(KeyPurpose);      # OR
    algorithm @1 :List(KeyAlgorithm);    # OR
    createdSince @2 :UInt64;
}

struct KeyAlgorithm {
    union {
        symmetric  @0 :SymmetricAlgorithm;
        asymmetric @1 :AsymmetricAlgorithm;
    }
}
```

## Concrete Key Sources

Not all of these ship on day one. Phases below give a sequence.

### `ManifestEmbeddedKeySource` — development and CI only

Key material baked into `SystemManifest`. Unsealable. Boot-time
validation refuses to build a production-profile image against this
source. Used for QEMU smoke tests and hermetic CI.

### `PassphraseKeySource` — interactive unlock

Consumes a passphrase from the console login flow
([boot-to-shell-proposal.md](boot-to-shell-proposal.md)), runs
Argon2id with per-source parameters, derives a KEK, unwraps sealed
blobs. No persistent state beyond the salt and KDF parameters (which
are public).

### `PasskeyPrfKeySource` — session unlock from WebAuthn

Consumes a WebAuthn assertion whose `hmac-secret` / PRF extension
yields a per-credential symmetric secret. Derives a KEK from the PRF
output; KEK unwraps the user's sealed DEK. Key material never leaves
the authenticator; the PRF output never leaves the key service
process.

### `Tpm2KeySource` — hardware-bound, measured-boot-gated

A TPM 2.0 driver service holds the TPM; this source wraps it. Seal
policies bind keys to PCR digests; unseal succeeds only if the
running boot chain matches. Enables unattended boot while keeping the
key off the disk.

### `SecureEnclaveKeySource` — platform key stores

Analog for Apple Secure Enclave, Android StrongBox, Intel CSE. Same
interface shape as `Tpm2KeySource`; different backing primitive.

### `CloudKmsKeySource` — cloud envelope encryption

Wraps a cloud KMS (AWS KMS, GCP KMS, Azure Key Vault, HashiCorp
Vault, KMIP). Unlock calls the KMS `Decrypt` operation with a wrapped
DEK and returns the plaintext DEK as a `SymmetricKey` cap. Seal calls
KMS `Encrypt` under a named KEK.

Authentication to KMS uses the `InstanceIdentity` cap from
[cloud-metadata-proposal.md](cloud-metadata-proposal.md); no
long-lived credentials live in the capOS image.

Properties the system gets by following the envelope pattern:

- Free KEK rotation (rewrap the DEK; volume data is untouched).
- Revocation by disabling the KMS key or revoking the IAM grant.
- Cross-account / cross-region access via KMS grants.
- Every unwrap appears in the cloud provider's audit log —
  observability comes for free.

### `AttestationKeySource` — confidential computing

Consumes SEV-SNP, TDX, or Nitro attestation reports. `unlock` submits
the report to a remote verifier (often cloud KMS with attestation
policy) which returns the unwrapped DEK only if the report matches
an approved measurement. Enables "only this specific capOS image,
running on genuine attested hardware, can decrypt this volume."

### `NetworkKeySource` — Tang / Clevis-style

Unlock derives a key by interacting with one or more remote servers;
no single server sees the plaintext key (when combined with secret
sharing). Supports the "revoke access by taking the server offline"
model without physical-access requirements.

### `SoftwareStoredKeySource` — encrypted on disk, under another source

The recursive case: a source whose seal policy points at another
source. Used to compose, e.g., a file-backed key store encrypted under
a TPM-sealed master key. The outer source provides integrity (TPM
seal); the inner source provides convenience (named key lookup).

### `OidcFederatedKeySource` — token-exchange-gated unlock

Derives a key from a short-lived OIDC/OAuth2 access token. The source
holds an `OAuthClient` or `WorkloadIdentityFederation` cap (from
[oidc-and-oauth2-proposal.md](oidc-and-oauth2-proposal.md)). `unlock`
obtains a fresh token for the configured audience — either by
exchanging a local `InstanceIdentity` JWT, a Kubernetes projected
service-account token, or a user session's access token — then
presents it to a remote KMS / STS / custom key service which
returns the wrapped DEK.

Two common shapes:

1. **Cloud KMS with workload identity federation.** Audience is the
   cloud STS; after token exchange the resulting cloud credential
   calls KMS Decrypt. Replaces every baked long-lived cloud IAM
   credential in the image.
2. **Per-user volume.** Audience is a capOS-internal key service;
   the user's `AccessToken` cap proves the caller is Alice; the key
   service enforces `TokenExchangePolicy` and returns Alice's DEK.

Properties the envelope + token-exchange pattern gets the system:

- No long-lived credentials in any capOS image.
- Per-principal KMS audit (the token `sub` appears in every KMS
  decrypt log).
- Revocation by IdP account disable, token revocation, or KMS grant
  removal.
- Step-up authentication gating: a `TokenExchangePolicy` requiring
  `minAuthStrength >= loa3` means Alice must have MFA-backed
  `acr`/`amr` claims before her volume unlocks.

## Consumers

A non-exhaustive list of how this interface is meant to be used. Each
consumer either exists as a proposal or is called out as future work.

| Consumer                         | Interface  | Key source                     |
|---------------------------------|-----------|--------------------------------|
| `EncryptedBlockDevice`          | symmetric | any                            |
| `EncryptedNamespace`            | symmetric | passphrase / passkeyPrf / KMS  |
| TLS termination (web gateway)   | both      | passphrase / KMS / cloud certs |
| SSH host key signing            | private   | KeyVault / softwareStored / KMS |
| SSH public-key login            | public    | CredentialStore / authorized key store |
| mTLS between services           | both      | KeyVault with KMS seal         |
| Instance identity JWT signing   | private   | cloudKms / softwareStored      |
| Signed audit logs               | private   | KeyVault, append-only policy   |
| WebAuthn verification           | public    | CredentialStore (public keys)  |
| Signed boot manifests           | public    | public key baked into firmware |
| Encrypted swap                  | symmetric | per-boot ephemeral (in-RAM)    |
| Encrypted backups               | symmetric | dedicated KMS key              |
| Session tokens (HMAC)           | symmetric | KeyVault, rotated frequently   |

## Relationship to `CredentialStore`

The `CredentialStore` in
[boot-to-shell-proposal.md](boot-to-shell-proposal.md) stores
*verifiers* — WebAuthn public keys, password hashes, recovery codes.
Its job is *authentication*: matching a claim from a user against a
stored verifier.

The `KeyVault` proposed here stores *keys* — symmetric DEKs,
signing private keys, KEKs. Its job is *cryptography*: producing keys
for use by capOS services.

Overlap happens at passkey unlock: the `CredentialStore` verifies the
WebAuthn assertion; the resulting PRF output feeds a
`PasskeyPrfKeySource` that produces a `SymmetricKey` usable by
`EncryptedNamespace`. Two services, one flow.

Keeping these distinct matters because their audit, retention, and
exposure models differ. A `CredentialStore` can expose every stored
entry as metadata (public keys are public) without leaking secrets; a
`KeyVault` cannot. A deployment may want different replication,
backup, and recovery policies for authenticators vs. encryption keys.

## Threat Model

Separate from the consumer-specific threat models, the crypto/key
management service itself has these:

1. **Memory scraping of a live key service.** The service holds
   plaintext keys in RAM. Mitigation: small trusted-computing-base
   (one crate, audited), `mlock` the heap (no swap leakage), zeroize
   on drop, no panic-induced core dumps, cap-scoped access so only
   callers with a `Key` cap can trigger operations. Against a kernel
   exploit, no defense; that is a separate threat.
2. **Oracle abuse.** A malicious service granted a `SymmetricKey` cap
   uses it as a decryption oracle. Mitigation: granting callers
   attenuated caps (`decrypt`-only, `aad`-pinned). Audit records make
   abuse detectable.
3. **Side-channel leakage.** Timing, cache, power. Mitigation: use
   constant-time implementations (`aes` crate's hardware backend;
   `chacha20poly1305` crate is constant-time), prefer AEAD modes that
   resist nonce-reuse gracefully (GCM-SIV), avoid bespoke crypto.
4. **Downgrade attacks on algorithm selection.** A caller requests a
   weak algorithm on a key that supports stronger modes. Mitigation:
   `info()` records the canonical algorithm; `KeyPurpose` constrains
   the method set; algorithm negotiation is the caller's job, not a
   feature of the key cap.
5. **Key persistence in unintended places.** Kernel DMA buffers, swap,
   crash dumps, core files. Mitigations are deployment-level (no
   swap, or encrypted swap with a per-boot key; disable core dumps
   for the key service process; measure the boot chain so a tampered
   kernel is detectable).

## Phases

Phases align with the subsystems that need keys. Crypto primitives
come first; consumers follow their own proposals' phases.

### Phase 1 — Interfaces and RAM-only implementation

- Add `SymmetricKey`, `PrivateKey`, `PublicKey`, `KeySource`,
  `KeyVault`, and the enums/structs above to `schema/capos.capnp`.
- Implement a RAM-only key service using vetted Rust crates
  (`aes-gcm-siv`, `chacha20poly1305`, `ed25519-dalek`, `x25519-dalek`,
  `rsa`, `hmac`, `hkdf`). No persistence. Pure interface exercise.
- `ManifestEmbeddedKeySource` for dev/CI.
- Host tests: AEAD round-trips, signature round-trips, key agreement,
  fuzz the decrypt/verify paths.

### Phase 2 — `KeyVault` with in-memory storage

- Key generation, sealed blob storage, handle-based lookup.
- `rotateSeal` implementation (metadata-only KEK rotation).
- Policy enforcement for seal/unseal.
- Audit cap integration
  ([system-monitoring-proposal.md](system-monitoring-proposal.md)).

### Phase 3 — Persistent `KeyVault` over the Store

- Sealed blobs live in a Store or Namespace.
- Access control: `KeyVault` cap is itself attenuable (read-only,
  purpose-filtered).
- Cross-reboot survival requires the Store, which requires persistent
  storage tracked in `docs/roadmap.md`.

### Phase 4 — `PassphraseKeySource` and `PasskeyPrfKeySource`

- Passphrase flow wires into console login.
- PasskeyPRF flow wires into WebAuthn assertions from the web text
  shell gateway.
- Per-user `EncryptedNamespace` becomes implementable end-to-end.

### Phase 5 — `Tpm2KeySource`

- TPM 2.0 driver as a userspace service (separate crate; talks to the
  TPM over x86 platform TIS or a virtio passthrough in cloud VMs).
- Seal policies bound to PCR digests.
- Measured-boot chain definition (firmware → bootloader → kernel →
  init → key service). PCR composition documented.

### Phase 6 — `CloudKmsKeySource`

- AWS KMS first; GCP KMS, Azure Key Vault, HashiCorp Vault, KMIP
  follow.
- Depends on `InstanceIdentity` from cloud-metadata and a functioning
  network stack.
- Cross-region / cross-account grant handling documented.

### Phase 6b — `OidcFederatedKeySource`

- Depends on `OAuthClient` and `WorkloadIdentityFederation` from
  [oidc-and-oauth2-proposal.md](oidc-and-oauth2-proposal.md).
- Workload identity federation to cloud KMS (no baked long-lived
  IAM credentials). Subject token sources: `InstanceIdentity`,
  attestation report envelope, Kubernetes projected token, GitHub
  Actions OIDC.
- Per-user volume unlock via user `AccessToken` against a
  capOS-internal key service honoring `SealPolicy.tokenExchange`.
- `TokenExchangePolicy` enforcement for seal/unseal.

### Phase 7 — `AttestationKeySource`

- SEV-SNP, TDX, or Nitro — whichever the first target cloud
  environment requires.
- Verifier can be cloud KMS with attestation policy or a standalone
  service.

### Phase 8 — Post-quantum migration

- Add ML-KEM and ML-DSA to the algorithm enums when capOS picks its
  PQ stack. Primarily a schema evolution and an added `sign` /
  `agree` path; no change to the interface shape.

## Relationship to Other Proposals

- **`volume-encryption-proposal.md`** — primary first consumer.
  Uses `SymmetricKey` for block and object encryption,
  `EncryptedBlockDevice` factory as a wrapper over a raw
  `BlockDevice` + a `SymmetricKey` cap.
- **`boot-to-shell-proposal.md`** — `CredentialStore` stores
  authenticator verifiers; `PasskeyPrfKeySource` here produces keys
  from assertions that pass `CredentialStore` verification.
- **`networking-proposal.md`** — TLS and mTLS need
  `PrivateKey`/`PublicKey`; instance mTLS bootstraps from a
  `CloudKmsKeySource` or `KeyVault`-issued service identity key.
- **`ssh-shell-proposal.md`** — SSH host keys are sign-only
  `PrivateKey` wrappers backed by `KeyVault`; accepted OpenSSH-format
  public keys are verifier material that map to sessions but never grant
  shell authority directly.
- **`certificates-and-tls-proposal.md`** — layers X.509, trust
  stores, CT, OCSP, pinning, ACME, and TLS config on top of the
  keys defined here. A TLS server's private key lives in a
  `KeyVault` from this proposal; its chain, verifier, and stapler
  live in that one.
- **`oidc-and-oauth2-proposal.md`** — OIDC/OAuth2 client, token,
  JWKS, JWT wrapper, DPoP, and workload identity federation caps
  compose with the keys defined here. `OidcFederatedKeySource` and
  `SealPolicy.tokenExchange` live in this proposal because they
  are key-source shapes; the token protocol frame, discovery,
  JWKS handling, grant types, and verifier live there.
  `KeyPurpose.oauthClientAssertion` / `.oidcIdToken` /
  `.dpopBinding` mark keys used by that proposal's flows.
  `JwtSigner` / `JwtVerifier` are thin wrappers defined there
  over `PrivateKey` / `PublicKey` from here.
- **`cloud-metadata-proposal.md`** — `InstanceIdentity` cap consumed
  by `CloudKmsKeySource` and `AttestationKeySource`.
- **`user-identity-and-policy-proposal.md`** — per-user keys are
  bound to session identity; the same cap chain that says "you are
  Alice" yields Alice's `SymmetricKey` via `PasskeyPrfKeySource`.
- **`cloud-deployment-proposal.md`** — hardware abstraction for
  self-encrypting drives sets up a future
  `SelfEncryptingBlockDevice` cap with hardware-held keys, a
  distinct trust model from software-crypto keys here.
- **`security-and-verification-proposal.md`** — crypto is a top
  target for tiered tooling: constant-time linting, AEAD fuzzing,
  Loom models of the unlock state machine, Kani-style proofs of
  nonce-uniqueness.
- **`system-monitoring-proposal.md`** — every `Key` method call, every
  `KeyVault` operation, and every `KeySource.unlock` should flow
  through the audit cap. Schema for audit events is defined there;
  key-management produces a specific event family.
- **`formal-mac-mic-proposal.md`** — includes GOST-style modeling.
  GOST symmetric (Kuznyechik, Magma) and asymmetric (Streebog-signed
  schemes) algorithms can be added to the enums when a deployment
  requires them.
- **`storage-and-naming-proposal.md`** — Open Question #5 (manifest
  trust, secure boot) is a prerequisite for `Tpm2KeySource` to be
  meaningful.

## Open Questions

1. **Canonical algorithm set for v1.** Overshooting the enum invites
   implementation sprawl; undershooting forces schema evolution
   early. Proposed minimum: `aes256GcmSiv`, `xchacha20Poly1305`,
   `hmacSha256`, `ed25519`, `x25519`. Add `rsa*`, `p256`, post-quantum
   as real consumers arrive.
2. **Does `SymmetricKey` expose raw encrypt-without-AAD?** AEAD with
   empty AAD is trivially expressible, but some callers may want
   explicit guarantees that non-AEAD modes are unavailable. Decide
   whether the interface permits `aad == Data()` universally or
   whether `KeyPurpose` constrains it.
3. **Public key distribution.** `PublicKey` is a cap, but public
   material is *public* — should there be a "public key is
   freely-shareable bytes" escape hatch outside the cap system?
   Probably yes; `export()` exists for exactly that reason. How does
   a caller obtain a `PublicKey` cap from raw bytes? Via a
   `PublicKeyImporter` factory that verifies format, or directly in
   `KeyVault.importPublic`?
4. **Revocation of in-flight caps.** If a `SymmetricKey` cap is
   granted to 10 services and the key is compromised, can the issuer
   revoke it? capOS cap revocation is generally "drop at each
   holder"; this might warrant a `KeyVault.revoke(handle)` that
   breaks the server-side object so every `encrypt`/`decrypt` returns
   an error. Worth designing explicitly rather than leaving implicit.
5. **Audit record granularity.** Logging every `encrypt` call for
   a high-throughput volume is noisy; logging only unseal events
   misses oracle abuse. Probably: unseal and policy-violation events
   are always logged; per-operation logging is a per-`KeyVault`
   policy, off by default.
6. **Key-use quotas.** Rate-limit `decrypt` operations per cap-holder
   to contain oracle abuse? Nice to have; not clear whether it
   belongs at the `Key` interface or at a `KeyVault` policy.
7. **HSM integration.** `PKCS#11` is the de facto standard for
   HSM access. Does capOS grow a `Pkcs11KeySource`, or does each
   HSM vendor ship a capability-native driver? The cap-native path
   is cleaner but depends on vendor cooperation.
8. **Backwards compatibility with stored blobs.** `SealPolicy`,
   algorithm IDs, and seal blob formats will evolve. Define a
   versioned envelope around every sealed blob from day one, so
   rolling upgrades are possible.
9. **Side-channel guarantees per implementation.** Document the
   expectation for each `KeyAlgorithm` (e.g. "constant-time required
   for `aes*`; use the `aes` crate's hardware backend on x86_64 and
   bit-sliced implementation elsewhere"). Without this, the security
   posture varies silently across builds.
10. **GOST and other jurisdiction-mandated algorithms.** The
    `formal-mac-mic-proposal.md` carves out a GOST-style track.
    Adding Kuznyechik, Magma, and Streebog-signed schemes is an
    additive extension; what matters is that the enums stay forward-
    compatible so a GOST-capable build does not require a schema
    fork.