Managing GPG Keys¶
Most of the tools (like GPG) you need to manage GPG keys on your Librem Key should already be installed in PureOS or any other Linux distribution you might use, with the exception of scdaemon.
This daemon manages OpenPGP smart cards on the system and may not be installed by default, so use your package manager to install the scdaemon package.
If you want to use the command line you can type:
sudo apt install scdaemon
This will be necessary before you proceed to detect your OpenPGP Smart Card.
While your Librem Key can generate GPG keys on the device itself, doing so means you have no backups. If you plan to use your GPG key for email encryption and signing, then you will want to generate it on a computer so you can back it up. If you plan to just use the Librem Key for tamper-evident boot with Heads, then you may not need a backup of the key since you can still boot into your OS and can replace the current key in Heads with a different one later if you ever lose the Librem Key.
Detecting Your OpenPGP Smart Card¶
To detect your OpenPGP Smart Card, open a terminal application (hit the Purism logo key on your keyboard and type “terminal” in the window that appears) and then type:
gpg --card-status
You will see output like:
gpg --card-status
Reader ...........: 20A0:4108:000000000000000000006143:0
Application ID ...: D2760001240103030005000061430000
Version ..........: 3.3
Manufacturer .....: ZeitControl
Serial number ....: 00006143
Name of cardholder: [not set]
Language prefs ...: de
Sex ..............: unspecified
URL of public key : [not set]
Login data .......: [not set]
Signature PIN ....: forced
Key attributes ...: rsa2048 rsa2048 rsa2048
Max. PIN lengths .: 64 64 64
PIN retry counter : 3 0 3
Signature counter : 4
Signature key ....: [none]
Encryption key....: [none]
Authentication key: [none]
General key info..: [none]
Change or Unblock a PIN on the Librem Key¶
By default the user PIN on the Librem Key is 123456 and the admin PIN is 12345678 which are easy to guess.
it is good practice to change the default PIN to something else after receiving your Librem Key.
First enter the interactive GPG card edit menu:
gpg --card-edit
Now in the gpg/card> prompt type admin to enter admin mode and then passwd to change the PIN on your Librem Key:
admin
passwd
If you forget your PIN or enter it incorrectly too many times, the smart card will automatically block that user PIN and you will have to enter your GPG admin PIN to unlock it. This uses the same commands as to change the PIN:
admin
passwd
Once you are finished, you can type quit to exit.
If you get stuck, type help for more documentation on the available commands.
Generate GPG Keys On Your Computer¶
For most people facing average threats, it’s better to generate the GPG keys on your computer, back them up, and then transfer them to your Librem Key instead of generating them directly on the Librem Key. Otherwise, if you lose the Librem Key you won’t be able to restore your private GPG keys to a replacement.
The first step is to generate the key itself:
gpg --gen-key
This command will generate the master key used to sign any other GPG subkeys. You will be prompted for the name and email address to use for this key. If you intend on using this key to encrypt and sign email, be sure you specify the proper email address you intend to use.
When prompted to set an expiration date, either select the default (0) so the key doesn’t expire, or specify a particular date that the key will expire. The idea behind key expiry is to protect against an attacker who may have the capability in the future to crack your GPG private key, given enough time. By setting an expiration date of, for instance, a few years into the future, you are betting that it will take the attacker longer than that to crack the key or find a flaw in the current encryption used for the key. By that time you will have switched to a new key and all communications going forward will be protected. Whether you set an expiration date or not largely depends on your personal threat model, and the amount of effort you are willing to spend to generate fresh keys.
Your master key will have its own unique long ID you can use to refer to it, in case you have multiple GPG keys that have the same email address assigned to them:
gpg -k kyle.rankin@puri.sm
pub rsa4096/0xBD83B92B2F4BFD99 2018-01-11 [SC]
Key fingerprint = 7B85 0961 8D82 0DF6 3924 1BB6 BD83 B92B 2F4B FD99
uid [ unknown] Kyle Rankin <kyle.rankin@puri.sm>
The first line in the output shows you the key id (in my case 0xBD83B92B2F4BFD99):
pub rsa4096/0xBD83B92B2F4BFD99 2018-01-11 [SC]
In the above example I referred to my key by its email address, but I could also use its id 0xBD83B92B2F4BFD99:
gpg -k 0xBD83B92B2F4BFD99
pub rsa4096/0xBD83B92B2F4BFD99 2018-01-11 [SC]
Key fingerprint = 7B85 0961 8D82 0DF6 3924 1BB6 BD83 B92B 2F4B FD99
uid [ unknown] Kyle Rankin <kyle.rankin@puri.sm>
Add Subkeys to Your GPG Keys¶
Your Librem Key will not hold your master GPG key. That key will only be used to sign other GPG keys. When you generate your master key it automatically generates a subkey specifically for encryption, but you will need to generate additional subkeys for signing, and authentication and it’s these three subkeys that will get stored and used from the Librem Key.
To generate subkeys, you will need to edit the key you just created:
gpg --expert --edit-key <youremail@yourdomain.com>
This command will launch an interactive gpg> prompt where you can enter specific commands. The addkey command will create a new subkey under your master key and walk you through questions about:
key type (this will vary depending on which subkey you create)
key size (use 4096)
key expiration date (if in doubt, pick a similar expiration date to the one you used for your master key, or optionally a shorter one as it’s easier to rotate subkeys compared to a master key). For this example I picked no expiration date (0).
First create a new signing subkey:
addkey
4
4096
0
Then create the authentication subkey. This one is a bit special as you will have to disable Signing and Encryption capabilities and enable authenticate capabilities to generate this key:
addkey
8
S
E
A
Q
4096
0
Now that the subkeys are created, you should set the public key to the ultimate trust level and then save:
trust
5
save
Now you will be back to a normal terminal prompt.
Back Up your GPG Keys¶
The act of transferring subkeys over to the Librem Key will erase them on your current system, so you will want to back them up to removable media like one or two separate USB thumb drives. You can then store those keys in a safe, safe-deposit box, or other secure place. The advantage of backing up on two USB thumb drives is that you can store one on-site and one off-site.
Before backing everything up, you should generate a revocation certificate for your key. With this backed up somewhere, you will be able to revoke your key in case it’s ever compromised or you lose it:
gpg --output revoke.asc --gen-revoke <youremail@yourdomain.com>
Then you can back up the revoke.asc file that command generates.
Back Up the Whole GNUPG Directory¶
There are two main ways to back up your GPG keys.
The first is to just copy your entire ~/.gnupg directory over to a thumb drive.
Let’s say it is mounted at /media/kyle/8439-AFIJ (your PureOS desktop will automatically mount a thumb drive in a location like that when you insert it) you could use the GUI file manager to copy and paste the /home/yourusername/.gnupg directory over to the thumb drive, or in a terminal you could type:
cp -a ~/.gnupg /media/kyle/8439-AFIJ/
cp revoke.asc /media/kyle/8439-AFIJ/
Remember to change the destination directory to match wherever your thumb drive was mounted.
If in doubt, you can type the mount command to get a list of the currently mounted file systems.
Back Up Just Your Keys¶
If you just want to back up your keys, you can export them separately:
gpg --armor --output privkey.sec --export-secret-key <youremail@yourdomain.com>
gpg --armor --output subkey.sec --export-secret-subkeys <youremail@yourdomain.com>
gpg --armor --output pubkey.asc --export <youremail@yourdomain.com>
Now you can copy the privkey.sec, subkey.sec, pubkey.asc and the revoke.asc to a thumb drive:
cp privkey.sec subkey.sec pubkey.asc revoke.asc /media/kyle/8439-AFIJ/
Once you have backed them up, be sure to delete the privkey.sec, subkey.sec and revoke.asc files.
Move GPG Subkeys Over to The Librem Key¶
To transfer your GPG subkeys over to the Librem Key, first insert the Librem Key and make sure that gpg --card-status shows that it has detected the key:
gpg --card-status
Reader ...........: 20A0:4108:000000000000000000006143:0
Application ID ...: D2760001240103030005000061430000
Version ..........: 3.3
Manufacturer .....: ZeitControl
Serial number ....: 00006143
Name of cardholder: [not set]
Language prefs ...: de
Sex ..............: unspecified
URL of public key : [not set]
Login data .......: [not set]
Signature PIN ....: forced
Key attributes ...: rsa2048 rsa2048 rsa2048
Max. PIN lengths .: 64 64 64
PIN retry counter : 3 0 3
Signature counter : 4
Signature key ....: [none]
Encryption key....: [none]
Authentication key: [none]
General key info..: [none]
In this output you can see that no signature, encryption or authentication keys have been loaded:
Signature key ....: [none]
Encryption key....: [none]
Authentication key: [none]
General key info..: [none]
To copy keys over, we go back to the interactive GPG menu that shows up when we edit our key:
gpg --expert --edit-key <youremail@yourdomain.com>
In the output you will see a few subkeys listed:
$ gpg --expert --edit-key kyle.rankin@puri.sm
gpg (GnuPG) 2.1.18; Copyright (C) 2017 Free Software Foundation, Inc.
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
Secret key is available.
pub rsa4096/0xBD83B92B2F4BFD99
created: 2018-01-11 expires: never usage: SC
trust: ultimate validity: ultimate
ssb rsa2048/0x6A6F096B8E4C29C9
created: 2018-01-11 expires: never usage: E
ssb rsa2048/0x555577116BFA74B9
created: 2018-01-11 expires: never usage: S
ssb rsa2048/0x1801C77F078C5DEE
created: 2018-01-11 expires: never usage: A
[ unknown] (1). Kyle Rankin <kyle.rankin@puri.sm>
Now inside the gpg> prompt we will type key 1 to select the first subkey which will add an asterisk next to the “ssb” column for that key in the output:
key 1
pub rsa4096/0xBD83B92B2F4BFD99
created: 2018-01-11 expires: never usage: SC
trust: unknown validity: unknown
ssb* rsa2048/0x6A6F096B8E4C29C9
created: 2018-01-11 expires: never usage: E
ssb rsa2048/0x555577116BFA74B9
created: 2018-01-11 expires: never usage: S
ssb rsa2048/0x1801C77F078C5DEE
created: 2018-01-11 expires: never usage: A
[ unknown] (1). Kyle Rankin <kyle.rankin@puri.sm>
Now type the keytocard command to move that key over to the smart card.
When prompted tell it that you want to select 2, your Encryption key:
keytocard
Next you will type key 1 to untoggle key 1, then type key 2 to toggle key 2, and type keytocard to add that to your Librem Key.
When prompted tell it that you want to select 1, your Signature Key:
key 1
key 2
keytocard
Finally you will type key 2 to untoggle key 2, then type key 3 to toggle key 3, and type keytocard to add that to your Librem Key.
When prompted tell it that you want to select 3, your Authentication Key.
Then save to exit:
key 2
key 3
keytocard
save
Factory Reset GPG Keys on The Librem Key¶
If you ever want to delete all of the keys, passwords, and settings on the Librem Key you will need to enter the card edit menu for GPG:
gpg --card-edit
Then from the gpg/card> prompt you will type admin to enter admin mode and then factory-reset to erase keys and PINs and refer to factory settings:
admin
factory-reset
Generate GPG Subkeys on The Librem Key¶
If you do decide that you want your GPG keys to only exist on the Librem Key, you can generate them directly on that device. First enter the GPG card edit menu:
gpg --card-edit
Then from the gpg/card> prompt type admin to enter admin mode and then generate to generate new keys on the device:
admin
generate
Follow the interactive prompts to generate the keys.
You should be prompted with the option to export a copy of your keys to back them up, which I recommend you do.
Type quit to exit the menu when you are done:
quit
At the very least you will want a copy of your public key, so type:
gpg --armor --output pubkey.asc --export <youremail@yourdomain.com>
Then you can share pubkey.asc with a public key server or anyone you want to send you encrypted communications.
Changing Librem Key Language Settings¶
The Librem Key currently defaults to German as its on-board GPG language setting. This means when you plug it in, you might get a desktop prompt in German instead of English. To change the default language used by the Librem Key for GPG, first enter the GPG card edit menu:
gpg --card-edit
Then from the gpg/card> prompt type admin to enter admin mode and then lang to change the language.
For instance to change it from German to English, set it to en when you see the Language preferences: prompt:
admin
lang
Then type quit to exit the menu when you are done:
quit
Automatically Locking the Desktop When Removing the Librem Key¶
Through the use of a simple script and udev rules, you can have your computer lock the screen when you pull out your Librem Key.
This integration requires two files: /etc/udev/rules.d/85-libremkey.rules and /usr/local/bin/gnome-screensaver-lock:
ACTION=="remove", ENV{PRODUCT}=="316d/4c4b/101" RUN+="/usr/local/bin/gnome-screensaver-lock"
#!/bin/sh
user=`ps aux | egrep "gdm-(wayland|x)-session" | head -n 1 | awk '{print $1}'`
if [ -n $user ]; then
su $user -c "/usr/bin/dbus-send --type=method_call --dest=org.gnome.ScreenSaver /org/gnome/ScreenSaver org.gnome.ScreenSaver.Lock"
fi
You will need to trigger udev to reload upon installation so it picks up the new rule. You can do that this way:
systemctl restart udev
Using the Librem Key with Heads¶
TODO: This section will be incomplete until we finalize the initial Heads UI. In the meantime, The Librem Key Makes Tamper Detection Easy describes how the Librem Key integrates with Heads.