[PATCH v1 0/5] Update the maintainer PGP guide

[PATCH v1 0/5] Update the maintainer PGP guide

[Konstantin Ryabitsev]

This series updates the guide to match terminology used in the upstream
"protecting code integrity" guide [1] and brings the documentation in
line with the latest developments in the GnuPG world:

- uses "Certify key" instead of "master key" terms to remove common
  confusion that the "Certify key" is somehow able to restore lost
  private subkeys
- removes keyserver instructions because keyservers have largely gone
  semi-extinct due to GDPR enforcement and just general neglect
- adds a link to the kernel.org PGP keyring documentation
- updates information about ECC curve support among the devices the
  guide talks about (Yubikeys are able to use ED25519 curves with the
  latest firmware updates)
- adds a section on using PGP-signed patches with b4 and patatt

Signed-off-by: Konstantin Ryabitsev <konstantin@linuxfoundation.org>

---
Konstantin Ryabitsev (5):
      maintainer-pgp-guide: use key terminology consistent with upstream
      maintainer-pgp-guide: remove keyserver instructions
      maintainer-pgp-guide: update ECC support information
      maintainer-pgp-guide: add a section on PGP-signed patches
      maintainer-pgp-guide: minor wording tweaks

 Documentation/process/maintainer-pgp-guide.rst | 287 ++++++++++++-------------
 1 file changed, 142 insertions(+), 145 deletions(-)
---
base-commit: e0dccc3b76fb35bb257b4118367a883073d7390e
change-id: 20220727-docs-pgp-guide-1dfc91614c0f

Best regards,
-- 
Konstantin Ryabitsev <konstantin@linuxfoundation.org>

[PATCH v1 1/5] maintainer-pgp-guide: use key terminology consistent with upstream

[Konstantin Ryabitsev]

GnuPG does not use the word "master key" when referring to the subkey
marked with the "certification" capability. Our use of this term was not
only inconsistent, but also misleading, because in real life "master
keys" are able to open multiple locks made for different keys, while PGP
Certify key has no such capability.

Signed-off-by: Konstantin Ryabitsev <konstantin@linuxfoundation.org>

diff --git a/Documentation/process/maintainer-pgp-guide.rst b/Documentation/process/maintainer-pgp-guide.rst
index 29e7d7b1cd44..cdd108f50fe7 100644
--- a/Documentation/process/maintainer-pgp-guide.rst
+++ b/Documentation/process/maintainer-pgp-guide.rst
@@ -133,45 +133,55 @@ daily cronjob::
 Check the full path to your ``gpg`` or ``gpg2`` command and use the
 ``gpg2`` command if regular ``gpg`` for you is the legacy GnuPG v.1.
 
-.. _master_key:
+.. _protect_your_key:
 
-Protect your master PGP key
-===========================
+Protect your PGP key
+====================
 
 This guide assumes that you already have a PGP key that you use for Linux
 kernel development purposes. If you do not yet have one, please see the
 "`Protecting Code Integrity`_" document mentioned earlier for guidance
 on how to create a new one.
 
-You should also make a new key if your current one is weaker than 2048 bits
-(RSA).
-
-Master key vs. Subkeys
-----------------------
-
-Subkeys are fully independent PGP keypairs that are tied to the "master"
-key using certifying key signatures (certificates). It is important to
-understand the following:
-
-1. There are no technical differences between the "master key" and "subkeys."
-2. At creation time, we assign functional limitations to each key by
-   giving it specific capabilities.
-3. A PGP key can have 4 capabilities:
-
-   - **[S]** key can be used for signing
-   - **[E]** key can be used for encryption
-   - **[A]** key can be used for authentication
-   - **[C]** key can be used for certifying other keys
-
-4. A single key may have multiple capabilities.
-5. A subkey is fully independent from the master key. A message
-   encrypted to a subkey cannot be decrypted with the master key. If you
-   lose your private subkey, it cannot be recreated from the master key
-   in any way.
-
-The key carrying the **[C]** (certify) capability is considered the
-"master" key because it is the only key that can be used to indicate
-relationship with other keys. Only the **[C]** key can be used to:
+You should also make a new key if your current one is weaker than 2048
+bits (RSA).
+
+Understanding PGP Subkeys
+-------------------------
+
+A PGP key rarely consists of a single keypair -- usually it is a
+collection of independent subkeys that can be used for different
+purposes based on their capabilities, assigned at their creation time.
+PGP defined four capabilities that a key can have:
+
+- **[S]** keys can be used for signing
+- **[E]** keys can be used for encryption
+- **[A]** keys can be used for authentication
+- **[C]** keys can be used for certifying other keys
+
+The **[C]** (certification) key is often called the "master" key, but
+this terminology is misleading because it implies that the Certify key
+can be used in place of any of other subkey on the same chain (like a
+physical "master key" would). For this reason, this guide will refer to
+it as "the Certify key" to avoid any ambiguity.
+
+It is critical to fully understand the following:
+
+1. All subkeys are fully independent from each other. If you lose a
+   private subkey, it cannot be restored or recreated from any other
+   private key on your chain.
+2. With the exception of the Certify key, there can be multiple subkeys
+   with identical capabilities (e.g. you can have 2 valid encryption
+   subkeys, 3 valid signing subkeys, but only one valid certification
+   subkey). All subkeys are fully independent -- a message encrypted to
+   one **[E]** subkey cannot be decrypted with any other **[E]** subkey
+   you may also have.
+3. A single subkey may have multiple capabilities (e.g. your **[C]** key
+   can also be your **[S]** key).
+
+The key carrying the **[C]** (certify) capability is the only key that
+can be used to indicate relationship with other keys. Only the **[C]**
+key can be used to:
 
 - add or revoke other keys (subkeys) with S/E/A capabilities
 - add, change or revoke identities (uids) associated with the key
@@ -180,7 +190,7 @@ relationship with other keys. Only the **[C]** key can be used to:
 
 By default, GnuPG creates the following when generating new keys:
 
-- A master key carrying both Certify and Sign capabilities (**[SC]**)
+- One subkey carrying both Certify and Sign capabilities (**[SC]**)
 - A separate subkey with the Encryption capability (**[E]**)
 
 If you used the default parameters when generating your key, then that
@@ -192,9 +202,6 @@ for example::
     uid           [ultimate] Alice Dev <adev@kernel.org>
     ssb   rsa2048 2018-01-23 [E] [expires: 2020-01-23]
 
-Any key carrying the **[C]** capability is your master key, regardless
-of any other capabilities it may have assigned to it.
-
 The long line under the ``sec`` entry is your key fingerprint --
 whenever you see ``[fpr]`` in the examples below, that 40-character
 string is what it refers to.
@@ -215,9 +222,9 @@ strong passphrase. To set it or change it, use::
 Create a separate Signing subkey
 --------------------------------
 
-Our goal is to protect your master key by moving it to offline media, so
-if you only have a combined **[SC]** key, then you should create a separate
-signing subkey::
+Our goal is to protect your Certify key by moving it to offline media,
+so if you only have a combined **[SC]** key, then you should create a
+separate signing subkey::
 
     $ gpg --quick-addkey [fpr] ed25519 sign
 
@@ -230,8 +237,8 @@ your new subkey::
 
     GnuPG 2.1 and later has full support for Elliptic Curve
     Cryptography, with ability to combine ECC subkeys with traditional
-    RSA master keys. The main upside of ECC cryptography is that it is
-    much faster computationally and creates much smaller signatures when
+    RSA keys. The main upside of ECC cryptography is that it is much
+    faster computationally and creates much smaller signatures when
     compared byte for byte with 2048+ bit RSA keys. Unless you plan on
     using a smartcard device that does not support ECC operations, we
     recommend that you create an ECC signing subkey for your kernel
@@ -244,8 +251,8 @@ your new subkey::
     "nistp256" instead or "ed25519."
 
 
-Back up your master key for disaster recovery
----------------------------------------------
+Back up your Certify key for disaster recovery
+----------------------------------------------
 
 The more signatures you have on your PGP key from other developers, the
 more reasons you have to create a backup version that lives on something
@@ -300,7 +307,7 @@ will use for backup purposes. You will need to encrypt them using LUKS
 -- refer to your distro's documentation on how to accomplish this.
 
 For the encryption passphrase, you can use the same one as on your
-master key.
+PGP key.
 
 Once the encryption process is over, re-insert the USB drive and make
 sure it gets properly mounted. Copy your entire ``.gnupg`` directory
@@ -319,7 +326,7 @@ far away, because you'll need to use it every now and again for things
 like editing identities, adding or revoking subkeys, or signing other
 people's keys.
 
-Remove the master key from  your homedir
+Remove the Certify key from your homedir
 ----------------------------------------
 
 The files in our home directory are not as well protected as we like to
@@ -334,7 +341,7 @@ think.  They can be leaked or stolen via many different means:
 Protecting your key with a good passphrase greatly helps reduce the risk
 of any of the above, but passphrases can be discovered via keyloggers,
 shoulder-surfing, or any number of other means. For this reason, the
-recommended setup is to remove your master key from your home directory
+recommended setup is to remove your Certify key from your home directory
 and store it on offline storage.
 
 .. warning::
@@ -343,7 +350,7 @@ and store it on offline storage.
     your GnuPG directory in its entirety. What we are about to do will
     render your key useless if you do not have a usable backup!
 
-First, identify the keygrip of your master key::
+First, identify the keygrip of your Certify key::
 
     $ gpg --with-keygrip --list-key [fpr]
 
@@ -359,7 +366,7 @@ The output will be something like this::
           Keygrip = 3333000000000000000000000000000000000000
 
 Find the keygrip entry that is beneath the ``pub`` line (right under the
-master key fingerprint). This will correspond directly to a file in your
+Certify key fingerprint). This will correspond directly to a file in your
 ``~/.gnupg`` directory::
 
     $ cd ~/.gnupg/private-keys-v1.d
@@ -369,13 +376,13 @@ master key fingerprint). This will correspond directly to a file in your
     3333000000000000000000000000000000000000.key
 
 All you have to do is simply remove the .key file that corresponds to
-the master keygrip::
+the Certify key keygrip::
 
     $ cd ~/.gnupg/private-keys-v1.d
     $ rm 1111000000000000000000000000000000000000.key
 
 Now, if you issue the ``--list-secret-keys`` command, it will show that
-the master key is missing (the ``#`` indicates it is not available)::
+the Certify key is missing (the ``#`` indicates it is not available)::
 
     $ gpg --list-secret-keys
     sec#  rsa2048 2018-01-24 [SC] [expires: 2020-01-24]
@@ -404,7 +411,7 @@ file, which still contains your private keys.
 Move the subkeys to a dedicated crypto device
 =============================================
 
-Even though the master key is now safe from being leaked or stolen, the
+Even though the Certify key is now safe from being leaked or stolen, the
 subkeys are still in your home directory. Anyone who manages to get
 their hands on those will be able to decrypt your communication or fake
 your signatures (if they know the passphrase). Furthermore, each time a
@@ -627,10 +634,10 @@ Other common GnuPG operations
 Here is a quick reference for some common operations you'll need to do
 with your PGP key.
 
-Mounting your master key offline storage
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Mounting your safe offline storage
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-You will need your master key for any of the operations below, so you
+You will need your Certify key for any of the operations below, so you
 will first need to mount your backup offline storage and tell GnuPG to
 use it::
 
@@ -644,7 +651,7 @@ your regular home directory location).
 Extending key expiration date
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The master key has the default expiration date of 2 years from the date
+The Certify key has the default expiration date of 2 years from the date
 of creation. This is done both for security reasons and to make obsolete
 keys eventually disappear from keyservers.
 

-- 
b4 0.10.0-dev-49460

[PATCH v1 2/5] maintainer-pgp-guide: remove keyserver instructions

[Konstantin Ryabitsev]

Keyservers are largely a thing of the past with the replacement systems
like keys.openpgp.net specifically designed to offer no support for the
web of trust. Remove all sections that talk about keyservers and add a
small section with the link to kernel.org documentation that talks about
using the kernel.org public key repository.

Signed-off-by: Konstantin Ryabitsev <konstantin@linuxfoundation.org>

diff --git a/Documentation/process/maintainer-pgp-guide.rst b/Documentation/process/maintainer-pgp-guide.rst
index cdd108f50fe7..01112ac7723e 100644
--- a/Documentation/process/maintainer-pgp-guide.rst
+++ b/Documentation/process/maintainer-pgp-guide.rst
@@ -121,18 +121,6 @@ edit your ``~/.gnupg/gpg-agent.conf`` file to set your own values::
     to remove anything you had in place for older versions of GnuPG, as
     it may not be doing the right thing any more.
 
-Set up a refresh cronjob
-~~~~~~~~~~~~~~~~~~~~~~~~
-
-You will need to regularly refresh your keyring in order to get the
-latest changes on other people's public keys, which is best done with a
-daily cronjob::
-
-    @daily /usr/bin/gpg2 --refresh >/dev/null 2>&1
-
-Check the full path to your ``gpg`` or ``gpg2`` command and use the
-``gpg2`` command if regular ``gpg`` for you is the legacy GnuPG v.1.
-
 .. _protect_your_key:
 
 Protect your PGP key
@@ -228,11 +216,6 @@ separate signing subkey::
 
     $ gpg --quick-addkey [fpr] ed25519 sign
 
-Remember to tell the keyservers about this change, so others can pull down
-your new subkey::
-
-    $ gpg --send-key [fpr]
-
 .. note:: ECC support in GnuPG
 
     GnuPG 2.1 and later has full support for Elliptic Curve
@@ -906,65 +889,17 @@ the new default in GnuPG v2). To set it, add (or modify) the
 
     trust-model tofu+pgp
 
-How to use keyservers (more) safely
------------------------------------
-
-If you get a "No public key" error when trying to validate someone's
-tag, then you should attempt to lookup that key using a keyserver. It is
-important to keep in mind that there is absolutely no guarantee that the
-key you retrieve from PGP keyservers belongs to the actual person --
-that much is by design. You are supposed to use the Web of Trust to
-establish key validity.
-
-How to properly maintain the Web of Trust is beyond the scope of this
-document, simply because doing it properly requires both effort and
-dedication that tends to be beyond the caring threshold of most human
-beings. Here are some shortcuts that will help you reduce the risk of
-importing a malicious key.
-
-First, let's say you've tried to run ``git verify-tag`` but it returned
-an error saying the key is not found::
-
-    $ git verify-tag sunxi-fixes-for-4.15-2
-    gpg: Signature made Sun 07 Jan 2018 10:51:55 PM EST
-    gpg:                using RSA key DA73759BF8619E484E5A3B47389A54219C0F2430
-    gpg:                issuer "wens@...org"
-    gpg: Can't check signature: No public key
-
-Let's query the keyserver for more info about that key fingerprint (the
-fingerprint probably belongs to a subkey, so we can't use it directly
-without finding out the ID of the master key it is associated with)::
-
-    $ gpg --search DA73759BF8619E484E5A3B47389A54219C0F2430
-    gpg: data source: hkp://keys.gnupg.net
-    (1) Chen-Yu Tsai <wens@...org>
-          4096 bit RSA key C94035C21B4F2AEB, created: 2017-03-14, expires: 2019-03-15
-    Keys 1-1 of 1 for "DA73759BF8619E484E5A3B47389A54219C0F2430".  Enter number(s), N)ext, or Q)uit > q
-
-Locate the ID of the master key in the output, in our example
-``C94035C21B4F2AEB``. Now display the key of Linus Torvalds that you
-have on your keyring::
-
-    $ gpg --list-key torvalds@kernel.org
-    pub   rsa2048 2011-09-20 [SC]
-          ABAF11C65A2970B130ABE3C479BE3E4300411886
-    uid           [ unknown] Linus Torvalds <torvalds@kernel.org>
-    sub   rsa2048 2011-09-20 [E]
-
-Next, find a trust path from Linus Torvalds to the key-id you found via ``gpg
---search`` of the unknown key.  For this, you can use several tools including
-https://github.com/mricon/wotmate,
-https://git.kernel.org/pub/scm/docs/kernel/pgpkeys.git/tree/graphs, and
-https://the.earth.li/~noodles/pathfind.html.
-
-If you get a few decent trust paths, then it's a pretty good indication
-that it is a valid key. You can add it to your keyring from the
-keyserver now::
-
-    $ gpg --recv-key C94035C21B4F2AEB
-
-This process is not perfect, and you are obviously trusting the
-administrators of the PGP Pathfinder service to not be malicious (in
-fact, this goes against :ref:`devs_not_infra`). However, if you
-do not carefully maintain your own web of trust, then it is a marked
-improvement over blindly trusting keyservers.
+Using the kernel.org web of trust repository
+--------------------------------------------
+
+Kernel.org maintains a git repository with developers' public keys as a
+replacement for replicating keyserver networks that have gone mostly
+dark in the past few years. The full documentation for how to set up
+that repository as your source of public keys can be found here:
+
+- `Kernel developer PGP Keyring`_
+
+If you are a kernel developer, please consider submitting your key for
+inclusion into that keyring.
+
+.. _`Kernel developer PGP Keyring`: https://korg.docs.kernel.org/pgpkeys.html

-- 
b4 0.10.0-dev-49460

[PATCH v1 3/5] maintainer-pgp-guide: update ECC support information

[Konstantin Ryabitsev]

Update ECC sections with the latest details, now that Yubikeys are able
to support ED25519 curves. Tweak a few links to smartcard devices to
reflect the latest URL changes.

Signed-off-by: Konstantin Ryabitsev <konstantin@linuxfoundation.org>

diff --git a/Documentation/process/maintainer-pgp-guide.rst b/Documentation/process/maintainer-pgp-guide.rst
index 01112ac7723e..62b0bab5d7c5 100644
--- a/Documentation/process/maintainer-pgp-guide.rst
+++ b/Documentation/process/maintainer-pgp-guide.rst
@@ -227,11 +227,9 @@ separate signing subkey::
     recommend that you create an ECC signing subkey for your kernel
     work.
 
-    If for some reason you prefer to stay with RSA subkeys, just replace
-    "ed25519" with "rsa2048" in the above command. Additionally, if you
-    plan to use a hardware device that does not support ED25519 ECC
-    keys, like Nitrokey Pro or a Yubikey, then you should use
-    "nistp256" instead or "ed25519."
+    Note, that if you plan to use a hardware device that does not
+    support ED25519 ECC keys, you should choose "nistp256" instead or
+    "ed25519."
 
 
 Back up your Certify key for disaster recovery
@@ -437,7 +435,8 @@ functionality. There are several options available:
 - `Yubikey 5`_: proprietary hardware and software, but cheaper than
   Nitrokey Pro and comes available in the USB-C form that is more useful
   with newer laptops. Offers additional security features such as FIDO
-  U2F, among others, and now finally supports ECC keys (NISTP).
+  U2F, among others, and now finally supports NISTP and ED25519 ECC
+  keys.
 
 `LWN has a good review`_ of some of the above models, as well as several
 others. Your choice will depend on cost, shipping availability in your
@@ -450,7 +449,7 @@ geographical region, and open/proprietary hardware considerations.
     Foundation.
 
 .. _`Nitrokey Start`: https://shop.nitrokey.com/shop/product/nitrokey-start-6
-.. _`Nitrokey Pro 2`: https://shop.nitrokey.com/shop/product/nitrokey-pro-2-3
+.. _`Nitrokey Pro 2`: https://shop.nitrokey.com/shop/product/nkpr2-nitrokey-pro-2-3
 .. _`Yubikey 5`: https://www.yubico.com/products/yubikey-5-overview/
 .. _Gnuk: https://www.fsij.org/doc-gnuk/
 .. _`LWN has a good review`: https://lwn.net/Articles/736231/

-- 
b4 0.10.0-dev-49460

[PATCH v1 4/5] maintainer-pgp-guide: add a section on PGP-signed patches

[Konstantin Ryabitsev]

With more developers beginning to use b4 and patatt, add a section to
the guide that talks about setting up and using patatt for PGP-signing
patch submissions.

Signed-off-by: Konstantin Ryabitsev <konstantin@linuxfoundation.org>

diff --git a/Documentation/process/maintainer-pgp-guide.rst b/Documentation/process/maintainer-pgp-guide.rst
index 62b0bab5d7c5..2ce38e5d547d 100644
--- a/Documentation/process/maintainer-pgp-guide.rst
+++ b/Documentation/process/maintainer-pgp-guide.rst
@@ -674,6 +674,7 @@ remote end.
 
 .. _`Agent Forwarding over SSH`: https://wiki.gnupg.org/AgentForwarding
 
+.. _pgp_with_git:
 
 Using PGP with Git
 ==================
@@ -817,6 +818,63 @@ You can tell git to always sign commits::
 
 .. _verify_identities:
 
+
+How to work with signed patches
+-------------------------------
+
+It is possible to use your PGP key to sign patches sent to kernel
+developer mailing lists. Since existing email signature mechanisms
+(PGP-Mime or PGP-inline) tend to cause problems with regular code
+review tasks, you should use the tool kernel.org created for this
+purpose that puts cryptographic attestation signatures into message
+headers (a-la DKIM):
+
+- `Patatt Patch Attestation`_
+
+.. _`Patatt Patch Attestation`: https://pypi.org/project/patatt/
+
+Installing and configuring patatt
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Patatt is packaged for many distributions already, so please check there
+first. You can also install it from pypi using "``pip install patatt``".
+
+If you already have your PGP key configured with git (via the
+``user.signingKey`` configuration parameter), then patatt requires no
+further configuration. You can start signing your patches by installing
+the git-send-email hook in the repository you want::
+
+    patatt install-hook
+
+Now any patches you send with ``git send-email`` will be automatically
+signed with your cryptographic signature.
+
+Checking patatt signatures
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you are using ``b4`` to retrieve and apply patches, then it will
+automatically attempt to verify all DKIM and patatt signatures it
+encounters, for example::
+
+    $ b4 am 20220720205013.890942-1-broonie@kernel.org
+    [...]
+    Checking attestation on all messages, may take a moment...
+    ---
+      ✓ [PATCH v1 1/3] kselftest/arm64: Correct buffer allocation for SVE Z registers
+      ✓ [PATCH v1 2/3] arm64/sve: Document our actual ABI for clearing registers on syscall
+      ✓ [PATCH v1 3/3] kselftest/arm64: Enforce actual ABI for SVE syscalls
+      ---
+      ✓ Signed: openpgp/broonie@kernel.org
+      ✓ Signed: DKIM/kernel.org
+
+.. note::
+
+    Patatt and b4 are still in active development and you should check
+    the latest documentation for these projects for any new or updated
+    features.
+
+.. _kernel_identities:
+
 How to verify kernel developer identities
 =========================================
 

-- 
b4 0.10.0-dev-49460

[PATCH v1 5/5] maintainer-pgp-guide: minor wording tweaks

[Konstantin Ryabitsev]

Tweak some wording to remove redundant information or fix spacing.

Signed-off-by: Konstantin Ryabitsev <konstantin@linuxfoundation.org>

diff --git a/Documentation/process/maintainer-pgp-guide.rst b/Documentation/process/maintainer-pgp-guide.rst
index 2ce38e5d547d..ea74c87d09d8 100644
--- a/Documentation/process/maintainer-pgp-guide.rst
+++ b/Documentation/process/maintainer-pgp-guide.rst
@@ -265,9 +265,7 @@ home, such as your bank vault.
     Your printer is probably no longer a simple dumb device connected to
     your parallel port, but since the output is still encrypted with
     your passphrase, printing out even to "cloud-integrated" modern
-    printers should remain a relatively safe operation. One option is to
-    change the passphrase on your master key immediately after you are
-    done with paperkey.
+    printers should remain a relatively safe operation.
 
 Back up your whole GnuPG directory
 ----------------------------------
@@ -311,7 +309,7 @@ Remove the Certify key from your homedir
 ----------------------------------------
 
 The files in our home directory are not as well protected as we like to
-think.  They can be leaked or stolen via many different means:
+think. They can be leaked or stolen via many different means:
 
 - by accident when making quick homedir copies to set up a new workstation
 - by systems administrator negligence or malice

-- 
b4 0.10.0-dev-49460

Re: [PATCH v1 2/5] maintainer-pgp-guide: remove keyserver instructions

[Bagas Sanjaya]

On 7/29/22 03:57, Konstantin Ryabitsev wrote:
> Keyservers are largely a thing of the past with the replacement systems
> like keys.openpgp.net specifically designed to offer no support for the
> web of trust. Remove all sections that talk about keyservers and add a
> small section with the link to kernel.org documentation that talks about
> using the kernel.org public key repository.
> 

AFAIK, keyservers are synchronized (federated). For example, when I submit
my key to keys.openpgp.net, other keyservers (like keyserver.ubuntu.com
that I use) also gets a copy of my key. So "replacement systems" in
this case is referred to kernel.org key repository (using git). The
wording should be "Replace keyservers section with kernel.org public
key repository usage".

-- 
An old man doll... just what I always wanted! - Clara

Re: [PATCH v1 3/5] maintainer-pgp-guide: update ECC support information

[Bagas Sanjaya]

On Thu, Jul 28, 2022 at 04:57:06PM -0400, Konstantin Ryabitsev wrote:
>  
> -    If for some reason you prefer to stay with RSA subkeys, just replace
> -    "ed25519" with "rsa2048" in the above command. Additionally, if you
> -    plan to use a hardware device that does not support ED25519 ECC
> -    keys, like Nitrokey Pro or a Yubikey, then you should use
> -    "nistp256" instead or "ed25519."
> +    Note, that if you plan to use a hardware device that does not
> +    support ED25519 ECC keys, you should choose "nistp256" instead or
> +    "ed25519."
>  

nistp256 isn't just ECC key algo other than ed25519. In fact, it is a
part of NIST curve family (the others are nistp384 and nistp521).

Maybe we can just say "If unsure, or if your hardware device does not
support ED25519, use one of NIST curves (nistp256, nistp384, or nistp521)
instead".

-- 
An old man doll... just what I always wanted! - Clara

Re: [PATCH v1 5/5] maintainer-pgp-guide: minor wording tweaks

[Randy Dunlap]

On 7/28/22 13:57, Konstantin Ryabitsev wrote:
> Tweak some wording to remove redundant information or fix spacing.
> 
> Signed-off-by: Konstantin Ryabitsev <konstantin@linuxfoundation.org>
> 
> diff --git a/Documentation/process/maintainer-pgp-guide.rst b/Documentation/process/maintainer-pgp-guide.rst
> index 2ce38e5d547d..ea74c87d09d8 100644
> --- a/Documentation/process/maintainer-pgp-guide.rst
> +++ b/Documentation/process/maintainer-pgp-guide.rst
> @@ -265,9 +265,7 @@ home, such as your bank vault.
>      Your printer is probably no longer a simple dumb device connected to
>      your parallel port, but since the output is still encrypted with
>      your passphrase, printing out even to "cloud-integrated" modern
> -    printers should remain a relatively safe operation. One option is to
> -    change the passphrase on your master key immediately after you are
> -    done with paperkey.
> +    printers should remain a relatively safe operation.
>  
>  Back up your whole GnuPG directory
>  ----------------------------------
> @@ -311,7 +309,7 @@ Remove the Certify key from your homedir
>  ----------------------------------------
>  
>  The files in our home directory are not as well protected as we like to
> -think.  They can be leaked or stolen via many different means:
> +think. They can be leaked or stolen via many different means:

One or 2 spaces after a period is one of the things that we historically
don't care about (can go either way).
Along with use the serial comma and British/American spellings.

>  
>  - by accident when making quick homedir copies to set up a new workstation
>  - by systems administrator negligence or malice
> 

-- 
~Randy

Re: [PATCH v1 1/5] maintainer-pgp-guide: use key terminology consistent with upstream

[Wu XiangCheng]

[-- Attachment #1: Type: text/plain, Size: 4187 bytes --]

Hi,

话说 Konstantin Ryabitsev 于 2022-07-28 (四) 16:57:04 -0400 曰过：
> GnuPG does not use the word "master key" when referring to the subkey
> marked with the "certification" capability. Our use of this term was not
> only inconsistent, but also misleading, because in real life "master
> keys" are able to open multiple locks made for different keys, while PGP
> Certify key has no such capability.

They use "primary key" in their interface and document.

For example in their .po file:

msgid "Note: The public primary key and all its subkeys will be deleted.\n"
msgid "using subkey %s instead of primary key %s\n"

Also in gnupg/doc/gpg.texi:

By specifying the key to export using a key ID or a fingerprint
suffixed with an exclamation mark (!), a specific subkey or the
primary key can be exported.  This does not even require that the key
has the authentication capability flag set.

Using the new word?

> 
> Signed-off-by: Konstantin Ryabitsev <konstantin@linuxfoundation.org>
> 
> diff --git a/Documentation/process/maintainer-pgp-guide.rst b/Documentation/process/maintainer-pgp-guide.rst
> index 29e7d7b1cd44..cdd108f50fe7 100644
> --- a/Documentation/process/maintainer-pgp-guide.rst
> +++ b/Documentation/process/maintainer-pgp-guide.rst
[...]
> +
> +Understanding PGP Subkeys
> +-------------------------
> +
> +A PGP key rarely consists of a single keypair -- usually it is a
> +collection of independent subkeys that can be used for different
> +purposes based on their capabilities, assigned at their creation time.
> +PGP defined four capabilities that a key can have:
> +
> +- **[S]** keys can be used for signing
> +- **[E]** keys can be used for encryption
> +- **[A]** keys can be used for authentication
> +- **[C]** keys can be used for certifying other keys
> +
> +The **[C]** (certification) key is often called the "master" key, but

Maybe "The key carrying the **[C]**" is better, match the following
description. As your said, gpg always create a [SC] key by default.

> +this terminology is misleading because it implies that the Certify key
> +can be used in place of any of other subkey on the same chain (like a
> +physical "master key" would). For this reason, this guide will refer to
> +it as "the Certify key" to avoid any ambiguity.
> +
> +It is critical to fully understand the following:
> +
> +1. All subkeys are fully independent from each other. If you lose a
> +   private subkey, it cannot be restored or recreated from any other
> +   private key on your chain.
> +2. With the exception of the Certify key, there can be multiple subkeys
> +   with identical capabilities (e.g. you can have 2 valid encryption
> +   subkeys, 3 valid signing subkeys, but only one valid certification
> +   subkey). All subkeys are fully independent -- a message encrypted to
> +   one **[E]** subkey cannot be decrypted with any other **[E]** subkey
> +   you may also have.
> +3. A single subkey may have multiple capabilities (e.g. your **[C]** key
> +   can also be your **[S]** key).

Reminding the limit of algorithms' capabilities by the way?
Like: As long as under the algorithm's capabilities.

> +
> +The key carrying the **[C]** (certify) capability is the only key that
> +can be used to indicate relationship with other keys. Only the **[C]**
> +key can be used to:
>  
>  - add or revoke other keys (subkeys) with S/E/A capabilities
>  - add, change or revoke identities (uids) associated with the key
> @@ -180,7 +190,7 @@ relationship with other keys. Only the **[C]** key can be used to:
>  
>  By default, GnuPG creates the following when generating new keys:
>  
> -- A master key carrying both Certify and Sign capabilities (**[SC]**)
> +- One subkey carrying both Certify and Sign capabilities (**[SC]**)

I suggest to use "primary key" here. Gnupg use it in their doc, and it is
really shown differently when typing --list-keys.

>  - A separate subkey with the Encryption capability (**[E]**)
>  
>  If you used the default parameters when generating your key, then that
[...]

-- 
Thanks,
Wu XiangCheng 
0x32684A40BCA7AEA7


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 659 bytes --]

Re: [PATCH v1 0/5] Update the maintainer PGP guide

[Alexander Dahl]

Hallo Konstantin,

Am Thu, Jul 28, 2022 at 04:57:03PM -0400 schrieb Konstantin Ryabitsev:
> This series updates the guide to match terminology used in the upstream
> "protecting code integrity" guide [1] and brings the documentation in
> line with the latest developments in the GnuPG world:

I could not find [1]. Did you miss to add the footnote?

Greets
Alex

> - uses "Certify key" instead of "master key" terms to remove common
>   confusion that the "Certify key" is somehow able to restore lost
>   private subkeys
> - removes keyserver instructions because keyservers have largely gone
>   semi-extinct due to GDPR enforcement and just general neglect
> - adds a link to the kernel.org PGP keyring documentation
> - updates information about ECC curve support among the devices the
>   guide talks about (Yubikeys are able to use ED25519 curves with the
>   latest firmware updates)
> - adds a section on using PGP-signed patches with b4 and patatt
> 
> Signed-off-by: Konstantin Ryabitsev <konstantin@linuxfoundation.org>
> 
> ---
> Konstantin Ryabitsev (5):
>       maintainer-pgp-guide: use key terminology consistent with upstream
>       maintainer-pgp-guide: remove keyserver instructions
>       maintainer-pgp-guide: update ECC support information
>       maintainer-pgp-guide: add a section on PGP-signed patches
>       maintainer-pgp-guide: minor wording tweaks
> 
>  Documentation/process/maintainer-pgp-guide.rst | 287 ++++++++++++-------------
>  1 file changed, 142 insertions(+), 145 deletions(-)
> ---
> base-commit: e0dccc3b76fb35bb257b4118367a883073d7390e
> change-id: 20220727-docs-pgp-guide-1dfc91614c0f
> 
> Best regards,
> -- 
> Konstantin Ryabitsev <konstantin@linuxfoundation.org>

Re: [PATCH v1 0/5] Update the maintainer PGP guide

[Konstantin Ryabitsev]

On Tue, Aug 02, 2022 at 11:07:21AM +0200, Alexander Dahl wrote:
> Hallo Konstantin,
> 
> Am Thu, Jul 28, 2022 at 04:57:03PM -0400 schrieb Konstantin Ryabitsev:
> > This series updates the guide to match terminology used in the upstream
> > "protecting code integrity" guide [1] and brings the documentation in
> > line with the latest developments in the GnuPG world:
> 
> I could not find [1]. Did you miss to add the footnote?

I did. I'll send a follow-up v2. The footnote was supposed to be to the
following URL:

[1]: https://github.com/lfit/itpol/blob/master/protecting-code-integrity.md

-K

Re: [PATCH v1 1/5] maintainer-pgp-guide: use key terminology consistent with upstream

[Konstantin Ryabitsev]

On Sat, Jul 30, 2022 at 09:12:35PM +0800, Wu XiangCheng wrote:
> They use "primary key" in their interface and document.
> 
> For example in their .po file:
> 
> msgid "Note: The public primary key and all its subkeys will be deleted.\n"
> msgid "using subkey %s instead of primary key %s\n"
> 
> Also in gnupg/doc/gpg.texi:
> 
> By specifying the key to export using a key ID or a fingerprint
> suffixed with an exclamation mark (!), a specific subkey or the
> primary key can be exported.  This does not even require that the key
> has the authentication capability flag set.
> 
> Using the new word?

Hmm.. this documentation must be newer than I last looked at it. Still, I
prefer to call it the "certify" key, because "primary key" is also ambiguous:

- "primary" key suggests that other keys are "secondary", which they are not
- "primary key" clashes with "primary identity" in an important way -- you can
  change your primary identity by adding a new one and assigning it a primary
  status, but you cannot add a new certify key

So, I'm sticking with the wording "certify key".

> > +The **[C]** (certification) key is often called the "master" key, but
> 
> Maybe "The key carrying the **[C]**" is better, match the following
> description. As your said, gpg always create a [SC] key by default.

Sure, I will consider this change.

> > +1. All subkeys are fully independent from each other. If you lose a
> > +   private subkey, it cannot be restored or recreated from any other
> > +   private key on your chain.
> > +2. With the exception of the Certify key, there can be multiple subkeys
> > +   with identical capabilities (e.g. you can have 2 valid encryption
> > +   subkeys, 3 valid signing subkeys, but only one valid certification
> > +   subkey). All subkeys are fully independent -- a message encrypted to
> > +   one **[E]** subkey cannot be decrypted with any other **[E]** subkey
> > +   you may also have.
> > +3. A single subkey may have multiple capabilities (e.g. your **[C]** key
> > +   can also be your **[S]** key).
> 
> Reminding the limit of algorithms' capabilities by the way?
> Like: As long as under the algorithm's capabilities.

I think that's unnecessary in this context. Yes, ed25519 keys cannot be used
for encryption (that's for cv25519 keys), but I'm just illustrating that a
single key can have multiple capabilities, so just leaving it at "may" is
enough here, imo.

Thank you for your suggestions.

Regards,
Konstantin

Re: [PATCH v1 5/5] maintainer-pgp-guide: minor wording tweaks

[Konstantin Ryabitsev]

On Fri, Jul 29, 2022 at 03:55:45PM -0700, Randy Dunlap wrote:
> >  The files in our home directory are not as well protected as we like to
> > -think.  They can be leaked or stolen via many different means:
> > +think. They can be leaked or stolen via many different means:
> 
> One or 2 spaces after a period is one of the things that we historically
> don't care about (can go either way).

Hm... I didn't know that applied within the context of a single file. Anyway,
I'm happy to drop this change -- pretty sure it's only there because my vim is
configured to replace ".  " with ". " on "gq" operations.

-K

Re: [PATCH v1 3/5] maintainer-pgp-guide: update ECC support information

[Konstantin Ryabitsev]

On Fri, Jul 29, 2022 at 04:11:26PM +0700, Bagas Sanjaya wrote:
> > -    If for some reason you prefer to stay with RSA subkeys, just replace
> > -    "ed25519" with "rsa2048" in the above command. Additionally, if you
> > -    plan to use a hardware device that does not support ED25519 ECC
> > -    keys, like Nitrokey Pro or a Yubikey, then you should use
> > -    "nistp256" instead or "ed25519."
> > +    Note, that if you plan to use a hardware device that does not
> > +    support ED25519 ECC keys, you should choose "nistp256" instead or
> > +    "ed25519."
> >  
> 
> nistp256 isn't just ECC key algo other than ed25519. In fact, it is a
> part of NIST curve family (the others are nistp384 and nistp521).
> 
> Maybe we can just say "If unsure, or if your hardware device does not
> support ED25519, use one of NIST curves (nistp256, nistp384, or nistp521)
> instead".

Hm... ED25519 is the default for GnuPG 2.3+, so I'm not sure it makes sense to
go into this level of detail here. Folks who are likely to need to use NIST
curves will probably already know this information without needing to list it
in this guide. As far as I can recall, TPMs and older Nitrokey Pros are some
of the few remaining devices that can't do ed25519, so the number of people
who would need to use NIST curves will likely be super small.

-K

Re: [PATCH v1 2/5] maintainer-pgp-guide: remove keyserver instructions

[Konstantin Ryabitsev]

On Fri, Jul 29, 2022 at 08:47:02AM +0700, Bagas Sanjaya wrote:
> On 7/29/22 03:57, Konstantin Ryabitsev wrote:
> > Keyservers are largely a thing of the past with the replacement systems
> > like keys.openpgp.net specifically designed to offer no support for the
> > web of trust. Remove all sections that talk about keyservers and add a
> > small section with the link to kernel.org documentation that talks about
> > using the kernel.org public key repository.
> > 
> 
> AFAIK, keyservers are synchronized (federated).

This is only the case for the keyserver network that has to the large degree
gone dark. The few remaining keyservers are either configured to be
non-federating (pgp.mit.edu, afaik), or written without that feature in the
first place (keys.openpgp.org).

> For example, when I submit
> my key to keys.openpgp.net, other keyservers (like keyserver.ubuntu.com
> that I use) also gets a copy of my key.

I would be very much susprised if that's the case (unless the ubuntu keyserver
pulls updates from keys.openpgp.org). Last I looked, hagrid-keyserver did not
support replication/federation.

-K