[PATCH v3 2/9] ssh signing: add documentation
From: Fabian Stelzer <fs@gigacodes.de>
Signed-off-by: Fabian Stelzer <fs@gigacodes.de>
---
Documentation/config/gpg.txt | 35 +++++++++++++++++++++++++++++++++--
Documentation/config/user.txt | 6 ++++++
2 files changed, 39 insertions(+), 2 deletions(-)
diff --git a/Documentation/config/gpg.txt b/Documentation/config/gpg.txt
index d94025cb368..16af0b0ada8 100644
--- a/Documentation/config/gpg.txt
+++ b/Documentation/config/gpg.txt
@@ -11,13 +11,13 @@ gpg.program::
gpg.format::
Specifies which key format to use when signing with `--gpg-sign`.
- Default is "openpgp" and another possible value is "x509".
+ Default is "openpgp". Other possible values are "x509", "ssh".
gpg.<format>.program::
Use this to customize the program used for the signing format you
chose. (see `gpg.program` and `gpg.format`) `gpg.program` can still
be used as a legacy synonym for `gpg.openpgp.program`. The default
- value for `gpg.x509.program` is "gpgsm".
+ value for `gpg.x509.program` is "gpgsm" and `gpg.ssh.program` is "ssh-keygen".
gpg.minTrustLevel::
Specifies a minimum trust level for signature verification. If
@@ -33,3 +33,34 @@ gpg.minTrustLevel::
* `marginal`
* `fully`
* `ultimate`
+
+gpg.ssh.keyring::
+ A file containing all valid SSH public signing keys.
+ Similar to an .ssh/authorized_keys file.
+ See ssh-keygen(1) "ALLOWED SIGNERS" for details.
+ If a signing key is found in this file then the trust level will
+ be set to "fully". Otherwise if the key is not present
+ but the signature is still valid then the trust level will be "undefined".
+
+ This file can be set to a location outside of the repository
+ and every developer maintains their own trust store.
+ A central repository server could generate this file automatically
+ from ssh keys with push access to verify the code against.
+ In a corporate setting this file is probably generated at a global location
+ from some automation that already handles developer ssh keys.
+
+ A repository that is only allowing signed commits can store the file
+ in the repository itself using a relative path. This way only committers
+ with an already valid key can add or change keys in the keyring.
+
+ Using a SSH CA key with the cert-authority option
+ (see ssh-keygen(1) "CERTIFICATES") is also valid.
+
+ To revoke a key place the public key without the principal into the
+ revocationKeyring.
+
+gpg.ssh.revocationKeyring::
+ Either a SSH KRL or a list of revoked public keys (without the principal prefix).
+ See ssh-keygen(1) for details.
+ If a public key is found in this file then it will always be treated
+ as having trust level "never" and signatures will show as invalid.
diff --git a/Documentation/config/user.txt b/Documentation/config/user.txt
index 59aec7c3aed..b3c2f2c541e 100644
--- a/Documentation/config/user.txt
+++ b/Documentation/config/user.txt
@@ -36,3 +36,9 @@ user.signingKey::
commit, you can override the default selection with this variable.
This option is passed unchanged to gpg's --local-user parameter,
so you may specify a key using any method that gpg supports.
+ If gpg.format is set to "ssh" this can contain the literal ssh public
+ key (e.g.: "ssh-rsa XXXXXX identifier") or a file which contains it and
+ corresponds to the private key used for signing. The private key
+ needs to be available via ssh-agent. Alternatively it can be set to
+ a file containing a private key directly. If not set git will call
+ "ssh-add -L" and try to use the first key available.
--
gitgitgadget
Fabian Stelzer via GitGitGadget <gitgitgadget@gmail.com>