summaryrefslogtreecommitdiff
path: root/README.rst
diff options
context:
space:
mode:
authorKonstantin Ryabitsev <konstantin@linuxfoundation.org>2020-11-23 15:33:24 -0500
committerKonstantin Ryabitsev <konstantin@linuxfoundation.org>2020-11-23 15:33:24 -0500
commit816375b5a8fb342324d3fd1cc6630f2fde7483da (patch)
tree328fbd6a1b11f89124dc770ddf6ba7aa82f5f188 /README.rst
parent1413539c899bd2ecbc208f3ef70f99d2ecbb3352 (diff)
downloadb4-816375b5a8fb342324d3fd1cc6630f2fde7483da.tar.gz
Add sendemail-validate hook and attestation docs
This adds a symlinkable hook that can perform inline attstation straight from the b4 checkout dir, plus documentation that explains some of the core concepts behind in-header attestation. Signed-off-by: Konstantin Ryabitsev <konstantin@linuxfoundation.org>
Diffstat (limited to 'README.rst')
-rw-r--r--README.rst99
1 files changed, 99 insertions, 0 deletions
diff --git a/README.rst b/README.rst
index 274cf0e..266c62a 100644
--- a/README.rst
+++ b/README.rst
@@ -30,6 +30,105 @@ alias in your .bash_profile::
Setting up a symlink should also be possible.
+Patch attestation (EXPERIMENTAL)
+--------------------------------
+Starting with version 0.6, b4 implements in-header patch attestation,
+following the approach proposed here:
+
+https://git.kernel.org/pub/scm/linux/kernel/git/mricon/patch-attestation-poc.git/tree/README.rst
+
+At this time, only PGP mode is implemented, but further work is expected
+in future versions of b4.
+
+Attesting your own patches
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+Patch attestation is done via message headers and stays out of the way
+of usual code submission and review workflow. At this time, only
+maintainers using b4 to retrieve patches and patch series will benefit
+from patch attestation, but everyone is encouraged to submit
+cryptographic patch attestation with their work anyway, in hopes that it
+becomes a common and widely used procedure.
+
+To start attesting your own patches:
+
+1. Make sure you have b4 version 0.6.0 or above:
+ ``b4 --version``
+2. If you don't already have a PGP key, you can follow the following
+ guide on how to generate it:
+ https://www.kernel.org/doc/html/latest/process/maintainer-pgp-guide.html
+3. It is strongly recommended to use ed25519 as your signing key
+ algorithm, as it will result in much smaller signatures, preventing
+ unnecessary email header bloat.
+4. Make sure your ``user.email`` and ``user.signingkey`` are set either
+ globally, or in the repository you will be using for attestation.
+5. Add the ``sendemail-validate`` hook to each repository you want
+ enabled for attestation, with the following single line of content as
+ the hook body:
+ ``b4 attest $1``.
+
+If you are using b4 from git checkout, you can use a symlink instead::
+
+ ln -s path/to/b4/hooks/sendemail-validate-attestation-hook \
+ .git/hooks/sendemail-validate
+
+(Note, that there's a second "E" in send*E*mail.)
+
+Next time you run ``git send-email``, b4 will automatically add
+attestation headers to all patches before they go out.
+
+Verifying attestation on received patches
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+There are three attestation verification policies in b4:
+
+- check (default)
+- softfail
+- hardfail
+
+The default "check" policy is look for any available attestation and try
+to verify it. If verification fails, b4 will not output any errors, but
+will not show verification checkmarks either.
+
+In "softfail" mode, any verification errors will be prominently
+displayed, but b4 will still generate the .mbx file with patches.
+
+The "hardfail" mode will show verification errors and exit without
+generating the .mbox file with patches.
+
+You can set the preferred policy via the git configuration file::
+
+ [b4]
+ attestation-policy = softfail
+
+Using with mutt
+~~~~~~~~~~~~~~~
+You can show patch attestation data with mutt, using the following
+configuration parameters::
+
+ set display_filter="b4 -q attest -m"
+ ignore *
+ unignore from date subject to cc list-id:
+ unignore x-patch-hashes: x-patch-sig:
+ unignore attested-by: attestation-failed:
+
+When displaying a message containing in-header PGP attestation
+signatures, mutt will display either the "Attested-By" or the
+"Attestation-Failed" headers, e.g.::
+
+ Date: Mon, 23 Nov 2020 13:38:50 -0500
+ From: Konstantin Ryabitsev <konstantin@linuxfoundation.org>
+ To: mricon@kernel.org
+ Subject: [PATCH 3/5] Fix in-header attestation code
+ Attested-By: Konstantin Ryabitsev <konstantin@linuxfoundation.org> (pgp: B6C41CE35664996C)
+
+or::
+
+ Date: Mon, 23 Nov 2020 13:38:48 -0500
+ From: Konstantin Ryabitsev <konstantin@linuxfoundation.org>
+ To: mricon@kernel.org
+ Subject: [PATCH 1/5] Add not very simple dkim key caching
+ Attestation-Failed: signature failed (commit message, patch metadata)
+
+
Support
-------
For support or with any other questions, please email