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_TOKENPrograms 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
Locationwould 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.exeon 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'scacerts, Firefox, and Node on Windows) need the authority added there, or a setting such asREQUESTS_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.