.. include:: /urls.rst .. _librem_key_gpg: GPG Keys ======== Most tools required to manage GPG keys on your Librem Key are pre-installed in PureOS or other Linux distributions. However, the ``scdaemon`` package, essential for detecting and managing OpenPGP Smart Cards, may not be installed by default. To install ``scdaemon``, :ref:`open a terminal ` and run the following command: .. code-block:: bash sudo apt install scdaemon While your Librem Key can generate GPG keys directly on the device, this approach has a significant drawback: you will not have any backups of the keys. If you intend to use your GPG key for email encryption and signing, it is advisable to generate the key on a computer where you can create a backup. Conversely, if your primary use of the Librem Key is for tamper-evident boot with Heads, you may not require a backup. In this case, you can still boot into your operating system and replace the current key in Heads with a different one if you ever lose the Librem Key. Detecting an OpenPGP smart card ------------------------------- To detect your OpenPGP Smart Card, :ref:`open a terminal ` and run: .. code-block:: bash gpg --card-status You will see output like: .. code-block:: 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] .. _librem_key_pin: Change or unblock a PIN on the Librem Key ----------------------------------------- Librem Key :ref:`default user and admin PINs ` are easy to guess. It is good practice to change the default PIN to something else after receiving your Librem Key. #. :ref:`Open a terminal ` and enter the interactive GPG card edit menu: .. code-block:: bash 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: .. code-block:: admin passwd .. note:: If you forget your PIN or enter it incorrectly too many times, the smart card will automatically block that user PIN. The GPG admin PIN must be used to unlock it. #. This uses the same commands as to change the PIN: .. code-block:: admin passwd #. Once you are finished, type ``quit`` to exit. .. tip:: If you get stuck, type ``help`` for more documentation on the available commands. .. _librem_key_gpg_gen: Generate GPG keys on a 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. :ref:`In a terminal `, run: .. code-block:: bash 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. .. note:: 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 the time the key is cracked, you will have already switched to a new key and therefore protected all further communications. Whether or not you set an expiration date 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: .. code-block:: gpg -k youremail@yourdomain.com pub rsa4096/0xBD83B92B2F4BFD99 2018-01-11 [SC] Key fingerprint = 7B85 0961 8D82 0DF6 3924 1BB6 BD83 B92B 2F4B FD99 uid [ unknown] Firstname Lastname The first line in the output shows you the key id (in my case 0xBD83B92B2F4BFD99): .. code-block:: 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: .. code-block:: gpg -k 0xBD83B92B2F4BFD99 pub rsa4096/0xBD83B92B2F4BFD99 2018-01-11 [SC] Key fingerprint = 7B85 0961 8D82 0DF6 3924 1BB6 BD83 B92B 2F4B FD99 uid [ unknown] Firstname Lastname .. _librem_key_gpg_subkeys: Add subkeys to your GPG keys ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Your Librem Key does not store your master GPG key; the master key only signs other GPG keys. An encryption subkey is automatically created when a master key is generated, but you must generate additional signing and authentication subkeys. These three subkeys will get stored and used on the Librem Key. To generate subkeys, you will need to edit the key you just created. #. :ref:`Open a terminal ` and run the following command: .. code-block:: bash gpg --expert --edit-key .. tip:: This command launches 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). #. Create a new signing subkey: .. code-block:: addkey 4 4096 0 #. Now 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: .. code-block:: 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: .. code-block:: trust 5 save Now you will be back to a normal terminal prompt. .. _librem_key_gpg_backup: Backing up 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 is lost or compromised. :ref:`Open a terminal ` and run the following command: .. code-block:: bash gpg --output revoke.asc --gen-revoke Then you can back up the revoke.asc file that command generates. .. _librem_key_gpg_backup_everything: Back up the entire GNUPG directory ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ There are two main ways to back up your GPG keys. The first is to copy your entire ``~/.gnupg`` directory to a USB flash drive. Assuming it is mounted at ``/media/kyle/8439-AFIJ`` (your PureOS desktop will automatically mount a USB flash 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 flash drive. In a :ref:`terminal `, you could type: .. code-block:: bash 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. .. _librem_key_gpg_backup_keys: Back up just the keys ^^^^^^^^^^^^^^^^^^^^^ If you just want to back up your keys, you can export them separately. :ref:`Open a terminal ` and run the following commands: .. code-block:: bash gpg --armor --output privkey.sec --export-secret-key gpg --armor --output subkey.sec --export-secret-subkeys gpg --armor --output pubkey.asc --export Now you can copy the ``privkey.sec``, ``subkey.sec``, ``pubkey.asc`` and the ``revoke.asc`` to a USB flash drive: .. code-block:: bash 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. .. _librem_key_move_keys: Move GPG subkeys to a Librem Key -------------------------------- To transfer your GPG subkeys to a Librem Key, first insert the Librem Key and make sure that ``gpg --card-status`` shows that it has detected the key: .. code-block:: 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: .. code-block:: 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: .. code-block:: bash gpg --expert --edit-key In the output you will see a few subkeys listed: .. code-block:: $ gpg --expert --edit-key youremail@yourdomain.com 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). Firstname Lastname Now inside the ``gpg>`` prompt, type ``key 1`` to select the first subkey. This will add an asterisk next to the "ssb" column for that key in the output: .. code-block:: 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). Firstname Lastname 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: .. code-block:: 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: .. code-block:: 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: .. code-block:: key 2 key 3 keytocard save Generate GPG subkeys on a 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. #. :ref:`Open a terminal ` and enter the GPG card edit menu: .. code-block:: bash gpg --card-edit #. From the ``gpg/card>`` prompt, type ``admin`` to enter admin mode #. Type ``generate`` to generate new keys on the device: .. code-block:: 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 is recommended. #. Type ``quit`` to exit the menu when you are finished: .. code-block:: quit #. At the very least you will want a copy of your public key, so type: .. code-block:: bash gpg --armor --output pubkey.asc --export You can now share ``pubkey.asc`` with a public key server or anyone you want to send you encrypted communications.