# Credentials in sandboxes and jobs Credentials let your jobs and sandbox sessions call services that need a password or a key, without the secret appearing in your image, your logs or your certificates. You store each secret once by name. A job or session can use only the secrets that you allow for that destination. Hangar stores each secret in Sydney, sealed under the key of your organisation. A job receives a credential when the job starts. A sandbox session receives no credential, because the gateway attaches the credential outside the session. Every record and certificate shows the secret's name and never shows the value. ## Setting a secret ```sh op read "op://Build/GitHub/token" | hangar secret set GITHUB_TOKEN hangar secret set GITHUB_TOKEN < token.txt ``` The CLI reads the value from standard input only. Pipe the value from a password manager, or redirect the value from a file that only you can read. The CLI never takes a value from the command line or from a prompt. The value therefore stays out of your shell's history, the machine's process list and the terminal's scrollback. The value travels once, over TLS 1.3, to Hangar in Sydney. Hangar seals the value with AES-256-GCM under your organisation's key, bound to your organisation and to the secret's name. Hangar keeps the sealed value in the secret store in Sydney. Hangar wraps the organisation's key under Hangar's root in Australia. A name is a capital letter followed by up to 63 capitals, digits or underscores. Setting a name again replaces the value. A value is up to 16 KiB. ```sh hangar secret list # names and when each was set hangar secret delete GITHUB_TOKEN # removes the value from the store ``` ### Secrets for a tenant A vendor that serves its own customers keeps each customer's secrets apart as a tenant: ```sh op read "op://Acme/GitHub/token" | hangar secret set GITHUB_TOKEN --tenant acme-t1 hangar secret list --tenant acme-t1 hangar secret delete GITHUB_TOKEN --tenant acme-t1 ``` A tenant name is a lower-case letter or digit, then up to 62 lower-case letters, digits, dots, hyphens or underscores. Each tenant has its own names, apart from your organisation's own secrets and from every other tenant's secrets. `GITHUB_TOKEN` for `acme-t1` and `GITHUB_TOKEN` for your organisation are therefore two secrets. Hangar seals a tenant's value under your organisation's key and binds the value to your organisation, the tenant and the name. The value opens for no other tenant. `hangar secret list` prints names and times. After you set a value, Hangar shows the value to nobody: no command, page or route returns the value. The change record for a secret shows the secret's name and contains no value. ## In a job A job lists its secrets in `hangar.toml` or with `--env NAME`. These things happen: 1. The slot's instance proves what it is. 2. The control plane opens each listed secret and seals the secret again for that instance alone. 3. The worker writes each secret once. The worker writes the secret as an environment variable from a file in memory, or as a read-only file at the path that you choose. 4. The worker deletes the secret when the job ends. The movement record and the job certificate list the secret names. If a job prints a value in its log, the worker replaces the value with `[secret NAME]` before the line leaves the instance. Treat logs as sensitive all the same, because a program can print a value in a form that the worker does not recognise. ## In a sandbox session A session lists its credentials with `--attach SECRET=destination:header[:scheme]`. A session started with `--tenant` attaches that tenant's secret. `--org-attach SECRET=destination:header[:scheme]` attaches your organisation's own secret. A session for one tenant never finds another tenant's secret. The gateway, which TALOS Defence operates, receives the value over TLS 1.3 from the control plane. The gateway keeps the value in memory for the session's whole life. The gateway writes the value into the named header of each request to that destination. The session, its containers, its environment and its files contain no credential. An agent, a companion or a dependency in the session has no credential to read. The first use of each credential in a session waits for a named person's approval on their phone, unless an owner turns that off in the sandbox policy. A destination can echo the value in a reply. The gateway then masks the value before the reply reaches the session, and the session certificate shows the secret by name as masked. The session certificate lists each attachment by name and destination. When the session ends, the gateway drops every value that the gateway held for the session and records each by name. That record is the `secrets_detached` step of the sandbox reset. Deleting a secret takes the secret out of the store at once. A session that is already running keeps the value that its gateway attached, until the session pauses or ends. Revoke All ends the session immediately. ### At pause and resume A pause ends every value that the gateway held for the session. At resume, or at recovery after an interruption, the gateway receives each value again from the store, as the value stands then. A secret that you deleted while the session was paused is absent after resume, and the session runs without that attachment. An attachment whose destination is no longer on your account's egress list is dropped in the same way. ### The session volume key A session's workspace is on a volume of its own. Hangar encrypts the volume under a 64-byte key that Hangar makes for that session. Hangar seals the key under your organisation's key. Hangar hands the key only to the session's instance, for each attempt, after the instance proves what it is. AWS KMS never holds the key. The key opens that one volume only. The key is not a credential for anything outside the session. Hangar destroys the key when the session ends, in the `credentials_revoked` step of the sandbox reset. ## Who can do what Members and owners of your organisation can set and delete secrets, for the organisation and for each tenant. Viewers can list names. A session token cannot set, list or delete a secret. Every set and every deletion is a signed record that shows who made the change.