Skip to content

Couriers

The Zaita Courier can download secrets from a Locker and write them to a local file, making it straightforward to inject secrets into applications that read from .env files or JSON configuration at startup, and to integrate secret delivery into CI/CD pipelines and scheduled jobs.

The Courier authenticates with the platform, performs an ECDH key exchange to receive an encrypted secrets bundle, decrypts the bundle locally, and writes the output file. Plaintext secret values never traverse the network.

The Courier must be registered in the platform and granted access to the Locker before it can download secrets. See CLM Couriers — Setting Up for Courier registration, and Managing Lockers and Secrets for granting Locker access.

When to Use a Courier

Couriers are best suited for:

  • Applications that read secrets from environment files (.env, systemd EnvironmentFile) at startup
  • Scheduled tasks and cron jobs that need secrets injected periodically
  • CI/CD pipelines that need secrets at build or deploy time
  • Systems managed by configuration management tooling

For applications that need to resolve secrets dynamically at runtime, consider a Workload instead. For environments with multiple local consumers and high-availability requirements, consider a Bridge.

Output Formats

The Courier supports two output formats:

env_file

Writes secrets as NAME=value lines, compatible with dotenv loaders and systemd EnvironmentFile directives.

DB_PASSWORD=s3cr3t-password
API_KEY=pk_live_abc123
STRIPE_WEBHOOK_SECRET=whsec_xyz789

json

Writes secrets as a flat JSON object with secret names as keys.

{
  "DB_PASSWORD": "s3cr3t-password",
  "API_KEY": "pk_live_abc123",
  "STRIPE_WEBHOOK_SECRET": "whsec_xyz789"
}

Output files are always written with mode 0600 (owner read/write only), regardless of format.

Encryption Protocol

When downloading secrets, the Courier:

  1. Generates a fresh ephemeral EC P-521 key pair.
  2. Sends the ephemeral public key (PEM SPKI) to the platform with the download request.
  3. The platform's Secured Back Control Plane decrypts each secret, collects the plaintext, generates its own ephemeral P-521 key pair, and derives a shared secret via ECDH.
  4. The BCP encrypts the secrets bundle using AES-256-GCM with a key derived from SHA-256(shared_secret).
  5. The Courier performs ECDH with the BCP's ephemeral public key and its own private key to derive the same shared secret.
  6. The Courier decrypts the bundle and writes the secrets to the output file.

Each download uses a fresh ephemeral key pair on both sides, providing forward secrecy — compromise of one download bundle does not expose others.

Next Steps