Introduction

Open Sesame is a trust-scoped secret and identity fabric for the desktop. It manages encrypted secret vaults with per-profile trust boundaries, provides window switching with letter-hint overlays, clipboard history with sensitivity detection, keyboard input capture, and text snippet expansion. Everything is scoped to trust profiles that activate based on context or manual selection.

Packages

Open Sesame ships as two packages:

open-sesame (headless core) contains the sesame CLI, daemon-profile, daemon-secrets, daemon-launcher, and daemon-snippets. It runs anywhere with systemd: desktops, servers, containers, and VMs. This package provides encrypted vaults, secret management, environment variable injection, application launching, and profile management without any GUI dependencies.

open-sesame-desktop (GUI layer) depends on open-sesame and adds daemon-wm, daemon-clipboard, and daemon-input. It requires a COSMIC or Wayland desktop. This package provides the window switcher overlay, clipboard history, and keyboard input capture.

Installing open-sesame-desktop pulls in open-sesame automatically. On a server or in a container, install just open-sesame for encrypted secrets and application launching.

Audience

This documentation is written for:

• Contributors working on the Open Sesame codebase. The architecture and platform sections describe internal design, crate structure, IPC protocols, and implementation patterns.
• Extension authors building WASM component model extensions. The extending section covers the extension host runtime, SDK, WIT interfaces, and OCI distribution.
• Platform implementors adding support for new operating systems or compositor backends. The platform section documents the trait abstractions, factory patterns, and feature gating used across platform crates.
• Security auditors reviewing the trust model, cryptographic primitives, sandbox enforcement, and key hierarchy. The secrets, authentication, and compliance sections provide the relevant detail.
• Deployment engineers operating Open Sesame in production. The deployment and packaging sections cover systemd integration, service topology, and package structure.

Navigating the Documentation

• Architecture – internal design: crate map, daemon topology, IPC bus, data flows. Start here for a structural understanding of the system.
• Secrets – vault system: SQLCipher storage, key hierarchy, Argon2id KDF, key-encryption keys, per-profile isolation.
• Authentication – unlock mechanisms: password, SSH agent, multi-factor auth policy engine.
• Platform – OS abstraction layer: Linux (Wayland, D-Bus, evdev, systemd), macOS (Accessibility, Keychain, launchd), Windows (UI Automation, Credential Manager, Task Scheduler).
• Extending – extension system: Wasmtime host, WASI component model, WIT bindings, OCI packaging.
• Desktop – window management: compositor integration, overlay rendering, focus tracking.
• Deployment – operations: systemd units, service readiness, watchdog, packaging.
• Compliance – security posture: Landlock, seccomp, mlock, guard pages, audit logging.

For user-facing quick start instructions, CLI reference, and configuration guide, see the README.

Architecture Overview

Open Sesame is a trust-scoped secret and identity fabric for Linux, built as 21 Rust crates organized into a Cargo workspace. The system runs as seven cooperating daemons under systemd, communicating over a Noise IK encrypted IPC bus. Two Debian packages partition the daemons into a headless core suitable for servers, containers, and VMs, and a desktop layer that requires a Wayland compositor.

Crate Topology

The workspace (Cargo.toml:2-26) contains 21 crates in five layers: memory and cryptographic foundations, shared abstractions, platform bindings, daemon binaries, and the extension system.

Foundation Layer

Abstraction Layer

Platform Layer

Daemon Layer

Orchestration and Extension Layer

Daemon Model

The seven daemons are split across two systemd targets and two Debian packages.

Headless Daemons (package: open-sesame)

These four daemons have no GUI dependencies and run on any system with systemd: bare-metal servers, containers, VMs, and desktops alike.

Desktop Daemons (package: open-sesame-desktop)

These three daemons require a COSMIC or Wayland compositor. The open-sesame-desktop package depends on open-sesame, so installing it pulls in all headless daemons automatically.

Headless/Desktop Split Rationale

The split exists so that secret management, application launching, and snippet expansion can run on headless infrastructure (CI runners, jump hosts, fleet nodes) without pulling in Wayland, GTK, or GPU dependencies. A server running only open-sesame gets encrypted vaults, profile-scoped secrets, and environment injection (sesame env -p work -- aws s3 ls) with no graphical stack. A developer workstation installs open-sesame-desktop for the full experience: window switching, clipboard history, and keyboard shortcuts layered on top of the same headless core.

IPC Bus

All inter-daemon communication flows through a Noise IK encrypted IPC bus implemented in core-ipc.

Hub-and-Spoke Topology

daemon-profile hosts the BusServer. Every other daemon and every sesame CLI invocation connects as a BusClient. There is no peer-to-peer communication between daemons; all messages route through the hub.

Noise IK Transport

The IPC bus uses the Noise IK handshake pattern from the snow crate (Cargo.toml:89). In the IK pattern the initiator (client) knows the responder’s (server’s) static public key before the handshake begins. This provides mutual authentication and forward secrecy on every connection. Messages are framed with postcard (Cargo.toml:65) for compact binary serialization and deserialized into core-types::EventKind variants.

Ephemeral CLI Connections

The sesame CLI binary does not maintain a long-lived connection. Each CLI invocation opens a Noise IK session to daemon-profile, sends one or more EventKind messages, receives the response, and disconnects. The CLI has no persistent state and can be invoked from scripts, cron jobs, or CI pipelines without session management.

Message Flow Example

A sesame secret get -p work aws-access-key invocation follows this path:

1. sesame CLI opens a Noise IK session to daemon-profile.
2. daemon-profile authenticates the client and routes the secret-get request to daemon-secrets.
3. daemon-secrets verifies the caller’s clearance against the vault ACL, decrypts the value from the SQLCipher store, and returns it as a SensitiveBytes payload.
4. daemon-profile forwards the response to the CLI.
5. The CLI writes the secret to stdout and exits.

All secret material in transit is encrypted by the Noise session. All secret material at rest in daemon memory is held in ProtectedAlloc pages backed by memfd_secret(2) (see Memory Protection).

Daemon Topology

graph TD
    subgraph "open-sesame (headless)"
        DP[daemon-profile<br/><i>IPC bus host, profiles</i>]
        DS[daemon-secrets<br/><i>vault broker</i>]
        DL[daemon-launcher<br/><i>app launch, frecency</i>]
        DN[daemon-snippets<br/><i>snippet expansion</i>]
    end

    subgraph "open-sesame-desktop (GUI)"
        DW[daemon-wm<br/><i>window switcher overlay</i>]
        DC[daemon-clipboard<br/><i>clipboard history</i>]
        DI[daemon-input<br/><i>keyboard capture</i>]
    end

    CLI[sesame CLI<br/><i>ephemeral connections</i>]

    DS -->|BusClient| DP
    DL -->|BusClient| DP
    DN -->|BusClient| DP
    DW -->|BusClient| DP
    DC -->|BusClient| DP
    DI -->|BusClient| DP
    CLI -.->|ephemeral BusClient| DP

    subgraph "Foundation Crates"
        CM[core-memory]
        CC[core-crypto]
        CT[core-types]
        CI[core-ipc]
        CF[core-config]
        CZ[core-fuzzy]
        CSE[core-secrets]
        CP[core-profile]
        CA[core-auth]
    end

    subgraph "Platform Crates"
        PL[platform-linux]
    end

    subgraph "Extension System"
        EH[extension-host]
        ES[extension-sdk]
    end

    DP --> CI
    DP --> CP
    DP --> CF
    DP --> CT
    DS --> CSE
    DS --> CC
    DS --> CM
    DL --> CZ
    DL --> CF
    DW --> PL
    DC --> PL
    DI --> PL
    CI --> CT
    CI --> CM
    CC --> CM
    CSE --> CC
    CA --> CC
    EH --> ES

Crate Dependency Highlights

• Every daemon depends on core-ipc (for bus connectivity) and core-types (for the EventKind protocol schema).
• core-ipc depends on core-memory because Noise session keys are held in ProtectedAlloc.
• core-crypto depends on core-memory because SecureBytes wraps ProtectedAlloc for key material.
• The three desktop daemons (daemon-wm, daemon-clipboard, daemon-input) depend on platform-linux for Wayland protocol bindings, evdev access, and compositor integration.
• core-secrets depends on core-crypto for vault encryption and core-auth depends on core-crypto for key derivation during authentication.
• The extension-host crate uses wasmtime (Cargo.toml:164) with the component model and pooling allocator for sandboxed WASM extension execution.

Security Boundaries

Each daemon runs as a separate systemd service with:

• Landlock filesystem restrictions (platform-linux, landlock crate at Cargo.toml:136) limiting each daemon to only the filesystem paths it needs.
• seccomp syscall filtering (platform-linux, libseccomp crate at Cargo.toml:137) restricting each daemon to a minimal syscall allowlist.
• Noise IK mutual authentication on every IPC connection, preventing unauthorized processes from joining the bus.
• ProtectedAlloc secure memory for all key material, with memfd_secret(2) removing secret pages from the kernel direct map (see Memory Protection).

See Also

• Memory Protection – secure memory allocator internals
• IPC Protocol – Noise IK handshake, framing, and message schema
• Sandbox Model – Landlock and seccomp configuration
• Profile Trust Model – profile isolation contracts

Memory Protection

All secret-carrying types in Open Sesame are backed by core-memory::ProtectedAlloc, a page-aligned secure memory allocator that uses memfd_secret(2) on Linux 5.14+ to remove secret pages from the kernel direct map entirely. This page documents the allocator internals, the memory layout, the fallback path, and the type hierarchy built on top of it.

ProtectedAlloc Memory Layout

Every ProtectedAlloc instance maps a contiguous region of virtual memory containing five sections: three PROT_NONE guard pages, one read-only metadata page, and one or more read-write data pages. The layout is defined in core-memory/src/alloc.rs:31-32 where OVERHEAD_PAGES is set to 4 (guard0 + metadata + guard1 + guard2), and data pages are sized to fit the 16-byte canary plus the requested user data length.

                              mmap'd region (mmap_total bytes)
 +------------+------------+------------+---------------------------+------------+
 | guard pg 0 |  metadata  | guard pg 1 |       data pages ...      | guard pg 2 |
 | PROT_NONE  | PROT_READ  | PROT_NONE  |  PROT_READ | PROT_WRITE  | PROT_NONE  |
 +------------+------------+------------+---------------------------+------------+
 ^            ^            ^            ^                           ^
 |            |            |            |                           |
 mmap_base    +1 page      +2 pages     +3 pages                   +3 pages
              (metadata)                 (data_region)              +data_region_len
                                                                   (guard2)


              Detail of data pages (right-aligned user data):

 |<------------- data_region_len (data_pages * page_size) ------------->|
 +-------------------+-----------+--------------------------------------+
 |     padding       |  canary   |             user data                |
 |  (filled 0xDB)    |  16 bytes |           (user_len bytes)           |
 +-------------------+-----------+--------------------------------------+
 ^                   ^           ^                                      ^
 data_start          canary_ptr  user_data                              guard page 2
                                                                        (PROT_NONE)

Byte-Level Sizes

Given a system page size P (typically 4096) and a requested allocation of N bytes:

The padding is filled with 0xDB (PADDING_FILL, alloc.rs:29), matching libsodium’s garbage fill convention.

Guard Pages

Three guard pages are set to PROT_NONE via mprotect(2) (alloc.rs:422-434). Any read or write to a guard page triggers an immediate SIGSEGV:

• guard0 (mmap_base): prevents underflow from adjacent lower-address allocations.
• guard1 (mmap_base + 2*P): separates the read-only metadata page from the writable data region. Prevents metadata corruption from data-region underflow.
• guard2 (mmap_base + 3*P + data_region_len): the trailing guard page. Because user data is right-aligned within the data region, a buffer overflow of even one byte hits this page immediately.

Right-Alignment

User data is placed at the end of the data region (alloc.rs:455):

#![allow(unused)]
fn main() {
let user_data_ptr = data_start.add(data_region_len - user_len);
}

This right-alignment means a sequential buffer overflow crosses from user data directly into the trailing guard page (guard2), triggering SIGSEGV on the first out-of-bounds byte. Without right-alignment, an overflow would silently write into unused padding within the same page before reaching the guard.

Metadata Page

The metadata page (alloc.rs:438-451) stores allocation bookkeeping at fixed offsets, then is downgraded to PROT_READ:

The metadata page is restored to PROT_READ|PROT_WRITE during Drop (alloc.rs:688-694) so it can be volatile-zeroed before munmap.

memfd_secret(2) Backend

The preferred allocation backend on Linux is memfd_secret(2), invoked via raw syscall 447 (alloc.rs:130,335). This syscall, available since Linux 5.14, creates an anonymous file descriptor whose pages are:

• Removed from the kernel direct map: the pages are not addressable by any kernel code path, including /proc/pid/mem reads, process_vm_readv(2), kernel modules, and DMA engines.
• Invisible to ptrace: even CAP_SYS_PTRACE cannot read the page contents.
• Implicitly locked: the kernel does not swap memfd_secret pages to disk. No explicit mlock(2) is needed.

The syscall requires CONFIG_SECRETMEM=y in the kernel configuration. To check whether a running kernel has this enabled:

zgrep CONFIG_SECRETMEM /proc/config.gz
# or
grep CONFIG_SECRETMEM /boot/config-$(uname -r)

Probe and Caching

The allocator probes for memfd_secret availability once at process startup via probe_memfd_secret() (alloc.rs:125-188) and caches the result in a OnceLock<bool> (alloc.rs:45). The probe sequence:

1. Call syscall(447, 0) to create a secret fd.
2. If fd < 0, log an ERROR-level security degradation and cache false.
3. If fd >= 0, close the fd immediately and cache true.

Allocation Sequence

The memfd_secret_mmap() function (alloc.rs:333-372) performs the full allocation:

1. syscall(447, 0) – create the secret fd.
2. ftruncate(fd, size) – set the mapping size.
3. mmap(NULL, size, PROT_READ|PROT_WRITE, MAP_SHARED, fd, 0) – map the pages. MAP_SHARED is required for memfd_secret.
4. close(fd) – the mapping persists after the fd is closed.

Fallback: mmap(MAP_ANONYMOUS)

On kernels without memfd_secret support (Linux < 5.14 or CONFIG_SECRETMEM disabled), the allocator falls back to mmap(MAP_ANONYMOUS|MAP_PRIVATE) (alloc.rs:380-398). This fallback applies two additional protections that memfd_secret provides implicitly:

• mlock(2) (alloc.rs:495): locks the data region pages into RAM, preventing the kernel from swapping them to disk. If mlock fails with ENOMEM (the RLIMIT_MEMLOCK limit is exceeded), the allocator logs a WARN-level security degradation but continues (alloc.rs:498-511). If mlock fails with any other errno, allocation fails with ProtectedAllocError::MmapFailed.
• madvise(MADV_DONTDUMP) (alloc.rs:482): excludes the data region from core dumps. This is Linux-specific.

The fallback is a security degradation: pages remain on the kernel direct map and are readable via /proc/pid/mem by any process running as the same UID. An ERROR-level audit log is emitted by both probe_memfd_secret() (alloc.rs:147-161) and core_memory::init() (core-memory/src/lib.rs:83-91) when operating in fallback mode. The log message explicitly states that fallback mode does not meet IL5/IL6, STIG, or PCI-DSS requirements (lib.rs:88).

Canary Verification

Each ProtectedAlloc instance places a 16-byte canary (CANARY_SIZE, alloc.rs:25) immediately before the user data region. The canary value is a process-wide random generated once from getrandom(2) (on Linux, alloc.rs:56) or getentropy(2) (on macOS, alloc.rs:67) and cached in a OnceLock<[u8; 16]> (alloc.rs:39).

Placement

The canary is written at user_data_ptr - 16 (alloc.rs:457-464). A copy is also stored in the metadata page at offset 40 (alloc.rs:446).

Constant-Time Verification on Drop

During ProtectedAlloc::drop() (alloc.rs:636-720), the canary is verified before any cleanup:

1. The 16 bytes at canary_ptr are read as a slice (alloc.rs:641-642).

2. They are compared to the global canary using fixed_len_constant_time_eq() (alloc.rs:613-624). This function XORs each byte pair into an accumulator and reads the result through read_volatile to prevent the compiler from short-circuiting the comparison:

   #![allow(unused)]
   fn main() {
   fn fixed_len_constant_time_eq(a: &[u8], b: &[u8]) -> bool {
       if a.len() != b.len() {
           return false;
       }
       let mut acc: u8 = 0;
       for (x, y) in a.iter().zip(b.iter()) {
           acc |= x ^ y;
       }
       let result = unsafe { std::ptr::read_volatile(&acc) };
       result == 0
   }
   }

3. If the comparison fails, an ERROR-level audit log is emitted and the process aborts via std::process::abort() (alloc.rs:656). The process aborts rather than continuing with potentially compromised key material.

Canary corruption indicates a buffer underflow, heap corruption, or use-after-free in secret-handling code.

Volatile Zeroize

After canary verification passes, the entire data region (not just the user data portion) is volatile-zeroed via volatile_zero() (alloc.rs:627-632):

#![allow(unused)]
fn main() {
fn volatile_zero(ptr: *mut u8, len: usize) {
    let slice = unsafe { std::slice::from_raw_parts_mut(ptr, len) };
    slice.zeroize();
    std::sync::atomic::compiler_fence(std::sync::atomic::Ordering::SeqCst);
}
}

The zeroize crate (Cargo.toml:85) performs volatile writes that the compiler cannot elide. The compiler_fence(SeqCst) (alloc.rs:631) provides an additional barrier preventing reordering of the zeroize with the subsequent munmap. This zeroes the canary, the 0xDB padding, and the user data before the pages are returned to the kernel.

Drop Sequence

The full Drop implementation (alloc.rs:636-720) proceeds in order:

1. Canary check – constant-time comparison, abort on corruption.
2. Volatile-zero the data region – data_region_len bytes starting at data_region.
3. munlock (fallback only) – unlock data pages (alloc.rs:665).
4. MADV_DODUMP (fallback only, Linux) – re-enable core dump inclusion for the zeroed pages (alloc.rs:675).
5. Zero metadata page – restore PROT_READ|PROT_WRITE, volatile-zero (alloc.rs:686-695).
6. munmap – release the entire mapping back to the kernel (alloc.rs:700).

Type Hierarchy

Three types build on ProtectedAlloc to provide ergonomic secret handling at different layers of the system.

SecureBytes (core-crypto/src/secure_bytes.rs)

SecureBytes is the primary vehicle for cryptographic key material: master keys, vault keys, derived keys, and KEKs. It wraps a ProtectedAlloc with an actual_len field to support empty values (backed by a 1-byte sentinel allocation, secure_bytes.rs:55-56).

Key properties:

• from_slice(&[u8]) (secure_bytes.rs:73-81): copies directly into protected memory with no intermediate heap allocation. This is the preferred constructor.
• new(Vec<u8>) (secure_bytes.rs:51-63): accepts an owned Vec, copies into protected memory, then zeroizes the source Vec on the unprotected heap. The doc comment (secure_bytes.rs:37-44) explicitly notes the brief heap exposure and recommends from_slice when possible.
• into_protected_alloc() (secure_bytes.rs:107-120): zero-copy transfer of the inner ProtectedAlloc to a new owner. Uses ManuallyDrop to suppress the SecureBytes destructor and ptr::read to move the allocation out. The ProtectedAlloc is never copied or re-mapped.
• Clone (secure_bytes.rs:124-129): creates a fully independent ProtectedAlloc with its own guard pages, canary, and mlock. Both original and clone zeroize independently on drop.
• Debug (secure_bytes.rs:146-148): redacted output showing only byte count (SecureBytes([REDACTED; 32 bytes])), never contents.

SecureBytes does not implement Serialize or Deserialize. Secrets must be explicitly converted to SensitiveBytes before crossing a serialization boundary.

SecureVec (core-crypto/src/secure_vec.rs)

SecureVec is a password input buffer designed for character-by-character collection in graphical overlays where the full password length is not known in advance. It pre-allocates a fixed-size ProtectedAlloc (512 bytes for for_password(), secure_vec.rs:14,61) and provides UTF-8 aware push_char/pop_char operations.

Key properties:

• No reallocation: the buffer is fixed-size. push_char panics if the buffer is full (secure_vec.rs:118-122). The 512-byte limit accommodates passwords up to approximately 128 four-byte Unicode characters (secure_vec.rs:13).
• Lazy allocation: SecureVec::new() (secure_vec.rs:43-48) creates an empty instance with inner: None and no mmap. for_password() or with_capacity() triggers the actual ProtectedAlloc.
• UTF-8 aware pop: pop_char() (secure_vec.rs:133-160) scans backwards to find multi-byte character boundaries (checking the 0xC0 continuation mask) and zeroizes the removed bytes in-place before adjusting the cursor.
• clear() (secure_vec.rs:199-208): zeroizes all written bytes and resets the cursor without deallocating, allowing buffer reuse for sequential vault unlocks.
• Double zeroize on drop: Drop (secure_vec.rs:217-229) zeroizes written bytes before ProtectedAlloc::drop performs its own volatile-zero of the entire data region.

SensitiveBytes (core-types/src/sensitive.rs)

SensitiveBytes is the wire-compatible type for secret values in EventKind IPC messages. It wraps a ProtectedAlloc and implements Serialize/Deserialize for postcard framing.

Key properties:

• Zero-copy deserialization path: the custom SensitiveBytesVisitor (sensitive.rs:112-146) implements visit_bytes (sensitive.rs:123-125) which receives a borrowed &[u8] from the deserializer and copies directly into a ProtectedAlloc. When postcard performs in-memory deserialization, this path avoids any intermediate heap Vec<u8>.
• Fallback deserialization path: visit_byte_buf (sensitive.rs:129-132) handles deserializers that provide owned bytes. The Vec<u8> is copied into protected memory and immediately zeroized.
• Sequence fallback: visit_seq (sensitive.rs:136-145) handles deserializers that encode bytes as a sequence of u8 values. The collected Vec<u8> is zeroized after copying.
• from_protected() (sensitive.rs:57-62): accepts a ProtectedAlloc and actual_len directly, enabling zero-copy transfer from SecureBytes.
• Serialization (sensitive.rs:95-99): calls serializer.serialize_bytes() directly from the protected memory slice. postcard reads the slice without copying.
• Debug (sensitive.rs:160-163): redacted output ([REDACTED; 32 bytes]).

Zero-Copy Lifecycle

The three types form a zero-copy pipeline for secret material:

1. A vault key is derived by core-crypto and stored as SecureBytes (in ProtectedAlloc).
2. When the key must cross the IPC bus, SecureBytes::into_protected_alloc() transfers the ProtectedAlloc to SensitiveBytes::from_protected() with no heap copy and no re-mapping.
3. SensitiveBytes serializes directly from the ProtectedAlloc pages into the Noise-encrypted IPC frame.
4. On the receiving end, postcard’s visit_bytes path deserializes directly into a new ProtectedAlloc.

At no point does plaintext key material exist on the unprotected heap, provided the from_slice constructor path is used rather than SecureBytes::new(Vec<u8>).

init_secure_memory() Pre-Sandbox Probe

The core_memory::init() function (core-memory/src/lib.rs:58-107) must be called before the seccomp sandbox is applied. It performs a probe allocation of 1 byte (lib.rs:68) which triggers probe_memfd_secret() internally, caching whether syscall 447 is available. If this probe ran after seccomp activation, the raw syscall would be killed by the filter.

The function also reads RLIMIT_MEMLOCK via getrlimit(2) (lib.rs:62-65) and logs it alongside the security posture:

• memfd_secret available: INFO-level log with backend = "memfd_secret" and the rlimit_memlock_bytes value (lib.rs:71-78).
• memfd_secret unavailable: ERROR-level log with backend = "mmap(MAP_ANONYMOUS) fallback" and remediation instructions (lib.rs:83-91).
• Probe allocation failure: ERROR-level log warning that all secret-carrying types will panic on allocation (lib.rs:95-103).

The function is idempotent (lib.rs:57). The OnceLock values for CANARY, PAGE_SIZE, and MEMFD_SECRET_AVAILABLE (alloc.rs:39,42,45) ensure that the probe syscall, the getrandom call, and the sysconf call each execute exactly once per process regardless of how many times init() is called.

Guard Page SIGSEGV Test Methodology

The guard page tests (core-memory/tests/guard_page_sigsegv.rs) use a subprocess harness pattern because the expected outcome is process death by signal, which cannot be caught within a single test process.

Test Structure

Each test case consists of a parent test and a child harness:

1. Parent test (e.g., overflow_hits_trailing_guard_page, guard_page_sigsegv.rs:58-62): spawns the test binary targeting the harness function by name via --exact, with a gating environment variable __GUARD_PAGE_HARNESS.
2. Child harness (e.g., overflow_harness, guard_page_sigsegv.rs:66-83): checks the environment variable, allocates a ProtectedAlloc via from_slice(b"test"), performs a deliberate out-of-bounds read_volatile, and calls exit(1) if the read succeeds (which it must not).
3. Signal assertion (assert_signal_death, guard_page_sigsegv.rs:25-53): the parent verifies the child was killed by SIGSEGV (signal 11) or SIGBUS (signal 7), handling both direct signal death (ExitStatusExt::signal()) and the 128+signal exit code convention used by some platforms.

Test Cases

The overflow test validates right-alignment: because user data is flush against guard page 2, the very first out-of-bounds byte lands on a PROT_NONE page. The underflow test reads backward past the canary and padding into guard page 1 (between metadata and data region).

The environment variable gate (guard_page_sigsegv.rs:67) ensures that when the test binary is run normally (without __GUARD_PAGE_HARNESS set), the harness functions return immediately without performing any unsafe operations.

Platform Support Summary

The non-Unix stub (core-memory/src/lib.rs:111-182) exists solely so the crate compiles in workspace-wide cargo check runs. All methods on the stub panic or return errors; no secrets can be handled on unsupported platforms.

See Also

• Architecture Overview – crate topology and daemon model
• IPC Protocol – Noise IK transport that carries SensitiveBytes payloads
• Sandbox Model – Landlock and seccomp filters applied after init_secure_memory()

IPC Bus Protocol

The core-ipc crate implements the inter-process communication protocol used by all Open Sesame daemons and the sesame CLI.

Bus Architecture

The IPC bus uses a star topology. daemon-profile hosts a BusServer that binds a Unix domain socket at $XDG_RUNTIME_DIR/pds/bus.sock. All other daemons and the sesame CLI connect to this socket as BusClient instances.

The server accept loop (BusServer::run in server.rs) listens for incoming connections, extracts UCred credentials via SO_PEERCRED, enforces a same-UID policy (rejecting connections from different users), and spawns a per-connection handler task. Each connection performs a mandatory Noise IK handshake before any application data flows.

Per-connection state is tracked in ConnectionState, which holds:

• The daemon’s DaemonId (set on first message)
• A registry-verified daemon name (verified_name, from Noise IK handshake)
• An outbound mpsc::Sender<Vec<u8>> channel (capacity 256)
• PeerCredentials (PID and UID)
• SecurityLevel clearance
• Subscription filters
• An optional TrustVector computed at connection time

An atomic u64 counter assigns monotonically increasing connection IDs. Connection state is registered only after the Noise handshake succeeds, preventing a race where broadcast frames arrive on the outbound channel before the writer task is ready.

On BusServer::drop, the socket file is removed from the filesystem.

Noise IK Handshake

All socket connections use the Noise Protocol Framework with the IK pattern:

Noise_IK_25519_ChaChaPoly_BLAKE2s

The primitives are:

• X25519 Diffie-Hellman key agreement
• ChaCha20-Poly1305 authenticated encryption (AEAD)
• BLAKE2s hashing

The IK pattern means the initiator (connecting daemon) transmits its static key encrypted in the first message, and the responder’s (bus server’s) static key is pre-known to the initiator. This provides mutual authentication in a single round-trip (2 messages).

From the initiator (client) perspective:

1. Write message 1 to responder (ephemeral key + encrypted static key)
2. Read message 2 from responder (responder’s ephemeral key)
3. Transition to transport mode with forward-secret keys

From the responder (server) perspective:

1. Read message 1 from initiator (contains initiator’s ephemeral + encrypted static)
2. Write message 2 to initiator (contains responder’s ephemeral)
3. Transition to transport mode with forward-secret keys

The handshake has a 5-second timeout (HANDSHAKE_TIMEOUT) to prevent denial-of-service via slow handshake. The snow crate provides the Noise implementation.

Prologue Binding

The Noise prologue cryptographically binds OS-level transport identity to the encrypted channel. Both sides construct an identical prologue from UCred credentials:

PDS-IPC-v1:<lower_pid>:<lower_uid>:<higher_pid>:<higher_uid>

Canonical ordering is by PID (lower PID first), ensuring both sides produce identical bytes regardless of which side is the server. If either side has incorrect peer credentials (e.g., due to spoofing), the prologue mismatch causes the Noise handshake to fail cryptographically.

PeerCredentials are obtained via:

• extract_ucred(): calls UnixStream::peer_cred() (uses SO_PEERCRED on Linux) to get the remote peer’s PID and UID.
• local_credentials(): calls rustix::process::getuid() and std::process::id() for the local process.

An in-process sentinel (PeerCredentials::in_process()) uses u32::MAX as the UID, which never matches a real UCred check.

Encrypted Transport

After handshake completion, NoiseTransport wraps a snow::TransportState and provides chunked encrypted I/O.

Noise transport messages are limited to 65535 bytes. The maximum plaintext per Noise message is 65519 bytes (65535 minus the 16-byte AEAD tag). Application frames up to 16 MiB (MAX_FRAME_SIZE = 16 * 1024 * 1024) are chunked into multiple Noise messages.

Encrypted Frame Wire Format

[4-byte BE chunk_count]     (length-prefixed, plaintext)
[length-prefixed encrypted chunk 1]
[length-prefixed encrypted chunk 2]
...
[length-prefixed encrypted chunk N]

Each chunk is individually encrypted by snow::TransportState::write_message and written via the length-prefixed framing layer. The chunk count header is transmitted in the clear because it is not sensitive and the reader needs it to know how many chunks to expect.

Zero-length payloads send one empty encrypted chunk. On the read path, the reassembled payload is validated against MAX_FRAME_SIZE, and the intermediate decrypt buffer is zeroized via zeroize::Zeroize.

A 200 KiB payload requires approximately 4 chunks (200 * 1024 / 65519). The maximum number of chunks for a 16 MiB payload is validated on read to reject fabricated chunk counts.

Mutual Exclusion

snow::TransportState requires &mut self for both encrypt and decrypt. Both the server and client use tokio::select! to multiplex reads and writes in a single task rather than splitting into separate reader/writer tasks with a Mutex. The Mutex approach would deadlock because the reader would hold the lock while awaiting socket I/O, starving the writer.

Decrypted postcard buffers on the server side and plaintext outbound buffers on the client side are zeroized after processing, as they may contain serialized secret values.

Framing Layer

The framing layer (framing.rs) provides two independent services.

Serialization

encode_frame and decode_frame convert between typed Rust values and postcard byte payloads:

• encode_frame<T: Serialize>(value) -> Vec<u8>: calls postcard::to_allocvec.
• decode_frame<T: DeserializeOwned>(payload) -> T: calls postcard::from_bytes.

These are symmetric: decode_frame(encode_frame(v)) == v.

Wire I/O

write_frame and read_frame add and strip a 4-byte big-endian length prefix for socket transport:

• write_frame(writer, payload): writes [4-byte BE length][payload], then flushes.
• read_frame(reader) -> Vec<u8>: reads the 4-byte length, validates against MAX_FRAME_SIZE (16 MiB), then reads the payload.

The length prefix is a wire-only concern. Internal channels (bus routing, BusServer::publish, subscriber mpsc channels) carry raw postcard payloads without it.

Socket wire format: [4-byte BE length][postcard payload]

Frames with a length exceeding MAX_FRAME_SIZE are rejected on read to prevent out-of-memory conditions from malformed or malicious length prefixes.

Message Envelope

Every IPC message is wrapped in Message<T> (message.rs). The current wire version is 3 (WIRE_VERSION = 3).

MessageContext carries per-client identity state so Message::new() can populate all fields. A minimal context requires only a DaemonId; v3 fields default to None.

The verified_sender_name is set exclusively by route_frame() in the bus server. Client-supplied values are overwritten. None indicates an unregistered client. Postcard uses positional encoding, so all Option fields must always be present on the wire; skip_serializing_if is deliberately not used.

Message::new() generates a UUID v7 for msg_id (time-ordered) and leaves correlation_id at None. The with_correlation(id) builder method sets it for response messages.

Clearance Model

SecurityLevel Enum

SecurityLevel (core-types/src/security.rs) classifies message sensitivity for bus routing. The variants, ordered from lowest to highest by their derived Ord:

Because SecurityLevel derives PartialOrd and Ord, clearance comparisons use standard Rust ordering: Open < Internal < ProfileScoped < SecretsOnly.

ClearanceRegistry

ClearanceRegistry (registry.rs) maps X25519 static public keys ([u8; 32]) to DaemonClearance entries:

#![allow(unused)]
fn main() {
pub struct DaemonClearance {
    pub name: String,
    pub security_level: SecurityLevel,
    pub generation: u64,
}
}

The generation counter increments on every key change (rotation or crash-revocation). It is used by two-phase rotation to detect concurrent revocations.

The registry is populated by daemon-profile at startup from per-daemon keypairs. It is wrapped in RwLock<ClearanceRegistry> inside ServerState to allow runtime mutation.

After the Noise IK handshake, the server extracts the client’s static public key via NoiseTransport::remote_static() (which calls TransportState::get_remote_static()). The Noise IK pattern guarantees the remote static key is available after handshake. The 32-byte key is looked up in the registry:

• Found: the connection receives the registered name and clearance level.
• Not found: the connection is treated as an ephemeral client with SecretsOnly clearance.

The registry supports rotate_key(old, new) (removes old entry, inserts new with incremented generation), revoke(pubkey) (removes and returns the entry), register_with_generation (for revoke-then-reregister flows), and find_by_name (linear scan, acceptable for fewer than 10 daemons).

Routing Enforcement

route_frame() enforces two clearance rules:

1. Sender clearance: A daemon may only emit messages at or below its own clearance level. If conn.security_clearance < msg.security_level, the frame is rejected and an AccessDenied response is sent back to the sender.
2. Recipient clearance: When broadcasting, the server skips subscribers whose security_clearance is below the message’s security_level.

Sender Identity Verification

On the first message from a connection, route_frame() records the self-declared DaemonId. Subsequent messages must use the same DaemonId. A change mid-session is treated as an impersonation attempt: the frame is dropped and an AccessDenied response is returned.

The server stamps verified_sender_name onto every routed message by re-encoding it after registry lookup. If the connection’s trust_snapshot field is not set on the message, the server also stamps the connection-level TrustVector. This re-encode adds serialization overhead on every routed frame, but for a local IPC bus with fewer than 10 daemons the cost is negligible (microseconds per frame).

Ephemeral Clients

Clients whose static public key is not in the ClearanceRegistry receive SecurityLevel::SecretsOnly clearance. This applies to the sesame CLI and any other transient tool.

Ephemeral clients are still authenticated: the same-UID check and Noise IK handshake both apply. They simply lack a pre-registered identity in the registry. The audit log records these connections as ephemeral-client-accepted events with the client’s X25519 public key and PID/UID.

Key Management

Key generation, persistence, and tamper detection are implemented in noise_keys.rs.

Keypair Generation

generate_keypair() produces an X25519 static keypair via snow::Builder::generate_keypair(). Both the public and private keys are 32 bytes. The returned ZeroizingKeypair wrapper guarantees private key zeroization on drop (including during panics), since snow::Keypair has no Drop implementation. ZeroizingKeypair::into_inner() transfers ownership using mem::take to zero the wrapper’s copy.

Filesystem Layout

Keys are stored under $XDG_RUNTIME_DIR/pds/:

The keys/ directory is set to mode 0700 to prevent local users from enumerating registered daemons.

Atomic Writes

Private keys are written atomically: the key is written to a .tmp file with 0600 permissions set at open time via OpenOptionsExt::mode, fsynced, then renamed to the final path. This prevents a window where the key file exists with default (permissive) permissions. The write is performed inside tokio::task::spawn_blocking to avoid blocking the async runtime.

Tamper Detection Checksums

Each keypair has an accompanying .checksum file containing blake3::keyed_hash(public_key, private_key) – a BLAKE3 keyed hash using the 32-byte public key as the key and the private key as the data. On read, the checksum is recomputed and compared to the stored value. A mismatch produces a TAMPER DETECTED error with instructions to delete the affected files and restart daemon-profile.

This detects partial corruption or partial tampering (e.g., private key replaced but checksum file untouched). It does not prevent an attacker with full filesystem write access from replacing all three files (private key, public key, checksum) with a self-consistent set. That threat model requires a root-of-trust outside the filesystem such as TPM-backed attestation.

Missing checksum files (from older installations) produce a warning rather than an error, for backward compatibility.

Key Rotation

The ClearanceRegistry supports runtime key rotation via rotate_key(old_pubkey, new_pubkey), which atomically removes the old entry and inserts the new one with the same name and clearance level but an incremented generation counter.

The rotation protocol uses KeyRotationPending and KeyRotationComplete events:

1. daemon-profile generates a new keypair for the target daemon, writes it to disk, and broadcasts KeyRotationPending with the new public key and a grace period.
2. The target daemon calls BusClient::handle_key_rotation, which reads the new keypair from disk, verifies the announced public key matches what is on disk (detecting tampering), reconnects to the bus with the new key, and re-announces via DaemonStarted.
3. On reconnection, if the server detects a DaemonStarted from a verified name that already has an active connection, it evicts the stale old connection and registers the new one in name_to_conn.

connect_with_keypair_retry supports crash-restart scenarios where daemon-profile may have regenerated a daemon’s keypair. Each retry re-reads the keypair from disk with exponential backoff.

Request-Response Correlation

The bus supports three message routing patterns.

Request-Response (Unicast Reply)

When a message arrives without a correlation_id, route_frame() records (msg_id -> sender_conn_id) in the pending_requests table. The message is then broadcast to eligible subscribers. When a response arrives (identified by having a correlation_id), the server removes the matching entry from pending_requests and delivers the response only to the originating connection.

On the client side, BusClient::request() creates a message, registers a oneshot::channel waiter keyed by msg_id, sends the message, and awaits the response with a caller-specified timeout. If the timeout expires, the waiter is cleaned up and an error is returned.

Confirmed RPC

The server provides register_confirmation(correlation_id, mpsc::Sender), which returns an RAII ConfirmationGuard. When a correlated response matching the registered correlation_id arrives at route_frame(), the raw frame is sent to the confirmation channel instead of (or in addition to) the normal routing path. The ConfirmationGuard deregisters the route on drop, preventing stale entries from accumulating if the caller times out or encounters an error.

Pub-Sub Broadcast

Messages without a correlation_id that are not responses are broadcast to all connected subscribers whose security_clearance meets or exceeds the message’s security_level. The sender’s own connection is excluded to prevent feedback loops. The same echo-suppression applies to BusServer::publish() for in-process subscribers (it decodes the frame to extract the sender DaemonId and skips matching connections).

Named Unicast

The server maintains a name_to_conn: HashMap<String, u64> mapping, populated when route_frame() processes DaemonStarted events from connections with a verified_sender_name. send_to_named(daemon_name, frame) resolves the daemon name to a connection ID for O(1) unicast delivery without broadcasting.

Socket Path Resolution

socket_path() in transport.rs resolves the platform-appropriate socket path:

On Linux, XDG_RUNTIME_DIR must be set; its absence is a fatal error.

Socket Permissions

The bus server applies defense-in-depth permissions on bind:

• The socket file is set to mode 0700.
• The parent directory is set to mode 0700.

The real security boundary is UCred UID validation (the same-UID check in the accept loop), but restrictive filesystem permissions harden against misconfigured XDG_RUNTIME_DIR permissions.

See Also

• Protocol Evolution – forward compatibility and wire versioning
• Memory Protection – zeroization and secret handling

Protocol Evolution

This page documents how the Open Sesame IPC protocol handles versioning, forward compatibility, and the addition of new event types without breaking existing daemons.

EventKind and Unknown Variant Deserialization

The protocol schema is defined by the EventKind enum in core-types/src/events.rs. This enum is marked #[non_exhaustive] and contains a catch-all variant:

#![allow(unused)]
fn main() {
#[derive(Clone, Serialize, Deserialize)]
#[non_exhaustive]
pub enum EventKind {
    // ... all named variants ...

    #[serde(other)]
    Unknown,
}
}

The #[serde(other)] attribute on the Unknown variant is the forward-compatibility mechanism. When a daemon receives a postcard-encoded EventKind with a variant discriminant it does not recognize (because the sender is running a newer version of the code), serde deserializes it as EventKind::Unknown instead of returning a deserialization error.

This means a daemon compiled against an older version of core-types can receive messages containing event variants that did not exist when it was compiled. The message deserializes successfully; the daemon sees EventKind::Unknown and can choose to ignore it, log it, or pass it through.

The #[non_exhaustive] attribute enforces at compile time that all match arms on EventKind must include a wildcard or Unknown branch. This prevents new variants from causing compile errors in downstream crates that have not been updated.

Postcard Encoding Properties

The IPC bus uses postcard (a #[no_std]-compatible, compact binary serde format) for all serialization. Several properties of postcard’s encoding are relevant to protocol evolution.

Externally-Tagged Enums

EventKind uses serde’s default externally-tagged representation. Postcard encodes externally-tagged enums as a varint discriminant followed by the variant’s fields in declaration order. The events.rs source contains an explicit note:

Externally-tagged enum (serde default) for postcard wire compatibility. Postcard does not support #[serde(tag = "...", content = "...")].

This means:

• Each variant is identified by its position (index) in the enum declaration.
• Adding new variants at the end of the enum produces new discriminant values that older decoders do not recognize, triggering #[serde(other)] deserialization to Unknown.
• Reordering existing variants would change their discriminants and break all existing decoders. Variant ordering must be append-only.

Positional Field Encoding

Postcard encodes struct fields positionally (by declaration order), not by name. The Message<T> envelope in message.rs contains a comment making this explicit:

No skip_serializing_if – postcard uses positional encoding, so the field must always be present in the wire format for decode compatibility.

This means:

• Every field in Message<T> must always be serialized, even if its value is None. Omitting an Option field via skip_serializing_if would shift all subsequent fields by one position, causing decode failures.
• New fields can only be appended to the end of the struct. The v3 fields (origin_installation, agent_id, trust_snapshot) are explicitly commented as “v3 fields (appended for positional encoding safety).”
• Removing or reordering existing fields is a breaking change.

Implications for Field Addition

When a v3 sender transmits a message with the three new trailing fields to a v2 receiver, the v2 decoder reads only the fields it knows about and ignores trailing bytes. Postcard’s from_bytes does not require that all input bytes be consumed – it reads fields sequentially and stops when the struct is fully populated. This means appending new Option fields to Message<T> is backward-compatible as long as older decoders were compiled without those fields.

When a v2 sender transmits a message missing the v3 trailing fields to a v3 receiver, postcard::from_bytes encounters end-of-input when trying to decode the missing fields. In practice, the codebase treats wire version bumps as requiring atomic deployment of all binaries (see the wire version section below).

Wire Version Field

The Message<T> struct contains a wire_version: u8 field, always serialized first. The current value is 3, defined as pub const WIRE_VERSION: u8 = 3 in message.rs.

The source code documents the wire version contract:

WIRE FORMAT CONTRACT:

v2 fields: wire_version, msg_id, correlation_id, sender, timestamp, payload, security_level, verified_sender_name

All v2 binaries must be deployed atomically (single compilation unit). Adding fields requires incrementing this constant and updating the decode path to handle both old and new versions during rolling upgrades.

What the Wire Version Encodes

The wire version tracks changes to the Message<T> envelope structure – specifically, which fields are present and in what order. It does not track changes to EventKind variants (those are handled by #[serde(other)]).

• v2: 8 fields (wire_version through verified_sender_name)
• v3: 11 fields (adds origin_installation, agent_id, trust_snapshot)

Version Negotiation

The protocol does not perform explicit version negotiation. There is no handshake phase where client and server agree on a wire version. Instead, Message::new() always stamps the current WIRE_VERSION, and the source code states that all binaries must be deployed atomically when the wire version changes.

A receiver can inspect msg.wire_version after deserialization to determine which generation of the protocol the sender used. The current codebase does not implement version-conditional decode logic; all daemons are expected to be at the same wire version. The comment about “updating the decode path to handle both old and new versions during rolling upgrades” describes an intended future capability, not current behavior.

How New Event Variants Are Added

Adding a new EventKind variant follows this procedure:

1. Append the new variant to the end of the EventKind enum in core-types/src/events.rs. Inserting it in the middle would change the discriminant indices of all subsequent variants.
2. Add a Debug arm in the impl_event_debug! macro invocation at the bottom of events.rs. The macro enforces exhaustiveness – omitting a variant is a compile error. Sensitive variants (containing passwords or secret values) go in the sensitive section with explicit REDACTED annotations. All others go in the transparent section.
3. No wire version bump is needed for new EventKind variants. The Unknown catch-all handles unrecognized discriminants at the EventKind level. Wire version bumps are only needed for changes to the Message<T> envelope structure.

Daemons compiled against the old core-types deserialize the new variant as EventKind::Unknown. Daemons compiled against the new core-types see the fully typed variant. Both can coexist on the same bus.

How New Message Fields Are Added

Adding a new field to Message<T> is a more disruptive change:

1. Append the new field to the end of the Message<T> struct. Postcard’s positional encoding means insertion or reordering breaks all existing decoders.
2. Increment WIRE_VERSION to signal the structural change.
3. Deploy all binaries atomically. The codebase does not currently implement multi-version decode logic. All daemons must be rebuilt and redeployed together.
4. Update MessageContext if the new field should be populated by the sender (as was done for origin_installation, agent_id, and trust_snapshot in v3).
5. Do not use skip_serializing_if on the new field. The field must always be present on the wire for positional decode compatibility.

Practical Constraints

Variant Stability

The EventKind enum currently contains over 80 variants spanning window management, profile lifecycle, clipboard, input, secrets RPC, launcher RPC, agent lifecycle, authorization, federation, device posture, multi-factor auth, and bus-level errors. Each variant’s position in the enum declaration is its wire discriminant. Removing a variant or changing its position is a breaking wire change.

Enum Variant Field Changes

Postcard encodes variant fields positionally, the same as struct fields. Adding a field to an existing variant, removing a field, or reordering fields within a variant is a breaking wire change. New fields for existing functionality should be introduced as new variants rather than modifications to existing ones.

Sensitivity Redaction

The Debug implementation for EventKind uses a compile-time exhaustive macro (impl_event_debug!) that separates sensitive variants from transparent ones. Sensitive variants (SecretGetResponse, SecretSet, UnlockRequest, SshUnlockRequest, FactorSubmit) have their secret-bearing fields rendered as [REDACTED; N bytes] in debug output. Adding a new variant that carries secret material requires placing it in the sensitive section of the macro.

Forward Compatibility Boundaries

The #[serde(other)] mechanism provides forward compatibility only for unknown enum variants. It does not help with:

• Unknown fields within a known variant (postcard has no field-skipping mechanism for positional encoding)
• Structural changes to the Message<T> envelope
• Changes to the framing layer (length-prefix format, encryption chunking)
• Changes to the Noise handshake parameters

These categories of change require coordinated deployment of all binaries.

See Also

• IPC Bus Protocol – transport, framing, and routing details

Sandbox Model

Open Sesame enforces a three-layer process containment model on Linux: Landlock filesystem sandboxing, seccomp-bpf syscall filtering, and systemd unit hardening. Each daemon receives a tailored sandbox that grants the minimum privileges required for its function. Sandbox application is mandatory — every daemon treats sandbox failure as fatal and refuses to start unsandboxed.

Process Hardening

Before any sandbox is applied, every daemon calls harden_process() (platform-linux/src/security.rs:14). This function performs two operations:

1. PR_SET_DUMPABLE(0) — prevents ptrace attachment by non-root processes and prevents core dumps from containing process memory (security.rs:19).
2. RLIMIT_CORE(0,0) — sets both soft and hard core dump limits to zero, preventing core files even if dumpable is re-enabled by setuid (security.rs:32-36).

Resource limits are applied via apply_resource_limits() (security.rs:66). All daemons set RLIMIT_NOFILE to 4096. The memlock_bytes parameter is set to 0 at the application level; systemd units provide the actual LimitMEMLOCK=64M constraint.

These hardening calls log errors but do not abort. A daemon still proceeds to Landlock and seccomp even if prctl or setrlimit fails. The Landlock and seccomp layers are the hard security boundary.

Landlock Filesystem Sandbox

Landlock provides unprivileged filesystem sandboxing on Linux kernels >= 5.13. The shared implementation lives in platform-linux/src/sandbox.rs. Each daemon defines its own ruleset in a per-daemon apply_sandbox() function.

ABI Level and Enforcement Policy

The sandbox targets Landlock ABI V6 (sandbox.rs:77), which covers filesystem access (AccessFs), network access (AccessNet), and scope restrictions (abstract Unix sockets and cross-process signals via Scope). The Ruleset is created with handle_access(AccessFs::from_all(abi)) and handle_access(AccessNet::from_all(abi)) to handle all access types at the V6 level (sandbox.rs:85-96).

Partial enforcement is treated as a fatal error. If the kernel ABI cannot fully enforce the requested rules, apply_landlock() returns an error and the daemon aborts (sandbox.rs:157-161). There is no graceful degradation path.

ENOENT Handling

Paths that do not exist at sandbox application time are silently skipped (sandbox.rs:114-120). This is strictly more restrictive than granting the path, because Landlock denies access to any path not present in the ruleset. This design handles the case where directories have not yet been created — for example, the vaults directory before sesame init runs, or $XDG_RUNTIME_DIR/pds/ before daemon-profile creates it.

Nix Symlink Resolution

On NixOS, configuration files are symlinks into /nix/store. Each daemon calls core_config::resolve_config_real_dirs() before applying Landlock to discover the real filesystem paths behind config symlinks. These resolved paths are added as read-only Landlock rules so that config hot-reload can follow symlinks after the sandbox is applied.

daemon-wm additionally grants blanket read-only access to /nix/store (daemon-wm/src/sandbox.rs:68-69) for shared libraries, GLib schemas, locale data, and XKB keyboard rules.

daemon-profile creates its Landlock target directories if they do not exist before opening PathFd handles (daemon-profile/src/sandbox.rs:38-42). This handles the race condition where systemd restarts daemon-profile after a sesame init --wipe-reset-destroy-all-data before the directories are recreated.

Non-Directory Inode Handling

The implementation performs fstat() on each PathFd after opening it to detect whether the inode is a directory or a non-directory file (sandbox.rs:130-136). For non-directory inodes (sockets, regular files), directory-only access flags (ReadDir, MakeDir, etc.) are masked off using AccessFs::from_file(abi). This prevents the Landlock crate’s PathBeneath::try_compat_inner from reporting PartiallyEnforced on non-directory fds.

The FsAccess::ReadWriteFile variant (sandbox.rs:22-24) exists specifically for non-directory paths such as Unix domain sockets, granting file-level read-write access without directory-only flags.

Scope Restrictions

Two scope modes are available via the LandlockScope enum (sandbox.rs:54-60):

• Full — blocks both abstract Unix sockets and cross-process signals. Uses Scope::from_all(abi) which on ABI V6 includes AbstractUnixSocket and Signal.
• SignalOnly — blocks cross-process signals only, permitting abstract Unix sockets. Uses Scope::Signal alone.

Daemons that need D-Bus or Wayland communication via abstract Unix sockets use SignalOnly. Daemons with no such requirement use Full.

Per-Daemon Filesystem Rules

daemon-profile

Source: daemon-profile/src/sandbox.rs:29. Scope: SignalOnly (needs D-Bus).

daemon-profile is the only daemon that hosts the IPC bus server socket. It requires ReadWrite on the entire $XDG_RUNTIME_DIR/pds/ directory because it creates the bus.sock and bus.pub files at startup.

SSH agent socket handling resolves symlinks to their target inodes. On Konductor VMs, ~/.ssh/agent.sock is a stable symlink to a per-session /tmp/ssh-XXXX/agent.PID path. Landlock resolves symlinks to their target inodes, so the implementation grants access to the symlink path, the canonicalized target, and the parent directory of the target for path traversal (daemon-profile/src/sandbox.rs:81-149).

daemon-secrets

Source: daemon-secrets/src/sandbox.rs:7. Scope: Full (no abstract Unix sockets needed).

daemon-secrets has the narrowest Landlock ruleset of all daemons that handle secret material. It uses LandlockScope::Full to block abstract Unix sockets. The D-Bus filesystem socket at $XDG_RUNTIME_DIR/bus is granted as a ReadWriteFile rule because it is a non-directory inode (daemon-secrets/src/sandbox.rs:44-47).

daemon-wm

Source: daemon-wm/src/sandbox.rs:8. Scope: SignalOnly (Wayland uses abstract sockets).

daemon-wm has the broadest Landlock ruleset because it renders a Wayland overlay using SCTK and tiny-skia. It requires access to fonts, theme data, and system shared resources. GPU/DRI access is intentionally excluded — rendering uses wl_shm CPU shared memory buffers only (daemon-wm/src/sandbox.rs:91-93).

daemon-clipboard

Source: daemon-clipboard/src/main.rs:306. Scope: Full.

daemon-input

Source: daemon-input/src/main.rs:319. Scope: Full.

daemon-input is the only daemon with access to /dev/input and /sys/class/input. It reads raw keyboard events via evdev.

daemon-snippets

Source: daemon-snippets/src/main.rs:241. Scope: Full.

daemon-snippets has the narrowest Landlock ruleset of all sandboxed daemons. It requires only IPC bus access and read-only config access.

daemon-launcher

daemon-launcher does not apply Landlock or seccomp. It spawns arbitrary desktop applications as child processes via fork+exec. Landlock and seccomp filters inherit across fork+exec and would kill every spawned application (daemon-launcher/src/main.rs:119-121). The security boundary for daemon-launcher is IPC bus authentication via Noise IK. systemd unit hardening provides the process containment layer.

seccomp-bpf Syscall Filtering

The seccomp implementation uses libseccomp to build per-daemon BPF filters (platform-linux/src/sandbox.rs:259). seccomp is always applied after Landlock because Landlock setup requires syscalls (landlock_create_ruleset, landlock_add_rule, landlock_restrict_self) that the seccomp filter does not permit.

Default Action

The default action for disallowed syscalls is ScmpAction::KillThread (SECCOMP_RET_KILL_THREAD) (sandbox.rs:268). This sends SIGSYS to the offending thread rather than using KillProcess, which would skip the signal handler entirely. The choice of KillThread over Errno or Log is deliberate — Errno or Log would allow an attacker to probe for allowed syscalls (sandbox.rs:256-258).

SIGSYS Handler

A custom SIGSYS signal handler is installed before the seccomp filter is loaded (sandbox.rs:173-238). The handler is designed to be async-signal-safe:

• It uses no allocator and makes no heap allocations.
• It extracts the syscall number from siginfo_t at byte offset 24 from the struct base on x86_64 (sandbox.rs:201). This offset corresponds to si_call_addr (8-byte pointer) followed by si_syscall (4-byte int) within the _sigsys union member, which starts at byte offset 16 from the struct base.
• It formats the number into a stack-allocated buffer and writes "SECCOMP VIOLATION: syscall=NNN" to stderr via raw libc::write() on fd 2.
• After logging, it resets SIGSYS to SIG_DFL via libc::signal() and re-raises the signal via libc::raise() (sandbox.rs:226-228).

The handler is registered with SA_SIGINFO | SA_RESETHAND flags (sandbox.rs:235). SA_RESETHAND ensures the handler fires only once — subsequent SIGSYS deliveries use the default disposition.

Per-Daemon Syscall Differences

All six sandboxed daemons share a common baseline of approximately 50 syscalls covering I/O basics (read, write, close, openat, lseek, pread64, fstat, stat, newfstatat, statx, access), memory management (mmap, mprotect, munmap, madvise, brk), process/threading (futex, clone3, clone, set_robust_list, set_tid_address, rseq, sched_getaffinity, prlimit64, prctl, getpid, gettid, getuid, geteuid, kill), epoll (epoll_wait, epoll_ctl, epoll_create1, eventfd2, poll, ppoll), timers (clock_gettime, timer_create, timer_settime, timer_delete), networking (socket, connect, sendto, recvfrom, recvmsg, sendmsg, getsockname, getpeername, setsockopt, socketpair, shutdown, getsockopt), signals (sigaltstack, rt_sigaction, rt_sigprocmask, rt_sigreturn, tgkill), inotify (inotify_init1, inotify_add_watch, inotify_rm_watch), and misc (exit_group, exit, getrandom, memfd_secret, ftruncate, restart_syscall, pipe2, dup).

The following table lists syscalls that differentiate the daemons:

Key observations:

• daemon-secrets uniquely requires mlock/munlock for zeroization of secret material in memory, plus pwrite64 and fallocate for SQLCipher database journal operations.
• daemon-wm has the broadest syscall allowlist (~88 syscalls) due to Wayland/SCTK runtime requirements including mremap, mlock2, statfs/fstatfs, sysinfo, and sched_get_priority_max.
• daemon-profile requires bind/listen/accept4 because it hosts the IPC bus server socket. It also requires fchown for setting socket ownership.
• daemon-input and daemon-snippets have the narrowest allowlists (~57-60 syscalls).
• All sandboxed daemons permit memfd_secret for secure memory allocation and getrandom for cryptographic random number generation.

systemd Unit Hardening

Each daemon runs as a Type=notify systemd user service with WatchdogSec=30. Service files are located in contrib/systemd/.

Common Directives

All seven daemons share the following systemd hardening:

Per-Daemon systemd Differences

Notable design decisions:

• daemon-secrets (open-sesame-secrets.service:18) is the only daemon with PrivateNetwork=yes, placing it in its own network namespace with no connectivity. It communicates exclusively via the Unix domain IPC bus socket. It has the lowest LimitNOFILE (1024) but the highest MemoryMax (256M) to accommodate Argon2id, which allocates 19 MiB per key derivation.
• daemon-launcher (open-sesame-launcher.service:17-21) does not set ProtectHome or ProtectSystem because these mount namespace restrictions inherit to child processes spawned via systemd-run --scope. Firefox, for example, writes to /run/user/1000/dconf/ and fails with “Read-only file system” when ProtectSystem=strict is applied to the launcher. Instead, daemon-launcher uses kernel control plane protections and an empty CapabilityBoundingSet to drop all Linux capabilities. KillMode=process ensures spawned applications survive launcher restarts.
• ReadWritePaths vary per daemon: daemon-profile and daemon-secrets get %t/pds and %h/.config/pds; daemon-wm and daemon-clipboard get %h/.cache/open-sesame; daemon-wm additionally gets %h/.cache/fontconfig.

Sandbox Application Order

The sandbox layers are applied in a strict sequence during daemon startup:

1. harden_process() — PR_SET_DUMPABLE(0), RLIMIT_CORE(0,0)
2. apply_resource_limits() — RLIMIT_NOFILE, RLIMIT_MEMLOCK
3. Pre-sandbox I/O — open file descriptors, connect to IPC bus, read keypairs, scan desktop entries (daemon-launcher), open evdev devices (daemon-input)
4. init_secure_memory() — probe memfd_secret before seccomp locks down syscalls
5. apply_landlock() — filesystem containment (implicitly sets PR_SET_NO_NEW_PRIVS via landlock_restrict_self)
6. apply_seccomp() — syscall filtering (must follow Landlock)

This ordering is critical. Landlock setup requires the landlock_create_ruleset, landlock_add_rule, and landlock_restrict_self syscalls, which are not in any daemon’s seccomp allowlist. The IPC bus connection must be established before Landlock restricts filesystem access, because the daemon reads its keypair from $XDG_RUNTIME_DIR/pds/keys/.

Daemon Sandbox Capability Matrix

Profile Trust Model

Trust profiles are the fundamental isolation boundary in Open Sesame. Every scoped resource – secrets, clipboard content, frecency data, snippets, audit entries, and launch configurations – is partitioned by trust profile.

TrustProfileName Validation

The TrustProfileName type in core-types/src/profile.rs enforces strict validation at construction time. It is impossible to hold an invalid TrustProfileName value after construction.

Invariants:

• Non-empty.
• Maximum 64 bytes.
• Must start with an ASCII alphanumeric character: [a-zA-Z0-9].
• Body characters restricted to: [a-zA-Z0-9_-].
• Not . or .. (path traversal prevention).
• No whitespace, path separators, or null bytes.

Invalid characters produce a detailed error message including the byte value and position: "trust profile name contains invalid byte 0x{b:02x} at position {i}".

These rules make the name safe for direct use in filesystem paths without additional sanitization.

Filesystem mappings:

TrustProfileName implements TryFrom<String> and TryFrom<&str>, returning Error::Validation on failure. It serializes transparently (via #[serde(transparent)]) as a plain string and deserializes with validation. All boundary-facing code – CLI argument parsers, IPC message handlers, config file loaders – validates at entry.

Profile Scoping

Each trust profile isolates the following resources:

The IsolatedResource enum in core-profile/src/lib.rs defines the five isolatable resource types: Clipboard, Secrets, Frecency, Extensions, WindowList. It is serialized with #[serde(rename_all = "lowercase")] for configuration and audit log entries.

Profile State Machine

Each profile has an independent lifecycle state, represented by the ProfileState enum:

• Inactive: vault closed, no secrets served.
• Active(ProfileId): vault open, serving secrets.
• Transitioning(ProfileId): activation or deactivation in progress.

Multiple profiles may be active concurrently. There is no global “active profile” singleton – the system supports simultaneous active profiles with independent vaults. The active_profiles set in daemon-profile is a HashSet<TrustProfileName>.

Context-Driven Activation

The ContextEngine in core-profile/src/context.rs evaluates system signals against activation rules to determine the default profile for new unscoped launches. Changing the default does not deactivate other active profiles.

Context Signals

Signals that trigger rule evaluation:

Signal sources are spawned as long-lived tokio tasks in daemon-profile/src/main.rs. They are conditionally compiled behind #[cfg(all(target_os = "linux", feature = "desktop"))].

Activation Rules

Each profile’s activation configuration (ProfileActivation) contains:

• rules: a Vec<ActivationRule>, each specifying a RuleTrigger type and a string value to match.
• combinator: RuleCombinator::All (every rule must match the signal) or RuleCombinator::Any (one matching rule suffices).
• priority: u32 value. When multiple profiles match, the highest priority wins.
• switch_delay_ms: u64 debounce interval in milliseconds. Prevents rapid oscillation when a signal fires repeatedly.

Evaluation Algorithm

When ContextEngine::evaluate(signal) is called:

1. All profiles whose rules match the signal are collected. For All combinators, every rule in the profile must match; for Any, at least one rule must match.
2. Candidates are sorted by priority descending.
3. The highest-priority candidate is selected.
4. If it is already the current default, None is returned (no change).
5. Debounce check: if the candidate was last switched to within switch_delay_ms ago, None is returned.
6. Otherwise, the default is updated, the switch time is recorded, and the new ProfileId is returned.

Rule matching is type-strict: an Ssid trigger only matches SsidChanged signals, an AppFocus trigger only matches AppFocused signals, and so on. Mismatched trigger/signal pairs always return false.

Default Profile

The default profile determines which trust profile is used for new unscoped launches (launches without an explicit --profile flag). It is set by:

1. Configuration: global.default_profile in the config file, loaded at startup.
2. Context engine: automatic switching based on runtime signals overrides the config default.
3. Hot reload: when config changes are detected by ConfigWatcher, the context engine is rebuilt with the new default and the default_profile_name is updated. The config_profile_names list is also refreshed so that sesame profile list reflects added or removed profiles.

Default profile changes are:

• Audited via AuditAction::DefaultProfileChanged.
• Broadcast on the IPC bus as EventKind::DefaultProfileChanged.
• Reported by sesame status.

Profile Inheritance

There is no profile inheritance in the current implementation. Each trust profile is an independent, self-contained configuration with its own launch profiles, vault, and isolation boundaries. Cross-profile interaction is limited to qualified tag references (e.g., work:corp) in launch profile composition, which merge environment at launch time without merging the profile definitions themselves.

Workspace Conventions

Open Sesame enforces a deterministic directory layout for source code repositories. Git remote URLs are parsed into canonical filesystem paths following the convention {root}/{user}/{server}/{org}/{repo}.

Canonical Path Convention

Every repository maps to a unique filesystem path:

/workspace/{user}/{server}/{org}/{repo}

For example:

The default root is /workspace, configurable via the SESAME_WORKSPACE_ROOT environment variable or settings.root in workspaces.toml.

URL Parsing

The parse_url function in sesame-workspace/src/convention.rs accepts two URL formats:

HTTPS

https://github.com/org/repo[.git]

Splits on / after stripping the scheme. Requires at least three path components: server/org/repo.

SSH

git@github.com:org/repo.git

Splits on @ to isolate the user portion, then on : to separate the server from the org/repo path. The path after the colon is split on / to extract org and repo.

workspace.git Format

URLs where the repo component is workspace (or workspace.git) are treated as org-level workspace repositories. These represent a monorepo pattern where the org directory itself is a git repository containing sibling project repos. The canonical path stops at the org level:

https://github.com/braincraftio/workspace.git
  -> /workspace/usrbinkat/github.com/braincraftio/

The CloneTarget enum distinguishes Regular(PathBuf) from WorkspaceGit(PathBuf). Cloning a workspace.git into an existing org directory that already contains sibling repos triggers a special initialization flow: git init, git remote add origin, git fetch origin, then git checkout -f origin/HEAD -B main.

Normalization and Validation

• Server names are lowercased (GITHUB.COM becomes github.com).
• .git suffixes are stripped from repo names.
• Insecure http:// URLs log a tracing warning about cleartext credential transmission but are not rejected.

Component validation (validate_component) rejects:

Git-Aware Discovery

is_git_repo

The git::is_git_repo function in sesame-workspace/src/git.rs checks for the existence of a .git entry (directory or file) at the given path. It does not shell out to git.

Remote URL Extraction

git::remote_url runs git -C {path} remote get-url origin via std::process::Command with explicit .arg() calls. Returns Ok(None) if the path lacks a .git entry or has no origin remote. Returns Ok(Some(url)) on success.

Additional Git Operations

The git module provides:

• current_branch(path): runs git rev-parse --abbrev-ref HEAD.
• is_clean(path): runs git status --porcelain and checks for empty output.
• clone_repo(url, target, depth): clones with optional --depth and -- separator before URL/path arguments.

All commands use explicit .arg() calls. The module-level documentation states: “NEVER use format!() to build command strings. NEVER use shell interpolation.”

Workspace Discovery

discover::discover_workspaces in sesame-workspace/src/discover.rs walks the directory tree at {root}/{user}/ to find all git repositories. The walk follows the convention depth structure:

1. Server level: enumerate directories under {root}/{user}/.
2. Org level: enumerate directories under each server. If an org directory contains a .git entry, it is recorded as a workspace.git discovery.
3. Repo level: enumerate directories under each org. Directories with .git entries are recorded as regular repositories.

Security properties of the walk:

• Symlinks skipped: entry.file_type()?.is_symlink() causes the entry to be skipped at every level. This prevents symlink loops and TOCTOU traversal attacks.
• Permission denied: silently skipped (ErrorKind::PermissionDenied returns Ok(())).
• .git directories: explicitly skipped as traversal targets (they are detected but not descended into).

Results are sorted by path. Each DiscoveredWorkspace includes:

• path: filesystem path to the repository root.
• convention: parsed WorkspaceConvention components (server, org, repo).
• remote_url: from git remote get-url origin, if available.
• linked_profile: resolved from workspace config links, if configured.
• is_workspace_git: true for org-level workspace.git repositories.

Workspace Configuration

workspaces.toml

The user-level workspace configuration is stored at ~/.config/pds/workspaces.toml. The schema is defined by WorkspaceConfig in core-config/src/schema_workspace.rs:

[settings]
root = "/workspace"
user = "usrbinkat"
default_ssh = true

[links]
"/workspace/usrbinkat/github.com/org" = "personal"
"/workspace/usrbinkat/github.com/org/k9" = "work"

Settings fields:

Links section: a BTreeMap<String, String> mapping canonical paths to profile names. More specific paths override less specific ones (longest prefix wins).

Profile Link Resolution

resolve_workspace_profile in sesame-workspace/src/config.rs resolves a filesystem path to a profile name using two strategies:

1. Exact match: the path matches a link key exactly.
2. Longest prefix match: the longest link key that is a prefix of the path wins. Path boundary enforcement prevents /org from matching /organic – the link path must match exactly or be followed by /.

.sesame.toml (Local Config)

Workspace-level and repo-level configuration files (.sesame.toml) provide per-directory overrides. The schema is LocalSesameConfig in core-config/src/schema_workspace.rs:

# /workspace/usrbinkat/github.com/org/.sesame.toml
profile = "work"
secret_prefix = "MYAPP"
tags = ["dev-rust"]

[env]
RUST_LOG = "debug"

Multi-Layer Config Precedence

resolve_effective_config in sesame-workspace/src/config.rs merges configuration from all layers. Precedence (highest to lowest):

1. Repo .sesame.toml ({path}/.sesame.toml)
2. Workspace .sesame.toml ({root}/{user}/{server}/{org}/.sesame.toml)
3. User config links (workspaces.toml [links] section)

Merge semantics per field:

• profile: highest-priority layer wins outright.
• env: all layers are merged into a single BTreeMap. Higher-priority keys override lower-priority ones; keys unique to lower layers are preserved.
• tags: all layers’ tags are concatenated (workspace tags first, then repo tags).
• secret_prefix: highest-priority layer wins outright.

The ConfigProvenance struct tracks which layer determined each value ("user config link", "workspace .sesame.toml", or "repo .sesame.toml").

Platform-Specific Root Resolution

The workspace root is resolved in sesame-workspace/src/config.rs (resolve_root) with this priority:

1. SESAME_WORKSPACE_ROOT environment variable.
2. config.settings.root from workspaces.toml.
3. Default: /workspace.

The default WorkspaceSettings reads SESAME_WORKSPACE_ROOT at construction time, so the env var takes effect even without an explicit workspaces.toml. The username defaults to the USER environment variable, falling back to the string "user".

Shell Injection Prevention

All git operations in sesame-workspace/src/git.rs use std::process::Command with explicit .arg() calls. The -- separator is used before URL and path arguments in git clone to prevent argument injection (a URL starting with - would otherwise be interpreted as a flag). No temporary files are created. No secret material is written to disk.

Cryptographic Agility

Open Sesame implements config-driven cryptographic algorithm selection across five independent axes: key derivation (KDF), hierarchical key derivation (HKDF), Noise IPC transport cipher, Noise IPC transport hash, and audit log chain hash. Algorithm choices are declared in the [crypto] section of config.toml and dispatched at runtime through typed enum matching. No algorithm is hardcoded at call sites.

Configuration Schema

The [crypto] section of config.toml maps to CryptoConfigToml (core-config/src/schema_crypto.rs:14), a string-based TOML representation with six fields:

[crypto]
kdf = "argon2id"
hkdf = "blake3"
noise_cipher = "chacha-poly"
noise_hash = "blake2s"
audit_hash = "blake3"
minimum_peer_profile = "leading-edge"

These defaults are defined in the Default implementation (schema_crypto.rs:30-38). At load time, CryptoConfigToml::to_typed() (schema_crypto.rs:48) converts the string values to validated enum variants in core_types::CryptoConfig (core-types/src/crypto.rs:82). Unrecognized algorithm names produce a core_types::Error::Config error, preventing the daemon from starting with an invalid configuration.

Algorithm Axes

KDF: Password to Master Key

The KDF converts a user password and 16-byte salt into a 32-byte master key. Two algorithms are available, selected by the kdf config field and dispatched through derive_key_kdf() (core-crypto/src/kdf.rs:60-69).

argon2id (default, KdfAlgorithm::Argon2id):

• Algorithm: Argon2id (hybrid mode, resists both side-channel and GPU attacks)
• Memory cost: 19,456 KiB (19 MiB) (kdf.rs:28)
• Time cost: 2 iterations (kdf.rs:29)
• Parallelism: 1 lane (kdf.rs:30)
• Output: 32 bytes (kdf.rs:31)
• Version: 0x13 (kdf.rs:35)
• Parameters follow OWASP minimum recommendations (kdf.rs:14-17)
• Implementation: argon2 crate with Argon2::new(Algorithm::Argon2id, Version::V0x13, params) (kdf.rs:35)

pbkdf2-sha256 (KdfAlgorithm::Pbkdf2Sha256):

• Algorithm: PBKDF2-HMAC-SHA256
• Iterations: 600,000 (kdf.rs:51)
• Output: 32 bytes
• Parameters follow OWASP recommendations for PBKDF2-SHA256 (kdf.rs:47)
• Implementation: pbkdf2 crate with Hmac<Sha256> (kdf.rs:51)

Both functions return SecureBytes — mlock’d, zeroize-on-drop memory backed by core_memory::ProtectedAlloc. Intermediate stack arrays are zeroized via zeroize::Zeroizing before the function returns (kdf.rs:37, kdf.rs:50).

HKDF: Master Key to Per-Purpose Keys

The HKDF layer derives per-profile, per-purpose 32-byte keys from the master key. Two algorithms are available, dispatched through the *_with_algorithm() family of functions in core-crypto/src/hkdf.rs.

blake3 (default, HkdfAlgorithm::Blake3):

• Uses BLAKE3’s built-in derive_key mode, which provides extract-then-expand semantics equivalent to HKDF (hkdf.rs:1-5)
• Context string format: "pds v2 <purpose> <profile_id>" (hkdf.rs:39-41)
• Domain separation is achieved via BLAKE3’s context string parameter, which internally derives a context key from the string and uses it to key the hash of the input keying material (hkdf.rs:27-33)
• Implementation: blake3::derive_key(context, ikm) (hkdf.rs:31)
• Performance: 5-14x faster than SHA-256 with hardware acceleration via AVX2/AVX512/NEON (hkdf.rs:5)

hkdf-sha256 (HkdfAlgorithm::HkdfSha256):

• Standard HKDF extract-then-expand per RFC 5869
• Salt: None (the IKM serves as both input keying material and implicit salt) (hkdf.rs:121)
• Info: the context string bytes, providing domain separation (hkdf.rs:123)
• Output: 32 bytes (hkdf.rs:122)
• Implementation: Hkdf::<Sha256>::new(None, ikm) followed by hk.expand(context.as_bytes(), &mut key) (hkdf.rs:121-124)
• Intermediate output array is zeroized before return (hkdf.rs:126)

The key hierarchy derived through HKDF (hkdf.rs:7-14):

User password -> Argon2id -> Master Key (32 bytes)
  -> HKDF "vault-key"          -> per-profile vault key (encrypts SQLCipher DB)
  -> HKDF "clipboard-key"      -> per-profile clipboard key (zeroed on profile deactivation)
  -> HKDF "ipc-auth-token"     -> per-profile IPC authentication token
  -> HKDF "ipc-encryption-key" -> per-profile IPC field encryption key

Each purpose has a dedicated public function (derive_vault_key, derive_clipboard_key, derive_ipc_auth_token, derive_ipc_encryption_key) with a corresponding *_with_algorithm() variant that accepts an HkdfAlgorithm parameter. The algorithm-dispatching variants use a match statement to route to the correct implementation (hkdf.rs:137-141).

A key-encrypting-key (KEK) for platform keyring storage is derived separately via derive_kek() (hkdf.rs:91-101). The KEK uses the hardcoded context string "pds v2 key-encrypting-key" and concatenates password + salt as the IKM, ensuring cryptographic independence from the Argon2id master key derivation path. The concatenated IKM is zeroized after use (hkdf.rs:99).

An extensibility function derive_key() (hkdf.rs:107-110) accepts an arbitrary purpose string, allowing new key purposes to be added without modifying the module. Callers must ensure purpose strings are globally unique.

Noise Cipher: IPC Transport Encryption

The Noise IK protocol used for inter-daemon IPC communication supports two cipher selections via the noise_cipher config field:

chacha-poly (default, NoiseCipher::ChaChaPoly):

• ChaCha20-Poly1305 authenticated encryption
• Constant-time on all architectures without hardware AES
• The leading-edge default for environments where AES-NI is not guaranteed

aes-gcm (NoiseCipher::AesGcm):

• AES-256-GCM authenticated encryption
• Optimal on processors with AES-NI hardware acceleration
• Required for NIST/FedRAMP compliance

The cipher selection is read from config and passed to the Noise protocol builder at IPC bus initialization. The NoiseCipher enum is defined in core-types/src/crypto.rs:31-37.

Noise Hash: IPC Transport Hash

The Noise protocol hash function is selected via the noise_hash config field:

blake2s (default, NoiseHash::Blake2s):

• BLAKE2s (256-bit output, optimized for 32-bit and 64-bit platforms)
• Faster than SHA-256 on platforms without SHA extensions
• The leading-edge default

sha256 (NoiseHash::Sha256):

• SHA-256
• Required for NIST/FedRAMP compliance
• Optimal on processors with SHA-NI hardware extensions

The NoiseHash enum is defined in core-types/src/crypto.rs:43-49.

Audit Hash: Audit Log Chain Integrity

The audit log uses a hash chain where each entry’s hash covers the previous entry’s hash, providing tamper evidence. The hash function is selected via the audit_hash config field:

blake3 (default, AuditHash::Blake3):

• BLAKE3 (256-bit output)
• Hardware-accelerated via AVX2/AVX512/NEON where available
• The leading-edge default

sha256 (AuditHash::Sha256):

• SHA-256
• Required for NIST/FedRAMP compliance

The AuditHash enum is defined in core-types/src/crypto.rs:55-61.

At-Rest Encryption

Vault data at rest is encrypted with AES-256-GCM via the EncryptionKey type (core-crypto/src/encryption.rs:13). This cipher is not configurable — it is always AES-256-GCM regardless of the [crypto] config section. The implementation uses the RustCrypto aes-gcm crate (encryption.rs:5-6).

• Key size: 32 bytes (AES-256) (encryption.rs:24)
• Nonce size: 12 bytes (encryption.rs:42)
• Output: ciphertext with appended 16-byte authentication tag (encryption.rs:37)
• Decrypted plaintext is returned as SecureBytes (mlock’d, zeroize-on-drop) (encryption.rs:61)
• The Debug implementation redacts key material, printing "EncryptionKey([REDACTED])" (encryption.rs:66-68)

Nonce reuse catastrophically breaks both confidentiality and authenticity. Callers are responsible for ensuring nonce uniqueness per encryption with the same key (encryption.rs:36-37).

Pre-Defined Crypto Profiles

The minimum_peer_profile config field selects a pre-defined algorithm profile via the CryptoProfile enum (core-types/src/crypto.rs:67-75):

leading-edge (default, CryptoProfile::LeadingEdge):

This profile uses modern algorithms that prioritize security margin and performance on commodity hardware without requiring specific hardware acceleration.

governance-compatible (CryptoProfile::GovernanceCompatible):

This profile uses exclusively NIST-approved algorithms suitable for environments subject to FedRAMP, FIPS 140-3, or equivalent governance frameworks.

custom (CryptoProfile::Custom):

Individual algorithm selection via the per-axis config fields. Allows mixing algorithms across profiles (e.g., Argon2id KDF with AES-GCM Noise cipher).

The minimum_peer_profile field specifies the minimum cryptographic profile that the local node will accept from federation peers. A node configured with "leading-edge" will reject connections from peers advertising a weaker profile. This field is defined in CryptoConfig as minimum_peer_profile: CryptoProfile (core-types/src/crypto.rs:89).

Config-to-Runtime Dispatch

Algorithm selection flows from config to runtime through a three-stage pipeline:

1. TOML parsing: The [crypto] section is deserialized into CryptoConfigToml (core-config/src/schema_crypto.rs:14), which stores all algorithm names as String values.

2. Validation: CryptoConfigToml::to_typed() (schema_crypto.rs:48) converts each string to a typed enum variant via match statements. Unrecognized strings produce an error. The result is a core_types::CryptoConfig struct with typed fields (core-types/src/crypto.rs:82-90).

3. Dispatch: Runtime code calls algorithm-dispatching functions that accept the typed enum and route to the correct implementation. For example, derive_key_kdf() (core-crypto/src/kdf.rs:60-69) matches on KdfAlgorithm:

   #![allow(unused)]
   fn main() {
   pub fn derive_key_kdf(
       algorithm: &KdfAlgorithm,
       password: &[u8],
       salt: &[u8; 16],
   ) -> core_types::Result<SecureBytes> {
       match algorithm {
           KdfAlgorithm::Argon2id => derive_key_argon2(password, salt),
           KdfAlgorithm::Pbkdf2Sha256 => derive_key_pbkdf2(password, salt),
       }
   }
   }

   Similarly, derive_vault_key_with_algorithm() (core-crypto/src/hkdf.rs:131-141) matches on HkdfAlgorithm:

   #![allow(unused)]
   fn main() {
   pub fn derive_vault_key_with_algorithm(
       algorithm: &HkdfAlgorithm,
       master_key: &[u8],
       profile_id: &str,
   ) -> SecureBytes {
       let ctx = build_context("vault-key", profile_id);
       match algorithm {
           HkdfAlgorithm::Blake3 => derive_32(&ctx, master_key),
           HkdfAlgorithm::HkdfSha256 => derive_32_hkdf_sha256(&ctx, master_key),
       }
   }
   }

This pattern ensures that adding a new algorithm requires three changes: add a variant to the core_types enum, add a match arm in the TOML validator, and add a match arm in the dispatch function. No call sites need modification.

FIPS Considerations

Open Sesame does not claim FIPS 140-3 validation. The cryptographic implementations are provided by RustCrypto crates (argon2, pbkdf2, aes-gcm, blake3, hkdf, sha2) which have not undergone CMVP certification.

For deployments subject to FIPS requirements, the governance-compatible profile restricts algorithm selection to NIST-approved primitives (PBKDF2-SHA256, HKDF-SHA256, AES-256-GCM, SHA-256). This satisfies the algorithm selection requirement but does not address the validated module requirement. Organizations requiring a FIPS-validated cryptographic module would need to replace the RustCrypto backends with a certified implementation (e.g., AWS-LC, BoringCrypto) and re-validate.

The minimum_peer_profile mechanism provides a policy enforcement point: setting it to "governance-compatible" ensures that no peer in a federated deployment can negotiate a session using non-NIST algorithms, even if the local node supports them.

Memory Protection

All key material derived through the KDF and HKDF paths is returned as SecureBytes (core-crypto/src/lib.rs:16), which is backed by core_memory::ProtectedAlloc. This provides:

• Page-aligned allocation with guard pages
• mlock to prevent swapping to disk
• Volatile zeroization on drop
• Canary bytes for buffer overflow detection

The init_secure_memory() function (core-crypto/src/lib.rs:29-31) must be called before the seccomp sandbox is applied, because it probes memfd_secret availability. After seccomp is active, memfd_secret remains in the allowlist for all sandboxed daemons.

Vault Engine

The vault engine provides encrypted per-profile secret storage backed by SQLCipher databases with a multi-layer key hierarchy derived from BLAKE3.

SQLCipher Configuration

Each vault database is a SQLCipher-encrypted SQLite file. The following PRAGMA directives are applied in SqlCipherStore::open() (core-secrets/src/sqlcipher.rs) before any table access:

SQLCipher encrypts every database page with AES-256-CBC and authenticates each page with HMAC-SHA256. The page encryption key is supplied via PRAGMA key as a raw 32-byte hex-encoded value. After the key pragma executes, both the hex string and the SQL statement are zeroized in place via zeroize::Zeroize before any further operations proceed.

Key Hierarchy

The key derivation chain from user password to on-disk encryption proceeds through three stages:

User password + per-profile 16-byte random salt
    --> Argon2id
    --> Master Key (32 bytes, held in SecureBytes / mlock'd memory)
        --> BLAKE3 derive_key(context="pds v2 vault-key {profile_id}")
        --> Vault Key (32 bytes) -- used as SQLCipher PRAGMA key
            --> BLAKE3 derive_key(context="pds v2 entry-encryption-key")
            --> Entry Key (32 bytes) -- used for per-entry AES-256-GCM

BLAKE3’s derive_key mode accepts a context string that provides domain separation. The vault key and entry key share the same vault key as input keying material but use different context strings, making them cryptographically independent. The vault_key_derivation_domain_separation test in core-secrets/src/sqlcipher.rs verifies this property.

The full set of derived keys sharing the same master key (defined in core-crypto/src/hkdf.rs):

An HKDF-SHA256 alternative is available via derive_vault_key_with_algorithm(), selectable per the HkdfAlgorithm enum. BLAKE3 is the default. The blake3_and_hkdf_sha256_produce_different_keys test confirms the two algorithms produce different outputs for the same inputs.

Double Encryption

Each secret value receives two independent layers of encryption:

1. Page-level: SQLCipher encrypts the entire database page (key names, values, metadata) using the vault key via AES-256-CBC + HMAC-SHA256.
2. Entry-level: Each value is individually encrypted with AES-256-GCM using the entry key before being written to the value column. The wire format stored in the database is [12-byte random nonce][ciphertext + 16-byte GCM tag].

Every encryption operation generates a fresh 12-byte random nonce via getrandom. The minimum wire length for decryption is 28 bytes (12-byte nonce + 16-byte GCM tag); shorter values are rejected with an error. The encrypt_same_value_produces_different_ciphertext test verifies nonce uniqueness across 100 consecutive encryptions of identical plaintext.

The db_file_contains_no_plaintext and db_file_contains_no_key_names_in_plaintext tests read raw database file bytes and assert that neither secret values nor key names appear anywhere in the on-disk file.

Database Schema

The schema is created via an idempotent CREATE TABLE IF NOT EXISTS statement during SqlCipherStore::open():

CREATE TABLE IF NOT EXISTS secrets (
    key        TEXT PRIMARY KEY,
    value      BLOB NOT NULL,
    created_at INTEGER NOT NULL,
    updated_at INTEGER NOT NULL
);

Timestamps are stored as Unix epoch seconds via SystemTime::now(). The schema_migration_idempotent test verifies that opening a database multiple times does not fail or corrupt existing data. After schema creation, SqlCipherStore::open() executes SELECT count(*) FROM sqlite_master to verify the key is correct; a wrong key causes this statement to fail with “wrong key or corrupt database”.

Per-Profile Vault Isolation

Each profile receives a separate database file at {config_dir}/vaults/{profile_name}.db and a separate 16-byte random salt file at {config_dir}/vaults/{profile_name}.salt. The salt is generated by getrandom on first unlock and persisted to disk by generate_profile_salt() in daemon-secrets/src/unlock.rs.

Isolation is cryptographic, not namespace-based. core_crypto::derive_vault_key(master_key, profile_id) uses the context string "pds v2 vault-key {profile_id}", producing a different 32-byte key for each profile ID even when the master key is the same. Attempting to open a vault encrypted with profile A’s key using profile B’s key fails at the SELECT count(*) FROM sqlite_master verification step.

Tests in core-secrets/src/sqlcipher.rs that verify isolation:

• cross_profile_keys_are_independent – different profile IDs yield different keys, and opening a database with the wrong profile’s key fails.
• cross_profile_secret_access_returns_error – reading a key from the wrong profile’s vault returns NotFound.
• different_vault_keys_cannot_access – a database opened with key A rejects key B.

Vault Lifecycle

Create

A vault is created implicitly on first access after a profile is unlocked. VaultState::vault_for() in daemon-secrets/src/vault.rs creates the {config_dir}/vaults/ directory if needed, then calls SqlCipherStore::open() inside tokio::task::spawn_blocking with a 10-second timeout to avoid blocking the async event loop during synchronous SQLCipher I/O. The timeout is a defensive measure: if the blocking thread is killed (e.g., by seccomp SIGSYS), the JoinHandle would hang indefinitely without it. The opened store is wrapped in JitDelivery with the configured TTL (default 300 seconds, set via the --ttl CLI flag or PDS_SECRET_TTL environment variable).

Open

SqlCipherStore::open() performs the following steps in order:

1. Validate that the vault key is exactly 32 bytes.
2. Open the SQLite connection via Connection::open().
3. Set the encryption key via PRAGMA key in raw hex mode, then zeroize the hex string and the SQL statement.
4. Apply SQLCipher configuration PRAGMAs (cipher_page_size, HMAC algorithm, KDF algorithm, KDF iterations, WAL mode).
5. Run the idempotent schema migration (CREATE TABLE IF NOT EXISTS).
6. Verify the key by executing SELECT count(*) FROM sqlite_master.
7. Derive the entry key via blake3::derive_key("pds v2 entry-encryption-key", vault_key), then zeroize the intermediate byte array.

Rekey (C-level Key Scrub)

SqlCipherStore::pragma_rekey_clear() issues PRAGMA rekey = '' to scrub SQLCipher’s internal C-level copy of the page encryption key from memory. This is defense-in-depth: the Rust-side entry_key: SecureBytes already zeroizes on drop, but this call ensures the C library’s internal buffer is also cleared. The method logs a warning on failure but does not panic, since the connection may already be in a broken state. The pragma_rekey_clear_does_not_remove_encryption test confirms this scrubs the in-memory key without removing on-disk encryption.

An AtomicBool (cleared) prevents redundant PRAGMA rekey calls in the Drop implementation.

Close

Vault closing occurs during profile deactivation (VaultState::deactivate_profile()) or locking (handle_lock_request()). The sequence is:

1. Remove the profile from the active_profiles authorization set. This is the security-critical step and happens first, before any I/O.
2. Flush the JIT cache via vault.flush().await. All SecureBytes entries are zeroized on drop when the HashMap is cleared.
3. Call pragma_rekey_clear() to scrub the C-level key buffer.
4. Drop the SqlCipherStore. The entry_key: SecureBytes zeroizes on drop, and Drop skips the redundant PRAGMA rekey because cleared is already set.
5. Remove the master key from the master_keys map. SecureBytes zeroizes on drop.
6. Remove any partial multi-factor unlock state for the profile.
7. On Linux, delete the profile’s platform keyring entry via keyring_delete_profile().

On lock-all (no profile specified in LockRequest), the rate limiter state is also reset to a fresh SecretRateLimiter instance.

Secret Lifecycle

This page describes how secrets move through the system: from storage in an encrypted vault, through a JIT cache, across the IPC bus, and into a child process’s environment. It also covers key material lifecycle and the compliance testing framework.

Secret Storage Operations

The SecretsStore trait (core-secrets/src/store.rs) defines four operations that every storage backend must implement:

The list_keys method intentionally avoids returning values. Listing secrets does not trigger bulk decryption of every entry, limiting the window during which plaintext exists in memory.

Two implementations exist:

• SqlCipherStore (core-secrets/src/sqlcipher.rs): Production backend. Each set encrypts the value with per-entry AES-256-GCM before writing to the database. Each get decrypts after reading. The Mutex<Connection> serializes all database access.
• InMemoryStore (core-secrets/src/store.rs): Testing backend. Holds secrets in a HashMap<String, SecureBytes> protected by a tokio::sync::RwLock. Values are stored as SecureBytes (mlock’d, zeroize-on-drop). Does not persist to disk.

JIT Cache

The JitDelivery<S> wrapper (core-secrets/src/jit.rs) adds a time-limited in-memory cache in front of any SecretsStore implementation. It exists to avoid repeated SQLCipher decryption for frequently accessed secrets.

Resolution

JitDelivery::resolve(key) checks the cache first. If a valid (non-expired) entry exists, the cached SecureBytes clone is returned without touching the underlying store. If the entry is missing or expired, the value is fetched from the store, cached, and returned.

Both the cache entry and the returned value are independent SecureBytes clones. Each independently zeroizes on drop.

TTL Expiry

Each cache entry records its fetched_at timestamp as a std::time::Instant. On the next resolve call, if fetched_at.elapsed() >= ttl, the cached value is considered expired and a fresh fetch occurs. The default TTL is 300 seconds, configurable via the daemon’s --ttl flag or PDS_SECRET_TTL environment variable.

The ttl_expiry_refetches test verifies that after TTL expiry, the underlying store is re-queried and updated values are returned.

Flush on Lock

JitDelivery::flush() clears the entire cache by calling cache.clear(). Because each value in the cache is a SecureBytes, dropping the HashMap entries triggers zeroization of all cached secret material. Flush is called during profile deactivation and locking, before the vault is closed and key material is destroyed.

The flush_clears_cache test verifies that after a flush, the next resolve call fetches fresh data from the underlying store.

Store Bypass

JitDelivery::store() provides direct access to the underlying SecretsStore, bypassing the cache. This is used for write operations (set, delete, list_keys) which should not interact with the read cache. After a set or delete, the daemon calls vault.flush().await to invalidate any stale cache entries.

Key Material Lifecycle

All key material in the secrets subsystem is held in SecureBytes (core-crypto), which provides:

• mlock: The backing memory is locked to prevent swapping to disk. On Linux, this uses memfd_secret with guard pages when available.
• Zeroize on drop: When a SecureBytes value is dropped, its backing memory is overwritten with zeros before deallocation. This is implemented via the zeroize crate’s Zeroize trait.
• Clone independence: Cloning a SecureBytes value creates a new mlock’d allocation. Dropping the clone does not affect the original, and vice versa.

The lifecycle of key material through the system:

1. Derivation: The master key is derived via Argon2id from the user’s password and a per-profile 16-byte salt (derive_master_key() in daemon-secrets/src/unlock.rs, which delegates to core_crypto::derive_key_argon2()). The result is a 32-byte SecureBytes value.
2. Storage: The master key is stored in VaultState::master_keys (daemon-secrets/src/vault.rs), a HashMap<TrustProfileName, SecureBytes>.
3. Derivation (vault key): On first vault access, core_crypto::derive_vault_key() derives a 32-byte vault key from the master key via BLAKE3. The intermediate stack array is wrapped in zeroize::Zeroizing and zeroized on scope exit.
4. Use: The vault key is passed to SqlCipherStore::open(), which uses it for PRAGMA key and derives the entry key. The vault key is not retained by the store after open completes.
5. Destruction: On lock or deactivation, the JIT cache is flushed (zeroizing cached secrets), pragma_rekey_clear() scrubs the C-level key buffer, the SqlCipherStore is dropped (zeroizing the entry key), and the master key is removed from the map (zeroizing on drop).

Field-Level IPC Encryption

When the ipc-field-encryption feature is enabled, secret values are encrypted with AES-256-GCM before being placed on the IPC bus, providing a second encryption layer on top of the Noise IK transport.

The per-profile IPC encryption key is derived via core_crypto::derive_ipc_encryption_key(master_key, profile_id) using the context string "pds v2 ipc-encryption-key {profile_id}". The wire format is [12-byte random nonce][AES-256-GCM ciphertext + tag].

This feature is gated behind ipc-field-encryption and disabled by default for the following reasons, documented in daemon-secrets/src/vault.rs:

• The Noise IK transport is already the security boundary, matching the precedent set by ssh-agent, 1Password, Vault, and gpg-agent.
• CLI clients lack the master key needed to decrypt per-field encrypted values.
• The per-field key derives from the same master key that transits inside the Noise channel, so it is not an independent trust root.

When enabled, the encryption path in handle_secret_get (daemon-secrets/src/crud.rs) encrypts values before sending the SecretGetResponse, and the decryption path in handle_secret_set decrypts incoming values before writing to the vault. The decrypted intermediate Vec<u8> is explicitly zeroized after the store write completes.

Compliance Testing

The compliance_tests() function (core-secrets/src/compliance.rs) defines a portable test suite that every SecretsStore implementation must pass. The suite verifies:

The in_memory_store_passes_compliance test runs this suite against InMemoryStore. The SQLCipher backend has its own compliance tests in core-secrets/src/sqlcipher.rs that additionally verify encryption properties (no plaintext on disk, cross-profile isolation, nonce uniqueness).

Six-Gate Security Pipeline

Every secret CRUD operation passes through a six-gate security pipeline in daemon-secrets/src/crud.rs before the vault is accessed. The gates execute in order from cheapest to most expensive:

1. Lock check: Rejects the request if no profiles are unlocked (master_keys is empty).
2. Active profile check: Rejects if the requested profile is not in the active_profiles set.
3. Identity check: Logs the requester’s verified_sender_name (stamped by the IPC bus server from the Noise IK registry). Expected requesters are daemon-secrets, daemon-launcher, or None (CLI relay).
4. Rate limit check: Applies per-requester token bucket rate limiting.
5. ACL check: Evaluates per-daemon per-key access control rules from config. 5.5. Key validation: Validates the secret key name via core_types::validate_secret_key().
6. Vault access: Opens (or retrieves) the vault and performs the requested operation.

Each gate that denies a request emits both a structured tracing log entry and a SecretOperationAudit IPC event (fire-and-forget to daemon-profile for persistent audit logging). The denial response is sent immediately and processing stops.

Access Control

The secrets daemon enforces per-daemon per-key access control over secret operations. ACL rules are defined in the configuration file and evaluated as pure functions over config state with no I/O or mutable state. Rate limiting provides a second layer of defense against enumeration attacks.

Per-Daemon Per-Key ACL

Access control is implemented in daemon-secrets/src/acl.rs as two pure functions: check_secret_access() for get/set/delete operations, and check_secret_list_access() for list operations.

Configuration

ACL rules are defined in the config file under [profiles.<name>.secrets.access]. Each entry maps a daemon name to a list of secret key names that daemon is permitted to access:

[profiles.work.secrets.access]
daemon-launcher = ["api-key", "db-password"]
daemon-wm = []

In this example, daemon-launcher can access api-key and db-password in the work profile. daemon-wm has an explicit empty list, which denies all access including listing.

Evaluation Rules for Get/Set/Delete

The check_secret_access() function evaluates the following rules in order. The first matching rule determines the outcome:

Evaluation Rules for List

The check_secret_list_access() function follows the same rules as get/set/delete with one difference at the daemon-level check:

All other conditions match check_secret_access().

Test Coverage

The ACL module contains 15 tests (acl_001 through acl_015) that verify every branch of both functions. Each test is prefixed with a SECURITY INVARIANT comment documenting the property it protects.

Unregistered Client Handling

Client identity is determined by the verified_sender_name field on each IPC message. This field is stamped by the IPC bus server from the Noise IK static key registry – it is not self-declared by the client. The check_secret_requester() function in daemon-secrets/src/acl.rs logs an anomaly warning if a daemon other than daemon-secrets or daemon-launcher requests secrets, since those are the only expected requesters.

Unregistered clients (those with verified_sender_name set to None) are CLI relay connections that transit through daemon-profile with Open clearance. When any ACL policy is active, unregistered clients are denied access to both individual secrets and the key listing. This prevents bypass via unauthenticated connections.

Audit Logging

Every secret operation emits a structured audit log entry via the audit_secret_access() function, regardless of whether the operation succeeds or is denied. The log entry includes:

• event_type: The operation (get, set, delete, list, unlock, lock).
• requester: The DaemonId (UUID) of the requesting client.
• profile: The target trust profile name.
• key: The secret key name (or - for operations that do not target a specific key).
• outcome: The result (success, denied-locked, denied-acl, rate-limited, not-found, etc.).

In addition to local tracing logs, each operation also emits a SecretOperationAudit IPC event that is published to the bus for persistent logging by daemon-profile. This event is fire-and-forget: delivery failure does not block or fail the secret operation. Both audit paths are required; the code comments explicitly state that neither should be removed assuming the other is sufficient.

Rate Limiting

Rate limiting is implemented in daemon-secrets/src/rate_limit.rs using the governor crate’s in-memory GCRA (Generic Cell Rate Algorithm) token bucket.

Configuration

The rate limiter is configured with a fixed quota:

• Sustained rate: 10 requests per second
• Burst capacity: 20 requests

These values are hardcoded in SecretRateLimiter::new().

Per-Daemon Buckets

Each daemon receives an independent rate limit bucket, keyed on its verified_sender_name. Exhausting one daemon’s quota does not affect any other daemon’s ability to access secrets. Buckets are created lazily on first request from each daemon.

Anonymous Client Isolation

All unregistered clients (those with verified_sender_name set to None) share a single rate limit bucket keyed on the sentinel value __anonymous__. This prevents bypass via the new-connection-per-request pattern: an attacker who opens a fresh IPC connection for every request still draws from the same shared anonymous bucket.

The anonymous bucket is independent from all named daemon buckets. Exhausting the anonymous bucket does not affect registered daemons, and vice versa.

Rate Limiter Reset

When a lock-all operation succeeds (no profile specified in LockRequest), the rate limiter is reset to a fresh instance with empty buckets. This occurs in handle_lock_request() in daemon-secrets/src/unlock.rs.

Test Coverage

The rate limiting module contains five tests (rate_001 through rate_005) that verify:

• Burst capacity of 20 requests is allowed (rate_001).
• The 21st request after burst exhaustion is denied (rate_002).
• Daemon buckets are independent (rate_003).
• The anonymous bucket is independent from named daemon buckets (rate_004).
• All anonymous clients share a single bucket (rate_005).

Secret Injection

The sesame CLI provides two commands for injecting vault secrets into running processes: sesame env for spawning a child process with secrets as environment variables, and sesame export for emitting secrets in shell, dotenv, or JSON format. Both commands enforce a runtime denylist that blocks security-sensitive environment variable names.

sesame env

sesame env spawns a child process with all secrets from the specified profile(s) injected as environment variables.

sesame env -p work -- my-application --flag

The command resolves profile specs from the -p flag or, if omitted, from the SESAME_PROFILES environment variable. If neither is set, the default profile name is used.

The child process also receives a SESAME_PROFILES environment variable containing a CSV of the resolved profile specs (e.g., work,braincraft:operations), allowing it to know its security context.

After the child process exits, all secret byte vectors are zeroized via zeroize::Zeroize before the parent process exits with the child’s exit code.

Multi-Profile Support

Multiple profiles can be specified as a comma-separated list:

sesame env -p "default,work" -- my-application

Secrets are fetched from each profile in order and merged with left-wins collision resolution: if the same secret key name exists in multiple profiles, the value from the first profile in the list is used. This is implemented in fetch_multi_profile_secrets() in open-sesame/src/ipc.rs, which uses a HashSet to track seen key names.

Prefix

The --prefix flag prepends a string to all generated environment variable names:

sesame env -p work --prefix MYAPP -- my-application
# Secret "api-key" becomes MYAPP_API_KEY

sesame export

sesame export emits secrets in one of three formats, suitable for shell evaluation or file generation.

Shell Format

sesame export -p work --format shell

Output:

export API_KEY="the-secret-value"
export DB_PASSWORD="another-value"

Dotenv Format

sesame export -p work --format dotenv

Output:

API_KEY="the-secret-value"
DB_PASSWORD="another-value"

JSON Format

sesame export -p work --format json

Output:

{"API_KEY":"the-secret-value","DB_PASSWORD":"another-value"}

After output, all intermediate string copies are zeroized via unsafe as_bytes_mut().zeroize().

Secret Name to Environment Variable Conversion

The secret_key_to_env_var() function in open-sesame/src/env.rs converts secret key names to environment variable names using the following rules:

The entire result is uppercased. If a prefix is provided, it is prepended with an underscore separator.

Examples (from tests in open-sesame/src/env.rs):

Environment Variable Denylist

The DENIED_ENV_VARS constant in open-sesame/src/env.rs defines environment variable names that must never be overwritten by secret injection. The is_denied_env_var() function checks against this list using case-insensitive comparison. The BASH_FUNC_ prefix is matched as a prefix (any variable starting with BASH_FUNC_ is denied).

If a secret’s converted name matches a denied variable, the secret is skipped with a warning printed to stderr. It is not injected into the child process or emitted in export output.

Full Denylist

Dynamic linker – arbitrary code execution:

• LD_PRELOAD
• LD_LIBRARY_PATH
• LD_AUDIT
• LD_DEBUG
• LD_DEBUG_OUTPUT
• LD_DYNAMIC_WEAK
• LD_PROFILE
• LD_SHOW_AUXV
• LD_BIND_NOW
• LD_BIND_NOT
• DYLD_INSERT_LIBRARIES
• DYLD_LIBRARY_PATH
• DYLD_FRAMEWORK_PATH

Core execution environment:

• PATH
• HOME
• USER
• SHELL
• LOGNAME
• LANG
• TERM
• DISPLAY
• WAYLAND_DISPLAY
• XDG_RUNTIME_DIR

Shell injection vectors:

• BASH_ENV
• ENV
• BASH_FUNC_ (prefix match)
• CDPATH
• GLOBIGNORE
• SHELLOPTS
• BASHOPTS
• PROMPT_COMMAND
• PS1, PS2, PS4
• MAIL, MAILPATH, MAILCHECK
• IFS

Language runtime code execution:

• PYTHONPATH, PYTHONSTARTUP, PYTHONHOME
• NODE_OPTIONS, NODE_PATH, NODE_EXTRA_CA_CERTS
• PERL5LIB, PERL5OPT
• RUBYLIB, RUBYOPT
• GOPATH, GOROOT, GOFLAGS
• JAVA_HOME, CLASSPATH, JAVA_TOOL_OPTIONS

Security and authentication:

• SSH_AUTH_SOCK
• GPG_AGENT_INFO
• KRB5_CONFIG, KRB5CCNAME
• SSL_CERT_FILE, SSL_CERT_DIR
• CURL_CA_BUNDLE, REQUESTS_CA_BUNDLE
• GIT_SSL_CAINFO
• NIX_SSL_CERT_FILE

Nix:

• NIX_PATH
• NIX_CONF_DIR

Sudo and privilege escalation:

• SUDO_ASKPASS
• SUDO_EDITOR
• VISUAL
• EDITOR

Systemd and D-Bus:

• SYSTEMD_UNIT_PATH
• DBUS_SESSION_BUS_ADDRESS

Open Sesame namespace:

• SESAME_PROFILE

Shell Escaping

The shell_escape() function in open-sesame/src/env.rs produces output safe for embedding in double-quoted export statements. The following transformations are applied:

JSON Escaping

The json_escape() function produces output safe for embedding in JSON string values:

Cross-Profile Behavior

Open Sesame enforces strict per-profile isolation for secret storage while providing controlled mechanisms for accessing secrets from multiple profiles in a single session.

Profile Isolation Guarantees

Each trust profile is a cryptographically independent security domain. The following properties hold:

Independent Master Keys

Each profile has its own password, its own 16-byte random salt (stored at {config_dir}/vaults/{profile}.salt), and its own Argon2id-derived master key. Knowing the password for profile A reveals nothing about the master key for profile B, even if the user chooses the same password for both, because the salts differ.

Independent Vault Keys

The vault key for each profile is derived via core_crypto::derive_vault_key(master_key, profile_id) using the BLAKE3 context string "pds v2 vault-key {profile_id}". Different profile IDs produce different vault keys even from the same master key. The different_profiles_produce_different_keys test in core-crypto/src/hkdf.rs verifies this property.

Independent Database Files

Each profile’s secrets are stored in a separate SQLCipher database file at {config_dir}/vaults/{profile_name}.db. There is no shared database. Opening profile A’s database file with profile B’s vault key fails at the SELECT count(*) FROM sqlite_master verification step in SqlCipherStore::open().

Independent Unlock State

Each profile is unlocked independently via UnlockRequest with an optional profile field. The VaultState struct in daemon-secrets/src/vault.rs maintains per-profile state in several maps:

• master_keys: HashMap<TrustProfileName, SecureBytes> – per-profile master keys.
• vaults: HashMap<TrustProfileName, JitDelivery<SqlCipherStore>> – per-profile open vault handles.
• active_profiles: HashSet<TrustProfileName> – profiles authorized for secret access.
• partial_unlocks: HashMap<TrustProfileName, PartialUnlock> – in-progress multi-factor unlock sessions.

Multiple profiles may be unlocked and active concurrently. There is no global “locked” state; the daemon starts with empty maps and each profile is unlocked individually.

Independent Deactivation

Locking a single profile (LockRequest with a profile field) removes only that profile’s master key, vault handle, partial unlock state, and keyring entry. Other profiles remain unlocked and accessible.

Cross-Profile Tag References

The profile spec format used by sesame env and sesame export supports an org:vault syntax for referencing profiles with organizational namespaces:

default                    --> ProfileSpec { org: None,                  vault: "default" }
braincraft:operations      --> ProfileSpec { org: Some("braincraft"),    vault: "operations" }

This parsing is implemented in parse_profile_specs() in open-sesame/src/ipc.rs. The org field is currently informational – it is included in the SESAME_PROFILES CSV injected into child processes but does not affect vault lookup. The vault field is used as the TrustProfileName for IPC requests.

The format is designed for future extension to container registry-style references (e.g., docker.io/project/org:vault@sha256).

Multi-Profile Secret Injection

The sesame env and sesame export commands accept a comma-separated list of profile specs:

sesame env -p "default,work" -- my-application
sesame export -p "default,work,braincraft:operations" --format json

The profile list can also be set via the SESAME_PROFILES environment variable, which is checked when the -p flag is omitted. Resolution order is implemented in resolve_profile_specs() in open-sesame/src/ipc.rs:

1. If -p is provided, use it.
2. Otherwise, read SESAME_PROFILES from the environment.
3. If neither is set, use the default profile name.

Merge Behavior

fetch_multi_profile_secrets() iterates over the profile specs in order. For each profile, it fetches all secret keys via SecretList, then fetches each value via SecretGet. Keys are merged into the result with left-wins collision resolution: the first profile in the list that contains a given key wins. A HashSet<String> tracks which key names have already been seen.

If a profile has no secrets, a warning is printed to stderr but processing continues with the remaining profiles.

Denylist Enforcement

After the secret key name is converted to an environment variable name (via secret_key_to_env_var()), the result is checked against the denylist (is_denied_env_var()). Denied variables are skipped with a warning on stderr. This check applies identically regardless of which profile the secret originated from.

What Crosses Profile Boundaries

The only mechanism by which secrets from different profiles can coexist in the same memory space is the sesame env / sesame export multi-profile merge, which operates in the CLI process after secrets have been fetched via IPC from independently unlocked vaults.

Multi-Profile Unlock

Each profile must be unlocked independently before its secrets can be accessed. The sesame unlock command accepts a -p flag:

sesame unlock -p default
sesame unlock -p work

There is no batch unlock command that accepts multiple profiles in a single invocation. Each UnlockRequest IPC message targets a single profile. If a profile is already unlocked, the daemon rejects the request with UnlockRejectedReason::AlreadyUnlocked.

Locking supports both single-profile and all-profile modes:

sesame lock -p work          # Lock only the "work" profile
sesame lock                  # Lock all profiles

Lock-all removes all master keys, flushes all JIT caches, scrubs all C-level key buffers, deletes all keyring entries, clears all partial unlock state, and resets the rate limiter.

Factor Architecture

This page describes the pluggable authentication backend system in core-auth. The system defines a trait-based dispatch mechanism that allows multiple authentication methods to coexist, with the AuthDispatcher coordinating backend selection at unlock time.

AuthFactorId

The AuthFactorId enum in core-types/src/auth.rs identifies each authentication factor type. Six variants exist:

The enum derives Serialize, Deserialize, Copy, Hash, Ord, and uses #[serde(rename_all = "kebab-case")]. The four future variants (Fido2, Tpm, Fingerprint, Yubikey) are defined to permit forward-compatible policy configuration: a vault metadata file can reference these factor types in its auth_policy before their backends are implemented.

AuthFactorId::from_config_str() parses the config-file string form. AuthFactorId::as_config_str() returns the static string. The Display implementation delegates to as_config_str().

VaultAuthBackend Trait

Defined in core-auth/src/backend.rs, the VaultAuthBackend trait is the extension point for adding new authentication methods. It requires Send + Sync and uses #[async_trait].

Required Methods

The enroll method accepts an optional selected_key_index for backends that offer multiple eligible keys (e.g., SSH agent with multiple loaded keys). If None, the backend picks the first eligible key.

AuthInteraction

The AuthInteraction enum describes the interaction model:

• None – Backend can unlock silently (SSH agent with a software key, future TPM, future keyring).
• PasswordEntry – Keyboard input required.
• HardwareTouch – Physical touch on a hardware token (future FIDO2, PIV with touch policy).

FactorContribution

The FactorContribution enum describes what a backend provides to the unlock process:

• CompleteMasterKey – The backend independently unwraps or derives a complete 32-byte master key. Used in Any and Policy modes.
• FactorPiece – The backend provides a piece that must be combined with pieces from other factors via BLAKE3 derive_key. Used in All mode.

VaultMetadata::contribution_type() returns FactorPiece when auth_policy is All, and CompleteMasterKey for Any and Policy.

UnlockOutcome

The UnlockOutcome struct is returned by a successful unlock() call:

• master_key: SecureBytes – The 32-byte master key (mlock’d, zeroize-on-drop).
• audit_metadata: BTreeMap<String, String> – Backend-specific metadata for audit logging (e.g., ssh_fingerprint, key_type).
• ipc_strategy: IpcUnlockStrategy – Which IPC message type to use (PasswordUnlock or DirectMasterKey).
• factor_id: AuthFactorId – Which factor this outcome represents.

IpcUnlockStrategy

• PasswordUnlock – Use the UnlockRequest IPC message; daemon-secrets performs the KDF.
• DirectMasterKey – Use the SshUnlockRequest or FactorSubmit IPC message with a pre-derived master key.

Both implemented backends (PasswordBackend and SshAgentBackend) use DirectMasterKey. The password backend derives the KEK client-side via Argon2id and unwraps the master key before sending it over IPC.

AuthDispatcher

Defined in core-auth/src/dispatcher.rs, the AuthDispatcher holds a Vec<Box<dyn VaultAuthBackend>> and provides methods for backend discovery and selection.

Construction

AuthDispatcher::new() registers two backends in priority order:

1. SshAgentBackend (non-interactive)
2. PasswordBackend (interactive fallback)

Methods

backends(&self) -> &[Box<dyn VaultAuthBackend>] – Access all registered backends.

applicable_backends(profile, config_dir, meta) -> Vec<&dyn VaultAuthBackend> – Returns backends that are both enrolled in the vault metadata (meta.has_factor(backend.factor_id())) AND can currently perform an unlock (backend.can_unlock()). Used by the CLI to determine which factors to attempt.

find_auto_backend(profile, config_dir) -> Option<&dyn VaultAuthBackend> – Returns the first backend where requires_interaction() == AuthInteraction::None, is_enrolled() is true, and can_unlock() is true. Does not consult vault metadata – checks enrollment files directly on disk.

can_auto_unlock(profile, config_dir, meta) -> bool – Policy-aware auto-unlock feasibility check:

• Any mode: delegates to find_auto_backend() – a single non-interactive backend suffices.
• All or Policy mode: all applicable backends must be non-interactive. Returns false conservatively if any required factor needs interaction.

password_backend(&self) -> &dyn VaultAuthBackend – Returns the password backend. Panics if not registered (programming error – the constructor always registers it).

VaultMetadata

Defined in core-auth/src/vault_meta.rs, VaultMetadata is the JSON-serialized record of a vault’s authentication state. Stored at {config_dir}/vaults/{profile}.vault-meta with permissions 0o600.

Fields

VaultInitMode

• Password – Initialized with password only.
• SshKeyOnly – Initialized with SSH key only (random master key, no password).
• MultiFactor { factors: Vec<AuthFactorId> } – Initialized with multiple factors.

EnrolledFactor

Each enrolled factor records:

• factor_id: AuthFactorId – The factor type.
• label: String – Human-readable label (e.g., SSH key fingerprint, “master password”).
• enrolled_at: u64 – Unix epoch seconds.

Version Gating

VaultMetadata::load() rejects metadata where version > MAX_SUPPORTED_VERSION (currently 1). This prevents a newer binary from silently misinterpreting a vault metadata format it does not understand.

Persistence

JSON is used rather than TOML to distinguish machine-managed metadata from user-editable configuration. Writes use atomic rename via a .vault-meta.tmp intermediate file. File permissions are set to 0o600 on Unix before the rename.

Factory Methods

• new_password(auth_policy) – Creates metadata with a single Password enrolled factor.
• new_ssh_only(fingerprint, auth_policy) – Creates metadata with a single SshAgent enrolled factor.
• new_multi_factor(factors, auth_policy) – Creates metadata with arbitrary enrolled factors.

Factor Management

• has_factor(factor_id) -> bool – Check enrollment.
• add_factor(factor_id, label) – Idempotent add (no-op if already enrolled).
• remove_factor(factor_id) – Remove by factor ID.
• contribution_type() -> FactorContribution – Returns FactorPiece for All mode, CompleteMasterKey for Any/Policy.

Adding a New Factor

To add a new authentication factor (e.g., FIDO2):

1. The AuthFactorId variant already exists in core-types/src/auth.rs (e.g., Fido2).
2. Create a new module in core-auth/src/ implementing a struct (e.g., Fido2Backend).
3. Implement VaultAuthBackend for the struct:
   • factor_id() returns the corresponding AuthFactorId variant.
   • is_enrolled() checks for the factor’s enrollment artifact on disk.
   • can_unlock() checks whether the hardware or service is available.
   • requires_interaction() returns the appropriate AuthInteraction variant.
   • unlock() derives or unwraps the 32-byte master key.
   • enroll() wraps the master key under the factor’s KEK and writes an enrollment blob.
   • revoke() zeroizes and deletes the enrollment blob.
4. Register the backend in AuthDispatcher::new() at the appropriate priority position (non-interactive backends before interactive ones).
5. The CLI unlock flow in open-sesame/src/unlock.rs handles unknown factors by reporting that the factor is not yet supported. Adding a match arm in try_auto_factor() (for non-interactive factors) or the phase 3 loop (for interactive factors) enables CLI support.

No changes to daemon-secrets are required – the FactorSubmit IPC handler and PartialUnlock state machine operate on AuthFactorId and SecureBytes generically.

Policy Engine

This page describes the multi-factor authentication policy system. Policies are declared in configuration, persisted in vault metadata, and enforced by daemon-secrets at unlock time through a partial unlock state machine.

AuthCombineMode

Defined in core-types/src/auth.rs, the AuthCombineMode enum determines both the key wrapping scheme at initialization and the unlock policy evaluation at runtime. It derives Serialize, Deserialize, and uses #[serde(rename_all = "kebab-case")].

Any (default)

AuthCombineMode::Any

The master key is a random 32-byte value generated via getrandom. Each enrolled factor independently wraps this master key under its own KEK (Argon2id-derived for password, BLAKE3-derived for SSH). Any single enrolled factor can unlock the vault alone.

At unlock time in daemon-secrets, the first valid factor submitted completes the unlock immediately. The PartialUnlock state machine clears all remaining requirements when Any mode is detected:

#![allow(unused)]
fn main() {
if matches!(meta.auth_policy, AuthCombineMode::Any) {
    partial.remaining_required.clear();
    partial.remaining_additional = 0;
}
}

All

AuthCombineMode::All

Every enrolled factor must be provided at unlock time. Each factor contributes a “piece” (its unwrapped key material). Once all pieces are collected, daemon-secrets combines them into the master key via BLAKE3 derive_key:

1. Factor pieces are sorted by AuthFactorId (which derives Ord).
2. The sorted pieces are concatenated.
3. BLAKE3 derive_key is called with context "pds v2 combined-master-key {profile_name}" and the concatenated bytes as input.
4. The result is a 32-byte master key.

The KDF context constant is ALL_MODE_KDF_CONTEXT defined in daemon-secrets/src/vault.rs as "pds v2 combined-master-key".

The VaultMetadata::contribution_type() method returns FactorContribution::FactorPiece for All mode. daemon-secrets checks this to decide whether to verify each factor’s key material against the vault DB independently (it does not – verification only happens after combination).

Policy

AuthCombineMode::Policy(AuthPolicy {
    required: Vec<AuthFactorId>,
    additional_required: u32,
})

A policy expression combining mandatory factors with a threshold of additional factors. Key wrapping uses independent wraps (same as Any mode – each factor wraps the same random master key). Policy enforcement happens at the daemon level.

• required: Factors that must always succeed. Every factor in this list must be submitted.
• additional_required: How many additional enrolled factors (beyond those in required) must also succeed.

Example: required: [Password], additional_required: 1 means the password is always required, plus one more factor (e.g., SSH agent or a future FIDO2 token).

FactorContribution is CompleteMasterKey for Policy mode – each factor independently unwraps the same master key.

Configuration

Auth policy is configured in config.toml under [profiles.<name>.auth], defined by the AuthConfig struct in core-config/src/schema_secrets.rs:

[profiles.default.auth]
mode = "any"                          # "any", "all", or "policy"
required = ["password", "ssh-agent"]  # For mode="policy" only
additional_required = 1               # For mode="policy" only

AuthConfig::to_typed() converts the string-based config representation to AuthCombineMode. It validates that all factor names in required are recognized via AuthFactorId::from_config_str(). The default AuthConfig uses mode "any" with empty required and additional_required = 0.

PartialUnlock State Machine

Defined in daemon-secrets/src/vault.rs, the PartialUnlock struct tracks in-progress multi-factor unlocks. At most one PartialUnlock exists per profile, stored in VaultState::partial_unlocks.

State

Lifecycle

1. Creation: A PartialUnlock is created on the first FactorSubmit for a profile. The remaining_required and remaining_additional fields are initialized from the vault’s AuthCombineMode.

2. Factor acceptance: Each FactorSubmit records the factor’s key material in received_factors and removes the factor from remaining_required. If the factor is not in the required set and remaining_additional > 0, the additional counter is decremented.

3. Completion check: is_complete() returns true when remaining_required is empty AND remaining_additional == 0.

4. Promotion: When complete, the partial state is removed from the map and the master key is either taken directly (for Any/Policy mode, the first received factor’s key) or derived by combining all pieces (for All mode).

5. Expiration: is_expired() checks whether tokio::time::Instant::now() >= deadline. Expired partials are rejected on the next FactorSubmit and removed from the map.

Timeouts

• PARTIAL_UNLOCK_TIMEOUT_SECS: 120 seconds. The deadline for collecting all required factors after the first factor is submitted.
• PARTIAL_UNLOCK_SWEEP_INTERVAL_SECS: 30 seconds. The interval at which daemon-secrets sweeps and discards expired partial unlock state.

Key Combination (All Mode)

When all factors have been received in All mode, daemon-secrets combines them:

#![allow(unused)]
fn main() {
let mut pieces: Vec<_> = partial.received_factors.into_iter().collect();
pieces.sort_by_key(|(id, _)| *id);
let mut combined = Vec::new();
for (_id, piece) in &pieces {
    combined.extend_from_slice(piece.as_bytes());
}
let ctx_str = format!("{ALL_MODE_KDF_CONTEXT} {target}");
let derived: [u8; 32] = blake3::derive_key(&ctx_str, &combined);
combined.zeroize();
}

The sorting by AuthFactorId ensures deterministic ordering regardless of submission order.

CLI Unlock Flow

The CLI unlock command in open-sesame/src/unlock.rs orchestrates factor submission in three phases:

Phase 1: Auto-Submit Non-Interactive Factors

The CLI iterates over all enrolled factors and calls try_auto_factor() for each. Currently, only AuthFactorId::SshAgent is handled – it checks can_unlock() on the SshAgentBackend, and if available, calls unlock() to derive the master key client-side and submits it via FactorSubmit IPC.

If the vault uses Any mode and the SSH agent succeeds, the vault is fully unlocked and no further factors are needed.

Phase 2: Query Remaining Factors

The CLI sends a VaultAuthQuery IPC message to daemon-secrets, which returns:

• enrolled_factors: All enrolled factor IDs.
• auth_policy: The vault’s AuthCombineMode.
• partial_in_progress: Whether a PartialUnlock exists.
• received_factors: Which factors have already been accepted.

The CLI filters out already-received factors to determine what remains.

Phase 3: Prompt Interactive Factors

The CLI iterates over remaining factors:

• Password: Prompts for password (via dialoguer if terminal, or reads from stdin), derives the master key client-side using PasswordBackend::unlock(), and submits via FactorSubmit.
• Other factors: The CLI reports that the factor is not yet supported and exits with an error.

Each FactorSubmit response includes unlock_complete, remaining_factors, and remaining_additional, allowing the CLI to track progress.

Factor Submission IPC

The submit_factor() function sends EventKind::FactorSubmit with:

• factor_id: Which factor type.
• key_material: The master key in a SensitiveBytes (mlock’d ProtectedAlloc).
• profile: Target profile name.
• audit_metadata: Backend-specific audit fields.

The daemon responds with EventKind::FactorResponse containing acceptance status, completion status, and remaining factor information.

Daemon-Side Verification

For Any and Policy modes (CompleteMasterKey contribution), daemon-secrets verifies each submitted factor’s key material against the vault database before accepting it. It derives the vault key via core_crypto::derive_vault_key() and attempts to open the SQLCipher database. If the open fails (wrong key, GCM authentication failure), the factor is rejected.

For All mode (FactorPiece contribution), individual pieces cannot be verified against the vault database. Verification happens after all pieces are combined into the master key.

Password Backend

This page describes the password authentication backend implemented in core-auth/src/password.rs and core-auth/src/password_wrap.rs. The backend uses Argon2id to derive a key-encrypting key (KEK) from user-provided password bytes, then wraps or unwraps a 32-byte master key using AES-256-GCM.

PasswordBackend

The PasswordBackend struct holds an optional SecureVec containing password bytes. Password bytes must be injected via with_password() (builder pattern) or set_password() (mutation) before calling unlock() or enroll(). The SecureVec type provides mlock’d memory and zeroize-on-drop semantics.

Trait Implementation

KEK Derivation

The derive_kek() method performs:

1. Validate salt is exactly 16 bytes.
2. Call core_crypto::derive_key_argon2(password, salt) – Argon2id with project-wide parameters.
3. Copy the first 32 bytes of the Argon2id output into a [u8; 32] KEK array.

The Argon2id parameters are defined in core-crypto (not in core-auth).

Unlock Flow

1. Read password bytes from the stored SecureVec. Fail with BackendNotApplicable if no password was set.
2. Load the PasswordWrapBlob from {config_dir}/vaults/{profile}.password-wrap.
3. Derive the KEK via derive_kek(password, salt).
4. Call blob.unwrap(&mut kek) to decrypt the master key via AES-256-GCM. The KEK is zeroized after use.
5. Return an UnlockOutcome with ipc_strategy: DirectMasterKey and factor_id: Password.

Enrollment Flow

1. Read password bytes from the stored SecureVec.
2. Derive the KEK via derive_kek(password, salt).
3. Call PasswordWrapBlob::wrap(master_key, &mut kek) to encrypt the master key. The KEK is zeroized after use.
4. Write the blob to disk via blob.save(config_dir, profile).

Revocation

Revocation overwrites the wrap file with zeros before deletion to prevent casual recovery from disk:

1. Read the file length.
2. Write a zero-filled buffer of the same length.
3. Delete the file via std::fs::remove_file.

PasswordWrapBlob

Defined in core-auth/src/password_wrap.rs, the PasswordWrapBlob struct represents the on-disk binary format for the AES-256-GCM wrapped master key.

Binary Format

Offset  Length  Field
0       1       Version byte (0x01)
1       12      Nonce (random, generated via getrandom)
13      48      Ciphertext (32-byte master key + 16-byte GCM tag)

Total size: 61 bytes.

The version constant PASSWORD_WRAP_VERSION is 0x01.

Wrapping (Encryption)

PasswordWrapBlob::wrap(master_key, kek_bytes):

1. Construct an EncryptionKey from the 32-byte KEK.
2. Generate a 12-byte random nonce via getrandom.
3. Encrypt the master key with AES-256-GCM using the KEK and nonce.
4. Zeroize the KEK bytes.
5. Return the blob containing version, nonce, and ciphertext.

Unwrapping (Decryption)

PasswordWrapBlob::unwrap(kek_bytes):

1. Construct an EncryptionKey from the 32-byte KEK.
2. Zeroize the KEK bytes immediately after key construction.
3. Decrypt using AES-256-GCM with the stored nonce and ciphertext.
4. Return the plaintext as SecureBytes (mlock’d, zeroize-on-drop).
5. If GCM authentication fails (wrong password), return AuthError::UnwrapFailed.

Deserialization

PasswordWrapBlob::deserialize(data) rejects:

• Data shorter than 61 bytes (AuthError::InvalidBlob).
• Version bytes other than 0x01 (AuthError::InvalidBlob).

Persistence

Path: {config_dir}/vaults/{profile}.password-wrap

Write: save() uses atomic rename via a .password-wrap.tmp intermediate file. On Unix, file permissions are set to 0o600 (owner read/write only) before the rename. The parent vaults/ directory is created if it does not exist.

Read: load() reads the file and calls deserialize().

Zeroization

The PasswordWrapBlob struct implements Drop to zeroize its nonce and ciphertext fields. All KEK arrays are zeroized immediately after use in both wrap() and unwrap().

Salt

Each profile has an independent 16-byte salt stored at {config_dir}/vaults/{profile}.salt. The salt is generated via getrandom during vault initialization (daemon-secrets/src/unlock.rs::generate_profile_salt).

During sesame init, the salt file is written with:

• The vaults/ directory created with permissions 0o700.
• The salt file itself written via core_config::atomic_write and then set to permissions 0o600.

The salt is used as input to both the Argon2id KDF (password backend) and the BLAKE3 challenge derivation (SSH agent backend). Using a per-profile salt ensures that the same password produces different KEKs for different profiles.

Key Material Handling

The password backend’s key material lifecycle:

1. Password bytes: Stored in SecureVec (mlock’d, zeroize-on-drop). Acquired from the user via dialoguer::Password (terminal) or stdin (pipe). The String holding the raw password is zeroized immediately after copying into the SecureVec.

2. KEK (Argon2id output): A [u8; 32] stack array. Zeroized by PasswordWrapBlob::wrap() and PasswordWrapBlob::unwrap() after use.

3. Master key: Returned as SecureBytes (backed by ProtectedAlloc – mlock’d, mprotect’d, zeroize-on-drop). Transferred to daemon-secrets via SensitiveBytes IPC wrapper which also uses ProtectedAlloc.

At no point does the master key exist in an unprotected heap allocation. The KEK exists briefly on the stack and is zeroized before the function returns.

SSH Agent Backend

This page describes the SSH agent authentication backend implemented in core-auth/src/ssh.rs and core-auth/src/ssh_types.rs. The backend connects to the user’s SSH agent, signs a deterministic challenge, derives a KEK from the signature via BLAKE3, and wraps or unwraps the vault master key using AES-256-GCM.

SshAgentBackend

The SshAgentBackend struct is a zero-sized type. All state lives in the SSH agent process and on-disk enrollment blobs.

Trait Implementation

The can_unlock() check connects to the SSH agent via spawn_blocking (the ssh-agent-client-rs crate uses synchronous Unix socket I/O) and searches the agent’s identity list for a key matching the fingerprint stored in the enrollment blob.

Challenge Construction

The challenge is a deterministic 32-byte value derived from the profile name and salt:

context = "pds v2 ssh-challenge {profile_name}"
challenge = BLAKE3::derive_key(context, salt)

The same profile name and salt always produce the same challenge. Different profiles or salts produce different challenges. This determinism is essential because the backend must produce the same challenge at both enrollment and unlock time.

Signature to KEK Derivation

After the SSH agent signs the challenge, the raw signature bytes are fed into a second BLAKE3 derive_key call:

context = "pds v2 ssh-vault-kek {profile_name}"
kek = BLAKE3::derive_key(context, signature_bytes)

The raw signature bytes are zeroized immediately after KEK derivation. The KEK is a 32-byte value used as an AES-256-GCM key to wrap or unwrap the master key.

This two-step derivation (challenge from salt, KEK from signature) ensures:

• The KEK is bound to both the profile identity and the specific SSH key.
• The signature is never stored – only the wrapped master key is persisted.
• The BLAKE3 derivation provides domain separation between the challenge and KEK contexts.

Supported Key Types

Defined in core-auth/src/ssh_types.rs, the SshKeyType enum restricts which SSH key types can be used:

Excluded key types:

• ECDSA (ecdsa-sha2-nistp256, etc.): Non-deterministic. Uses a random k value per signature. A different signature on each unlock would produce a different KEK and fail to unwrap the enrollment blob.
• RSA-PSS: Non-deterministic. Uses a random salt per signature.

SshKeyType::from_algorithm() converts from ssh_key::Algorithm, rejecting non-deterministic types with AuthError::UnsupportedKeyType. SshKeyType::from_wire_name() parses the SSH wire format string.

EnrollmentBlob

The EnrollmentBlob struct persists the SSH-agent enrollment on disk at {config_dir}/vaults/{profile}.ssh-enrollment.

Binary Format

Offset    Length  Field
0         1       Version byte (0x01)
1         2       Key fingerprint length N (big-endian u16)
3         N       Key fingerprint (ASCII, e.g. "SHA256:...")
3+N       1       Key type length M (u8)
4+N       M       Key type wire name (ASCII, e.g. "ssh-ed25519")
4+N+M     12      Nonce (random)
16+N+M    48      Ciphertext (32-byte master key + 16-byte GCM tag)

The version constant ENROLLMENT_VERSION is 0x01.

Security

• Fingerprint length is capped at 256 bytes during deserialization to prevent allocation attacks from malformed blobs.
• File permissions are set to 0o600 before atomic rename.
• Revocation overwrites the file with zeros before deletion.

Unlock Flow

1. Read and deserialize the enrollment blob from disk.
2. Derive the 32-byte challenge: BLAKE3::derive_key("pds v2 ssh-challenge {profile}", salt).
3. Connect to the SSH agent (via spawn_blocking to avoid blocking the tokio runtime).
4. Find the identity matching the enrolled fingerprint.
5. Sign the challenge with the enrolled key.
6. Derive the KEK: BLAKE3::derive_key("pds v2 ssh-vault-kek {profile}", signature_bytes).
7. Zeroize the raw signature bytes.
8. Construct an EncryptionKey from the KEK, then zeroize the KEK bytes.
9. Decrypt the master key from the enrollment blob’s ciphertext using AES-256-GCM.
10. Return an UnlockOutcome with ipc_strategy: DirectMasterKey, factor_id: SshAgent, and audit metadata including the SSH fingerprint and key type.

Enrollment Flow

1. Connect to the SSH agent, list all identities, filter to eligible key types (Ed25519, RSA).
2. Select a key by selected_key_index (required – None returns NoEligibleKey).
3. Sign the challenge with the selected key.
4. Derive the KEK from the signature (same derivation as unlock).
5. Zeroize the signature bytes.
6. Generate a 12-byte random nonce via getrandom.
7. Encrypt the master key with AES-256-GCM using the KEK and nonce.
8. Zeroize the KEK bytes.
9. Build and serialize the EnrollmentBlob with the key fingerprint, key type, nonce, and ciphertext.
10. Write to disk atomically via a .ssh-enrollment.tmp intermediate, with 0o600 permissions.

Key Selection

The CLI sesame ssh enroll command in open-sesame/src/ssh.rs supports three methods for selecting which SSH key to enroll:

Fingerprint via –ssh-key Flag

sesame ssh enroll --ssh-key SHA256:abc123...

The fingerprint is matched against loaded agent keys, with or without the SHA256: prefix.

Public Key File via –ssh-key Flag

sesame ssh enroll --ssh-key ~/.ssh/id_ed25519.pub

The file is read, parsed as an OpenSSH public key, and its SHA256 fingerprint is computed. Path traversal via ~/ is resolved through canonicalize() and verified to remain within $HOME. Files larger than 64 KB are rejected.

Interactive Menu

When --ssh-key is omitted and stdin is a terminal, dialoguer::Select presents a menu of eligible keys from the agent, showing fingerprint and algorithm. In non-interactive mode (piped stdin), --ssh-key is required.

Agent Connection

The connect_agent() function in core-auth/src/ssh.rs attempts two socket paths in order:

1. $SSH_AUTH_SOCK: The standard environment variable, set by ssh-agent, sshd forwarding, or systemd environment propagation.

2. ~/.ssh/agent.sock: A fallback stable symlink path. On Konductor VMs, /etc/profile.d/konductor-ssh-agent.sh creates ~/.ssh/agent.sock pointing to the forwarded agent socket (/tmp/ssh-XXXX/agent.PID) on each SSH login. This gives systemd user services a stable path to the forwarded agent, since $SSH_AUTH_SOCK points to a per-session temporary directory that changes on each login.

The function is intentionally synchronous – local Unix socket connect is sub-millisecond. All agent operations in the async VaultAuthBackend methods are wrapped in tokio::task::spawn_blocking to avoid blocking the tokio runtime.

Agent Forwarding

For remote or containerized environments where the SSH key lives on the operator’s workstation:

• The SSH agent socket is forwarded via ssh -A or ForwardAgent yes in SSH config.
• $SSH_AUTH_SOCK is set by sshd to the forwarded socket path.
• The stable symlink pattern (~/.ssh/agent.sock) provides systemd user services access to the forwarded agent, since systemd services do not inherit the per-session $SSH_AUTH_SOCK.
• The Konductor profile.d hook creates and maintains this symlink automatically on each SSH login.

This architecture allows vault unlock via SSH agent even when running inside a VM or container, provided the SSH agent is forwarded from the host.

FIDO2 / WebAuthn Backend

Status: Design Intent. The AuthFactorId::Fido2 variant exists in core-types::auth and the VaultAuthBackend trait is defined in core-auth::backend, but no struct implements this factor today. This page documents what the backend will do when built, grounded in the trait interface and FIDO2 standards.

The FIDO2 backend enables vault unlock using CTAP2-compliant authenticators – USB security keys, platform authenticators, and BLE/NFC tokens. It maps to AuthFactorId::Fido2 (config string "fido2") and operates through libfido2 directly, without a browser or the WebAuthn JavaScript API.

Relevant Standards

Mapping to VaultAuthBackend

factor_id()

Returns AuthFactorId::Fido2.

backend_id()

Returns "fido2".

name()

Returns "FIDO2/WebAuthn" (for overlay display and audit logs).

requires_interaction()

Returns AuthInteraction::HardwareTouch. CTAP2 authenticators require user presence (UP) at minimum; most also support user verification (UV) via on-device PIN or biometric. Both require physical interaction.

is_enrolled(profile, config_dir)

Checks whether a file {config_dir}/profiles/{profile}/fido2.enrollment exists and contains a valid enrollment blob (see Enrollment Blob Format below). The enrollment record contains the credential ID, relying party ID, and the wrapped master key blob. This is a synchronous filesystem check with no device communication.

can_unlock(profile, config_dir)

1. Verify enrollment exists via is_enrolled().
2. Enumerate connected FIDO2 devices via libfido2 device enumeration.
3. Return true if at least one device is present.

Device enumeration over HID typically completes in under 20ms, well within the 100ms trait budget. This method does not verify that the connected device holds the enrolled credential – that requires a CTAP2 transaction and user interaction, which is deferred to unlock().

enroll(profile, master_key, config_dir, salt, selected_key_index)

Enrollment proceeds as follows:

1. Enumerate connected FIDO2 authenticators. If selected_key_index is Some(i), select the i-th device; otherwise select the first.
2. Construct a relying party ID: open-sesame:{profile} (synthetic, not a web origin).
3. Generate a random 32-byte user ID and a random 16-byte challenge.
4. Perform authenticatorMakeCredential with:
   • Algorithm: ES256 (COSE -7) preferred, EdDSA (COSE -8) as fallback.
   • Extensions: hmac-secret: true, credProtect: 2, rk: true (resident key).
   • User verification: preferred (UV if the device supports it).
5. Store the attestation response (credential ID, public key, attestation object).
6. Immediately perform a getAssertion with the hmac-secret extension, passing salt as the HMAC-secret salt input. The authenticator returns a 32-byte HMAC output.
7. Use the HMAC output as a key-encryption key (KEK). Wrap master_key under this KEK using AES-256-GCM with a random 12-byte nonce.
8. Serialize and write the enrollment blob to {config_dir}/profiles/{profile}/fido2.enrollment.

unlock(profile, config_dir, salt)

Unlock proceeds as follows:

1. Load and deserialize the enrollment blob.
2. Perform authenticatorGetAssertion for the enrolled RP ID and credential ID, with:
   • Extensions: hmac-secret with salt as input.
   • User verification: preferred.
3. The authenticator returns a 32-byte HMAC output (the KEK) and an assertion signature.
4. Unwrap the master key from the enrollment blob using the KEK (AES-256-GCM decrypt).
5. If unwrap fails (wrong device or tampered blob), return AuthError::UnwrapFailed.
6. Return UnlockOutcome:
   • master_key: the unwrapped 32-byte key.
   • ipc_strategy: IpcUnlockStrategy::DirectMasterKey.
   • factor_id: AuthFactorId::Fido2.
   • audit_metadata: {"aaguid": "<hex>", "credential_id": "<hex>", "uv": "true|false"}.

revoke(profile, config_dir)

Deletes {config_dir}/profiles/{profile}/fido2.enrollment. Does not attempt to delete the resident credential from the authenticator (CTAP2 does not guarantee remote deletion support across all devices).

Enrollment Blob Format

Version: u8 (1)
RP ID: length-prefixed UTF-8
Credential ID: length-prefixed bytes
Public Key (COSE): length-prefixed bytes
Attestation Object: length-prefixed bytes (optional, for future policy use)
Wrapped Master Key: 12-byte nonce || ciphertext || 16-byte GCM tag

The blob is versioned to allow schema evolution. The version byte is checked on load; unknown versions produce AuthError::InvalidBlob.

FactorContribution

• AuthCombineMode::Any or AuthCombineMode::Policy: The backend provides FactorContribution::CompleteMasterKey. It independently unwraps the full 32-byte master key from its enrollment blob.
• AuthCombineMode::All: The backend provides FactorContribution::FactorPiece. The 32-byte HMAC-secret output is contributed as one input to the combined HKDF derivation. In this mode, enrollment does not wrap the master key; it stores only the credential ID and RP ID. The HMAC-secret output itself is the piece.

Platform Authenticator vs Roaming Authenticator

FIDO2 defines two authenticator attachment modalities:

• Platform authenticators are built into the host device (e.g., Windows Hello TPM-backed key, macOS Touch ID Secure Enclave key, Android biometric key). On Linux desktops, platform authenticators are uncommon.
• Roaming authenticators are external devices connected via USB HID, NFC, or BLE (e.g., YubiKey 5, SoloKeys, Google Titan, Nitrokey).

This backend targets roaming authenticators. For platform biometric unlock on Linux, the Biometrics backend (AuthFactorId::Fingerprint) is the appropriate choice – it uses fprintd/polkit rather than CTAP2.

Browser-less Operation

Open Sesame communicates directly with authenticators via libfido2, the reference CTAP2 C library maintained by Yubico. Consequences:

• No origin binding. The RP ID is a synthetic string (open-sesame:{profile}), not a web origin. There is no TLS channel binding.
• No browser UI. The daemon overlay prompts the user to touch the authenticator. The backend blocks on the CTAP2 transaction until UP/UV is satisfied or a timeout expires.
• Attestation is informational. The attestation object is stored for optional future policy enforcement (e.g., restricting enrollment to FIPS-certified authenticators via FIDO Metadata Service lookup) but is not verified during normal unlock.

Integration Dependencies

Threat Model Considerations

• Deterministic KEK. The HMAC-secret output is deterministic for a given (credential, salt) pair. Changing the vault salt invalidates the KEK; re-enrollment is required after re-keying.
• Loss recovery. If the authenticator is lost or destroyed, the enrollment blob is useless. Recovery requires another enrolled factor (password, SSH agent, etc.).
• Clone resistance. Depends on the authenticator hardware. Devices with a secure element (YubiKey 5, SoloKeys v2) resist cloning. Software-only CTAP2 implementations (e.g., libfido2 soft token) provide no clone resistance.
• PIN brute-force. CTAP2 authenticators implement per-device PIN retry counters with lockout. This is enforced by the authenticator firmware, not by Open Sesame.
• Relay attacks. An attacker with network access to the USB HID device could relay CTAP2 messages. Physical proximity verification is delegated to the authenticator’s UP mechanism.

See Also

• Factor Architecture – VaultAuthBackend trait definition and dispatch
• Hardware Tokens – YubiKey PIV/challenge-response (non-FIDO2 protocols)
• Biometrics – Platform biometric unlock via fprintd
• Policy Engine – Multi-factor combination modes (Any, All, Policy)

TPM 2.0 Backend

Status: Design Intent. The AuthFactorId::Tpm variant exists in core-types::auth and the VaultAuthBackend trait is defined in core-auth::backend, but no struct implements this factor today. This page documents what the backend will do when built, grounded in the trait interface and TPM 2.0 standards.

The TPM backend enables vault unlock by sealing the master key to the platform’s Trusted Platform Module. The sealed blob can only be unsealed when the TPM’s Platform Configuration Registers (PCRs) match the values recorded at seal time, binding the vault to a specific machine in a specific boot state. It maps to AuthFactorId::Tpm (config string "tpm").

Relevant Standards

Core Concept: Sealing to PCR State

TPM 2.0 sealing binds a data blob to an authorization policy that includes PCR values. The TPM only unseals the blob if the current PCR values match the policy. This creates a hardware-enforced link between the vault key and boot integrity state:

1. At enrollment, the backend reads the current PCR values, constructs an authorization policy from them, and seals the master key under the TPM’s Storage Root Key (SRK) with that policy.
2. At unlock, the backend asks the TPM to unseal the blob. The TPM internally compares current PCR values against the sealed policy. If they match, the blob is released. If any measured component has changed, unsealing fails.

PCR Selection

The default PCR selection for desktop Linux:

PCRs 4-6 (boot manager, GPT, resume events) are intentionally excluded by default because kernel updates would invalidate the seal on every update. The PCR set is configurable at enrollment time.

Extending to PCR 11 (unified kernel image measurement, used by systemd-stub) or PCR 10 (IMA) is supported as an opt-in for higher-assurance configurations.

Mapping to VaultAuthBackend

factor_id()

Returns AuthFactorId::Tpm.

backend_id()

Returns "tpm".

name()

Returns "TPM 2.0".

requires_interaction()

Returns AuthInteraction::None. TPM unsealing is a silent, non-interactive operation. The TPM does not require user presence for unsealing (unlike FIDO2). If a TPM PIN (authValue) is configured on the sealed object, the interaction type changes to AuthInteraction::PasswordEntry.

is_enrolled(profile, config_dir)

Checks whether {config_dir}/profiles/{profile}/tpm.enrollment exists and contains a valid sealed blob with a recognized version byte.

can_unlock(profile, config_dir)

1. Verify enrollment exists via is_enrolled().
2. Open a connection to the TPM via the TCTI (typically /dev/tpmrm0, the kernel resource manager).
3. Return true if the TPM device is accessible.

PCR matching is not checked here – a trial unseal could exceed the 100ms budget and may trigger rate limiting on some TPM implementations.

enroll(profile, master_key, config_dir, salt, selected_key_index)

1. Open a TPM context via tpm2-tss ESAPI.
2. Read the current PCR values for the configured PCR selection (default: 0, 1, 2, 3, 7).
3. Build a PolicyPCR authorization policy from the PCR digest.
4. Optionally, combine with PolicyAuthValue if the user wants a TPM PIN (defense-in-depth against evil-maid attacks where PCRs match but an attacker has physical access).
5. Create a sealed object under the SRK (Storage Hierarchy, persistent handle 0x81000001 or equivalent):
   • Object type: TPM2_ALG_KEYEDHASH with seal attribute.
   • Data: the 32-byte master_key.
   • Auth policy: the PCR policy (and optionally PIN policy).
6. Persist the sealed object to a TPM NV index, or serialize the public/private portions to disk.
7. Write the enrollment blob to {config_dir}/profiles/{profile}/tpm.enrollment.

selected_key_index is unused (there is one TPM per machine). It is ignored.

unlock(profile, config_dir, salt)

1. Load the enrollment blob and deserialize the sealed object context.
2. Open a TPM context via ESAPI.
3. Load the sealed object into the TPM.
4. Start a policy session. Execute PolicyPCR with the enrolled PCR selection.
5. If a TPM PIN was configured, execute PolicyAuthValue and provide the PIN.
6. Call TPM2_Unseal with the policy session.
7. If unsealing succeeds, the TPM returns the 32-byte master key.
8. If unsealing fails (PCR mismatch), return AuthError::UnwrapFailed. The audit metadata should include which PCRs diverged, if determinable.
9. Return UnlockOutcome:
   • master_key: the unsealed 32-byte key.
   • ipc_strategy: IpcUnlockStrategy::DirectMasterKey.
   • factor_id: AuthFactorId::Tpm.
   • audit_metadata: {"pcr_selection": "0,1,2,3,7", "tpm_manufacturer": "<vendor>"}.

revoke(profile, config_dir)

1. If the sealed object was persisted to a TPM NV index, evict it with TPM2_EvictControl.
2. Delete {config_dir}/profiles/{profile}/tpm.enrollment.

Enrollment Blob Format

Version: u8 (1)
PCR selection: u32 bitmask (bit N set = PCR N included)
PCR digest at seal time: 32 bytes (SHA-256)
Sealed object public area: length-prefixed bytes (TPM2B_PUBLIC)
Sealed object private area: length-prefixed bytes (TPM2B_PRIVATE)
SRK handle: u32
PIN flag: u8 (0 = no PIN, 1 = PolicyAuthValue included)

FactorContribution

• AuthCombineMode::Any or AuthCombineMode::Policy: The backend provides FactorContribution::CompleteMasterKey. The TPM directly unseals the full 32-byte master key.
• AuthCombineMode::All: The backend provides FactorContribution::FactorPiece. At enrollment, a random 32-byte piece is sealed (not the master key itself). At unlock, the unsealed piece is contributed to the combined HKDF derivation.

Measured Boot Chain

The security of this backend depends on the integrity of the measured boot chain:

1. UEFI firmware measures itself and boot configuration into PCRs 0-3.
2. Shim / bootloader (GRUB, systemd-boot) is measured by the firmware into PCR 4.
3. Secure Boot state (whether Secure Boot is enabled, which keys are enrolled) is reflected in PCR 7.
4. Kernel and initramfs, if using systemd-stub unified kernel images (UKI), are measured into PCR 11.

If an attacker modifies any component in this chain, the corresponding PCR value changes, and the TPM refuses to unseal the vault key.

Firmware and Kernel Updates

After a firmware or kernel update, PCR values change and the sealed blob becomes invalid. Strategies to manage this:

• Predictive re-sealing. Before a kernel update, predict the new PCR values (using systemd-pcrphase or systemd-measure) and create a second sealed blob for the new values. Delete the old one after successful boot.
• Fallback factor. Always maintain a second enrolled factor (password, SSH agent) so access is not lost when PCR values change unexpectedly.
• PCR selection trade-offs. Excluding volatile PCRs (4, 5, 6) from the policy reduces re-enrollment frequency at the cost of reduced boot integrity coverage.

Platform Binding

The TPM is a physical chip (or firmware TPM) soldered to the motherboard. The sealed blob is bound to that specific TPM – it cannot be moved to another machine. This provides:

• Hardware binding. The vault is tied to a specific physical device.
• Anti-theft. A stolen drive cannot be unlocked on another machine.
• Anti-cloning. TPM private keys cannot be extracted (the TPM is designed to resist physical attacks on the chip package).

Integration Dependencies

The user must have read/write access to /dev/tpmrm0 (typically via the tss group or a udev rule).

Threat Model Considerations

• Evil-maid with matching PCRs. If an attacker can reproduce the exact boot chain (same firmware, same bootloader, same Secure Boot keys), they can unseal the key. Adding a TPM PIN (PolicyAuthValue) mitigates this.
• Firmware TPM (fTPM) vulnerabilities. Firmware TPMs run inside the CPU or chipset firmware. Vulnerabilities in fTPM firmware (e.g., AMD fTPM voltage glitching) can potentially extract sealed data. Discrete TPM chips (e.g., Infineon SLB9670) offer stronger physical resistance.
• Running-system compromise. TPM sealing protects at-rest data. Once the system is booted and the vault is unlocked, an attacker with root access can read the master key from daemon-secrets process memory. TPM does not protect against runtime compromise.
• PCR reset attacks. On some platforms, a hardware reset of the TPM (e.g., via LPC bus manipulation) can reset PCRs to zero. Sealing to PCR 7 (Secure Boot state) partially mitigates this because Secure Boot measurements are replayed from firmware on reset.
• vTPM in virtualized environments. A virtual TPM provides no physical security. The hypervisor can read all sealed data. TPM enrollment in a VM is useful for binding a vault to a specific VM instance, not for hardware-level tamper resistance.

See Also

• Factor Architecture – VaultAuthBackend trait definition and dispatch
• SED/Opal – Drive-level hardware binding (complementary to TPM)
• Policy Engine – Multi-factor combination modes
• FIDO2/WebAuthn – Alternative hardware factor (portable, not platform-bound)

Biometrics Backend

Status: Design Intent. The AuthFactorId::Fingerprint variant exists in core-types::auth and the VaultAuthBackend trait is defined in core-auth::backend, but no struct implements this factor today. This page documents what the backend will do when built, grounded in the trait interface and platform biometric APIs.

The biometrics backend enables vault unlock gated by fingerprint verification (and, in the future, other biometric modalities such as face recognition). It maps to AuthFactorId::Fingerprint (config string "fingerprint"). The critical design principle: biometric data is never used as key material. Biometrics are authentication gates that release a stored key, not secrets from which keys are derived.

Design Principle: Biometrics Are Not Secrets

Biometric features (fingerprint minutiae, facial geometry) are not secret – they can be observed, photographed, or lifted from surfaces. They are also not stable – they vary between readings. For these reasons, the biometrics backend never derives cryptographic key material from biometric data. Instead:

1. At enrollment, the master key (or a KEK) is encrypted and stored on disk.
2. The decryption key for that blob is held in a platform keystore that requires biometric verification to release.
3. At unlock, the platform biometric subsystem verifies the user, and if successful, releases the decryption key to the backend.

The biometric template (the mathematical representation of the fingerprint or face) never leaves the platform biometric subsystem. Open Sesame never sees, stores, or transmits biometric data.

Platform Biometric APIs

Linux: fprintd

On Linux, fingerprint authentication is mediated by fprintd, a D-Bus service that manages fingerprint readers and templates. The authentication flow:

1. The backend calls net.reactivated.Fprint.Device.VerifyStart on the fprintd D-Bus interface.
2. fprintd communicates with the fingerprint sensor hardware via libfprint, acquires a fingerprint image, and matches it against enrolled templates.
3. On match, fprintd emits a VerifyStatus signal with verify-match. On failure, verify-no-match or verify-retry-scan.
4. The backend calls VerifyStop to end the session.

The backend uses the fprintd D-Bus API directly (not PAM) to avoid requiring a full PAM session context.

Future: macOS LocalAuthentication

On macOS (if platform support is added), LocalAuthentication.framework provides Touch ID and Face ID gating of Keychain items. A Keychain item with kSecAccessControlBiometryCurrentSet requires biometric verification before the Keychain releases the stored secret. This maps directly to the “biometric gates release of a stored key” model.

Future: Windows Hello

On Windows, Windows.Security.Credentials.KeyCredentialManager and the Windows Hello biometric subsystem provide similar gating. The TPM-backed key is released only after Windows Hello verification succeeds.

Mapping to VaultAuthBackend

factor_id()

Returns AuthFactorId::Fingerprint.

backend_id()

Returns "fingerprint".

name()

Returns "Fingerprint".

requires_interaction()

Returns AuthInteraction::HardwareTouch. The user must place their finger on the sensor.

is_enrolled(profile, config_dir)

Checks two conditions:

1. An enrollment blob exists at {config_dir}/profiles/{profile}/fingerprint.enrollment.
2. At least one fingerprint is enrolled in fprintd for the current system user (queried via net.reactivated.Fprint.Device.ListEnrolledFingers).

Both must be true. If the system fingerprint enrollment is wiped (user re-enrolled fingers in system settings), the Open Sesame enrollment blob still exists on disk but the platform verification will match against different templates, making it effectively stale.

can_unlock(profile, config_dir)

1. Verify enrollment exists via is_enrolled().
2. Check that fprintd is running (D-Bus name net.reactivated.Fprint is available).
3. Check that at least one fingerprint reader device is present.

D-Bus name lookup and device enumeration complete well within the 100ms trait budget.

enroll(profile, master_key, config_dir, salt, selected_key_index)

1. Verify that fprintd has at least one enrolled fingerprint for the current user. If not, return AuthError::BackendNotApplicable("no fingerprints enrolled in fprintd; enroll via system settings first").
2. Generate a random 32-byte storage key.
3. Wrap master_key under the storage key using AES-256-GCM.
4. Store the storage key in a location protected by biometric gating:
   • Primary strategy (Linux): Store the storage key in the user’s kernel keyring (keyctl) under a session-scoped key. The keyring entry is created with a timeout matching the user session. Biometric verification via fprintd acts as the authorization gate before the backend retrieves the keyring secret at unlock time.
   • Fallback strategy: Encrypt the storage key with a key derived from salt and a device-specific identifier (machine-id). Store the encrypted storage key in the enrollment blob itself. The biometric check acts as the sole authorization gate.
5. Write the enrollment blob to {config_dir}/profiles/{profile}/fingerprint.enrollment.

selected_key_index is unused (there is one biometric subsystem per machine). It is ignored.

unlock(profile, config_dir, salt)

1. Load the enrollment blob.
2. Initiate fingerprint verification via fprintd D-Bus API (VerifyStart).
3. Wait for the VerifyStatus signal. The daemon overlay displays a “scan your fingerprint” prompt.
4. If verification fails (no match, timeout, or sensor error), return AuthError::UnwrapFailed.
5. If verification succeeds, retrieve the storage key from the kernel keyring (primary strategy) or decrypt it from the blob (fallback strategy).
6. Unwrap the master key using the storage key (AES-256-GCM decrypt).
7. Return UnlockOutcome:
   • master_key: the unwrapped 32-byte key.
   • ipc_strategy: IpcUnlockStrategy::DirectMasterKey.
   • factor_id: AuthFactorId::Fingerprint.
   • audit_metadata: {"method": "fprintd", "finger": "<which_finger>"} (if fprintd reports which finger matched).

revoke(profile, config_dir)

1. Remove the storage key from the kernel keyring (if using primary strategy).
2. Delete {config_dir}/profiles/{profile}/fingerprint.enrollment.

Does not remove fingerprints from fprintd – those are system-level enrollments managed by the user outside of Open Sesame.

Enrollment Blob Format

Version: u8 (1)
Storage strategy: u8 (1 = kernel keyring, 2 = embedded encrypted key)
Wrapped master key: 12-byte nonce || ciphertext || 16-byte GCM tag
Embedded encrypted storage key (strategy 2 only): 12-byte nonce || ciphertext || 16-byte tag
Device binding hash: 32 bytes (SHA-256 of machine-id || profile name)

FactorContribution

• AuthCombineMode::Any or AuthCombineMode::Policy: The backend provides FactorContribution::CompleteMasterKey. It unwraps the full master key after biometric verification succeeds.
• AuthCombineMode::All: The backend provides FactorContribution::FactorPiece. A random 32-byte piece (not the master key) is stored behind the biometric gate and contributed to HKDF derivation upon successful verification.

The biometric itself does not contribute entropy – it is a gate. The piece is a random value generated at enrollment time and stored behind the biometric gate.

Liveness Detection

Fingerprint sensors vary in their resistance to spoofing:

Open Sesame delegates liveness detection entirely to the sensor hardware and fprintd. The backend does not attempt its own liveness checks. Deployment guidance: use capacitive or ultrasonic sensors for security-sensitive configurations, and combine biometric with a second factor via AuthCombineMode::Policy.

Privacy Guarantees

1. No template storage. Open Sesame never stores, transmits, or processes biometric templates. Templates are managed exclusively by fprintd (stored in /var/lib/fprint/).
2. No template access. The backend never requests raw biometric data or template bytes. It uses only the verify/match API, which returns a boolean result.
3. No cross-profile linkability. The enrollment blob contains no biometric information. An attacker who obtains the blob cannot determine whose fingerprint unlocks the vault.
4. User-controlled deletion. Revoking the backend deletes only the encrypted key blob. Biometric templates remain under user control in fprintd.

Integration Dependencies

Threat Model Considerations

• Biometric spoofing. The backend is only as spoof-resistant as the sensor hardware. It should not be the sole factor for high-value vaults. Combining biometric with password or FIDO2 via AuthCombineMode::Policy is recommended.
• Stolen enrollment blob. The blob is useless without passing biometric verification (primary strategy) or without the device-specific derivation inputs (fallback strategy). The biometric gate is the critical protection.
• fprintd compromise. If an attacker can inject false D-Bus responses (by compromising fprintd or the user’s D-Bus session), they can bypass biometric verification. Running fprintd as a system service (not user session) and using D-Bus mediation via AppArmor or SELinux mitigates this.
• Irrevocable biometrics. If a fingerprint is compromised (lifted from a surface), the user cannot change their fingerprint. Mitigation: re-enroll with a different finger and revoke the old enrollment, or add a second factor requirement via policy.
• Fallback strategy weakness. The embedded-key fallback strategy protects the storage key only with device-specific derivation (machine-id + salt). An attacker with the enrollment blob and knowledge of the machine-id can bypass the biometric gate entirely. The primary strategy (kernel keyring) is strongly preferred.

See Also

• Factor Architecture – VaultAuthBackend trait definition and dispatch
• FIDO2/WebAuthn – Roaming authenticator with on-device biometric UV
• Policy Engine – Combining biometric with other factors

Hardware Tokens Backend (YubiKey / Smart Cards / PIV)

Status: Design Intent. The AuthFactorId::Yubikey variant exists in core-types::auth and the VaultAuthBackend trait is defined in core-auth::backend, but no struct implements this factor today. This page documents what the backend will do when built, grounded in the trait interface and relevant smart card standards.

The hardware tokens backend enables vault unlock using YubiKeys, PIV smart cards, and PKCS#11-compatible cryptographic tokens. It maps to AuthFactorId::Yubikey (config string "yubikey"). Despite the enum variant name referencing YubiKey specifically, the backend is designed to support the broader category of challenge-response and certificate-based hardware tokens.

This backend covers the non-FIDO2 capabilities of these devices. For FIDO2/CTAP2 operation, see the FIDO2/WebAuthn backend.

Supported Protocols

PIV (FIPS 201 / NIST SP 800-73)

Personal Identity Verification is a US government standard for smart card authentication. PIV cards (and YubiKeys with the PIV applet) contain X.509 certificates and corresponding private keys in hardware slots. The private key never leaves the card.

PIV slots relevant to Open Sesame:

Slot 9d (Key Management) is the natural fit for vault unlock – it is designed for key agreement and encryption operations, has a reasonable PIN policy (once per session), and supports touch policy configuration.

HMAC-SHA1 Challenge-Response (YubiKey Slot 2)

YubiKeys support HMAC-SHA1 challenge-response in their OTP applet (slots 1 and 2). The host sends a challenge, the YubiKey computes HMAC-SHA1 with a pre-programmed 20-byte secret, and returns the 20-byte response. This is the same mechanism used by ykman and ykchalresp.

Slot 2 (long press) is conventionally used for challenge-response to avoid conflicts with slot 1 (short press, often configured for OTP).

PKCS#11

PKCS#11 is the generic smart card interface. Any token with a PKCS#11 module (OpenSC, YubiKey YKCS11, Nitrokey, etc.) can be used. The backend loads the PKCS#11 shared library, finds a suitable private key object, and performs a sign or decrypt operation.

Mapping to VaultAuthBackend

factor_id()

Returns AuthFactorId::Yubikey.

backend_id()

Returns "yubikey".

name()

Returns "Hardware Token".

requires_interaction()

Returns AuthInteraction::HardwareTouch if the enrolled token has a touch policy enabled. Returns AuthInteraction::PasswordEntry if the token requires a PIN but no touch. The interaction type is recorded in the enrollment blob and returned by this method.

Most configurations require touch (physical presence), so HardwareTouch is the common case.

is_enrolled(profile, config_dir)

Checks whether {config_dir}/profiles/{profile}/yubikey.enrollment exists and contains a valid enrollment blob.

can_unlock(profile, config_dir)

1. Verify enrollment exists.
2. Based on the enrolled protocol:
   • HMAC-SHA1: Enumerate USB HID devices matching YubiKey vendor/product IDs.
   • PIV/PKCS#11: Attempt to open a PCSC connection and verify that a card is present in a reader.
3. Return true if a device is detected.

No cryptographic operation is performed (must stay within 100ms).

enroll(profile, master_key, config_dir, salt, selected_key_index)

The enrollment path depends on the protocol. The backend auto-detects the preferred protocol based on the connected device, or the user specifies via configuration.

HMAC-SHA1 Path

1. Enumerate connected YubiKeys. If selected_key_index is Some(i), select the i-th device.
2. Issue a challenge-response using salt as the challenge (hashed to fit the challenge length if needed).
3. The YubiKey returns a 20-byte HMAC-SHA1 response.
4. Derive a 32-byte KEK from the HMAC response using HKDF-SHA256: KEK = HKDF-SHA256(ikm=hmac_response, salt=salt, info="open-sesame:yubikey:{profile}").
5. Wrap master_key under the KEK using AES-256-GCM.
6. Store the enrollment blob with the YubiKey serial number, slot number, and wrapped master key.

PIV Path

1. Open a PCSC connection to the smart card.
2. Select the PIV applet (AID A0 00 00 03 08).
3. Authenticate to the card (PIN prompt if required by slot policy).
4. Read the certificate from the selected slot (default: 9d).
5. Generate a random 32-byte challenge.
6. Encrypt the challenge using the public key from the certificate (RSA-OAEP or ECDH depending on key type).
7. Derive a KEK: KEK = HKDF-SHA256(ikm=challenge, salt=salt, info="open-sesame:piv:{profile}").
8. Wrap master_key under the KEK.
9. Store the enrollment blob with the certificate fingerprint (SHA-256), slot number, encrypted challenge, and wrapped master key.

PKCS#11 Path

Follows the PIV path but uses the PKCS#11 API (C_FindObjects, C_Decrypt / C_Sign) instead of raw APDU commands. The enrollment blob additionally stores the PKCS#11 module path and token serial number.

unlock(profile, config_dir, salt)

HMAC-SHA1 Path

1. Load enrollment blob.
2. Issue challenge-response with salt as the challenge.
3. Derive KEK from the HMAC response (same HKDF as enrollment).
4. Unwrap master key. If unwrap fails (different YubiKey or different slot 2 secret), return AuthError::UnwrapFailed.

PIV Path

1. Load enrollment blob, including the encrypted challenge.
2. Open PCSC connection, select PIV applet, authenticate (PIN if required).
3. Decrypt the encrypted challenge using the card’s private key (slot 9d).
4. Derive KEK from the decrypted challenge (same HKDF as enrollment).
5. Unwrap master key.

Common Outcome

Return UnlockOutcome:

• master_key: the unwrapped 32-byte key.
• ipc_strategy: IpcUnlockStrategy::DirectMasterKey.
• factor_id: AuthFactorId::Yubikey.
• audit_metadata: {"protocol": "hmac-sha1|piv|pkcs11", "serial": "<device_serial>", "slot": "<slot>"}.

revoke(profile, config_dir)

Delete {config_dir}/profiles/{profile}/yubikey.enrollment. Does not modify the token itself (the HMAC secret or PIV keys remain on the device).

Enrollment Blob Format

Version: u8 (1)
Protocol: u8 (1 = HMAC-SHA1, 2 = PIV, 3 = PKCS#11)
Device serial: length-prefixed UTF-8
Slot/key identifier: length-prefixed UTF-8
Interaction type: u8 (maps to AuthInteraction variant)
--- Protocol-specific fields ---
[HMAC-SHA1]
  Wrapped master key: 12-byte nonce || ciphertext || 16-byte GCM tag
[PIV]
  Certificate fingerprint: 32 bytes (SHA-256)
  Encrypted challenge: length-prefixed bytes
  Wrapped master key: 12-byte nonce || ciphertext || 16-byte GCM tag
[PKCS#11]
  Module path: length-prefixed UTF-8
  Token serial: length-prefixed UTF-8
  Certificate fingerprint: 32 bytes
  Encrypted challenge: length-prefixed bytes
  Wrapped master key: 12-byte nonce || ciphertext || 16-byte GCM tag

FactorContribution

• AuthCombineMode::Any or AuthCombineMode::Policy: The backend provides FactorContribution::CompleteMasterKey. It independently unwraps the full master key.
• AuthCombineMode::All: The backend provides FactorContribution::FactorPiece. For HMAC-SHA1, the HKDF output derived from the HMAC response is the piece (32 bytes). For PIV, the decrypted challenge is the piece. The piece is contributed to the combined HKDF derivation.

Touch Requirement for Physical Presence

YubiKeys and some smart cards support a touch policy: the device requires the user to physically touch a contact sensor before performing a cryptographic operation. This provides proof of physical presence, mitigating malware that silently uses the token while plugged in.

The backend records the touch policy in the enrollment blob so that requires_interaction() returns the correct AuthInteraction variant. The daemon overlay displays a “touch your key” prompt when AuthInteraction::HardwareTouch is indicated.

HMAC-SHA1 Key Derivation Detail

The HMAC-SHA1 response is only 20 bytes, insufficient for a 32-byte AES key directly. The HKDF-SHA256 expansion step stretches this to 32 bytes:

• The HMAC-SHA1 secret on the YubiKey is 20 bytes (160 bits), programmed at configuration time.
• The challenge (vault salt) is up to 64 bytes.
• The 20-byte HMAC output has at most 160 bits of entropy.
• HKDF’s security bound is min(input_entropy, hash_output_length) = 160 bits, which exceeds the 128-bit security target for the derived 256-bit KEK.

Integration Dependencies

Threat Model Considerations

• HMAC-SHA1 secret extraction. The HMAC secret on a YubiKey cannot be read back after programming. Extracting it requires destructive chip analysis.
• PIN brute-force. PIV PINs have a retry counter (default 3 attempts before lockout). After lockout, the PUK (PIN Unlock Key) is required. After PUK lockout, the PIV applet must be reset (destroying all keys).
• Token loss. If the token is lost, the enrollment blob is useless without the physical device. Recovery requires an alternative enrolled factor.
• Relay attacks (HMAC-SHA1). HMAC-SHA1 challenge-response over USB HID can be relayed over a network. Touch policy (set to “always”) mitigates this by requiring physical presence.
• Relay attacks (PIV). Smart card operations over PCSC can be relayed using tools like virtualsmartcard. Touch policy on YubiKey PIV mitigates this.
• SHA-1 and HMAC-SHA1. HMAC-SHA1 is not affected by SHA-1 collision attacks. HMAC security depends on the PRF property of the compression function, not collision resistance. HMAC-SHA1 remains secure for key derivation.

See Also

• Factor Architecture – VaultAuthBackend trait definition and dispatch
• FIDO2/WebAuthn – FIDO2 mode of the same hardware (different protocol)
• TPM – Platform-bound hardware factor (non-portable)
• Policy Engine – Multi-factor combination modes

Self-Encrypting Drive (SED) / TCG Opal Backend

Status: Design Intent. No AuthFactorId variant exists for SED/Opal today. This backend is a future extension that would require adding an AuthFactorId::SedOpal variant to core-types::auth. The VaultAuthBackend trait in core-auth::backend defines the interface it would implement. This page documents the design intent.

The SED/Opal backend enables vault unlock by binding the master key to a Self-Encrypting Drive’s hardware encryption using the TCG Opal 2.0 specification. The drive’s encryption controller holds the key material, accessible only after the drive is unlocked with the correct credentials. This provides protection against physical drive theft without relying on software-layer full-disk encryption.

Relevant Standards

Core Concept: Drive-Bound Vault Keys

A Self-Encrypting Drive transparently encrypts all data written to it using a Media Encryption Key (MEK) stored in the drive controller. The MEK is wrapped by a Key Encryption Key (KEK) derived from the user’s authentication credential. Without the correct credential, the MEK cannot be unwrapped and the drive contents are cryptographically inaccessible.

The SED/Opal backend leverages this mechanism for vault key storage:

1. At enrollment, the backend stores the vault master key within an Opal locking range’s DataStore table. The locking range is protected by an Opal credential that the backend manages.
2. At unlock, the backend authenticates to the Opal Security Provider (SP) using the stored credential, reads the master key from the DataStore, and provides it to daemon-secrets.

Locking Range Architecture

Opal drives support multiple locking ranges. The backend uses a dedicated locking range for Open Sesame, separate from the global locking range (which may be used for full-disk encryption by the OS):

• Global Range (Range 0): Managed by the OS or firmware for full-disk encryption (e.g., sedutil-cli, BitLocker, systemd-cryptenroll).
• Dedicated Range (Range N): A small range allocated for Open Sesame DataStore usage. Contains only the encrypted vault master key blob.

If a dedicated range cannot be allocated (drive does not support multiple ranges, or all ranges are in use), the backend falls back to storing the wrapped key in the DataStore table associated with the Admin SP.

Mapping to VaultAuthBackend

factor_id()

Returns AuthFactorId::SedOpal (to be added to the enum).

backend_id()

Returns "sed-opal".

name()

Returns "Self-Encrypting Drive".

requires_interaction()

Returns AuthInteraction::None. SED unlock is non-interactive. The backend authenticates to the drive controller programmatically using a credential derived from device-specific secrets, not a user-entered password.

is_enrolled(profile, config_dir)

Checks whether {config_dir}/profiles/{profile}/sed-opal.enrollment exists and contains a valid enrollment blob identifying the drive (serial number, locking range, and Opal credential reference).

can_unlock(profile, config_dir)

1. Verify enrollment exists.
2. Identify the enrolled drive by serial number.
3. Check that the drive is present and accessible (block device exists or can be found by serial via sysfs).
4. Return true if the drive is present.

Does not attempt Opal authentication (may exceed 100ms and may trigger lockout counters on failure).

enroll(profile, master_key, config_dir, salt, selected_key_index)

1. Enumerate Opal-capable drives by sending TCG Discovery 0 to each block device.
2. If selected_key_index is Some(i), select the i-th drive. Otherwise select the first Opal-capable drive.
3. Authenticate to the drive’s Admin SP using the SID (Security Identifier) or a pre-configured admin credential.
4. Allocate or identify a locking range for Open Sesame use.
5. Generate a random Opal credential for the locking range (or derive one from salt and a device-specific secret).
6. Store the vault master_key in the DataStore table of the locking range.
7. Lock the range, binding it to the generated credential.
8. Write the enrollment blob to {config_dir}/profiles/{profile}/sed-opal.enrollment containing the drive serial, locking range index, and the Opal credential (encrypted under a key derived from salt and the machine ID).

unlock(profile, config_dir, salt)

1. Load the enrollment blob.
2. Derive the Opal credential (decrypt using salt and machine ID).
3. Open a session to the drive’s Locking SP.
4. Authenticate with the credential.
5. Read the master key from the DataStore table.
6. Return UnlockOutcome:
   • master_key: the 32-byte key read from the DataStore.
   • ipc_strategy: IpcUnlockStrategy::DirectMasterKey.
   • factor_id: AuthFactorId::SedOpal.
   • audit_metadata: {"drive_serial": "<serial>", "locking_range": "<N>"}.

revoke(profile, config_dir)

1. Authenticate to the drive’s Admin SP.
2. Erase the master key from the DataStore table (overwrite with zeros).
3. Optionally release the locking range allocation.
4. Delete {config_dir}/profiles/{profile}/sed-opal.enrollment.

Enrollment Blob Format

Version: u8 (1)
Drive serial: length-prefixed UTF-8
Drive model: length-prefixed UTF-8
Block device path at enrollment time: length-prefixed UTF-8 (informational; may change)
Locking range index: u16
Opal credential (encrypted): 12-byte nonce || ciphertext || 16-byte GCM tag
Machine binding hash: 32 bytes (SHA-256 of machine-id, used in credential derivation)

FactorContribution

• AuthCombineMode::Any or AuthCombineMode::Policy: The backend provides FactorContribution::CompleteMasterKey. The drive hardware releases the full master key from the DataStore.
• AuthCombineMode::All: The backend provides FactorContribution::FactorPiece. A random 32-byte piece (not the master key) is stored in the DataStore and contributed to combined HKDF derivation.

Pre-Boot Authentication

TCG Opal defines a Pre-Boot Authentication (PBA) mechanism: a small region of the drive (the Shadow MBR) is presented to the BIOS/UEFI before the main OS boots. The PBA image authenticates the user and unlocks the drive before the OS sees the encrypted data.

Open Sesame does not implement PBA. It operates entirely within the running OS. If the drive is locked at boot by system-level SED management, Open Sesame assumes the drive is already unlocked by the time daemon-secrets starts. The backend uses Opal only for its DataStore facility (key storage with hardware-gated access), not for drive-level boot locking.

Integration Dependencies

Privilege Requirements

Opal commands require raw SCSI/ATA/NVMe command passthrough, which typically requires root or CAP_SYS_RAWIO. Since daemon-secrets runs as a system service, this is consistent with its privilege model. Enrollment and revocation also require admin-level Opal credentials (SID or Admin1 authority).

Threat Model

Protects Against

• Physical drive theft. An attacker who steals the drive (but not the machine) cannot access the vault master key. The DataStore contents are encrypted by the drive’s MEK, inaccessible without the Opal credential.
• Offline forensic imaging. Imaging the raw drive platters or flash chips yields only ciphertext.
• Cold boot on different hardware. Moving the drive to another machine does not help because the Opal credential is derived from the original machine’s identity.

Does Not Protect Against

• Running-system compromise. Once the OS is booted and the drive is unlocked, an attacker with root access can read the DataStore contents. SED encryption is transparent to the running OS after unlock.
• DMA attacks. An attacker with physical access to the running machine can use DMA (e.g., via Thunderbolt or FireWire) to read memory containing the unlocked master key.
• SED firmware vulnerabilities. Research has demonstrated that some SED implementations have firmware bugs allowing bypass of Opal locking without the credential (e.g., the 2018 Radboud University disclosure affecting Crucial and Samsung drives). The backend cannot detect or mitigate firmware-level flaws.
• Evil-maid with machine access. If the attacker has access to the original machine (not just the drive), they can boot the machine, wait for the drive to be unlocked by the OS, and extract the master key.

Complementary Use with TPM

SED/Opal and TPM provide complementary hardware binding:

• TPM binds the vault to the boot integrity state (firmware, bootloader, Secure Boot policy). Protects against software-level boot chain tampering.
• SED/Opal binds the vault to the physical drive. Protects against drive theft.

Using both factors in AuthCombineMode::All provides defense in depth: the vault is bound to both the machine’s boot state and the specific physical drive.

See Also

• Factor Architecture – VaultAuthBackend trait definition and dispatch
• TPM – Complementary platform-binding factor
• Policy Engine – Combining SED with other factors

Federation Factors

Status: Design Intent. No AuthFactorId variant or VaultAuthBackend implementation exists for federation today. Federation is a future capability that builds on top of the existing factor backends. This page documents the design intent for cross-device factor delegation.

Federation factors allow a user to satisfy an authentication factor on one device and have that satisfaction count toward unlocking a vault on a different device. This enables scenarios such as unlocking a headless server’s vault using a phone’s fingerprint sensor, or centrally managing vault unlock across a fleet of machines via an HSM.

Core Concepts

Factor Delegation

Factor delegation separates where a factor is satisfied from where the vault is unlocked:

• Origin device: The device where the user physically performs authentication (touches a FIDO2 key, scans a fingerprint, enters a password).
• Target device: The device where the vault resides and where daemon-secrets runs.
• Delegation token: A cryptographic proof that a specific factor was satisfied on the origin device, valid for a bounded time and scope.

The delegation token does not contain the master key. It is an authorization proof that daemon-secrets on the target device accepts in lieu of direct local factor satisfaction.

Trust Chain

Federation introduces a multi-hop trust chain:

Device Attestation -> Factor Proof -> Delegation Token -> Vault Unlock

1. Device attestation. The origin device proves its identity and integrity to the target device. This may use TPM remote attestation, a pre-shared device certificate, or a Noise IK session where the origin device’s static public key is pre-enrolled.
2. Factor proof. The origin device satisfies a factor locally (e.g., fingerprint verification via fprintd) and produces a signed statement: “factor F was satisfied by user U at time T on device D.”
3. Delegation token. The factor proof is wrapped into a delegation token that specifies the target vault, permitted operations, expiration time, and scope restrictions.
4. Vault unlock. The target device’s daemon-secrets receives the delegation token, verifies the full chain (device identity, factor proof signature, token validity, scope), and uses it to authorize the unlock.

Delegation Token Structure

Version: u8 (1)
Token ID: 16 bytes (random, for revocation and audit)
Origin device ID: 32 bytes (public key fingerprint or device certificate hash)
Factor ID: AuthFactorId (which factor was satisfied)
Factor proof signature: length-prefixed bytes (signed by origin device's attestation key)
Timestamp: u64 (Unix epoch seconds when factor was satisfied)
Expiry: u64 (Unix epoch seconds when token becomes invalid)
Target vault: length-prefixed UTF-8 (profile name on target device)
Scope: DelegationScope (see below)
Token signature: length-prefixed bytes (signed by origin device's delegation key)

DelegationScope

Delegation tokens carry explicit scope restrictions that limit what the token can authorize:

#![allow(unused)]
fn main() {
struct DelegationScope {
    /// Which operations the token authorizes.
    allowed_operations: Vec<DelegatedOperation>,
    /// Maximum number of times the token can be used (None = unlimited within expiry).
    max_uses: Option<u32>,
    /// If set, token is only valid from these source IP addresses.
    source_addresses: Option<Vec<IpAddr>>,
}

enum DelegatedOperation {
    /// Unlock the vault (read access to secrets).
    VaultUnlock,
    /// Unlock and modify secrets.
    VaultUnlockWrite,
    /// Unlock a specific secret by path.
    SecretAccess(String),
}
}

Scope Narrowing

A delegation token can only have equal or narrower scope than the factor it represents. Scope narrowing is enforced at token creation time:

• A password factor with full vault access can delegate a token that only unlocks specific secrets.
• A biometric factor can delegate a token valid for 5 minutes instead of the session duration.
• A FIDO2 factor can delegate a token restricted to a single use.

Scope can never be widened. A token scoped to SecretAccess("/ssh/id_ed25519") cannot be used to unlock the entire vault.

Relationship to VaultAuthBackend

Federation does not implement VaultAuthBackend directly. Instead, it wraps existing backends:

1. On the origin device, a standard VaultAuthBackend (fingerprint, FIDO2, password, etc.) performs the actual authentication.
2. The origin device’s federation service creates a delegation token signed with the device’s attestation key.
3. On the target device, a FederationReceiver component (a new daemon component, not a VaultAuthBackend) validates the token and translates it into an internal unlock authorization.

The target device’s daemon-secrets treats a validated delegation token as equivalent to a local factor satisfaction for policy evaluation purposes. If the vault’s AuthCombineMode::Policy requires AuthFactorId::Fingerprint, a delegation token proving fingerprint satisfaction on a trusted origin device satisfies that requirement.

IPC Flow

Origin Device                          Target Device
─────────────                          ─────────────
User touches fingerprint sensor
    |
    v
FingerprintBackend.unlock() succeeds
    |
    v
FederationService creates
  delegation token
    |
    v
Noise IK session ──────────────────>  FederationReceiver
                                           |
                                           v
                                      Verify device attestation
                                      Verify factor proof signature
                                      Check token expiry and scope
                                           |
                                           v
                                      daemon-secrets accepts
                                      factor as satisfied
                                           |
                                           v
                                      Policy engine evaluates
                                      (may need more factors)
                                           |
                                           v
                                      Vault unlocked (if policy met)

FactorContribution

Federation does not change the FactorContribution type of the underlying factor. If the delegated factor provides FactorContribution::CompleteMasterKey locally, the delegation token authorizes release of the same master key on the target device (which must have its own wrapped copy from a prior enrollment of that factor type).

In AuthCombineMode::All, federation cannot provide a FactorPiece remotely because the piece must be combined locally with other pieces on the target device. Federation in All mode requires the origin device to contribute its piece to a multi-party key derivation protocol. This is deferred to a future design iteration (see Open Questions).

Use Cases

Unlock Server Vault from Phone

A developer manages secrets on a headless server. The server vault requires fingerprint + password (AuthCombineMode::Policy, both required). The developer:

1. Scans a fingerprint on their phone (origin device).
2. The phone creates a delegation token for the server vault, scoped to VaultUnlock, expiring in 60 seconds.
3. The token is sent to the server over a Noise IK session (phone’s static public key is pre-enrolled on the server).
4. The server’s daemon-secrets accepts the fingerprint factor as satisfied.
5. The developer enters a password directly on the server (or via SSH).
6. Both policy requirements are met; the vault unlocks.

Fleet Unlock via Central HSM

An organization operates a fleet of machines, each with a vault. A central HSM holds a master delegation key. An administrator:

1. Authenticates to the HSM management interface (FIDO2 + password).
2. The HSM creates delegation tokens for a set of target machines, each scoped to VaultUnlock, expiring in 5 minutes.
3. Tokens are distributed to target machines via the management plane.
4. Each machine’s daemon-secrets validates the token against the HSM’s pre-enrolled public key.
5. Vaults unlock. The HSM never sees the vault master keys.

Emergency Break-Glass

A break-glass procedure for when normal factors are unavailable:

1. An administrator authenticates to a break-glass service using a hardware token.
2. The service creates a single-use delegation token (max_uses: 1) for the target vault.
3. The token is transmitted to the target device.
4. The vault unlocks once. The token is consumed and cannot be reused.
5. All break-glass events are audit-logged with the token ID, origin device, and administrator identity.

Remote Attestation

Before a target device accepts a delegation token, it must verify that the origin device is trustworthy. Remote attestation provides this assurance.

Device Identity

Each device in the federation has a long-lived identity key pair. The public key is enrolled on peer devices during a setup ceremony. Options for the identity key:

• TPM-backed key. The device’s TPM generates a non-exportable attestation key. The public portion is enrolled on peers. This proves the origin device has not been cloned.
• Noise IK static keypair. The existing Open Sesame Noise IK transport provides mutual authentication. The origin device’s static public key is already known to the target device from IPC bus enrollment.
• X.509 certificate. A CA-issued device certificate, validated against a pinned CA public key. Suitable for organizational deployments with existing PKI.

Platform State Attestation

Optionally, the origin device can include a TPM quote (signed PCR values) in the delegation token, proving its boot integrity at the time of factor satisfaction. The target device verifies the quote against a known-good PCR policy. This prevents a compromised origin device from generating fraudulent factor proofs.

Time-Bounded Delegation Tokens

All delegation tokens have mandatory expiration:

• Minimum expiry: 10 seconds (prevents creation of tokens that expire before delivery).
• Maximum expiry: Configurable per-vault, default 300 seconds (5 minutes). Longer durations increase the window for token theft and replay.
• Clock skew tolerance: 30 seconds. The target device accepts tokens where now - 30s <= timestamp <= now + 30s and now <= expiry + 30s.

Token expiry is checked at the target device at time of use. A token that was valid when created but has since expired is rejected. There is no renewal mechanism; a new factor satisfaction and new token are required.

Replay Prevention

Each token has a unique random 16-byte ID. The target device maintains a set of consumed token IDs (in memory, persisted to disk for crash recovery). A token ID that has been seen before is rejected, even if the token has not expired.

The consumed-ID set is pruned of entries older than max_expiry + clock_skew_tolerance to bound memory usage.

Security Considerations

• Token theft. A stolen delegation token can be used by an attacker within its validity window and scope. Mitigations: short expiry, single-use tokens (max_uses: 1), source address restrictions, and Noise IK transport encryption (tokens are never sent in plaintext).
• Origin device compromise. If the origin device is compromised, an attacker can generate arbitrary delegation tokens. Mitigations: TPM-backed attestation keys (attacker cannot extract the signing key without hardware attack), platform state attestation (compromised boot state is detected), and administrative revocation of the device’s enrollment on all target devices.
• Target device compromise. If the target device is already compromised, delegation tokens are irrelevant – the attacker already has access to the running system. Federation does not increase or decrease the attack surface of a compromised target.
• Network partition. If origin and target devices cannot communicate directly, the token must be relayed through an intermediary. The token’s cryptographic signatures ensure integrity regardless of the relay path, but relay latency may cause expiry. Pre-generating tokens with longer expiry is an option for intermittently-connected environments.
• Scope escalation. The scope narrowing invariant (delegation can only narrow, never widen) is enforced at token creation on the origin device and verified at the target device. A malicious origin device could create a token with any scope up to the full permissions of the delegated factor – this is inherent to the delegation model. Trust in the origin device is a prerequisite for accepting its tokens.

Open Questions

• AuthCombineMode::All support. Federation in All mode requires multi-party key derivation where the origin device contributes its piece without revealing the combined master key. Threshold secret sharing or secure multi-party computation protocols may be needed.
• Token revocation broadcast. How does a target device learn that a token has been revoked before its natural expiry? Options include a revocation list pushed via the management plane, or making tokens short-lived enough that revocation is unnecessary.
• Multi-hop delegation. Can device A delegate to device B, which then re-delegates to device C? The current design does not support transitive delegation. Each token is signed by the origin device and validated against that device’s enrolled key directly.
• Offline token pre-generation. For air-gapped environments, tokens may need to be generated in advance with longer validity. This increases the theft window and requires careful scope restriction.

See Also

• Factor Architecture – VaultAuthBackend trait definition and dispatch
• Policy Engine – How delegated factors interact with AuthCombineMode
• Biometrics – Common delegation source (phone fingerprint)
• TPM – Remote attestation for device identity

Window Manager Daemon

The daemon-wm process implements a Wayland overlay window switcher with Vimium-style letter hints, application launching, and inline vault unlock. It runs as a single-threaded tokio process (current_thread runtime) connected to the IPC bus as a BusClient.

Controller State Machine

The OverlayController (controller.rs) is the single owner of all overlay state, timing, and decisions. The main loop feeds events in, executes the returned Command list, and does nothing else. The controller never performs I/O directly.

Phases

The controller tracks a Phase enum with the following variants:

• Idle – Nothing happening. No overlay visible, no timers running.
• Armed – Border visible, keyboard exclusive mode acquired via layer-shell. The picker is not yet visible. The controller waits for either modifier release (quick-switch) or dwell timeout (transition to Picking). Carries entered_at: Instant, selection: usize, input: String, dwell_ms: u32, and an optional PendingLaunch.
• Picking – Full picker visible. The user is browsing the window list or typing hint characters. Carries the same Snapshot, selection, input, and optional PendingLaunch.
• Launching – An application launch request has been sent to daemon-launcher via IPC. The overlay displays a status indicator while waiting for the response.
• LaunchError – A launch failed. The overlay shows an error toast. Any keystroke dismisses.
• Unlocking – Vault unlock in progress. Contains profiles_to_unlock, current_index, password_len, unlock_mode (one of AutoAttempt, WaitingForTouch, Password, Verifying), and the original launch command for retry after unlock.

Events

The controller accepts the following Event variants: