Why does git sign with GPG keys rather than using SSH keys?

Question

What are the differences between SSH and GPG asymmetric keys and why does git support signing with GPG rather than using the SSH agent?

Answer 1

Update Sept. 2022: 1Password supports generating and storing an SSH key for Git commit signature, recognized by GitHub.

---

Update 2021:

OpenSSH 8.2+ is available (packaged for instance in Git For Windows 2.33.1), and "it is now possible to sign arbitrary data with your SSH keys" (Andrew Ayer), including commits in Git.

Andrew points to git/git PR 1041 "ssh signing: Add commit & tag signing/verification via SSH keys using ssh-keygen", now with Git 2.34 (Nov. 2021)

gpg.format will have a new value "ssh"

set gpg.format = ssh and user.signingkey to a ssh public key string (like from an authorized_keys file) and commits/tags can be signed using the private key from your ssh-agent.

Andrew adds:

Always be wary of repurposing cryptographic keys for a different protocol. If not done carefully, there's a risk of cross-protocol attacks.

For example, if the structure of the messages signed by Git is similar to the structure of SSH protocol messages, an attacker might be able to forge Git artifacts by misappropriating the signature from an SSH transcript.

Fortunately, the structure of SSH protocol messages and the structure of messages signed by ssh-keygen are dissimilar enough that there is no risk of confusion.

That comes from:

Git 2.34 (Q4 2021): use ssh public crypto for object and push-cert signing.

See commit 1bfb57f, commit f265f2d, commit 3326a78, commit facca53, commit 4838f62, commit fd9e226, commit 29b3157, commit 64625c7, commit b5726a5 (10 Sep 2021) by Fabian Stelzer (FStelzer).
^{(Merged by Junio C Hamano -- gitster -- in commit 18c6653, 25 Oct 2021)}

ssh signing: verify signatures using ssh-keygen

^{Signed-off-by: Fabian Stelzer}

To verify a ssh signature we first call ssh-keygen -Y find-principal to look up the signing principal by their public key from the allowedSignersFile.
If the key is found then we do a verify.
Otherwise we only validate the signature but can not verify the signers identity.

Verification uses the gpg.ssh.allowedSignersFile (see ssh-keygen(1) "ALLOWED SIGNERS") which contains valid public keys and a principal (usually user@domain).
Depending on the environment this file can be managed by the individual developer or for example generated by the central repository server from known ssh keys with push access.
This file is usually stored outside the repository, but if the repository only allows signed commits/pushes, the user might choose to store it in the repository.

To revoke a key put the public key without the principal prefix into gpg.ssh.revocationKeyring or generate a KRL (see ssh-keygen(1) "KEY REVOCATION LISTS").
The same considerations about who to trust for verification as with the allowedSignersFile apply.

Using SSH CA Keys with these files is also possible.
Add "cert-authority" as key option between the principal and the key to mark it as a CA and all keys signed by it as valid for this CA.
See "CERTIFICATES" in ssh-keygen(1).

git config now includes in its man page:

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.: [email protected],[email protected] 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.

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.

---

With Git 2.35 (Q1 2022), extend the signing of objects with SSH keys and learn to pay attention to the key validity time range when verifying.

See commit 50992f9, commit 122842f, commit dd3aa41, commit 4bbf378, commit 6393c95, commit 30770aa, commit 0276943, commit cafd345, commit 5a2c1c0 (09 Dec 2021) by Fabian Stelzer (FStelzer).
^{(Merged by Junio C Hamano -- gitster -- in commit d2f0b72, 21 Dec 2021)}

ssh signing: make verify-commit consider key lifetime

^{Signed-off-by: Fabian Stelzer}

If valid-before/after dates are configured for this signatures key in the allowedSigners file then the verification should check if the key was valid at the time the commit was made.
This allows for graceful key rollover and revoking keys without invalidating all previous commits.
This feature needs openssh > 8.8.
Older ssh-keygen versions will simply ignore this flag and use the current time.
Strictly speaking this feature is available in 8.7, but since 8.7 has a bug that makes it unusable in another needed call we require 8.8.

Timestamp information is present on most invocations of check_signature.
However signer ident is not.
We will need the signer email / name to be able to implement "Trust on first use" functionality later.
Since the payload contains all necessary information we can parse it from there.
The caller only needs to provide us some info about the payload by setting payload_type in the signature_check struct.

• Add payload_type field & enum and payload_timestamp to struct `signature_check
• Populate the timestamp when not already set if we know about the payload type
• Pass -Overify-time={payload_timestamp} in the users timezone to all ssh-keygen verification calls
• Set the payload type when verifying commits
• Add tests for expired, not yet valid and keys having a commit date outside of key validity as well as within

git config now includes in its man page:

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 signatures creation.

This allows users to change a signing key without invalidating all previously made signatures.

---

And, still with Git 2.35 (Q1 2022), the cryptographic signing using ssh keys can specify literal keys for keytypes whose name do not begin with the "ssh-" prefix by using the "key::" prefix mechanism
(e.g. "key::ecdsa-sha2-nistp256").

See commit 3b4b5a7, commit 350a251 (19 Nov 2021) by Fabian Stelzer (FStelzer).
^{(Merged by Junio C Hamano -- gitster -- in commit ee1dc49, 21 Dec 2021)}

ssh signing: support non ssh-* keytypes

^{Signed-off-by: Fabian Stelzer}

The user.signingKey config for ssh signing supports either a path to a file containing the key or for the sake of convenience a literal string with the ssh public key.

To differentiate between those two cases we check if the first few characters contain "ssh-" which is unlikely to be the start of a path.
ssh supports other key types which are not prefixed with "ssh-" and will currently be treated as a file path and therefore fail to load.
To remedy this we move the prefix check into its own function and introduce the prefix key:: for literal ssh keys.
This way we don't need to add new key types when they become available.
The existing ssh- prefix is retained for compatibility with current user configs but removed from the official documentation to discourage its use.

git config now includes in its man page:

If gpg.format is set to ssh this can contain the path to either your private ssh key or the public key when ssh-agent is used. Alternatively it can contain a public key prefixed with key:: directly (e.g.: "key::ssh-rsa XXXXXX identifier").

The private key needs to be available via ssh-agent.
If not set git will call gpg.ssh.defaultKeyCommand (e.g.: "ssh-add -L") and try to use the first key available.

For backward compatibility, a raw key which begins with "ssh-", such as "ssh-rsa XXXXXX identifier", is treated as "key::ssh-rsa XXXXXX identifier", but this form is deprecated; use the key:: form instead.

---

"git merge $signed_tag"^(man) started to drop the tag message from the default merge message it uses by accident, which has been corrected with Git 2.35 (Q1 2022).

See commit c39fc06 (10 Jan 2022) by Taylor Blau (ttaylorr).
^{(Merged by Junio C Hamano -- gitster -- in commit cde28af, 12 Jan 2022)}

fmt-merge-msg: prevent use-after-free with signed tags

^{Reported-by: Linus Torvalds
Signed-off-by: Taylor Blau}

When merging a signed tag, fmt_merge_msg_sigs() is responsible for populating the body of the merge message with the names of the signed tags, their signatures, and the validity of those signatures.

In 0276943 ("ssh signing: use sigc struct to pass payload", 2021-12-09, Git v2.35.0-rc0 -- merge listed in batch #4), check_signature() was taught to pass the object payload via the sigc struct instead of passing the payload buffer separately.

In effect, 0276943 causes buf, and sigc.payload to point at the same region in memory.
This causes a problem for fmt_tag_signature(), which wants to read from this location, since it is freed beforehand by signature_check_clear() (which frees it via sigc's payload member).

That makes the subsequent use in fmt_tag_signature() a use-after-free.

As a result, merge messages did not contain the body of any signed tags.
Luckily, they tend not to contain garbage, either, since the result of strstr()-ing the object buffer in fmt_tag_signature() is guarded:

const char *tag_body = strstr(buf, "\n\n");
if (tag_body) {
  tag_body += 2;
  strbuf_add(tagbuf, tag_body, buf + len - tag_body);
}

Resolve this by waiting to call signature_check_clear() until after its contents can be safely discarded.
Harden ourselves against any future regressions in this area by making sure we can find signed tag messages in the output of fmt-merge-msg, too.

---

Original answer (2017): The very first notion of signing anything in Git was referenced in commit ec4465a, Git v0.99, Apr. 2005 (pretty much from the very beginning)

/**
 * A signature file has a very simple fixed format: three lines
 * of "object <sha1>" + "type <typename>" + "tag <tagname>",
 * followed by some free-form signature that git itself doesn't
 * care about, but that can be verified with gpg or similar.
 **/

So your question has legs.

The very first signed commit used gpg, but could have used anything else (commit 65f0d0e):

#!/bin/sh
object=${2:-$(cat .git/HEAD)}
type=$(cat-file -t $object) || exit 1
( echo -e "object $object\ntype $type\ntag $1\n"; cat ) > .tmp-tag
rm -f .tmp-tag.asc
gpg -bsa .tmp-tag && cat .tmp-tag.asc >> .tmp-tag
git-mktag < .tmp-tag
#rm .tmp-tag .tmp-tag.sig

Technically, you can use gpg in place of ssh. I haven't seen often the reverse though.
But you can use an ssh key-pair be used with PGP/GPG.
That means the first validation script might still work (commit f336e71)... except it expected a PGP comment:

#!/bin/sh
GIT_DIR=${GIT_DIR:-.git}

tag=$1
[ -f "$GIT_DIR/refs/tags/$tag" ] && tag=$(cat "$GIT_DIR/refs/tags/$tag")

git-cat-file tag $tag > .tmp-vtag || exit 1
cat .tmp-vtag | sed '/-----BEGIN PGP/Q' | gpg --verify .tmp-vtag -
rm -f .tmp-vtag

So, "Why does git sign with GPG keys rather than using SSH keys?": it is what GPG is meant to do, as opposed to SSH, which cannot do with openssh alone (it needs openssl).

As commented by torek, using SSH would be theoretically possible, it's just not convenient.

In addition, PGP has extra features (not that Git uses them directly—Git itself is just invokes some external software—but things like key revocation are useful in these contexts).

---

With Git 2.37 (Q3 2022) explains ssh.defaultKeyCommand:

See commit ce18a30 (08 Jun 2022) by Fabian Stelzer (FStelzer).
^{(Merged by Junio C Hamano -- gitster -- in commit 686790f, 15 Jun 2022)}

gpg docs: explain better use of ssh.defaultKeyCommand

^{Signed-off-by: Fabian Stelzer}

Using ssh-add -L for gpg.ssh.defaultKeyCommand is not a good recommendation.
It might switch keys depending on the order of known keys and it only supports ssh-* and no ecdsa or other keys.

Clarify that we expect a literal key prefixed by key::, give valid example use cases and refer to user.signingKey as the preferred option.

git config now includes in its man page:

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.

And, with commit ce18a30 (08 Jun 2022) by Fabian Stelzer (FStelzer).
^{(Merged by Junio C Hamano -- gitster -- in commit 686790f, 15 Jun 2022)}

686790f6c1:Merge branch 'fs/ssh-default-key-command-doc'

Doc update: fs/ssh-default-key-command-doc: gpg docs: explain better use of ssh.defaultKeyCommand

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.

Answer 2

The reason why you should NOT use ssh for signing commits is the one of the common rules of cryptography: You should not use the same keys for different applications/use cases.

In SSH you use a key for authentication, but that is something different then the signing your commits. For this, GPG is much more suited as it is already widely used for signing emails, files and so on.