2020-03-13 15:44:24 +05:30
|
|
|
---
|
|
|
|
type: concepts, howto
|
|
|
|
---
|
|
|
|
|
2020-05-24 23:13:21 +05:30
|
|
|
# Signing commits and tags with X.509
|
2020-03-13 15:44:24 +05:30
|
|
|
|
2020-05-24 23:13:21 +05:30
|
|
|
[X.509](https://en.wikipedia.org/wiki/X.509) is a standard format for public key
|
2020-03-13 15:44:24 +05:30
|
|
|
certificates issued by a public or private Public Key Infrastructure (PKI).
|
2020-05-24 23:13:21 +05:30
|
|
|
Personal X.509 certificates are used for authentication or signing purposes
|
2020-04-08 14:13:33 +05:30
|
|
|
such as SMIME, but Git also supports signing of commits and tags
|
2020-05-24 23:13:21 +05:30
|
|
|
with X.509 certificates in a similar way as with [GPG](../gpg_signed_commits/index.md).
|
|
|
|
The main difference is the trust anchor which is the PKI for X.509 certificates
|
2020-03-13 15:44:24 +05:30
|
|
|
instead of a web of trust with GPG.
|
|
|
|
|
2020-05-24 23:13:21 +05:30
|
|
|
## How GitLab handles X.509
|
2020-03-13 15:44:24 +05:30
|
|
|
|
|
|
|
GitLab uses its own certificate store and therefore defines the trust chain.
|
|
|
|
|
2020-05-24 23:13:21 +05:30
|
|
|
For a commit or tag to be *verified* by GitLab:
|
2020-03-13 15:44:24 +05:30
|
|
|
|
|
|
|
- The signing certificate email must match a verified email address used by the committer in GitLab.
|
|
|
|
- The Certificate Authority has to be trusted by the GitLab instance, see also
|
|
|
|
[Omnibus install custom public certificates](https://docs.gitlab.com/omnibus/settings/ssl.html#install-custom-public-certificates).
|
|
|
|
- The signing time has to be within the time range of the [certificate validity](https://www.rfc-editor.org/rfc/rfc5280.html#section-4.1.2.5)
|
|
|
|
which is usually up to three years.
|
|
|
|
- The signing time is equal or later then commit time.
|
|
|
|
|
2020-05-24 23:13:21 +05:30
|
|
|
NOTE: **Note:** Certificate revocation lists are checked on a daily basis via background worker.
|
2020-03-13 15:44:24 +05:30
|
|
|
|
2020-05-24 23:13:21 +05:30
|
|
|
NOTE: **Note:** Self signed certificates without `authorityKeyIdentifier`,
|
|
|
|
`subjectKeyIdentifier`, and `crlDistributionPoints` are not supported. We
|
|
|
|
recommend using certificates from a PKI that are in line with
|
|
|
|
[RFC 5280](https://tools.ietf.org/html/rfc5280).
|
|
|
|
|
|
|
|
## Obtaining an X.509 key pair
|
2020-03-13 15:44:24 +05:30
|
|
|
|
|
|
|
If your organization has Public Key Infrastructure (PKI), that PKI will provide
|
|
|
|
an S/MIME key.
|
|
|
|
|
|
|
|
If you do not have an S/MIME key pair from a PKI, you can either create your
|
|
|
|
own self-signed one, or purchase one. MozillaZine keeps a nice collection
|
|
|
|
of [S/MIME-capable signing authorities](http://kb.mozillazine.org/Getting_an_SMIME_certificate)
|
|
|
|
and some of them generate keys for free.
|
|
|
|
|
2020-05-24 23:13:21 +05:30
|
|
|
## Associating your X.509 certificate with Git
|
2020-03-13 15:44:24 +05:30
|
|
|
|
2020-05-24 23:13:21 +05:30
|
|
|
To take advantage of X.509 signing, you will need Git 2.19.0 or later. You can
|
2020-03-13 15:44:24 +05:30
|
|
|
check your Git version with:
|
|
|
|
|
2020-05-24 23:13:21 +05:30
|
|
|
```shell
|
2020-03-13 15:44:24 +05:30
|
|
|
git --version
|
|
|
|
```
|
|
|
|
|
|
|
|
If you have the correct version, you can proceed to configure Git.
|
|
|
|
|
|
|
|
### Linux
|
|
|
|
|
|
|
|
Configure Git to use your key for signing:
|
|
|
|
|
2020-05-24 23:13:21 +05:30
|
|
|
```shell
|
2020-03-13 15:44:24 +05:30
|
|
|
signingkey = $( gpgsm --list-secret-keys | egrep '(key usage|ID)' | grep -B 1 digitalSignature | awk '/ID/ {print $2}' )
|
|
|
|
git config --global user.signingkey $signingkey
|
|
|
|
git config --global gpg.format x509
|
|
|
|
```
|
|
|
|
|
|
|
|
### Windows and MacOS
|
|
|
|
|
2020-06-23 00:09:42 +05:30
|
|
|
Install [S/MIME Sign](https://github.com/github/smimesign) by downloading the
|
2020-03-13 15:44:24 +05:30
|
|
|
installer or via `brew install smimesign` on MacOS.
|
|
|
|
|
|
|
|
Get the ID of your certificate with `smimesign --list-keys` and set your
|
2020-06-23 00:09:42 +05:30
|
|
|
signing key `git config --global user.signingkey ID`, then configure X.509:
|
2020-03-13 15:44:24 +05:30
|
|
|
|
2020-05-24 23:13:21 +05:30
|
|
|
```shell
|
2020-03-13 15:44:24 +05:30
|
|
|
git config --global gpg.x509.program smimesign
|
|
|
|
git config --global gpg.format x509
|
|
|
|
```
|
|
|
|
|
|
|
|
## Signing commits
|
|
|
|
|
2020-05-24 23:13:21 +05:30
|
|
|
After you have [associated your X.509 certificate with Git](#associating-your-x509-certificate-with-git) you
|
2020-03-13 15:44:24 +05:30
|
|
|
can start signing your commits:
|
|
|
|
|
|
|
|
1. Commit like you used to, the only difference is the addition of the `-S` flag:
|
|
|
|
|
2020-05-24 23:13:21 +05:30
|
|
|
```shell
|
2020-03-13 15:44:24 +05:30
|
|
|
git commit -S -m "feat: x509 signed commits"
|
|
|
|
```
|
|
|
|
|
|
|
|
1. Push to GitLab and check that your commits [are verified](#verifying-commits).
|
|
|
|
|
|
|
|
If you don't want to type the `-S` flag every time you commit, you can tell Git
|
|
|
|
to sign your commits automatically:
|
|
|
|
|
2020-05-24 23:13:21 +05:30
|
|
|
```shell
|
2020-03-13 15:44:24 +05:30
|
|
|
git config --global commit.gpgsign true
|
|
|
|
```
|
|
|
|
|
|
|
|
## Verifying commits
|
|
|
|
|
|
|
|
To verify that a commit is signed, you can use the `--show-signature` flag:
|
|
|
|
|
2020-05-24 23:13:21 +05:30
|
|
|
```shell
|
2020-03-13 15:44:24 +05:30
|
|
|
git log --show-signature
|
|
|
|
```
|
2020-05-24 23:13:21 +05:30
|
|
|
|
|
|
|
## Signing tags
|
|
|
|
|
|
|
|
After you have [associated your X.509 certificate with Git](#associating-your-x509-certificate-with-git) you
|
|
|
|
can start signing your tags:
|
|
|
|
|
|
|
|
1. Tag like you used to, the only difference is the addition of the `-s` flag:
|
|
|
|
|
|
|
|
```shell
|
|
|
|
git tag -s v1.1.1 -m "My signed tag"
|
|
|
|
```
|
|
|
|
|
|
|
|
1. Push to GitLab and check that your tags [are verified](#verifying-tags).
|
|
|
|
|
|
|
|
If you don't want to type the `-s` flag every time you tag, you can tell Git
|
|
|
|
to sign your tags automatically:
|
|
|
|
|
|
|
|
```shell
|
|
|
|
git config --global tag.gpgsign true
|
|
|
|
```
|
|
|
|
|
|
|
|
## Verifying tags
|
|
|
|
|
|
|
|
To verify that a tag is signed, you can use the `--verify` flag:
|
|
|
|
|
|
|
|
```shell
|
|
|
|
git tag --verify v1.1.1
|
|
|
|
```
|