Documentation/process/maintainer-pgp-guide.rst

66 Your distro should already have GnuPG installed by default, you just
67 need to verify that you are using a reasonably recent version of it.
72 If you have version 2.2 or above, then you are good to go. If you have a
80 you use the ``gpg`` command and run in the background with the purpose
81 of caching the private key passphrase. There are two options you should
84 - ``default-cache-ttl`` (seconds): If you use the same key again before
87 - ``max-cache-ttl`` (seconds): Regardless of how recently you've used
89   countdown expires, you'll have to enter the passphrase again. The
92 If you find either of these defaults too short (or too long), you can
103     to remove anything you had in place for older versions of GnuPG, as
111 This guide assumes that you already have a PGP key that you use for Linux
112 kernel development purposes. If you do not yet have one, please see the
141 1. All subkeys are fully independent from each other. If you lose a
145    with identical capabilities (e.g. you can have 2 valid encryption
149    you may also have.
167 If you used the default parameters when generating your key, then that
168 is what you will have. You can verify by running ``gpg --list-secret-keys``,
177 whenever you see ``[fpr]`` in the examples below, that 40-character
197 so if you only have a combined **[SC]** key, then you should create a
204     Note, that if you intend to use a hardware token that does not
205     support ED25519 ECC keys, you should choose "nistp256" instead or
212 The more signatures you have on your PGP key from other developers, the
213 more reasons you have to create a backup version that lives on something
230 that passphrase, and if you ever change it you will not remember what it
231 used to be when you had created the backup -- *guaranteed*.
252 should you need to recover them. This is different from the
254 on these external copies whenever you need to use your Certify key --
258 Start by getting a small USB "thumb" drive (preferably two!) that you
262 For the encryption passphrase, you can use the same one as on your
275 If you don't get any errors, then you should be good to go. Unmount the
276 USB drive, distinctly label it so you don't blow it away next time you
278 far away, because you'll need to use it every now and again for things
302     Please see the previous section and make sure you have backed up
304     render your key useless if you do not have a usable backup!
331 All you have to do is simply remove the .key file that corresponds to
337 Now, if you issue the ``--list-secret-keys`` command, it will show that
350 If you don't have the "private-keys-v1.d" directory
353 If you do not have a ``~/.gnupg/private-keys-v1.d`` directory, then your
359 Once you get that done, make sure to delete the obsolete ``secring.gpg``
384 operating system of the computer into which you plug in the hardware
418     If you are listed in MAINTAINERS or have an account at kernel.org,
419     you `qualify for a free Nitrokey Start`_ courtesy of The Linux
431 Your smartcard device should Just Work (TM) the moment you plug it into
436 If you see full smartcard details, then you are good to go.
438 be working for you is way beyond the scope of this guide. If you are
442 To configure your smartcard, you will need to use the GnuPG menu system, as
453 the Admin PIN and the Reset Code (which allows you to completely wipe
454 the smartcard). You so rarely need to use the Admin PIN, that you will
455 inevitably forget what it is if you do not record it.
457 Getting back to the main card menu, you can also set other values (such
459 additionally leak information about your smartcard should you lose it.
468     Some devices may require that you move the subkeys onto the device
469     before you can change the passphrase. Please check the documentation
494 Using ``--edit-key`` puts us into the menu mode again, and you will
498 First, let's select the key we'll be putting onto the card -- you do
504 In the output, you should now see ``ssb*`` on the **[E]** key. The ``*``
506 meaning that if you type ``key 1`` again, the ``*`` will disappear and
517 slot.  When you submit your selection, you will be prompted first for
540 Saving the changes will delete the keys you moved to the card from your
547 If you perform ``--list-secret-keys`` now, you will see a subtle
558 available on the smartcard. If you go back into your secret keys
559 directory and look at the contents there, you will notice that the
571 To verify that the smartcard is working as intended, you can create a
578 show "Good signature" after you run ``gpg --verify``.
580 Congratulations, you have successfully made it extremely difficult to
586 Here is a quick reference for some common operations you'll need to do
592 You will need your Certify key for any of the operations below, so you
599 You want to make sure that you see ``sec`` and not ``sec#`` in the
600 output (the ``#`` means the key is not available and you're still using
627 After you make any changes to your key using the offline storage, you will
636 You can forward your gpg-agent over ssh if you need to sign tags or
642 It works more smoothly if you can modify the sshd server settings on the
653 repository is cloned to your system, you have full history of the
660 line in the commit says it was done by you, while you're pretty sure you
667 impersonate you without having access to your PGP keys.
674 If you only have one secret key in your keyring, then you don't really
676 you happen to have multiple secret keys, you can tell git which key
700 If you are pulling a tag from another fork of the project repository,
701 git should automatically verify the signature at the tip you're pulling
702 and show you the results during the merge operation::
715 If you are verifying someone else's git tag, then you will need to
722 Chances are, if you're creating an annotated tag, you'll want to sign
723 it. To force git to always sign annotated tags, you can set a global
740 However, if you have your working git tree publicly available at some
742 then the recommendation is that you sign all your git commits even if
750 2. If you ever need to re-clone your local repository (for example,
751    after a disk failure), this lets you easily verify the repository
759 To create a signed commit, you just need to pass the ``-S`` flag to the
774     Make sure you configure ``gpg-agent`` before you turn this on.
785 review tasks, you should use the tool kernel.org created for this
799 If you already have your PGP key configured with git (via the
802 the git-send-email hook in the repository you want::
806 Now any patches you send with ``git send-email`` will be automatically
812 If you are using ``b4`` to retrieve and apply patches, then it will
829     Patatt and b4 are still in active development and you should check
845 If you are not already someone with an extensive collection of other
846 developers' public keys, then you can jumpstart your keyring by relying
848 delegated trust technologies, namely DNSSEC and TLS, to get you going if
866 accounts. Once you have the above changes in your ``gpg.conf``, you can
867 auto-retrieve the keys for Linus Torvalds and Greg Kroah-Hartman (if you
872 If you have a kernel.org account, then you should `add the kernel.org
890 "the SSH-like approach to trust." With SSH, the first time you connect
892 the key changes in the future, the SSH client will alert you and refuse
893 to connect, forcing you to make a decision on whether you choose to
894 trust the changed key or not. Similarly, the first time you import
898 you will need to manually figure out which one to keep.
900 We recommend that you use the combined TOFU+PGP trust model (which is
916 If you are a kernel developer, please consider submitting your key for