2018-10-27 08:23:03 +02:00
|
|
|
gpg.program::
|
|
|
|
|
Use this custom program instead of "`gpg`" found on `$PATH` when
|
|
|
|
|
making or verifying a PGP signature. The program must support the
|
|
|
|
|
same command-line interface as GPG, namely, to verify a detached
|
2019-07-12 17:33:57 +02:00
|
|
|
signature, "`gpg --verify $signature - <$file`" is run, and the
|
2018-10-27 08:23:03 +02:00
|
|
|
program is expected to signal a good signature by exiting with
|
|
|
|
|
code 0, and to generate an ASCII-armored detached signature, the
|
|
|
|
|
standard input of "`gpg -bsau $key`" is fed with the contents to be
|
|
|
|
|
signed, and the program is expected to send the result to its
|
|
|
|
|
standard output.
|
|
|
|
|
|
|
|
|
|
gpg.format::
|
|
|
|
|
Specifies which key format to use when signing with `--gpg-sign`.
|
2021-09-10 22:07:36 +02:00
|
|
|
Default is "openpgp". Other possible values are "x509", "ssh".
|
2018-10-27 08:23:03 +02:00
|
|
|
|
|
|
|
|
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
|
2019-03-06 07:30:18 +01:00
|
|
|
be used as a legacy synonym for `gpg.openpgp.program`. The default
|
2021-09-10 22:07:36 +02:00
|
|
|
value for `gpg.x509.program` is "gpgsm" and `gpg.ssh.program` is "ssh-keygen".
|
gpg-interface: add minTrustLevel as a configuration option
Previously, signature verification for merge and pull operations checked
if the key had a trust-level of either TRUST_NEVER or TRUST_UNDEFINED in
verify_merge_signature(). If that was the case, the process die()d.
The other code paths that did signature verification relied entirely on
the return code from check_commit_signature(). And signatures made with
a good key, irregardless of its trust level, was considered valid by
check_commit_signature().
This difference in behavior might induce users to erroneously assume
that the trust level of a key in their keyring is always considered by
Git, even for operations where it is not (e.g. during a verify-commit or
verify-tag).
The way it worked was by gpg-interface.c storing the result from the
key/signature status *and* the lowest-two trust levels in the `result`
member of the signature_check structure (the last of these status lines
that were encountered got written to `result`). These are documented in
GPG under the subsection `General status codes` and `Key related`,
respectively [1].
The GPG documentation says the following on the TRUST_ status codes [1]:
"""
These are several similar status codes:
- TRUST_UNDEFINED <error_token>
- TRUST_NEVER <error_token>
- TRUST_MARGINAL [0 [<validation_model>]]
- TRUST_FULLY [0 [<validation_model>]]
- TRUST_ULTIMATE [0 [<validation_model>]]
For good signatures one of these status lines are emitted to
indicate the validity of the key used to create the signature.
The error token values are currently only emitted by gpgsm.
"""
My interpretation is that the trust level is conceptionally different
from the validity of the key and/or signature. That seems to also have
been the assumption of the old code in check_signature() where a result
of 'G' (as in GOODSIG) and 'U' (as in TRUST_NEVER or TRUST_UNDEFINED)
were both considered a success.
The two cases where a result of 'U' had special meaning were in
verify_merge_signature() (where this caused git to die()) and in
format_commit_one() (where it affected the output of the %G? format
specifier).
I think it makes sense to refactor the processing of TRUST_ status lines
such that users can configure a minimum trust level that is enforced
globally, rather than have individual parts of git (e.g. merge) do it
themselves (except for a grace period with backward compatibility).
I also think it makes sense to not store the trust level in the same
struct member as the key/signature status. While the presence of a
TRUST_ status code does imply that the signature is good (see the first
paragraph in the included snippet above), as far as I can tell, the
order of the status lines from GPG isn't well-defined; thus it would
seem plausible that the trust level could be overwritten with the
key/signature status if they were stored in the same member of the
signature_check structure.
This patch introduces a new configuration option: gpg.minTrustLevel. It
consolidates trust-level verification to gpg-interface.c and adds a new
`trust_level` member to the signature_check structure.
Backward-compatibility is maintained by introducing a special case in
verify_merge_signature() such that if no user-configurable
gpg.minTrustLevel is set, then the old behavior of rejecting
TRUST_UNDEFINED and TRUST_NEVER is enforced. If, on the other hand,
gpg.minTrustLevel is set, then that value overrides the old behavior.
Similarly, the %G? format specifier will continue show 'U' for
signatures made with a key that has a trust level of TRUST_UNDEFINED or
TRUST_NEVER, even though the 'U' character no longer exist in the
`result` member of the signature_check structure. A new format
specifier, %GT, is also introduced for users that want to show all
possible trust levels for a signature.
Another approach would have been to simply drop the trust-level
requirement in verify_merge_signature(). This would also have made the
behavior consistent with other parts of git that perform signature
verification. However, requiring a minimum trust level for signing keys
does seem to have a real-world use-case. For example, the build system
used by the Qubes OS project currently parses the raw output from
verify-tag in order to assert a minimum trust level for keys used to
sign git tags [2].
[1] https://git.gnupg.org/cgi-bin/gitweb.cgi?p=gnupg.git;a=blob;f=doc/doc/DETAILS;h=bd00006e933ac56719b1edd2478ecd79273eae72;hb=refs/heads/master
[2] https://github.com/QubesOS/qubes-builder/blob/9674c1991deef45b1a1b1c71fddfab14ba50dccf/scripts/verify-git-tag#L43
Signed-off-by: Hans Jerry Illikainen <hji@dyntopia.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-12-27 14:55:57 +01:00
|
|
|
|
|
|
|
|
gpg.minTrustLevel::
|
|
|
|
|
Specifies a minimum trust level for signature verification. If
|
|
|
|
|
this option is unset, then signature verification for merge
|
|
|
|
|
operations require a key with at least `marginal` trust. Other
|
|
|
|
|
operations that perform signature verification require a key
|
|
|
|
|
with at least `undefined` trust. Setting this option overrides
|
|
|
|
|
the required trust-level for all operations. Supported values,
|
|
|
|
|
in increasing order of significance:
|
|
|
|
|
+
|
|
|
|
|
* `undefined`
|
|
|
|
|
* `never`
|
|
|
|
|
* `marginal`
|
|
|
|
|
* `fully`
|
|
|
|
|
* `ultimate`
|
2021-09-10 22:07:37 +02:00
|
|
|
|
2021-12-17 17:17:18 +01:00
|
|
|
gpg.ssh.defaultKeyCommand::
|
2021-09-10 22:07:37 +02:00
|
|
|
This command that will be run when user.signingkey is not set and a ssh
|
|
|
|
|
signature is requested. On successful exit a valid ssh public key is
|
2022-01-26 13:14:25 +01:00
|
|
|
expected in the first line of its output. To automatically use the first
|
2021-09-10 22:07:37 +02:00
|
|
|
available key from your ssh-agent set this to "ssh-add -L".
|
2021-09-10 22:07:39 +02:00
|
|
|
|
|
|
|
|
gpg.ssh.allowedSignersFile::
|
|
|
|
|
A file containing ssh public keys which you are willing to trust.
|
|
|
|
|
The file consists of one or more lines of principals followed by an ssh
|
|
|
|
|
public key.
|
2021-12-15 17:23:48 +01:00
|
|
|
e.g.: `user1@example.com,user2@example.com ssh-rsa AAAAX1...`
|
2021-09-10 22:07:39 +02:00
|
|
|
See ssh-keygen(1) "ALLOWED SIGNERS" for details.
|
|
|
|
|
The principal is only used to identify the key and is available when
|
|
|
|
|
verifying a signature.
|
|
|
|
|
+
|
|
|
|
|
SSH has no concept of trust levels like gpg does. To be able to differentiate
|
|
|
|
|
between valid signatures and trusted signatures the trust level of a signature
|
|
|
|
|
verification is set to `fully` when the public key is present in the allowedSignersFile.
|
2021-10-13 09:51:07 +02:00
|
|
|
Otherwise the trust level is `undefined` and git verify-commit/tag will fail.
|
2021-09-10 22:07:39 +02:00
|
|
|
+
|
|
|
|
|
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 automation that already handles developer ssh keys.
|
|
|
|
|
+
|
|
|
|
|
A repository that only allows signed commits can store the file
|
|
|
|
|
in the repository itself using a path relative to the top-level of the working tree.
|
|
|
|
|
This way only committers with an already valid key can add or change keys in the keyring.
|
|
|
|
|
+
|
2021-12-09 09:52:45 +01:00
|
|
|
Since OpensSSH 8.8 this file allows specifying a key lifetime using valid-after &
|
|
|
|
|
valid-before options. Git will mark signatures as valid if the signing key was
|
2022-01-26 13:14:26 +01:00
|
|
|
valid at the time of the signature's creation. This allows users to change a
|
2021-12-09 09:52:45 +01:00
|
|
|
signing key without invalidating all previously made signatures.
|
|
|
|
|
+
|
2021-09-10 22:07:39 +02:00
|
|
|
Using a SSH CA key with the cert-authority option
|
|
|
|
|
(see ssh-keygen(1) "CERTIFICATES") is also valid.
|
|
|
|
|
|
|
|
|
|
gpg.ssh.revocationFile::
|
|
|
|
|
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.
|