.TH WREN-KEY 1 "wren" "wren" "User Commands"
.SH NAME
wren-key \- make, keep and use Wren Linux's signing key
.SH SYNOPSIS
.B wren-key
.RI [ COMMAND ]
.SH DESCRIPTION
Every Wren Linux computer checks its updates against one key:
.B update.sh
brings in only commits it signed, and apt only packages from a repository it
signed.
Whoever has the key could put anything on all of those computers, as root;
whoever loses it can't publish Wren Linux any more.
.B wren-key
makes that key and uses it, the careful way.
.PP
The key has two parts.
The
.B primary key
only vouches for the other; it goes into a backup on your USB stick, encrypted
with a passphrase you choose, and is then deleted from this computer.
The
.B signing subkey
does the daily signing.
It is held by
.BR wren-signer ,
a system user with no password, no login and no network (a firewall rule drops
everything it sends), whose files your own user can't read.
Your user may run one program as that user, the signer, and only after typing
your sudo password.
The signer signs, hands out the public key, and makes or renews the key; it
never hands out a secret key.
.SH COMMANDS
.TP
.B wren-key
The first time: explains, asks for the name and email on the key, the folder
on a USB stick for the backup, and the backup's passphrase (at least 20
characters; it suggests one of random words), then makes the key.
In
.I FOLDER/wren-signing-key
it writes
.I wren-signing-key-backup.asc
(the whole key, encrypted with the passphrase),
.I wren-signing-key-revocation.asc
(declares the key void, if it is ever stolen; it works without the
passphrase) and
.I wren-signing-key-public.asc
(the public key).
Then it offers
.B git-setup
and
.BR pin .
Once there is a key, the same as
.BR status .
.TP
.B status
The key's fingerprint, until when the signing subkey signs, whether git signs
with it and whether
.I pins.sh
pins it.
It warns when the subkey stops signing within 90 days.
.TP
.BR git-setup " [\fIDIR\fR]"
git in
.I DIR
(by default the Wren Linux folder) signs every commit and tag with the key, through
.BR wren-key-gpg ,
which hands signing to the signer and checks signatures with the public key.
sudo asks for your password now and then.
.TP
.BR pin " [\fIDIR\fR]"
Writes the public key to
.I DIR/data/wren-signing-key.asc
and its fingerprint to
.B WREN_SIGNING_FPR
in
.IR DIR/pins.sh ,
for you to look at, commit (signed) and push.
From then on every Wren Linux computer that updates past that commit takes only
what this key signed.
.TP
.BI sign-repo " FOLDER DEB" ...
Makes a signed apt repository of Wren Linux's packages in
.I FOLDER
.RB ( tools/make-apt-repo.sh ),
signed by the signer.
Upload
.I FOLDER
as it is.
It is good for 14 days: sign it again within that time.
.TP
.BI renew " BACKUP"
Gives the signing subkey two more years, from the backup (it asks for its
passphrase).
The renewed backup replaces
.I BACKUP
(the old one is kept as
.IR BACKUP.old );
copy it to your second stick, then
.B pin
and publish the renewed public key before the old date.
.TP
.BI restore " BACKUP \fR[\fPFINGERPRINT\fR]"
On a new computer, or after reinstalling: the key from its backup into the
signer (it asks for the backup's passphrase).
Only the key
.I pins.sh
pins is taken, or the one
.I FINGERPRINT
names, and only when this computer has no key yet.
As on the first run, the signer keeps only the signing subkey; the primary key
stays in the backup.
.TP
.BR public ", " fingerprint
The public key, or the primary key's fingerprint.
.TP
.BR clearsign ", " detach-sign
Signs standard input to standard output, in place or detached (armored).
.TP
.BR \-\-help
A short help.
.SH KEEPING THE KEY SAFE
.IP \(bu 2
Making, renewing and restoring the key go ahead only at a quiet moment: the
network off, within 30 minutes of a restart, no window open but this terminal,
and nothing listed by the startup watch
.RB ( wren-watch ).
The backup's passphrase and the backup pass through programs running as you
then. Restart, log in, turn the network off
.RB ( "nmcli networking off" ),
and run it before anything else. A program already running as you could fake
these checks: they keep you from a bad moment, not from such a program.
.IP \(bu 2
Keep the backup on two USB sticks, in two places, away from this computer.
.IP \(bu 2
Keep the passphrase on paper, apart from the sticks: someone with both has
your key.
.IP \(bu 2
Keep the revocation certificate apart from the sticks too (printed, say):
whoever has it can void your key, though not sign with it.
.IP \(bu 2
Renew the subkey before it stops signing: after that every Wren Linux computer
refuses updates until a new key reaches it by hand.
.IP \(bu 2
If you think the signing subkey was taken (this computer was broken into),
make a new one from the backup, publish it, and say so.
.SH FILES
.TP
.I /usr/local/libexec/wren-signer
The signer, root's, run as wren-signer.
.TP
.I /var/lib/wren-signer
wren-signer's home: the signing subkey, readable by that user alone.
.TP
.I /etc/sudoers.d/wren-signer
What your user may run as wren-signer: the signer, with your password.
.TP
.I /etc/wren/signer.nft
The firewall rule that drops everything wren-signer sends.
.TP
.I ~/.local/share/wren/signing-key
What your user knows of the key: its fingerprint, until when it signs, and the
public key.
.SH ENVIRONMENT
.TP
.B WREN_DIR
The Wren Linux folder that
.BR git-setup ,
.B pin
and
.B sign-repo
use, if not the usual one.
.SH SEE ALSO
.BR wrenctl (1),
.BR gpg (1),
.IR docs/maintaining.md ,
.I THREAT-MODEL.md
in the Wren Linux folder.