cachepc-linux

Fork of AMDESE/linux with modifications for CachePC side-channel attack
git clone https://git.sinitax.com/sinitax/cachepc-linux
Log | Files | Refs | README | LICENSE | sfeed.txt

maintainer-pgp-guide.rst (38190B)


      1.. _pgpguide:
      2
      3===========================
      4Kernel Maintainer PGP guide
      5===========================
      6
      7:Author: Konstantin Ryabitsev <konstantin@linuxfoundation.org>
      8
      9This document is aimed at Linux kernel developers, and especially at
     10subsystem maintainers. It contains a subset of information discussed in
     11the more general "`Protecting Code Integrity`_" guide published by the
     12Linux Foundation. Please read that document for more in-depth discussion
     13on some of the topics mentioned in this guide.
     14
     15.. _`Protecting Code Integrity`: https://github.com/lfit/itpol/blob/master/protecting-code-integrity.md
     16
     17The role of PGP in Linux Kernel development
     18===========================================
     19
     20PGP helps ensure the integrity of the code that is produced by the Linux
     21kernel development community and, to a lesser degree, establish trusted
     22communication channels between developers via PGP-signed email exchange.
     23
     24The Linux kernel source code is available in two main formats:
     25
     26- Distributed source repositories (git)
     27- Periodic release snapshots (tarballs)
     28
     29Both git repositories and tarballs carry PGP signatures of the kernel
     30developers who create official kernel releases. These signatures offer a
     31cryptographic guarantee that downloadable versions made available via
     32kernel.org or any other mirrors are identical to what these developers
     33have on their workstations. To this end:
     34
     35- git repositories provide PGP signatures on all tags
     36- tarballs provide detached PGP signatures with all downloads
     37
     38.. _devs_not_infra:
     39
     40Trusting the developers, not infrastructure
     41-------------------------------------------
     42
     43Ever since the 2011 compromise of core kernel.org systems, the main
     44operating principle of the Kernel Archives project has been to assume
     45that any part of the infrastructure can be compromised at any time. For
     46this reason, the administrators have taken deliberate steps to emphasize
     47that trust must always be placed with developers and never with the code
     48hosting infrastructure, regardless of how good the security practices
     49for the latter may be.
     50
     51The above guiding principle is the reason why this guide is needed. We
     52want to make sure that by placing trust into developers we do not simply
     53shift the blame for potential future security incidents to someone else.
     54The goal is to provide a set of guidelines developers can use to create
     55a secure working environment and safeguard the PGP keys used to
     56establish the integrity of the Linux kernel itself.
     57
     58.. _pgp_tools:
     59
     60PGP tools
     61=========
     62
     63Use GnuPG v2
     64------------
     65
     66Your distro should already have GnuPG installed by default, you just
     67need to verify that you are using version 2.x and not the legacy 1.4
     68release -- many distributions still package both, with the default
     69``gpg`` command invoking GnuPG v.1. To check, run::
     70
     71    $ gpg --version | head -n1
     72
     73If you see ``gpg (GnuPG) 1.4.x``, then you are using GnuPG v.1. Try the
     74``gpg2`` command (if you don't have it, you may need to install the
     75gnupg2 package)::
     76
     77    $ gpg2 --version | head -n1
     78
     79If you see ``gpg (GnuPG) 2.x.x``, then you are good to go. This guide
     80will assume you have the version 2.2 of GnuPG (or later). If you are
     81using version 2.0 of GnuPG, then some of the commands in this guide will
     82not work, and you should consider installing the latest 2.2 version of
     83GnuPG. Versions of gnupg-2.1.11 and later should be compatible for the
     84purposes of this guide as well.
     85
     86If you have both ``gpg`` and ``gpg2`` commands, you should make sure you
     87are always using GnuPG v2, not the legacy version. You can enforce this
     88by setting the appropriate alias::
     89
     90    $ alias gpg=gpg2
     91
     92You can put that in your ``.bashrc`` to make sure it's always the case.
     93
     94Configure gpg-agent options
     95~~~~~~~~~~~~~~~~~~~~~~~~~~~
     96
     97The GnuPG agent is a helper tool that will start automatically whenever
     98you use the ``gpg`` command and run in the background with the purpose
     99of caching the private key passphrase. There are two options you should
    100know in order to tweak when the passphrase should be expired from cache:
    101
    102- ``default-cache-ttl`` (seconds): If you use the same key again before
    103  the time-to-live expires, the countdown will reset for another period.
    104  The default is 600 (10 minutes).
    105- ``max-cache-ttl`` (seconds): Regardless of how recently you've used
    106  the key since initial passphrase entry, if the maximum time-to-live
    107  countdown expires, you'll have to enter the passphrase again. The
    108  default is 30 minutes.
    109
    110If you find either of these defaults too short (or too long), you can
    111edit your ``~/.gnupg/gpg-agent.conf`` file to set your own values::
    112
    113    # set to 30 minutes for regular ttl, and 2 hours for max ttl
    114    default-cache-ttl 1800
    115    max-cache-ttl 7200
    116
    117.. note::
    118
    119    It is no longer necessary to start gpg-agent manually at the
    120    beginning of your shell session. You may want to check your rc files
    121    to remove anything you had in place for older versions of GnuPG, as
    122    it may not be doing the right thing any more.
    123
    124Set up a refresh cronjob
    125~~~~~~~~~~~~~~~~~~~~~~~~
    126
    127You will need to regularly refresh your keyring in order to get the
    128latest changes on other people's public keys, which is best done with a
    129daily cronjob::
    130
    131    @daily /usr/bin/gpg2 --refresh >/dev/null 2>&1
    132
    133Check the full path to your ``gpg`` or ``gpg2`` command and use the
    134``gpg2`` command if regular ``gpg`` for you is the legacy GnuPG v.1.
    135
    136.. _master_key:
    137
    138Protect your master PGP key
    139===========================
    140
    141This guide assumes that you already have a PGP key that you use for Linux
    142kernel development purposes. If you do not yet have one, please see the
    143"`Protecting Code Integrity`_" document mentioned earlier for guidance
    144on how to create a new one.
    145
    146You should also make a new key if your current one is weaker than 2048 bits
    147(RSA).
    148
    149Master key vs. Subkeys
    150----------------------
    151
    152Subkeys are fully independent PGP keypairs that are tied to the "master"
    153key using certifying key signatures (certificates). It is important to
    154understand the following:
    155
    1561. There are no technical differences between the "master key" and "subkeys."
    1572. At creation time, we assign functional limitations to each key by
    158   giving it specific capabilities.
    1593. A PGP key can have 4 capabilities:
    160
    161   - **[S]** key can be used for signing
    162   - **[E]** key can be used for encryption
    163   - **[A]** key can be used for authentication
    164   - **[C]** key can be used for certifying other keys
    165
    1664. A single key may have multiple capabilities.
    1675. A subkey is fully independent from the master key. A message
    168   encrypted to a subkey cannot be decrypted with the master key. If you
    169   lose your private subkey, it cannot be recreated from the master key
    170   in any way.
    171
    172The key carrying the **[C]** (certify) capability is considered the
    173"master" key because it is the only key that can be used to indicate
    174relationship with other keys. Only the **[C]** key can be used to:
    175
    176- add or revoke other keys (subkeys) with S/E/A capabilities
    177- add, change or revoke identities (uids) associated with the key
    178- add or change the expiration date on itself or any subkey
    179- sign other people's keys for web of trust purposes
    180
    181By default, GnuPG creates the following when generating new keys:
    182
    183- A master key carrying both Certify and Sign capabilities (**[SC]**)
    184- A separate subkey with the Encryption capability (**[E]**)
    185
    186If you used the default parameters when generating your key, then that
    187is what you will have. You can verify by running ``gpg --list-secret-keys``,
    188for example::
    189
    190    sec   rsa2048 2018-01-23 [SC] [expires: 2020-01-23]
    191          000000000000000000000000AAAABBBBCCCCDDDD
    192    uid           [ultimate] Alice Dev <adev@kernel.org>
    193    ssb   rsa2048 2018-01-23 [E] [expires: 2020-01-23]
    194
    195Any key carrying the **[C]** capability is your master key, regardless
    196of any other capabilities it may have assigned to it.
    197
    198The long line under the ``sec`` entry is your key fingerprint --
    199whenever you see ``[fpr]`` in the examples below, that 40-character
    200string is what it refers to.
    201
    202Ensure your passphrase is strong
    203--------------------------------
    204
    205GnuPG uses passphrases to encrypt your private keys before storing them on
    206disk. This way, even if your ``.gnupg`` directory is leaked or stolen in
    207its entirety, the attackers cannot use your private keys without first
    208obtaining the passphrase to decrypt them.
    209
    210It is absolutely essential that your private keys are protected by a
    211strong passphrase. To set it or change it, use::
    212
    213    $ gpg --change-passphrase [fpr]
    214
    215Create a separate Signing subkey
    216--------------------------------
    217
    218Our goal is to protect your master key by moving it to offline media, so
    219if you only have a combined **[SC]** key, then you should create a separate
    220signing subkey::
    221
    222    $ gpg --quick-addkey [fpr] ed25519 sign
    223
    224Remember to tell the keyservers about this change, so others can pull down
    225your new subkey::
    226
    227    $ gpg --send-key [fpr]
    228
    229.. note:: ECC support in GnuPG
    230
    231    GnuPG 2.1 and later has full support for Elliptic Curve
    232    Cryptography, with ability to combine ECC subkeys with traditional
    233    RSA master keys. The main upside of ECC cryptography is that it is
    234    much faster computationally and creates much smaller signatures when
    235    compared byte for byte with 2048+ bit RSA keys. Unless you plan on
    236    using a smartcard device that does not support ECC operations, we
    237    recommend that you create an ECC signing subkey for your kernel
    238    work.
    239
    240    If for some reason you prefer to stay with RSA subkeys, just replace
    241    "ed25519" with "rsa2048" in the above command. Additionally, if you
    242    plan to use a hardware device that does not support ED25519 ECC
    243    keys, like Nitrokey Pro or a Yubikey, then you should use
    244    "nistp256" instead or "ed25519."
    245
    246
    247Back up your master key for disaster recovery
    248---------------------------------------------
    249
    250The more signatures you have on your PGP key from other developers, the
    251more reasons you have to create a backup version that lives on something
    252other than digital media, for disaster recovery reasons.
    253
    254The best way to create a printable hardcopy of your private key is by
    255using the ``paperkey`` software written for this very purpose. See ``man
    256paperkey`` for more details on the output format and its benefits over
    257other solutions. Paperkey should already be packaged for most
    258distributions.
    259
    260Run the following command to create a hardcopy backup of your private
    261key::
    262
    263    $ gpg --export-secret-key [fpr] | paperkey -o /tmp/key-backup.txt
    264
    265Print out that file (or pipe the output straight to lpr), then take a
    266pen and write your passphrase on the margin of the paper. **This is
    267strongly recommended** because the key printout is still encrypted with
    268that passphrase, and if you ever change it you will not remember what it
    269used to be when you had created the backup -- *guaranteed*.
    270
    271Put the resulting printout and the hand-written passphrase into an envelope
    272and store in a secure and well-protected place, preferably away from your
    273home, such as your bank vault.
    274
    275.. note::
    276
    277    Your printer is probably no longer a simple dumb device connected to
    278    your parallel port, but since the output is still encrypted with
    279    your passphrase, printing out even to "cloud-integrated" modern
    280    printers should remain a relatively safe operation. One option is to
    281    change the passphrase on your master key immediately after you are
    282    done with paperkey.
    283
    284Back up your whole GnuPG directory
    285----------------------------------
    286
    287.. warning::
    288
    289    **!!!Do not skip this step!!!**
    290
    291It is important to have a readily available backup of your PGP keys
    292should you need to recover them. This is different from the
    293disaster-level preparedness we did with ``paperkey``. You will also rely
    294on these external copies whenever you need to use your Certify key --
    295such as when making changes to your own key or signing other people's
    296keys after conferences and summits.
    297
    298Start by getting a small USB "thumb" drive (preferably two!) that you
    299will use for backup purposes. You will need to encrypt them using LUKS
    300-- refer to your distro's documentation on how to accomplish this.
    301
    302For the encryption passphrase, you can use the same one as on your
    303master key.
    304
    305Once the encryption process is over, re-insert the USB drive and make
    306sure it gets properly mounted. Copy your entire ``.gnupg`` directory
    307over to the encrypted storage::
    308
    309    $ cp -a ~/.gnupg /media/disk/foo/gnupg-backup
    310
    311You should now test to make sure everything still works::
    312
    313    $ gpg --homedir=/media/disk/foo/gnupg-backup --list-key [fpr]
    314
    315If you don't get any errors, then you should be good to go. Unmount the
    316USB drive, distinctly label it so you don't blow it away next time you
    317need to use a random USB drive, and put in a safe place -- but not too
    318far away, because you'll need to use it every now and again for things
    319like editing identities, adding or revoking subkeys, or signing other
    320people's keys.
    321
    322Remove the master key from  your homedir
    323----------------------------------------
    324
    325The files in our home directory are not as well protected as we like to
    326think.  They can be leaked or stolen via many different means:
    327
    328- by accident when making quick homedir copies to set up a new workstation
    329- by systems administrator negligence or malice
    330- via poorly secured backups
    331- via malware in desktop apps (browsers, pdf viewers, etc)
    332- via coercion when crossing international borders
    333
    334Protecting your key with a good passphrase greatly helps reduce the risk
    335of any of the above, but passphrases can be discovered via keyloggers,
    336shoulder-surfing, or any number of other means. For this reason, the
    337recommended setup is to remove your master key from your home directory
    338and store it on offline storage.
    339
    340.. warning::
    341
    342    Please see the previous section and make sure you have backed up
    343    your GnuPG directory in its entirety. What we are about to do will
    344    render your key useless if you do not have a usable backup!
    345
    346First, identify the keygrip of your master key::
    347
    348    $ gpg --with-keygrip --list-key [fpr]
    349
    350The output will be something like this::
    351
    352    pub   rsa2048 2018-01-24 [SC] [expires: 2020-01-24]
    353          000000000000000000000000AAAABBBBCCCCDDDD
    354          Keygrip = 1111000000000000000000000000000000000000
    355    uid           [ultimate] Alice Dev <adev@kernel.org>
    356    sub   rsa2048 2018-01-24 [E] [expires: 2020-01-24]
    357          Keygrip = 2222000000000000000000000000000000000000
    358    sub   ed25519 2018-01-24 [S]
    359          Keygrip = 3333000000000000000000000000000000000000
    360
    361Find the keygrip entry that is beneath the ``pub`` line (right under the
    362master key fingerprint). This will correspond directly to a file in your
    363``~/.gnupg`` directory::
    364
    365    $ cd ~/.gnupg/private-keys-v1.d
    366    $ ls
    367    1111000000000000000000000000000000000000.key
    368    2222000000000000000000000000000000000000.key
    369    3333000000000000000000000000000000000000.key
    370
    371All you have to do is simply remove the .key file that corresponds to
    372the master keygrip::
    373
    374    $ cd ~/.gnupg/private-keys-v1.d
    375    $ rm 1111000000000000000000000000000000000000.key
    376
    377Now, if you issue the ``--list-secret-keys`` command, it will show that
    378the master key is missing (the ``#`` indicates it is not available)::
    379
    380    $ gpg --list-secret-keys
    381    sec#  rsa2048 2018-01-24 [SC] [expires: 2020-01-24]
    382          000000000000000000000000AAAABBBBCCCCDDDD
    383    uid           [ultimate] Alice Dev <adev@kernel.org>
    384    ssb   rsa2048 2018-01-24 [E] [expires: 2020-01-24]
    385    ssb   ed25519 2018-01-24 [S]
    386
    387You should also remove any ``secring.gpg`` files in the ``~/.gnupg``
    388directory, which are left over from earlier versions of GnuPG.
    389
    390If you don't have the "private-keys-v1.d" directory
    391~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    392
    393If you do not have a ``~/.gnupg/private-keys-v1.d`` directory, then your
    394secret keys are still stored in the legacy ``secring.gpg`` file used by
    395GnuPG v1. Making any changes to your key, such as changing the
    396passphrase or adding a subkey, should automatically convert the old
    397``secring.gpg`` format to use ``private-keys-v1.d`` instead.
    398
    399Once you get that done, make sure to delete the obsolete ``secring.gpg``
    400file, which still contains your private keys.
    401
    402.. _smartcards:
    403
    404Move the subkeys to a dedicated crypto device
    405=============================================
    406
    407Even though the master key is now safe from being leaked or stolen, the
    408subkeys are still in your home directory. Anyone who manages to get
    409their hands on those will be able to decrypt your communication or fake
    410your signatures (if they know the passphrase). Furthermore, each time a
    411GnuPG operation is performed, the keys are loaded into system memory and
    412can be stolen from there by sufficiently advanced malware (think
    413Meltdown and Spectre).
    414
    415The best way to completely protect your keys is to move them to a
    416specialized hardware device that is capable of smartcard operations.
    417
    418The benefits of smartcards
    419--------------------------
    420
    421A smartcard contains a cryptographic chip that is capable of storing
    422private keys and performing crypto operations directly on the card
    423itself. Because the key contents never leave the smartcard, the
    424operating system of the computer into which you plug in the hardware
    425device is not able to retrieve the private keys themselves. This is very
    426different from the encrypted USB storage device we used earlier for
    427backup purposes -- while that USB device is plugged in and mounted, the
    428operating system is able to access the private key contents.
    429
    430Using external encrypted USB media is not a substitute to having a
    431smartcard-capable device.
    432
    433Available smartcard devices
    434---------------------------
    435
    436Unless all your laptops and workstations have smartcard readers, the
    437easiest is to get a specialized USB device that implements smartcard
    438functionality. There are several options available:
    439
    440- `Nitrokey Start`_: Open hardware and Free Software, based on FSI
    441  Japan's `Gnuk`_. One of the few available commercial devices that
    442  support ED25519 ECC keys, but offer fewest security features (such as
    443  resistance to tampering or some side-channel attacks).
    444- `Nitrokey Pro 2`_: Similar to the Nitrokey Start, but more
    445  tamper-resistant and offers more security features. Pro 2 supports ECC
    446  cryptography (NISTP).
    447- `Yubikey 5`_: proprietary hardware and software, but cheaper than
    448  Nitrokey Pro and comes available in the USB-C form that is more useful
    449  with newer laptops. Offers additional security features such as FIDO
    450  U2F, among others, and now finally supports ECC keys (NISTP).
    451
    452`LWN has a good review`_ of some of the above models, as well as several
    453others. Your choice will depend on cost, shipping availability in your
    454geographical region, and open/proprietary hardware considerations.
    455
    456.. note::
    457
    458    If you are listed in MAINTAINERS or have an account at kernel.org,
    459    you `qualify for a free Nitrokey Start`_ courtesy of The Linux
    460    Foundation.
    461
    462.. _`Nitrokey Start`: https://shop.nitrokey.com/shop/product/nitrokey-start-6
    463.. _`Nitrokey Pro 2`: https://shop.nitrokey.com/shop/product/nitrokey-pro-2-3
    464.. _`Yubikey 5`: https://www.yubico.com/products/yubikey-5-overview/
    465.. _Gnuk: https://www.fsij.org/doc-gnuk/
    466.. _`LWN has a good review`: https://lwn.net/Articles/736231/
    467.. _`qualify for a free Nitrokey Start`: https://www.kernel.org/nitrokey-digital-tokens-for-kernel-developers.html
    468
    469Configure your smartcard device
    470-------------------------------
    471
    472Your smartcard device should Just Work (TM) the moment you plug it into
    473any modern Linux workstation. You can verify it by running::
    474
    475    $ gpg --card-status
    476
    477If you see full smartcard details, then you are good to go.
    478Unfortunately, troubleshooting all possible reasons why things may not
    479be working for you is way beyond the scope of this guide. If you are
    480having trouble getting the card to work with GnuPG, please seek help via
    481usual support channels.
    482
    483To configure your smartcard, you will need to use the GnuPG menu system, as
    484there are no convenient command-line switches::
    485
    486    $ gpg --card-edit
    487    [...omitted...]
    488    gpg/card> admin
    489    Admin commands are allowed
    490    gpg/card> passwd
    491
    492You should set the user PIN (1), Admin PIN (3), and the Reset Code (4).
    493Please make sure to record and store these in a safe place -- especially
    494the Admin PIN and the Reset Code (which allows you to completely wipe
    495the smartcard). You so rarely need to use the Admin PIN, that you will
    496inevitably forget what it is if you do not record it.
    497
    498Getting back to the main card menu, you can also set other values (such
    499as name, sex, login data, etc), but it's not necessary and will
    500additionally leak information about your smartcard should you lose it.
    501
    502.. note::
    503
    504    Despite having the name "PIN", neither the user PIN nor the admin
    505    PIN on the card need to be numbers.
    506
    507.. warning::
    508
    509    Some devices may require that you move the subkeys onto the device
    510    before you can change the passphrase. Please check the documentation
    511    provided by the device manufacturer.
    512
    513Move the subkeys to your smartcard
    514----------------------------------
    515
    516Exit the card menu (using "q") and save all changes. Next, let's move
    517your subkeys onto the smartcard. You will need both your PGP key
    518passphrase and the admin PIN of the card for most operations::
    519
    520    $ gpg --edit-key [fpr]
    521
    522    Secret subkeys are available.
    523
    524    pub  rsa2048/AAAABBBBCCCCDDDD
    525         created: 2018-01-23  expires: 2020-01-23  usage: SC
    526         trust: ultimate      validity: ultimate
    527    ssb  rsa2048/1111222233334444
    528         created: 2018-01-23  expires: never       usage: E
    529    ssb  ed25519/5555666677778888
    530         created: 2017-12-07  expires: never       usage: S
    531    [ultimate] (1). Alice Dev <adev@kernel.org>
    532
    533    gpg>
    534
    535Using ``--edit-key`` puts us into the menu mode again, and you will
    536notice that the key listing is a little different. From here on, all
    537commands are done from inside this menu mode, as indicated by ``gpg>``.
    538
    539First, let's select the key we'll be putting onto the card -- you do
    540this by typing ``key 1`` (it's the first one in the listing, the **[E]**
    541subkey)::
    542
    543    gpg> key 1
    544
    545In the output, you should now see ``ssb*`` on the **[E]** key. The ``*``
    546indicates which key is currently "selected." It works as a *toggle*,
    547meaning that if you type ``key 1`` again, the ``*`` will disappear and
    548the key will not be selected any more.
    549
    550Now, let's move that key onto the smartcard::
    551
    552    gpg> keytocard
    553    Please select where to store the key:
    554       (2) Encryption key
    555    Your selection? 2
    556
    557Since it's our **[E]** key, it makes sense to put it into the Encryption
    558slot.  When you submit your selection, you will be prompted first for
    559your PGP key passphrase, and then for the admin PIN. If the command
    560returns without an error, your key has been moved.
    561
    562**Important**: Now type ``key 1`` again to unselect the first key, and
    563``key 2`` to select the **[S]** key::
    564
    565    gpg> key 1
    566    gpg> key 2
    567    gpg> keytocard
    568    Please select where to store the key:
    569       (1) Signature key
    570       (3) Authentication key
    571    Your selection? 1
    572
    573You can use the **[S]** key both for Signature and Authentication, but
    574we want to make sure it's in the Signature slot, so choose (1). Once
    575again, if your command returns without an error, then the operation was
    576successful::
    577
    578    gpg> q
    579    Save changes? (y/N) y
    580
    581Saving the changes will delete the keys you moved to the card from your
    582home directory (but it's okay, because we have them in our backups
    583should we need to do this again for a replacement smartcard).
    584
    585Verifying that the keys were moved
    586~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    587
    588If you perform ``--list-secret-keys`` now, you will see a subtle
    589difference in the output::
    590
    591    $ gpg --list-secret-keys
    592    sec#  rsa2048 2018-01-24 [SC] [expires: 2020-01-24]
    593          000000000000000000000000AAAABBBBCCCCDDDD
    594    uid           [ultimate] Alice Dev <adev@kernel.org>
    595    ssb>  rsa2048 2018-01-24 [E] [expires: 2020-01-24]
    596    ssb>  ed25519 2018-01-24 [S]
    597
    598The ``>`` in the ``ssb>`` output indicates that the subkey is only
    599available on the smartcard. If you go back into your secret keys
    600directory and look at the contents there, you will notice that the
    601``.key`` files there have been replaced with stubs::
    602
    603    $ cd ~/.gnupg/private-keys-v1.d
    604    $ strings *.key | grep 'private-key'
    605
    606The output should contain ``shadowed-private-key`` to indicate that
    607these files are only stubs and the actual content is on the smartcard.
    608
    609Verifying that the smartcard is functioning
    610~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    611
    612To verify that the smartcard is working as intended, you can create a
    613signature::
    614
    615    $ echo "Hello world" | gpg --clearsign > /tmp/test.asc
    616    $ gpg --verify /tmp/test.asc
    617
    618This should ask for your smartcard PIN on your first command, and then
    619show "Good signature" after you run ``gpg --verify``.
    620
    621Congratulations, you have successfully made it extremely difficult to
    622steal your digital developer identity!
    623
    624Other common GnuPG operations
    625-----------------------------
    626
    627Here is a quick reference for some common operations you'll need to do
    628with your PGP key.
    629
    630Mounting your master key offline storage
    631~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    632
    633You will need your master key for any of the operations below, so you
    634will first need to mount your backup offline storage and tell GnuPG to
    635use it::
    636
    637    $ export GNUPGHOME=/media/disk/foo/gnupg-backup
    638    $ gpg --list-secret-keys
    639
    640You want to make sure that you see ``sec`` and not ``sec#`` in the
    641output (the ``#`` means the key is not available and you're still using
    642your regular home directory location).
    643
    644Extending key expiration date
    645~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    646
    647The master key has the default expiration date of 2 years from the date
    648of creation. This is done both for security reasons and to make obsolete
    649keys eventually disappear from keyservers.
    650
    651To extend the expiration on your key by a year from current date, just
    652run::
    653
    654    $ gpg --quick-set-expire [fpr] 1y
    655
    656You can also use a specific date if that is easier to remember (e.g.
    657your birthday, January 1st, or Canada Day)::
    658
    659    $ gpg --quick-set-expire [fpr] 2020-07-01
    660
    661Remember to send the updated key back to keyservers::
    662
    663    $ gpg --send-key [fpr]
    664
    665Updating your work directory after any changes
    666~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    667
    668After you make any changes to your key using the offline storage, you will
    669want to import these changes back into your regular working directory::
    670
    671    $ gpg --export | gpg --homedir ~/.gnupg --import
    672    $ unset GNUPGHOME
    673
    674Using gpg-agent over ssh
    675~~~~~~~~~~~~~~~~~~~~~~~~
    676
    677You can forward your gpg-agent over ssh if you need to sign tags or
    678commits on a remote system. Please refer to the instructions provided
    679on the GnuPG wiki:
    680
    681- `Agent Forwarding over SSH`_
    682
    683It works more smoothly if you can modify the sshd server settings on the
    684remote end.
    685
    686.. _`Agent Forwarding over SSH`: https://wiki.gnupg.org/AgentForwarding
    687
    688
    689Using PGP with Git
    690==================
    691
    692One of the core features of Git is its decentralized nature -- once a
    693repository is cloned to your system, you have full history of the
    694project, including all of its tags, commits and branches. However, with
    695hundreds of cloned repositories floating around, how does anyone verify
    696that their copy of linux.git has not been tampered with by a malicious
    697third party?
    698
    699Or what happens if a backdoor is discovered in the code and the "Author"
    700line in the commit says it was done by you, while you're pretty sure you
    701had `nothing to do with it`_?
    702
    703To address both of these issues, Git introduced PGP integration. Signed
    704tags prove the repository integrity by assuring that its contents are
    705exactly the same as on the workstation of the developer who created the
    706tag, while signed commits make it nearly impossible for someone to
    707impersonate you without having access to your PGP keys.
    708
    709.. _`nothing to do with it`: https://github.com/jayphelps/git-blame-someone-else
    710
    711Configure git to use your PGP key
    712---------------------------------
    713
    714If you only have one secret key in your keyring, then you don't really
    715need to do anything extra, as it becomes your default key.  However, if
    716you happen to have multiple secret keys, you can tell git which key
    717should be used (``[fpr]`` is the fingerprint of your key)::
    718
    719    $ git config --global user.signingKey [fpr]
    720
    721**IMPORTANT**: If you have a distinct ``gpg2`` command, then you should
    722tell git to always use it instead of the legacy ``gpg`` from version 1::
    723
    724    $ git config --global gpg.program gpg2
    725    $ git config --global gpgv.program gpgv2
    726
    727How to work with signed tags
    728----------------------------
    729
    730To create a signed tag, simply pass the ``-s`` switch to the tag
    731command::
    732
    733    $ git tag -s [tagname]
    734
    735Our recommendation is to always sign git tags, as this allows other
    736developers to ensure that the git repository they are pulling from has
    737not been maliciously altered.
    738
    739How to verify signed tags
    740~~~~~~~~~~~~~~~~~~~~~~~~~
    741
    742To verify a signed tag, simply use the ``verify-tag`` command::
    743
    744    $ git verify-tag [tagname]
    745
    746If you are pulling a tag from another fork of the project repository,
    747git should automatically verify the signature at the tip you're pulling
    748and show you the results during the merge operation::
    749
    750    $ git pull [url] tags/sometag
    751
    752The merge message will contain something like this::
    753
    754    Merge tag 'sometag' of [url]
    755
    756    [Tag message]
    757
    758    # gpg: Signature made [...]
    759    # gpg: Good signature from [...]
    760
    761If you are verifying someone else's git tag, then you will need to
    762import their PGP key. Please refer to the
    763":ref:`verify_identities`" section below.
    764
    765.. note::
    766
    767    If you get "``gpg: Can't check signature: unknown pubkey
    768    algorithm``" error, you need to tell git to use gpgv2 for
    769    verification, so it properly processes signatures made by ECC keys.
    770    See instructions at the start of this section.
    771
    772Configure git to always sign annotated tags
    773~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    774
    775Chances are, if you're creating an annotated tag, you'll want to sign
    776it. To force git to always sign annotated tags, you can set a global
    777configuration option::
    778
    779    $ git config --global tag.forceSignAnnotated true
    780
    781How to work with signed commits
    782-------------------------------
    783
    784It is easy to create signed commits, but it is much more difficult to
    785use them in Linux kernel development, since it relies on patches sent to
    786the mailing list, and this workflow does not preserve PGP commit
    787signatures. Furthermore, when rebasing your repository to match
    788upstream, even your own PGP commit signatures will end up discarded. For
    789this reason, most kernel developers don't bother signing their commits
    790and will ignore signed commits in any external repositories that they
    791rely upon in their work.
    792
    793However, if you have your working git tree publicly available at some
    794git hosting service (kernel.org, infradead.org, ozlabs.org, or others),
    795then the recommendation is that you sign all your git commits even if
    796upstream developers do not directly benefit from this practice.
    797
    798We recommend this for the following reasons:
    799
    8001. Should there ever be a need to perform code forensics or track code
    801   provenance, even externally maintained trees carrying PGP commit
    802   signatures will be valuable for such purposes.
    8032. If you ever need to re-clone your local repository (for example,
    804   after a disk failure), this lets you easily verify the repository
    805   integrity before resuming your work.
    8063. If someone needs to cherry-pick your commits, this allows them to
    807   quickly verify their integrity before applying them.
    808
    809Creating signed commits
    810~~~~~~~~~~~~~~~~~~~~~~~
    811
    812To create a signed commit, you just need to pass the ``-S`` flag to the
    813``git commit`` command (it's capital ``-S`` due to collision with
    814another flag)::
    815
    816    $ git commit -S
    817
    818Configure git to always sign commits
    819~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    820
    821You can tell git to always sign commits::
    822
    823    git config --global commit.gpgSign true
    824
    825.. note::
    826
    827    Make sure you configure ``gpg-agent`` before you turn this on.
    828
    829.. _verify_identities:
    830
    831How to verify kernel developer identities
    832=========================================
    833
    834Signing tags and commits is easy, but how does one go about verifying
    835that the key used to sign something belongs to the actual kernel
    836developer and not to a malicious imposter?
    837
    838Configure auto-key-retrieval using WKD and DANE
    839-----------------------------------------------
    840
    841If you are not already someone with an extensive collection of other
    842developers' public keys, then you can jumpstart your keyring by relying
    843on key auto-discovery and auto-retrieval. GnuPG can piggyback on other
    844delegated trust technologies, namely DNSSEC and TLS, to get you going if
    845the prospect of starting your own Web of Trust from scratch is too
    846daunting.
    847
    848Add the following to your ``~/.gnupg/gpg.conf``::
    849
    850    auto-key-locate wkd,dane,local
    851    auto-key-retrieve
    852
    853DNS-Based Authentication of Named Entities ("DANE") is a method for
    854publishing public keys in DNS and securing them using DNSSEC signed
    855zones. Web Key Directory ("WKD") is the alternative method that uses
    856https lookups for the same purpose. When using either DANE or WKD for
    857looking up public keys, GnuPG will validate DNSSEC or TLS certificates,
    858respectively, before adding auto-retrieved public keys to your local
    859keyring.
    860
    861Kernel.org publishes the WKD for all developers who have kernel.org
    862accounts. Once you have the above changes in your ``gpg.conf``, you can
    863auto-retrieve the keys for Linus Torvalds and Greg Kroah-Hartman (if you
    864don't already have them)::
    865
    866    $ gpg --locate-keys torvalds@kernel.org gregkh@kernel.org
    867
    868If you have a kernel.org account, then you should `add the kernel.org
    869UID to your key`_ to make WKD more useful to other kernel developers.
    870
    871.. _`add the kernel.org UID to your key`: https://korg.wiki.kernel.org/userdoc/mail#adding_a_kernelorg_uid_to_your_pgp_key
    872
    873Web of Trust (WOT) vs. Trust on First Use (TOFU)
    874------------------------------------------------
    875
    876PGP incorporates a trust delegation mechanism known as the "Web of
    877Trust." At its core, this is an attempt to replace the need for
    878centralized Certification Authorities of the HTTPS/TLS world. Instead of
    879various software makers dictating who should be your trusted certifying
    880entity, PGP leaves this responsibility to each user.
    881
    882Unfortunately, very few people understand how the Web of Trust works.
    883While it remains an important aspect of the OpenPGP specification,
    884recent versions of GnuPG (2.2 and above) have implemented an alternative
    885mechanism called "Trust on First Use" (TOFU). You can think of TOFU as
    886"the SSH-like approach to trust." With SSH, the first time you connect
    887to a remote system, its key fingerprint is recorded and remembered. If
    888the key changes in the future, the SSH client will alert you and refuse
    889to connect, forcing you to make a decision on whether you choose to
    890trust the changed key or not. Similarly, the first time you import
    891someone's PGP key, it is assumed to be valid. If at any point in the
    892future GnuPG comes across another key with the same identity, both the
    893previously imported key and the new key will be marked as invalid and
    894you will need to manually figure out which one to keep.
    895
    896We recommend that you use the combined TOFU+PGP trust model (which is
    897the new default in GnuPG v2). To set it, add (or modify) the
    898``trust-model`` setting in ``~/.gnupg/gpg.conf``::
    899
    900    trust-model tofu+pgp
    901
    902How to use keyservers (more) safely
    903-----------------------------------
    904
    905If you get a "No public key" error when trying to validate someone's
    906tag, then you should attempt to lookup that key using a keyserver. It is
    907important to keep in mind that there is absolutely no guarantee that the
    908key you retrieve from PGP keyservers belongs to the actual person --
    909that much is by design. You are supposed to use the Web of Trust to
    910establish key validity.
    911
    912How to properly maintain the Web of Trust is beyond the scope of this
    913document, simply because doing it properly requires both effort and
    914dedication that tends to be beyond the caring threshold of most human
    915beings. Here are some shortcuts that will help you reduce the risk of
    916importing a malicious key.
    917
    918First, let's say you've tried to run ``git verify-tag`` but it returned
    919an error saying the key is not found::
    920
    921    $ git verify-tag sunxi-fixes-for-4.15-2
    922    gpg: Signature made Sun 07 Jan 2018 10:51:55 PM EST
    923    gpg:                using RSA key DA73759BF8619E484E5A3B47389A54219C0F2430
    924    gpg:                issuer "wens@...org"
    925    gpg: Can't check signature: No public key
    926
    927Let's query the keyserver for more info about that key fingerprint (the
    928fingerprint probably belongs to a subkey, so we can't use it directly
    929without finding out the ID of the master key it is associated with)::
    930
    931    $ gpg --search DA73759BF8619E484E5A3B47389A54219C0F2430
    932    gpg: data source: hkp://keys.gnupg.net
    933    (1) Chen-Yu Tsai <wens@...org>
    934          4096 bit RSA key C94035C21B4F2AEB, created: 2017-03-14, expires: 2019-03-15
    935    Keys 1-1 of 1 for "DA73759BF8619E484E5A3B47389A54219C0F2430".  Enter number(s), N)ext, or Q)uit > q
    936
    937Locate the ID of the master key in the output, in our example
    938``C94035C21B4F2AEB``. Now display the key of Linus Torvalds that you
    939have on your keyring::
    940
    941    $ gpg --list-key torvalds@kernel.org
    942    pub   rsa2048 2011-09-20 [SC]
    943          ABAF11C65A2970B130ABE3C479BE3E4300411886
    944    uid           [ unknown] Linus Torvalds <torvalds@kernel.org>
    945    sub   rsa2048 2011-09-20 [E]
    946
    947Next, find a trust path from Linus Torvalds to the key-id you found via ``gpg
    948--search`` of the unknown key.  For this, you can use several tools including
    949https://github.com/mricon/wotmate,
    950https://git.kernel.org/pub/scm/docs/kernel/pgpkeys.git/tree/graphs, and
    951https://the.earth.li/~noodles/pathfind.html.
    952
    953If you get a few decent trust paths, then it's a pretty good indication
    954that it is a valid key. You can add it to your keyring from the
    955keyserver now::
    956
    957    $ gpg --recv-key C94035C21B4F2AEB
    958
    959This process is not perfect, and you are obviously trusting the
    960administrators of the PGP Pathfinder service to not be malicious (in
    961fact, this goes against :ref:`devs_not_infra`). However, if you
    962do not carefully maintain your own web of trust, then it is a marked
    963improvement over blindly trusting keyservers.