summaryrefslogtreecommitdiff
path: root/Documentation/config/gpg.txt
blob: 86f6308c4c051814cc4f32a2d7b5d20aabb276e1 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
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
	signature, "`gpg --verify $signature - <$file`" is run, and the
	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`.
	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" and `gpg.ssh.program` is "ssh-keygen".
 
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`
 
gpg.ssh.defaultKeyCommand::
	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
	prefixed with `key::` is expected in the first line of its output.
	This allows for a script doing a dynamic lookup of the correct public
	key when it is impractical to statically configure `user.signingKey`.
	For example when keys or SSH Certificates are rotated frequently or
	selection of the right key depends on external factors unknown to git.
 
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.
	e.g.: `user1@example.com,user2@example.com ssh-rsa AAAAX1...`
	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.
Otherwise the trust level is `undefined` and git verify-commit/tag will fail.
+
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.
+
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
valid at the time of the signature's creation. This allows users to change a
signing key without invalidating all previously made signatures.
+
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.