feat: gpgtools configure_ssh, store_publickey, --file source, initialize (v0.7.0-v0.9.0)
- configure_ssh (0.7.0): marker-managed per-host ssh client block in ~/.ssh/config, idempotent, unmanaged-alias guard (exit 11) - store_publickey (0.8.0): on-site bootstrap mirror of send_pubkey - run on the machine access is granted to, installs the key into the local authorized_keys (multi-key preserving, material dedup, 700/600, no possession check by design); shared --file PATH source (USB stick) for both store subcommands; identity block printed before acting (line, source, SHA-256 material digest) - initialize (0.9.0): gnupg readiness check + install, no card expectations; --dry-run; initialize_yubikey step 1 shares the flow - spec-first per SPEC 6.11/6.12: gpgtools spec.md items 2.6/2.7, 4.1.5, 4.8, sections 10-12; 91 tests in test_gpgtools.py; README/registry/CHANGELOG/version pins through 0.9.0 Generated by Mistral Vibe. Co-Authored-By: Mistral Vibe <vibe@mistral.ai>
This commit is contained in:
+160
-16
@@ -15,6 +15,9 @@ Items are cited as `gpgtools spec item N.M`.
|
||||
- [7. Files written](#7-files-written)
|
||||
- [8. Testing approach](#8-testing-approach)
|
||||
- [9. References](#9-references)
|
||||
- [10. configure_ssh behavior](#10-configure_ssh-behavior)
|
||||
- [11. store_publickey behavior](#11-store_publickey-behavior)
|
||||
- [12. initialize behavior](#12-initialize-behavior)
|
||||
|
||||
<!-- toc-end -->
|
||||
|
||||
@@ -25,7 +28,10 @@ Items are cited as `gpgtools spec item N.M`.
|
||||
(`~/repositories/vibe-wiki/wiki/queries/yubikey-ssh-guide.md`):
|
||||
`initialize_yubikey` covers guide steps 1-4 (fresh machine ready
|
||||
for GPG), `send_pubkey` covers steps 5-6 (key to a server).
|
||||
Guide step 7 (per-host `~/.ssh/config`) is out of scope.
|
||||
`store_publickey` covers the on-site bootstrap case (section 11):
|
||||
installing the key from the machine that access is being
|
||||
granted to. Guide step 7 (per-host `~/.ssh/config`) is out of
|
||||
scope.
|
||||
- **1.2** Hard constraint: the YubiKey's OpenPGP applet is never
|
||||
written - no `gpg --card-edit`, no `keytocard`, no applet reset.
|
||||
Only public card data is read; the card PIN is typed by its
|
||||
@@ -38,26 +44,43 @@ Items are cited as `gpgtools spec item N.M`.
|
||||
## 2. Commands
|
||||
|
||||
- **2.1** `daedalus gpgtools` with no subcommand prints the
|
||||
overview of both subcommands and exits 0.
|
||||
overview of the subcommands and exits 0.
|
||||
- **2.2** `daedalus gpgtools initialize_yubikey [--dry-run]
|
||||
[--gnupg-home DIR]` - prepares this machine (section 3).
|
||||
- **2.3** `daedalus gpgtools send_pubkey
|
||||
(--yubikey | --url URL | --fingerprint FP | --pubkey LINE)
|
||||
(--yubikey | --url URL | --fingerprint FP | --pubkey LINE | --file PATH)
|
||||
[--no-verify] [--dry-run] you@server` - resolves one SSH
|
||||
public key, proves possession of the private half, appends it
|
||||
to the target (section 4). The four source flags are mutually
|
||||
to the target (section 4). The five source flags are mutually
|
||||
exclusive and exactly one is required; `you@server` is
|
||||
required.
|
||||
- **2.4** `--dry-run` on either subcommand prints what would
|
||||
happen and writes nothing; on `send_pubkey` it resolves and
|
||||
prints the key but never verifies and never connects.
|
||||
- **2.5** `daedalus gpgtools configure_ssh --alias NAME
|
||||
[--hostname HOST] [--user USER] [--pubkey FILE]
|
||||
[--fallback FILE | --no-fallback] [--config PATH] [--dry-run]`
|
||||
- writes the per-host ssh client block (guide step 7);
|
||||
behavior in section 10.
|
||||
- **2.6** `daedalus gpgtools store_publickey
|
||||
(--yubikey | --url URL | --fingerprint FP | --pubkey LINE | --file PATH)
|
||||
[--authorized-keys FILE] [--dry-run]` - resolves one SSH
|
||||
public key and installs it into *this* machine's
|
||||
authorized_keys (section 11). The source flags are the
|
||||
send_pubkey set (items 4.1.1-4.1.5), mutually exclusive,
|
||||
exactly one required.
|
||||
- **2.7** `daedalus gpgtools initialize [--dry-run]` - checks
|
||||
that gnupg is ready on this machine and installs what is
|
||||
missing; the gnupg-only half of initialize_yubikey
|
||||
(section 12).
|
||||
|
||||
## 3. initialize_yubikey behavior
|
||||
|
||||
- **3.1** Step 1 - gnupg: `gpg --version`. When it fails, the
|
||||
package manager is detected (`shutil.which` over apt-get, dnf,
|
||||
pacman) and gnupg installed via `sudo`; no known manager is
|
||||
exit 3. A failed install is exit 2.
|
||||
- **3.1** Step 1 - gnupg: the section 12 flow (item 12.1). When
|
||||
`gpg --version` fails, the package manager is detected
|
||||
(`shutil.which` over apt-get, dnf, pacman) and gnupg installed
|
||||
via `sudo`; no known manager is exit 3. A failed install is
|
||||
exit 2.
|
||||
- **3.2** Step 2 - card: `gpg --card-status` parsed for the
|
||||
`Application type`/`OpenPGP` markers; absent card (including
|
||||
gpg error text) is exit 4 with the pcscd hint
|
||||
@@ -101,6 +124,13 @@ Items are cited as `gpgtools spec item N.M`.
|
||||
All exhausted is exit 8 naming the stores.
|
||||
- **4.1.4** `--pubkey`: the literal line, validated by item 4.2;
|
||||
exit 8 when invalid.
|
||||
- **4.1.5** `--file PATH`: a file holding the SSH public key
|
||||
line - typically `yubikey_auth.pub` carried on a USB stick
|
||||
(zero network, zero gpg). Every line is validated per item
|
||||
4.2: no valid line is exit 8; several valid lines refuse
|
||||
listing them with the `--pubkey` hint (item 4.1.1
|
||||
precedent) rather than guessing; an unreadable or missing
|
||||
file is exit 8.
|
||||
- **4.2** Key line validation: `ssh-(ed25519|rsa|dss|ecdsa-sha2-*)
|
||||
<base64> [comment]`, full line; anything else is rejected.
|
||||
- **4.3** Key material (type + base64, comment ignored) is the
|
||||
@@ -128,20 +158,26 @@ Items are cited as `gpgtools spec item N.M`.
|
||||
credentials (agent, passphrase-less key, or ControlMaster
|
||||
socket). First contact to a brand-new server by password is out
|
||||
of scope - gain access once manually, then send the key.
|
||||
- **4.8** Output (identical in section 11): both resolve-and-store
|
||||
subcommands print the resolved key line, its source, and the
|
||||
SHA-256 hex digest of the key material (item 4.3) before
|
||||
acting, so the resolved value can be compared with the machine
|
||||
the key came from (or read over a phone).
|
||||
|
||||
## 5. Exit codes
|
||||
|
||||
| Code | Meaning |
|
||||
| --- | --- |
|
||||
| 0 | success (initialize ready; send appended or already present) |
|
||||
| 2 | package install failed (initialize) |
|
||||
| 3 | gpg missing and no known package manager (initialize) |
|
||||
| 2 | package install failed (initialize, initialize_yubikey) |
|
||||
| 3 | gpg missing and no known package manager (initialize, initialize_yubikey) |
|
||||
| 4 | no OpenPGP card found (initialize) |
|
||||
| 5 | public-key fetch did not pair the keyring (initialize) |
|
||||
| 6 | keyring unpaired and the card carries no URL (initialize) |
|
||||
| 7 | ssh to the target failed; nothing stored (send) |
|
||||
| 8 | no source resolved a usable key (send) |
|
||||
| 8 | no source resolved a usable key (send, store); pubkey file missing (configure) |
|
||||
| 10 | proof-of-possession verification failed; nothing sent (send) |
|
||||
| 11 | an unmanaged `Host <alias>` exists in the config (configure) |
|
||||
|
||||
## 6. Runner contract and injectability
|
||||
|
||||
@@ -169,6 +205,10 @@ Items are cited as `gpgtools spec item N.M`.
|
||||
workspace) are created under the system temp dir and removed in
|
||||
`finally`. The only persistent write is the target's
|
||||
`authorized_keys` append via ssh (item 4.6).
|
||||
- **7.3** store: the local `authorized_keys` (item 11.5) is the
|
||||
only persistent write; its parent gets mode 700, the file 600.
|
||||
Scratch rules of item 7.2 apply when remote sources resolve
|
||||
(item 4.5).
|
||||
|
||||
## 8. Testing approach
|
||||
|
||||
@@ -180,10 +220,13 @@ Items are cited as `gpgtools spec item N.M`.
|
||||
no URL, no auth subkey, unpaired), config merge (empty,
|
||||
preserving, complete), manager mapping and detection,
|
||||
GNUPGHOME resolution, the initialize flow's success, failure,
|
||||
warning, and persistence branches, the four sources including
|
||||
the store chain and fingerprint mismatch, challenge
|
||||
sign/verify success and refusal, send idempotence by material,
|
||||
and the CLI wiring, guards, and dry runs.
|
||||
warning, and persistence branches and the standalone
|
||||
readiness/install/re-check branches (section 12), the five
|
||||
sources including the store chain and fingerprint mismatch,
|
||||
challenge sign/verify success and refusal, send idempotence by
|
||||
material, store: file sources, append, preservation,
|
||||
idempotence, perms, dry run, and the CLI wiring, guards, and
|
||||
dry runs.
|
||||
- **8.3** The change order is spec item 6.12: this spec first,
|
||||
then failing tests, then the smallest implementation.
|
||||
|
||||
@@ -194,4 +237,105 @@ Items are cited as `gpgtools spec item N.M`.
|
||||
(steps 1-13; automation notes in section 13).
|
||||
- **9.2** Repository rules: SPEC items 6.6 (tests), 6.9
|
||||
(argcomplete opt-in after the parser), 9.8 (version bump).
|
||||
- **9.3** History: `CHANGELOG.md` entries 0.5.0 and 0.6.0.
|
||||
- **9.3** History: `CHANGELOG.md` entries 0.5.0, 0.6.0
|
||||
(initialize/send), 0.7.0 (configure_ssh), 0.8.0
|
||||
(--file source, store_publickey), 0.9.0 (initialize).
|
||||
|
||||
## 10. configure_ssh behavior
|
||||
|
||||
- **10.1** The block is written into `--config` (default
|
||||
`~/.ssh/config`) between managed markers, one block per alias:
|
||||
|
||||
```text
|
||||
# BEGIN daedalus gpgtools: <alias>
|
||||
Host <alias>
|
||||
HostName <hostname>
|
||||
User <user> (omitted without --user)
|
||||
IdentityFile <pubkey>
|
||||
IdentityFile <fallback> (omitted per item 10.4)
|
||||
IdentitiesOnly yes
|
||||
# END daedalus gpgtools: <alias>
|
||||
```
|
||||
|
||||
- **10.2** Defaults: `--hostname` defaults to the alias itself;
|
||||
`--pubkey` defaults to `~/.ssh/yubikey_auth.pub`;
|
||||
`--fallback` defaults to `~/.ssh/id_ed25519`.
|
||||
- **10.3** Idempotence: a run that finds the alias's markers
|
||||
replaces the whole marked block with the newly built one;
|
||||
everything outside the markers is preserved byte-for-byte.
|
||||
Running twice with the same arguments changes nothing.
|
||||
- **10.4** The fallback `IdentityFile` is included only when its
|
||||
file exists and `--no-fallback` was not given; a missing
|
||||
explicit `--fallback FILE` logs a warning.
|
||||
- **10.5** Guards: a `--pubkey` file that does not exist is exit
|
||||
8 with the derive hint; a `Host` line naming the same alias
|
||||
anywhere outside the managed markers is exit 11 (ssh would let
|
||||
the first match shadow the managed block).
|
||||
- **10.6** File hygiene: `~/.ssh` is created at mode 700 when
|
||||
missing; the config file is created at mode 600 when missing.
|
||||
- **10.7** `--dry-run` prints the block plus
|
||||
`creating`/`replacing`, and writes nothing.
|
||||
|
||||
## 11. store_publickey behavior
|
||||
|
||||
- **11.1** Installs one SSH public key into the *current user's*
|
||||
`~/.ssh/authorized_keys` (`--authorized-keys FILE` overrides)
|
||||
on this machine - the machine the key will later grant access
|
||||
to. Use case: a server with ssh password authentication
|
||||
disabled that no key authorizes yet; you are logged in at its
|
||||
console and install the key from inside, so the machine
|
||||
holding the YubiKey can ssh in afterwards. It is the mirror of
|
||||
section 4: send pushes the key from where it is, store pulls
|
||||
it from where the access is.
|
||||
- **11.2** Sources: identical to items 4.1.1-4.1.5, one per run.
|
||||
On a bare server the realistic ones are `--pubkey` (typed at
|
||||
the console), `--file` (USB stick; needs no network and no
|
||||
gpg), and `--fingerprint` (store chain, needs gpg and
|
||||
network); `--yubikey` works when the card is plugged into
|
||||
this machine. An unresolvable source is exit 8 (item 5).
|
||||
- **11.3** There is no proof-of-possession step (item 4.4) and
|
||||
no `--no-verify` flag: the private half is, by design,
|
||||
elsewhere - this machine is the one being granted access, so
|
||||
nothing here could sign the challenge. Hardening instead: line
|
||||
validation (item 4.2), fingerprint-checked stores (item
|
||||
4.1.3), and the identity block (item 11.4).
|
||||
- **11.4** Identity block: the resolved key line, its source,
|
||||
and the SHA-256 hex digest of the key material (item 4.3) are
|
||||
printed before writing (shared rule, item 4.8), so the value
|
||||
can be compared with the machine the key came from.
|
||||
- **11.5** Storage: the parent directory is created at mode 700
|
||||
when missing and the authorized_keys file forced to mode 600,
|
||||
on every write. Existing entries are preserved verbatim -
|
||||
authorized_keys is a multi-key file; there is no mismatch
|
||||
guard on the rest, only the new key's absence is checked.
|
||||
- **11.6** Idempotence follows item 4.3: the line is appended
|
||||
only when its material is absent (comments ignored); already
|
||||
present is reported and exits 0. A missing trailing newline
|
||||
in an existing file is repaired, never glued into a key line.
|
||||
- **11.7** `--dry-run` prints the identity block plus
|
||||
`already present`/`creating` and writes nothing.
|
||||
- **11.8** No ssh is run and the only persistent write is item
|
||||
11.5; remote sources keep item 4.5's throwaway-home rule
|
||||
(item 7.3). Exit codes: 0 stored or already present, 8 no
|
||||
source resolved a usable key.
|
||||
|
||||
## 12. initialize behavior
|
||||
|
||||
- **12.1** `initialize` covers the gnupg half of item 3.1
|
||||
only - no card, keyring, or agent expectations. `gpg
|
||||
--version` decides readiness: present prints the version
|
||||
line and exits 0. Missing runs manager detection and the
|
||||
`sudo` install (item 3.1's manager map); no known manager is
|
||||
exit 3, a failed install is exit 2. After a successful
|
||||
install the check re-runs once - still unusable is exit 2.
|
||||
- **12.2** `--dry-run` performs only the read-only
|
||||
`gpg --version`, prints what would happen (`already ready`
|
||||
with the version line, the install command it would run, or
|
||||
the install-manually message), installs nothing, and exits 0
|
||||
in every dry-run case.
|
||||
- **12.3** `initialize_yubikey` runs this flow as its step 1
|
||||
(item 3.1); a `-2`/`-3` return stops it before anything else.
|
||||
- **12.4** Intended use: the on-site companion to
|
||||
store_publickey (item 11) - on a machine without the
|
||||
YubiKey, run `initialize` first when a gpg-dependent source
|
||||
(`--fingerprint`, `--url`, `--yubikey`) is wanted.
|
||||
|
||||
Reference in New Issue
Block a user