Skip to content

Instantly share code, notes, and snippets.

@abeluck
Forked from KenMacD/cmd.md
Last active October 22, 2023 02:59
Show Gist options
  • Save abeluck/3383449 to your computer and use it in GitHub Desktop.
Save abeluck/3383449 to your computer and use it in GitHub Desktop.
GPG Offline Master Key w/ smartcard

About

This is a local copy of the commands from:

This guide serves as a reference of collected information necessary for strict management of PGP keys. This includes keeping a master key that always remains offline and while subkeys on an OpenPGP smart card. OpenPGP cards can be purchased at kernelconcepts.de. More information can be found at: http://g10code.com/p-card.html

Tails live privacy enhanced version of debian runs as a live CD or USB. This guide will assume you are using this. It currently lacks the necessary packages to use the smart cards so we will have to manually ferry those Debian packages to Tails. Abel on Github who I forked this Gist from is working on a customized version of Tails called 'Clean Room' that will include the necessary software and forcibly keep you offline. This guide will be updated to reflect that. Clean Room will also automate many of these tasks, but this guide will preserve all the information needed to do so manually. This will ensure you have to building blocks to manage your keys as you see fit. You might not have a PGP smartcard, but want to ensure you manage a offline master key for example The important principle is that you keep your master key offline.

Requirements

  • Bootable offline cd with gpg: http://tails.boum.org
  • OpenPGP smartcard
  • a card reader
  • your PIN
  • your Admin PIN
  • TWO USB sticks
    • one for master key backup
    • one to shuttle drivers, subkeys, and public keys between offline computer and your main computer.

Initial Commands

Setting up a Secure Environment

First, download tails from https://tails.boum.org/. Make sure to verify the iso image. Either burn it to a CD or USB drive. Instuctions for manually installing to a usb are found at https://tails.boum.org/doc/first_steps/manual_usb_installation/index.en.html

If you are using Linux to create a live USB then:

`apt-get install syslinux`
`isohybrid [tails.iso] --entry 4 --type 0x1c`
`cat [tails.iso] > [device] && sync`

Installing Smart Card Drivers

Install the smartcard driver and daemon packages: apt-get install libccid pcscd. You'll need to download the debs (apt-get download) from your work computer and place them on a USB so that you can transfer them to your live CD.

Specifically, I have found it necessary to manually download these .deb files from the wheezy release of Debian:

Download these and place on one of the USB drives

In the future Tails may support the smart card by default. See https://mailman.boum.org/pipermail/tails-dev/2012-January/000779.html and https://tails.boum.org/todo/support_OpenPGP_smartcards/.

Go offline

Reboot into the livecd, then disable the network. Install the smartcard packages from the USB drive.

Install using dpkg -i filename.deb and in the order listed above. May have to use --auto-deconfigure for libc6 package. Tested on Tails 12.1. You can use this script as well:

#/bin/bash
#Requires root! ('sudo su')
dpkg -i libc-bin_2.13-35_i386.deb
dpkg -i --auto-deconfigure libc6_2.13-35_i386.deb
dpkg -i multiarch-support_2.13-35_i386.deb
dpkg -i libpcsclite1_1.8.4-1_i386.deb
dpkg -i libccid_1.4.7-1_i386.deb
dpkg -i pcscd_1.8.4-1_i386.deb

Generate Master Key

I choose no expiration for the master key, and 1 year for subkeys. They can be extended any time later.

We generate the master key using the --expert flag to make sure the master key can only "certify" (sign other keys), and not sign or perform encryption.

$ gpg --expert --gen-key
gpg (GnuPG) 1.4.11; Copyright (C) 2010 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.

Please select what kind of key you want:
   (1) RSA and RSA (default)
   (2) DSA and Elgamal
   (3) DSA (sign only)
   (4) RSA (sign only)
   (7) DSA (set your own capabilities)
   (8) RSA (set your own capabilities)
Your selection? 8

Possible actions for a RSA key: Sign Certify Encrypt Authenticate 
Current allowed actions: Sign Certify Encrypt 

   (S) Toggle the sign capability
   (E) Toggle the encrypt capability
   (A) Toggle the authenticate capability
   (Q) Finished

Your selection? s

Possible actions for a RSA key: Sign Certify Encrypt Authenticate 
Current allowed actions: Certify Encrypt 

   (S) Toggle the sign capability
   (E) Toggle the encrypt capability
   (A) Toggle the authenticate capability
   (Q) Finished

Your selection? e

Possible actions for a RSA key: Sign Certify Encrypt Authenticate 
Current allowed actions: Certify 

   (S) Toggle the sign capability
   (E) Toggle the encrypt capability
   (A) Toggle the authenticate capability
   (Q) Finished

Your selection? q
RSA keys may be between 1024 and 4096 bits long.
What keysize do you want? (2048) 4096
Requested keysize is 4096 bits
Please specify how long the key should be valid.
     0 = key does not expire
      <n>  = key expires in n days
      <n>w = key expires in n weeks
      <n>m = key expires in n months
      <n>y = key expires in n years
Key is valid for? (0) 5y
Key expires at Tue  4 Oct 22:32:57 2016 ADT
Is this correct? (y/N) 

You need a user ID to identify your key; the software constructs the user ID
from the Real Name, Comment and Email Address in this form:
    "Heinrich Heine (Der Dichter) <heinrichh@duesseldorf.de>"

Real name: Kenny MacDermid
Email address: 
Comment: 
You selected this USER-ID:
    "Kenny MacDermid"

Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? o
You need a Passphrase to protect your secret key.

We need to generate a lot of random bytes. It is a good idea to perform
some other action (type on the keyboard, move the mouse, utilize the
disks) during the prime generation; this gives the random number
generator a better chance to gain enough entropy.
.....+++++
..............+++++
gpg: key 5AD20E1D marked as ultimately trusted
public and secret key created and signed.

gpg: checking the trustdb
gpg: 3 marginal(s) needed, 1 complete(s) needed, PGP trust model
gpg: depth: 0  valid:   4  signed:   0  trust: 0-, 0q, 0n, 0m, 0f, 4u
gpg: next trustdb check due at 2012-10-05
pub   4096R/5AD20E1D 2011-10-07 [expires: 2016-10-05]
      Key fingerprint = 2B85 0108 8296 B9FC 4FB8  AC86 8A4D 4610 5AD2 0E1D
uid                  Kenny MacDermid

Generate the sub keys

First we add the signing subkey, then the encryption subkey. Both are 3072 bits.

$ gpg --edit-key 5AD20E1D
gpg (GnuPG) 1.4.11; Copyright (C) 2010 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  4096R/5AD20E1D  created: 2011-10-07  expires: 2016-10-05  usage: C   
             trust: ultimate      validity: ultimate
[ultimate] (1). Kenny MacDermid

gpg> addkey
Key is protected.

You need a passphrase to unlock the secret key for
user: "Kenny MacDermid"
4096-bit RSA key, ID 5AD20E1D, created 2011-10-07

Please select what kind of key you want:
   (3) DSA (sign only)
   (4) RSA (sign only)
   (5) Elgamal (encrypt only)
   (6) RSA (encrypt only)
Your selection? 4
RSA keys may be between 1024 and 4096 bits long.
What keysize do you want? (2048) 3072
Requested keysize is 3072 bits
Please specify how long the key should be valid.
     0 = key does not expire
      <n>  = key expires in n days
      <n>w = key expires in n weeks
      <n>m = key expires in n months
      <n>y = key expires in n years
Key is valid for? (0) 1y
Key expires at Fri  5 Oct 22:42:39 2012 ADT
Is this correct? (y/N) y
Really create? (y/N) y
We need to generate a lot of random bytes. It is a good idea to perform
some other action (type on the keyboard, move the mouse, utilize the
disks) during the prime generation; this gives the random number
generator a better chance to gain enough entropy.
.........+++++
............+++++

pub  4096R/5AD20E1D  created: 2011-10-07  expires: 2016-10-05  usage: C   
             trust: ultimate      validity: ultimate
sub  3072R/8DD8FF1A  created: 2011-10-07  expires: 2012-10-06  usage: S   
[ultimate] (1). Kenny MacDermid

gpg> addkey
Key is protected.

You need a passphrase to unlock the secret key for
user: "Kenny MacDermid"
4096-bit RSA key, ID 5AD20E1D, created 2011-10-07

Please select what kind of key you want:
   (3) DSA (sign only)
   (4) RSA (sign only)
   (5) Elgamal (encrypt only)
   (6) RSA (encrypt only)
Your selection? 6
RSA keys may be between 1024 and 4096 bits long.
What keysize do you want? (2048) 3072
Requested keysize is 3072 bits
Please specify how long the key should be valid.
     0 = key does not expire
      <n>  = key expires in n days
      <n>w = key expires in n weeks
      <n>m = key expires in n months
      <n>y = key expires in n years
Key is valid for? (0) 1y
Key expires at Fri  5 Oct 22:43:07 2012 ADT
Is this correct? (y/N) y
Really create? (y/N) y
We need to generate a lot of random bytes. It is a good idea to perform
some other action (type on the keyboard, move the mouse, utilize the
disks) during the prime generation; this gives the random number
generator a better chance to gain enough entropy.
....+++++
.+++++

pub  4096R/5AD20E1D  created: 2011-10-07  expires: 2016-10-05  usage: C   
             trust: ultimate      validity: ultimate
sub  3072R/8DD8FF1A  created: 2011-10-07  expires: 2012-10-06  usage: S   
sub  3072R/9B51554C  created: 2011-10-07  expires: 2012-10-06  usage: E   
[ultimate] (1). Kenny MacDermid

gpg> save

Setup uids

UIDs can be added or deleted at any point in time. Just edit the key ID of your master key from Tails (the only time you should have access to your master key).

$ gpg --edit-key 5AD20E1D
gpg> adduid

If you type help at the gpg> prompt you can see other commands that let you perform other actions such as deleting uids.

Edit card content

gpg --card-edit

If you run this you will

Afterwards, your card content should look similar to this:

$ gpg --card-status
Application ID ...: D2760001240101010001000002290000
Version ..........: 1.1
Manufacturer .....: PPC Card Systems
Serial number ....: 00000229
Name of cardholder: Test Card User
Language prefs ...: en
Sex ..............: male
URL of public key : http://url.of/publickey.asc
Login data .......: [not set]
Private DO 1 .....: [not set]
Private DO 2 .....: [not set]
Signature PIN ....: forced
Max. PIN lengths .: 254 254 254
PIN retry counter : 3 3 3
Signature counter : 0
Signature key ....: [none]
Encryption key....: [none]
Authentication key: [none]
General key info..: [none]

Create Backups

Export the secret key for your identity key:

 $ gpg -a --export-secret-keys > master-secret-key.gpg

Export the secret keys for your subkeys (does NOT include master secret key):

 $ gpg -a --export-secret-subkeys > sub-secret-keys.gpg

Save Backups

Backup the following to the super-safe USB stick that is never plugged in to an online machine. Store this USB stick in your ork guarded vault:

  1. master-secret-key.gpg - copy of your master secret key
  2. sub-secret-keys.gpg - copy of your secret sub keys
  3. ~/.gnupg - your entire keyring. It will be used as the GNUPGHOME for future subkeys.

Move the subkeys to the card

Now we will transfer the subkeys generated before to the smartcard. The existing secret keys will be replaced by stubs. If your card gets damaged, you can repeat that step by simply using the backup we brought to the Orks.

The following was copy/pasted from the FSFE article, which uses a smaller key size. What we're doing here is selecting the encryption and signing subkeys and moving them to the card.

You can tell which subkey is which by looking at the usage: X, where X is S for signing or E for encryption.

After this is done, your secret-subkeys will only exist:

  1. On the smartcard

  2. On the ork-guarded USB stick (in the saved .gnupg/ and sub-secret-keys.gpg)

    $ gpg --edit-key 559C215F gpg (GnuPG) 1.4.9; Copyright (C) 2008 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 1024D/559C215F created: 2009-05-04 expires: never usage: SC
    trust: ultimate validity: ultimate
    sub 1024R/E1D9B30D created: 2009-05-13 expires: never usage: S
    sub 1024R/EDDA691E created: 2009-05-13 expires: never usage: E
    [ultimate] (1). Martin Gollowitzer (Testing environment) gollo@fsfe.org

    Command> toggle

    sec 1024D/559C215F created: 2009-05-04 expires: never
    ssb 1024R/E1D9B30D created: 2009-05-13 expires: never
    ssb 1024R/EDDA691E created: 2009-05-13 expires: never
    (1) Martin Gollowitzer (Testing environment) gollo@fsfe.org

    Command> key 1

    sec 1024D/559C215F created: 2009-05-04 expires: never

    ssb* 1024R/E1D9B30D created: 2009-05-13 expires: never
    ssb 1024R/EDDA691E created: 2009-05-13 expires: never
    (1) Martin Gollowitzer (Testing environment) gollo@fsfe.org

    Command> keytocard Signature key ....: [none] Encryption key....: [none] Authentication key: [none]

    Please select where to store the key: (1) Signature key (3) Authentication key Your selection? 1

    You need a passphrase to unlock the secret key for user: "Martin Gollowitzer (Testing environment) gollo@fsfe.org" 1024-bit RSA key, ID E1D9B30D, created 2009-05-13

    gpg: generating new key gpg: 3 Admin PIN attempts remaining before card is permanently locked

    Admin PIN

    MAY ASK FOR ADMIN PIN TWICE - this is OK! The first access resizes the key slot to 3072 bits, the second actually moves the key.

    sec 1024D/559C215F created: 2009-05-04 expires: never
    ssb* 1024R/E1D9B30D created: 2009-05-13 expires: never
    card-no: 0001 00000229 ssb 1024R/EDDA691E created: 2009-05-13 expires: never
    (1) Martin Gollowitzer (Testing environment) gollo@fsfe.org

    Command> key 1

    sec 1024D/559C215F created: 2009-05-04 expires: never

    ssb 1024R/E1D9B30D created: 2009-05-13 expires: never
    card-no: 0001 00000229 ssb 1024R/EDDA691E created: 2009-05-13 expires: never
    (1) Martin Gollowitzer (Testing environment) gollo@fsfe.org

    Command> key 2

    sec 1024D/559C215F created: 2009-05-04 expires: never
    ssb 1024R/E1D9B30D created: 2009-05-13 expires: never
    card-no: 0001 00000229 ssb* 1024R/EDDA691E created: 2009-05-13 expires: never
    (1) Martin Gollowitzer (Testing environment) gollo@fsfe.org

    Command> keytocard Signature key ....: [none] Encryption key....: [none] Authentication key: [none]

    Please select where to store the key: (2) Encryption key Your selection? 2

    You need a passphrase to unlock the secret key for user: "Martin Gollowitzer (Testing environment) gollo@fsfe.org" 1024-bit RSA key, ID EDDA691E, created 2009-05-13

    gpg: generating new key

    sec 1024D/559C215F created: 2009-05-04 expires: never
    ssb 1024R/E1D9B30D created: 2009-05-13 expires: never
    card-no: 0001 00000229 ssb* 1024R/EDDA691E created: 2009-05-13 expires: never
    card-no: 0001 00000229 (1) Martin Gollowitzer (Testing environment) gollo@fsfe.org

    Command> save

Export Stubs and Public Key

Export the public key for your identity key:

 $ gpg -a --export 5AD20E1D > pub-key.gpg

Export the secret key stubs for your subkeys. This doesn't include the actual secret keys since they were moved to the smart card, but act as a pointer of sorts to your smartcard. When you import this and your public key to your work computer gnupg will know to look on your smart card when it needs to access one of your private subkeys.

 $ gpg -a --export-secret-subkeys > sub-key-stubs.gpg

Backup pub-key.gpg and sub-key-stubs.gpg to the other USB stick that you used to transfer the drivers. This will be imported on your main machine.

Import keys on main machine

Reboot into your main machine. Insert the usb key from above.

$ gpg --import pub-key.gpg
gpg: key 5AD20E1D: public key "Kenny MacDermid" imported
gpg: Total number processed: 1
gpg:               imported: 1  (RSA: 1)
$ gpg --import sub-key-stubs.gpg
gpg: key 5AD20E1D: secret key imported
gpg:   secret keys imported: 1
$ gpg --list-secret-keys
sec#  4096R/5AD20E1D 2011-10-07 [expires: 2016-10-05]
uid                  Kenny MacDermid
ssb   2048R/8DD8FF1A 2011-10-07
ssb   2048R/9B51554C 2011-10-07

The secret key should say sec# instead of sec.

Mark your master key as ultimately trusted:

$ gpg --edit-key <UID or KeyID>
>gpg trust
Your Decision? 5

Using the smart card without root

You may want to use gpg from your user account on your local computer. If the pcscd package is installed you just need to add your user to the group pcscd.

Updating subkeys

You should update (read: replace) your subkeys when:

  • Your subkeys are about to expire --> Follow A
  • Your subkeys already expired --> Follow A
  • Your smartcard is lost/stolen/broken --> Follow B
  • You want to change your subkey size --> Follow B

A) To change the expiration date of the subkeys:

  1. Boot into your secure environment with your master key loaded into the keyring
  2. Use key N to select your subkeys
  3. Use expire to change the expiration date
  4. save and quit
  5. export-all

B) To replace your subkeys:

  1. Boot into your secure environment with your master key loaded into the keyring
  2. Follow the "Generate the sub keys" section, to add new subkeys
  3. Select the old subkeys using key N
  4. delkey to delete the keys
  5. export-all

Update the subkeys to the card

Follow the section "Move the subkeys to the card" but using your new subkeys.

Helper Scripts

  • soon

TODO

  • Signing other peoples keys.
  • Figure out importing signatures.
  • Generate and backup revocation certificate gpg --output revoke.asc --gen-revoke KEYNAME?
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment