The wizard
Some people prefer a page to a terminal, and a ceremony is easier to follow when each step is shown with its explanation next to it. The wizard is that: a guided front end that looks good and keeps you in charge.
What it is
Section titled “What it is”- A second face of the same engine. The wizard asks the ceremony engine for the plan, shows it, and asks you to confirm. It does not sign, verify or record by any code of its own (principle 14).
- In the terminal, or in a browser. The terminal wizard needs no browser. The web wizard is a page served by the program on your own computer.
- The user is in charge. Nothing happens without your confirmation. The PIN is typed at the terminal and goes to the card, and the touch is a touch on the card. The page never sees either.
What the page may and may not do
Section titled “What the page may and may not do”| The page may | The page may not |
|---|---|
| Show the plan, the facts about each key, and the teaching text for the step. | Confirm an irreversible step by itself. |
| Collect choices: which root, which request, which store. | Ask for, receive or show a PIN, a passphrase or a key. |
| Show progress, the record and what outsiders will see. | Load anything from outside your computer. |
The confirmation of every irreversible step is given in the terminal, or by the touch on the card, never only by a click in the page.
Security rules
Section titled “Security rules”The web wizard is a program on your computer that acts on root keys, so it is built to be hard to reach from anywhere else, including from another page open in the same browser.
- It listens on 127.0.0.1 only, and refuses to start on any other address.
- On a random port, chosen at each start.
- With a one-time token in the address it prints. A request without the token is refused, and the token stops working when the wizard stops.
- It checks the Host and Origin headers of every request against its own address and port. This stops a web page you visit from talking to it, including by a trick that points a hostile name at your own computer (DNS rebinding).
- It loads no remote assets: no web fonts, no scripts, no images from other sites. The page works with the network cable out.
- It sends a strict Content-Security-Policy that allows its own files only, and nothing else.
- Every irreversible step needs confirmation in the terminal or by touch.
- No telemetry, and no network call other than the ones a ceremony itself needs.
Each rule has a test in the plan for the wizard: a request with the wrong token, Host or Origin is refused, and the page loads nothing when the network is blocked.