diff options
author | GitLab Bot <gitlab-bot@gitlab.com> | 2020-02-07 00:09:12 +0000 |
---|---|---|
committer | GitLab Bot <gitlab-bot@gitlab.com> | 2020-02-07 00:09:12 +0000 |
commit | 6168721025dd8e98caeb2bf6844273e6690eaf69 (patch) | |
tree | 8c4fb20d793669e488a739bc9951dab8b363eed4 /doc/user/project/repository/x509_signed_commits/index.md | |
parent | a89cb5cbdd832d4d9e80517973aceda6bc0a3856 (diff) | |
download | gitlab-ce-6168721025dd8e98caeb2bf6844273e6690eaf69.tar.gz |
Add latest changes from gitlab-org/gitlab@master
Diffstat (limited to 'doc/user/project/repository/x509_signed_commits/index.md')
-rw-r--r-- | doc/user/project/repository/x509_signed_commits/index.md | 100 |
1 files changed, 100 insertions, 0 deletions
diff --git a/doc/user/project/repository/x509_signed_commits/index.md b/doc/user/project/repository/x509_signed_commits/index.md new file mode 100644 index 00000000000..421c2f60350 --- /dev/null +++ b/doc/user/project/repository/x509_signed_commits/index.md @@ -0,0 +1,100 @@ +--- +type: concepts, howto +--- + +# Signing commits with x509 + +[x509](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 +such as SMIME, but beside that, Git 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 +instead of a web of trust with GPG. + +## How GitLab handles x509 + +GitLab uses its own certificate store and therefore defines the trust chain. + +For a commit 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 + [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. + +NOTE: **Note:** There is no certificate revocation list check in place at the moment. + +## Obtaining an x509 key pair + +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. + +## Associating your x509 certificate with Git + +To take advantage of X509 signing, you will need Git 2.19.0 or later. You can +check your Git version with: + +```sh +git --version +``` + +If you have the correct version, you can proceed to configure Git. + +### Linux + +Configure Git to use your key for signing: + +```sh +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 + +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: + +```sh +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 +can start signing your commits: + +1. Commit like you used to, the only difference is the addition of the `-S` flag: + + ```sh + 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: + +```sh +git config --global commit.gpgsign true +``` + +## Verifying commits + +To verify that a commit is signed, you can use the `--show-signature` flag: + +```sh +git log --show-signature +``` |