Sign commits and tags with X.509 certificates

Still need help?

The Atlassian Community is here for you.

Ask the community

In Bitbucket Data Centre 8.15 and later, you can use X.509 certificates to sign your commits and tags.

Signature trust

To determine whether a signed commit or tag is trusted (verified) or not trusted (not verified), Bitbucket needs to know the X.509 certificates that issue any signing X.509 certificates. Bitbucket Data Center stores specific information about the issuing X.509 certificates in its database. To store this information, you need to add your root and intermediate X.509 certificates through the REST API.

Verification of a signed commit or tag

For a signed commit or tag to be considered verified in Bitbucket Data Center, the following conditions should be met:

  1. The signed Git content hasn’t been modified by a malicious third party and can be processed successfully.

  2. There is a matching user known in Bitbucket Data Center that has the same email address as the one defined on the X.509 certificate used for signing.

    1. Note that if there is more than one email address listed on the X.509 certificate, only the first email address will be used for matching to the user in Bitbucket Data Center.

  3. The X.509 certificate has never been revoked.

    1. Bitbucket Data Center will use the CRL (Certificate Revocation List) information of an issuing X.509 certificate to determine whether the signing X.509 certificate has been revoked or not.

    2. CRL entries are fetched every 24 hours for freshness from a specified CRL distribution point from the issuing X.509 certificate. But if a manual update of the CRL entries is warranted, the fetching of CRL entries can be performed through the REST API for the given issuing X.509 certificate.

  4. The X.509 certificate meets the defined validity period.

For any other case, the signature will be determined as not verified.

Installing smimesign

For the instructions to install smimesign, check the official GitHub documentation: smimesign (S/MIME Sign).

Configuring Git

You should configure Git globally or locally before using X.509 certificates to sign and verify commits and to sign tags.

Specify your X.509 key

If you're using an X.509 key that matches your committer identity, you can begin signing commits and tags without any further configuration.

However, if you aren’t using an X.509 certificate that matches your committer identity, you can list all your X.509 certificates that can be used by running the following command:

smimesign --list-keys

From the list of X.509 keys, copy the ID value of the X.509 key that you'd like to use. For example, from the following sample output, the used ID is 4df4ce209319b0904fb3f2813115d5e4438e8c3c.

       ID: 4df4ce209319b0904fb3f2813115d5e4438e8c3c
      S/N: 468e1711b4ade3fc
Algorithm: SHA256-RSA
 Validity: 2023-10-08 23:35:00 +0000 UTC - 2024-10-08 23:35:00 +0000 UTC
   Issuer: CN=DigiCert SHA2 Assured ID CA,OU=www.digicert.com,O=DigiCert Inc,C=US
  Subject: CN=Bitbucket,OU=Enterprise,O=Atlassian,L=Sydney,ST=NSW,C=AU
   Emails: bitbucket@example.com

Global configuration

If you’d like to configure the global signing of your commits and tags with X.509 keys for all repositories, use the following commands:

git config --global gpg.x509.program smimesign
git config --global gpg.format x509
git config --global user.signingkey <ID>

The <ID> in the last command corresponds to the ID of your X.509 key. In the example, the value for <ID> is 4df4ce209319b0904fb3f2813115d5e4438e8c3c.

Local configuration

If you’d like to configure signing your commits and tags with X.509 keys locally for a single repository then navigate to that repository you would like to use and use the following commands:

git config --local gpg.x509.program smimesign
git config --local gpg.format x509
git config --local user.signingkey <ID>

The <ID> in the last command corresponds to the ID of your X.509 key. In the example, the value for <ID> is 4df4ce209319b0904fb3f2813115d5e4438e8c3c.

Signing and verifying commits with X.509 certificates

Once your Git configuration has been set up with an X.509 certificate, you can begin signing your commits and tags and verifying the signed commits and tags locally.

Sign commits

To sign commits, run the following command:

git commit -S -m "Signed with an X.509 certificate"

Verify commits locally

To verify commits locally, run the following command:

git log --show-signature

After running the command, you should see a message similar to the following:

commit 29463c73b2bf9d9be670b24c5c64d213117cb748
smimesign: Signature made using certificate ID 0x298d2e3a40096cdf3c8855c7f1a85dbc08c59ab6
...

The certificate ID from the Git command should match both of the following SHA-1s:

  • the SHA-1 in the Bitbucket Data Center verification dialog for the verified commit

  • the SHA-1 of the signing X.509 certificate

Sign tags

To sign tags, run the following command:

git tag -s v1.0.0 -m "Tag signed with an X.509 certificate"
Last modified on Oct 25, 2023

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.