diff options
Diffstat (limited to 'doc/user/project/repository/x509_signed_commits/index.md')
-rw-r--r-- | doc/user/project/repository/x509_signed_commits/index.md | 71 |
1 files changed, 52 insertions, 19 deletions
diff --git a/doc/user/project/repository/x509_signed_commits/index.md b/doc/user/project/repository/x509_signed_commits/index.md index 19238839a5e..20143af0b33 100644 --- a/doc/user/project/repository/x509_signed_commits/index.md +++ b/doc/user/project/repository/x509_signed_commits/index.md @@ -2,21 +2,21 @@ type: concepts, howto --- -# Signing commits with x509 +# Signing commits and tags with X.509 -[x509](https://en.wikipedia.org/wiki/X.509) is a standard format for public key +[X.509](https://en.wikipedia.org/wiki/X.509) is a standard format for public key certificates issued by a public or private Public Key Infrastructure (PKI). -Personal x509 certificates are used for authentication or signing purposes +Personal X.509 certificates are used for authentication or signing purposes such as SMIME, but Git also supports signing of commits and tags -with x509 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 x509 certificates +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 instead of a web of trust with GPG. -## How GitLab handles x509 +## How GitLab handles X.509 GitLab uses its own certificate store and therefore defines the trust chain. -For a commit to be *verified* by GitLab: +For a commit or tag to be *verified* by GitLab: - 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 @@ -25,9 +25,14 @@ For a commit to be *verified* by GitLab: which is usually up to three years. - The signing time is equal or later then commit time. -NOTE: **Note:** There is no certificate revocation list check in place at the moment. +NOTE: **Note:** Certificate revocation lists are checked on a daily basis via background worker. -## Obtaining an x509 key pair +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 If your organization has Public Key Infrastructure (PKI), that PKI will provide an S/MIME key. @@ -37,12 +42,12 @@ 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. -## Associating your x509 certificate with Git +## Associating your X.509 certificate with Git -To take advantage of X509 signing, you will need Git 2.19.0 or later. You can +To take advantage of X.509 signing, you will need Git 2.19.0 or later. You can check your Git version with: -```sh +```shell git --version ``` @@ -52,7 +57,7 @@ If you have the correct version, you can proceed to configure Git. Configure Git to use your key for signing: -```sh +```shell 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 @@ -64,21 +69,21 @@ Install [smimesign](https://github.com/github/smimesign) by downloading the installer or via `brew install smimesign` on MacOS. Get the ID of your certificate with `smimesign --list-keys` and set your -signingkey `git config --global user.signingkey ID`, then configure x509: +signingkey `git config --global user.signingkey ID`, then configure X.509: -```sh +```shell git config --global gpg.x509.program smimesign git config --global gpg.format x509 ``` ## Signing commits -After you have [associated your x509 certificate with Git](#associating-your-x509-certificate-with-git) you +After you have [associated your X.509 certificate with Git](#associating-your-x509-certificate-with-git) you can start signing your commits: 1. Commit like you used to, the only difference is the addition of the `-S` flag: - ```sh + ```shell git commit -S -m "feat: x509 signed commits" ``` @@ -87,7 +92,7 @@ can start signing your commits: If you don't want to type the `-S` flag every time you commit, you can tell Git to sign your commits automatically: -```sh +```shell git config --global commit.gpgsign true ``` @@ -95,6 +100,34 @@ git config --global commit.gpgsign true To verify that a commit is signed, you can use the `--show-signature` flag: -```sh +```shell git log --show-signature ``` + +## 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 +``` |