Security Model

Understand how Vouch secures your credentials from hardware key to cloud service

Vouch brokers the most sensitive credentials in a developer’s stack: SSH certificates, AWS STS tokens, GitHub installation tokens, and container registry passwords. This page explains exactly how those credentials are protected at every layer.

Data flow

Every Vouch credential follows the same path from hardware key to cloud service:

YubiKey (FIDO2)
  → Vouch CLI (local machine)
    → Vouch Server (validates assertion, issues session)
      → External service (AWS STS / GitHub / SSH CA)
        → Short-lived credential returned to CLI
          → Tool uses credential (aws, ssh, git, docker)

1. FIDO2 assertion – The YubiKey signs a challenge using a private key that never leaves the hardware. The assertion includes origin binding (preventing phishing) and user verification (PIN + touch).
2. Session issuance – The Vouch server validates the signed assertion against the enrolled public key and issues a session token valid for 8 hours.
3. Credential exchange – When a tool needs a credential, the CLI exchanges the session token for a service-specific credential (STS AssumeRoleWithWebIdentity, SSH certificate signing, GitHub App installation token, etc.).
4. Tool consumption – The tool receives the short-lived credential and uses it normally. The credential expires on its own – there is nothing to revoke or rotate.

Credential lifecycle

All Vouch credentials share these properties:

Because credentials are never written to disk, they cannot be exfiltrated by malware scanning ~/.aws/credentials, ~/.ssh/, or environment variables.

Trust boundaries

Vouch operates across three trust boundaries:

1. Hardware key (YubiKey)

• Private key material is generated on the YubiKey and never exported.
• FIDO2 assertions are origin-bound – the key will not sign challenges from phishing domains.
• User verification requires both a PIN and a physical touch.

2. Local machine (CLI + Agent)

• The Vouch agent runs as a user-level process and holds session material in memory.
• Communication between the CLI and agent uses a Unix domain socket with filesystem permissions restricting access to the owning user.
• No credentials are persisted to disk. If the agent process stops, sessions must be re-established with a new vouch login.

3. Vouch server

• The server validates FIDO2 assertions and issues signed OIDC tokens (ES256 over P-256).
• Signing keys (OIDC ES256 and SSH CA Ed25519) are managed by AWS KMS — the server delegates signing operations and never holds private key material.
• The server does not store AWS credentials, SSH private keys, or GitHub tokens. It acts as an identity broker, not a secrets vault.
• Communication between CLI and server uses TLS 1.3.

Threat model

For the complete STRIDE-based threat analysis — including threat actors, trust boundaries, assumptions, structured threat statements, and mitigations — see the dedicated Threat Model page.

Encryption

In transit

All communication between the Vouch CLI and server uses TLS 1.3. The FIDO2 assertion is transmitted over this encrypted channel.

At rest

Vouch does not store credentials at rest. The server stores:

• Enrolled public keys – The FIDO2 public key registered during enrollment. This is not sensitive (it cannot be used to impersonate the user).
• User metadata – Email address, organization membership, and enrollment status.
• Audit logs – Records of authentication events and credential issuance.

No AWS credentials, SSH keys, or GitHub tokens are stored on the server.

User data and metadata are protected with document-level encryption using HPKE (RFC 9180) with DHKEM(P-384), HKDF-SHA384, and AES-256-GCM. Each document is encrypted individually with its own encapsulated key — the encryption is bound to the document type and ID, preventing ciphertext relocation. The document encryption key pair is generated via AWS KMS (GenerateDataKeyPairWithoutPlaintext), and the private key is only decrypted at server startup using a KMS key with NitroTPM attestation (when available), ensuring the plaintext private key is only recoverable on attested EC2 instances.

Blind equality indexes (for lookups by email, etc.) use HMAC-SHA256 with a KMS-managed key, so the database never contains plaintext identifiers.

FIDO2 security properties

Vouch uses FIDO2/WebAuthn for all user authentication. Key security properties:

• Origin binding – The authenticator (YubiKey) includes the relying party ID in the signed assertion. If an attacker stands up a phishing site at a different domain, the assertion will not validate against the Vouch server.
• Hardware key storage – The private key is generated on the YubiKey’s secure element and cannot be extracted, cloned, or backed up.
• User verification – Every assertion requires the user’s PIN and a physical touch of the key, providing two-factor authentication in a single gesture.
• Replay protection – Each assertion includes a signature counter that the server tracks. Replayed assertions are rejected.

OAuth 2.0 security architecture

FIDO2 proves the human is present. The OAuth 2.0 layer protects everything after — how the CLI identifies itself, how authorization requests are transmitted, and how tokens are bound to the device that requested them. Together, these form a FAPI 2.0 Security Profile.

No shared secrets. The CLI generates its own key pair and registers with the server automatically (RFC 7591). Client authentication uses private_key_jwt (RFC 7523) — there is no client secret to extract from a binary or config file.

Protected authorization requests. Authorization parameters are sent directly to the server over a back-channel (RFC 9126) and signed as JWTs (RFC 9101). The browser redirect carries only an opaque reference — nothing sensitive in URLs, browser history, or referrer headers.

Sender-constrained tokens. Every access token is bound to the CLI’s key pair via DPoP (RFC 9449). A stolen token cannot be used from a different machine.

Audience-restricted tokens. Each token includes a resource indicator (RFC 8707) restricting it to a specific service. A token issued for AWS cannot be presented to GitHub.

Supply chain security

SLSA provenance

Vouch release binaries are built with SLSA Level 3 provenance. Each release includes a provenance attestation that you can verify:

slsa-verifier verify-artifact vouch-linux-amd64 \
  --provenance-path vouch-linux-amd64.intoto.jsonl \
  --source-uri github.com/vouch-sh/vouch

This confirms the binary was built from the expected source repository using a tamper-resistant build process.

SHA256 checksums

Every release includes a checksums.txt file. Verify downloaded binaries:

sha256sum --check checksums.txt

Package manager verification

When installed via Homebrew, APT, or DNF, package signatures are verified automatically by the package manager using Vouch’s published GPG key.

Shared responsibility

Vouch’s responsibilities

• Secure the server infrastructure and FIDO2 registration data.
• Issue credentials with minimum necessary lifetime and scope.
• Provide SLSA-attested builds and signed packages.
• Revoke sessions when triggered by SCIM de-provisioning.
• Maintain audit logs of all authentication and credential issuance events.

Your responsibilities

• Protect YubiKeys and PINs. Report lost or stolen keys immediately.
• Configure IAM roles with least-privilege permissions.
• Set up SCIM to automate user lifecycle management.
• Monitor CloudTrail and server audit logs for anomalous activity.
• Keep the Vouch CLI updated to receive security patches.

Compliance

Vouch’s FAPI 2.0 security profile and hardware-backed authentication satisfy requirements across multiple compliance frameworks:

• NIST 800-53 — IA-2 (identification/authentication), IA-5 (authenticator management), SC-23 (session authenticity)
• SOC 2 — CC6.1 (logical access), CC6.8 (unauthorized access prevention), CC7.1 (detection)
• FedRAMP — Hardware MFA, DPoP sender-constrained tokens, non-extractable keys
• HIPAA — 164.312(d) (person authentication), 164.312(e) (transmission security)

Detailed control-by-control mappings are available in the Vouch server documentation.

Incident response

If you suspect a security issue with the Vouch service or have discovered a vulnerability:

• Email security@vouch.sh with details.
• Include reproduction steps if possible.
• Do not disclose the issue publicly until it has been addressed.

If a YubiKey is lost or stolen, remove it from the user’s account immediately to prevent unauthorized authentication.