Browse the docs

Network

Secrets

A secret is a token that a VM's programs use but never see. The value stays in your Mac's Keychain. Inside the VM, the secret's environment variable holds a placeholder, and Hangar replaces it with the value on its way to the hosts you allow, outside the guest.

hangar secret set deb GITHUB_TOKEN --host api.github.com      # asks for the value
gh auth token | hangar secret set deb GITHUB_TOKEN --host api.github.com --value-stdin
hangar secret list deb
hangar secret remove deb GITHUB_TOKEN

Programs in the VM see GITHUB_TOKEN=hangar…. When one sends that placeholder to api.github.com, the server gets the real token. A name is capital letters, digits and _; names the VM's shells and programs rely on, like PATH or anything starting with LD_, are refused.

Where the value goes

Option Where Hangar puts the value
(always) Any request header that holds the placeholder, like Authorization: Bearer $GITHUB_TOKEN
--header 'X-Api-Key: %s' That header, on every request to the hosts, placeholder or not

Only headers get the value. A URL or a body reaches the server as the VM sent it, placeholder and all.

How it works

  • Only these hosts are opened. HTTPS to the hosts of a secret goes to a proxy in the VM's process on your Mac, which opens it with a certificate authority of the VM's own. All other traffic passes as before. The VM trusts the authority's root, which signs an intermediate that can vouch only for those hosts.
  • The real server is checked first. The proxy connects to the real host and checks its certificate against your Mac's trust before any request is sent. A host whose certificate doesn't check out gets nothing.
  • A placeholder stays with its hosts. A placeholder sent to another opened host, a request naming another host than the connection's, a tunnel or a WebSocket upgrade is refused and never sent on. The traffic log shows each secret put in and each refusal, never the value.
  • The value doesn't come back in a header. Hangar searches the headers of every answer from these hosts for the values, as they are and percent-encoded, like a redirect's Location would carry them, and puts the placeholder back in their place. The traffic log shows each answer that held one. The body passes as the host sent it.
  • HTTP/3 is held back. QUIC and HTTPS DNS records for these hosts are dropped, so clients use HTTPS over TCP.

Secrets need the Hangar Managed network, a current agent in the VM, and the VM's names looked up through that network's DNS. A VM with secrets is always watched, so its traffic log fills even with traffic watching off.

Programs that were already running when a secret was added see its variable after you sign in again or restart them.

Each guest

Guest What the agent sets up
Linux The authority in the system's CA bundle; variables in /etc/profile.d and /etc/environment.d; NODE_EXTRA_CA_CERTS for Node
Windows The authority in the computer's Trusted Root store; variables in the system environment
macOS The authority in the System keychain, and variables in /etc/zshenv and in the apps of the user at the screen, with NODE_EXTRA_CA_CERTS for Node. macOS trusts a new authority only after a person agrees, so the first secret asks for your password once, in the VM's window

Some programs need more:

  • curl.exe on Windows checks revocation and finds none for the VM's own authority: pass --ssl-revoke-best-effort.
  • Programs with a CA bundle of their own (Python's certifi, Java's cacerts, Firefox, and Node on Windows) need the authority added there, or a setting such as REQUESTS_CA_BUNDLE.
  • Programs that pin certificates can't reach these hosts.
  • Programs that find addresses on their own, through DNS over HTTPS or a resolver of their own, aren't seen by Hangar: their placeholder reaches the server as it is.
  • Hangar speaks HTTP/1.1 and HTTP/2 to these hosts: a client gets HTTP/2 when it and the server both offer it, so gRPC works when the server speaks HTTP/2; a client that only speaks HTTP/2 can't reach a server that only speaks HTTP/1.1. Each connection takes 16 HTTP/2 requests at a time. WebSockets, over either, are refused.

A host that echoes requests in its body, as test services do, shows the value to the VM, and so does one that sends it back in another form, like base64. Give secrets only to hosts you trust with them, and tokens only the scope the VM needs. A value must be 8 to 8192 bytes, so putting the placeholder back can't catch unrelated text.