1# CA Commands
2
3Manage Gordon's internal Certificate Authority.
4
5## gordon ca
6
7### Subcommands
8
9| Subcommand | Description |
10|------------|-------------|
11| `export` | Export the root CA certificate in PEM format |
12| `info` | Show CA status (root CN, fingerprint, intermediate expiry) |
13| `install` | Install/uninstall the root CA in system trust stores |
14
15All subcommands require Gordon to have TLS-capable HTTPS fallback configured on an entrypoint such as `entrypoints.edge` with `protocol = "smart_tcp"`.
16
17### Local and remote
18
19`export` and `info` target a remote with the same rules as other commands: `--remote`, then `GORDON_REMOTE`, then the active remote saved with `gordon remotes`. When a remote is targeted, they fetch the CA through the authenticated admin API (`GET /admin/ca`, scope `admin:status:read`). The remote answers `404` when its internal TLS is disabled.
20
21The fetched certificate is checked locally: it must be a single self-signed CA certificate, and the displayed common name and fingerprint are computed from it. If the server reports a different fingerprint, the command fails. These checks prove the certificate is well formed, not where it came from: over an `insecure_tls` or `http://` remote the response can be replaced in transit. `export` prints the fingerprint on stderr; compare it with `gordon ca info` on the Gordon host before trusting the certificate.
22
23With no remote targeted, `export` and `info` read the local server config (`--config`, or `gordon.toml` in `/etc/gordon`, `~/.config/gordon`, or the current directory) and its data directory. If that config has no TLS-capable entrypoint, the error names the config file that was read.
24
25`install` is local-only and works on the Gordon host. It fails when a remote is targeted.
26
27---
28
29## gordon ca export
30
31Export the root CA certificate for manual trust installation on clients.
32
33```bash
34gordon ca export                  # Print PEM to stdout
35gordon ca export --out ca.pem     # Write to file
36gordon ca export --remote prod    # Fetch the CA from a remote Gordon
37```
38
39### Options
40
41| Option | Description |
42|--------|-------------|
43| `--out` | Write certificate to file instead of stdout |
44
45---
46
47## gordon ca info
48
49Show CA status information: root common name, SHA-256 fingerprint, and intermediate certificate expiry.
50
51```bash
52gordon ca info
53gordon ca info --json
54gordon ca info --remote prod
55```
56
57### Options
58
59| Option | Description |
60|--------|-------------|
61| `--json` | Output as JSON |
62
63### JSON Output
64
65```json
66{
67  "root_cn": "Gordon Internal Root CA",
68  "fingerprint": "SHA256:AB:CD:...",
69  "intermediate_expiry": "2026-07-01T12:00:00Z",
70  "intermediate_ttl": "2160h0m0s"
71}
72```
73
74---
75
76## gordon ca install
77
78Install or uninstall the root CA certificate in the system, Firefox, and Java trust stores of the **Gordon host machine**. Requires root privileges. The CA is read from the local Gordon data directory; the command never fetches it over the network.
79
80```bash
81sudo gordon ca install
82sudo gordon ca install --uninstall
83```
84
85If a remote is targeted (`--remote`, `GORDON_REMOTE`, or an active remote), the command fails with:
86
87```
88ca install only works on the Gordon host; from another machine run `gordon ca export --remote <name> --out gordon-ca.pem` and install that file with your OS trust tools
89```
90
91### Options
92
93| Option | Description |
94|--------|-------------|
95| `--uninstall` | Remove the CA from trust stores instead of installing |
96| `--json` | Output as JSON |
97
98> **Important:** This command is for the machine running Gordon, not for arbitrary clients. Other machines should export the certificate (`gordon ca export --remote <name> --out gordon-ca.pem`) or use one of the methods below.
99
100---
101
102## Client Trust Setup
103
104Clients that connect directly to Gordon's HTTPS port need the root CA certificate in their trust store. Gordon provides the certificate through a browser-accessible onboarding page at `https://<gordon-host>/.well-known/gordon/ca`, or over plain HTTP at `http://<gordon-host>/.well-known/gordon/ca` for first-time setup.
105
106### Firefox / Zen (NSS certificate store)
107
108Firefox and Zen use their own certificate store, separate from the OS.
109
1101. Open `https://<gordon-host>/.well-known/gordon/ca.crt` — Firefox will prompt to import the certificate.
1112. Check **Trust this CA to identify websites** and confirm.
112
113Alternatively, import manually: **Settings > Privacy & Security > Certificates > View Certificates > Import**.
114
115### Linux System Trust Store
116
117```bash
118# Download the certificate
119curl -k https://<gordon-host>/.well-known/gordon/ca.crt -o gordon-ca.pem
120
121# Debian / Ubuntu
122sudo cp gordon-ca.pem /usr/local/share/ca-certificates/gordon-ca.crt
123sudo update-ca-certificates
124
125# Fedora / RHEL
126sudo cp gordon-ca.pem /etc/pki/ca-trust/source/anchors/gordon-ca.pem
127sudo update-ca-trust
128```
129
130### Mobile Devices (iOS / Android)
131
132Visit `http://<gordon-host>/.well-known/gordon/ca` from the device browser. The onboarding page offers:
133
134- **iOS:** Download the `.mobileconfig` profile, then install it in **Settings > General > VPN & Device Management**.
135- **Android:** Download `ca.crt`, then install it in **Settings > Security > Encryption & credentials > Install a certificate**.
136
137---
138
139## Related
140
141- [Server Configuration](../config/server.md) — `force_https_redirect`, smart TCP edge, and internal CA settings
142- [CLI Commands](./index.md)
143- [Remotes](./remotes.md) — saved remote Gordon instances for `--remote`