Commit Signing with CAC

Overview

Use this document to understand commit signing and how to set your operating system up to sign commits with a CAC.

All commits must be signed using either a CAC or a GPG key. Developers who have a CAC can use it to sign commits in GitLab after completing the required setup steps and configuration. For projects operating in IL4 and IL5 environments, CAC signing is mandatory for all commits.

To learn how to sign commits using GPG instead, follow the How to Commit Sign with GPG Guide.

WARNING

Party Bus does not support using IDEs for code signing. You are free to do so, but if you cannot sign commits in your IDE, please do not open a ticket with the Party Bus help desk. You will need to fix your issue or use the command line to sign commits that you create in your IDE.

Prerequisites

Regardless of your operating system, you must ensure that DoW Certificates are installed on your machine. Refer to militarycac.com for more information and instructions to install the necessary certificates.

Ensure your CAC has a CDS with an associated email address. If no email is present, either visit a local ID Card (find a location here) or use GPG signing by following the How to Commit Sign with GPG Guide.

Confirm User’s Commit Signing Email Address

1. Confirm that the user's commit email address in GitLab matches the one associated with their CAC's CDS.

   a. Check which email address is currently set as the commit email in GitLab,

   • View User Settings > Emails
   • Look for this icon:

   

   b. Request that your CAC's CDS email address be added if it is not already listed by submitting a Request for Gitlab Commit Sign Email Validation .

   Requests for repo1.dso.mil should be directed to the Iron Bank team.

   WARNING

   Users should not add the new email address to GitLab themselves. Attempting to do so will cause errors. Email addresses added by the user must be verified with a confirmation email, and P1 prevents emails from being sent from code.ilx.dso.mil.

   NOTE

   If multiple developers need their email addresses added and verified in GitLab, collect all user details and submit a single ticket. If the team is not yet in the pipeline queue, add the information to the COT epic in Jira.

2. Once the ticket has been closed, go to GitLab's User Settings > Profile and change the commit email to the (newly-added/verified) CAC CDS-associated email address.

Mac

The user's CAC must have a CDS with an associated email address. Follow the instructions below to verify that a CAC has a CDS with an associated email address.

1. Install Homebrew by following the instructions on the Homebrew website.

2. Identify the CAC's CDS.

   a. In a terminal, install opensc by running brew install opensc.

   b. List all of the CAC's certificates with pkcs15-tool by running pkcs15-tool --list-certificates.

   c. Identify the CDS. Find the Encoded Serial field and note down the third number shown (e.g., Encoded serial: 02 04 01234567).

3. Run the following in your terminal.

   # First Install Homebrew via bash script on brew.sh
   # Install OpenSC
   brew install opensc
   # List all certs
   pkcs15-tool --list-certificates

4. Check to see if the certificate has an email address.

   a. Install a signing utility.

   • MacOS/Windows: Use S/MIME. View installation instructions on GitHub.

   b. List certificates by running smimesign --list-keys

   c. Identify the certificate with a S/N value matching the encoded serial number noted in step 2c. The S/N value may have leading zeroes dropped (e.g., 01234567 --> 1234567).

Once the correct certificate has been identified, note the ID field's value; it will be used as the $signing_key in the following section.

       ID: 1234567890abcdefghijklmnopea7de1908d74b0 ⬅ Copy this signing key for git commit signing setup
      S/N: 123456 ⬅ Matches serial from previous step
Algorithm: SHA256-RSA
 Validity: 2025-01-07 00:00:00 +0000 UTC - 2026-01-02 23:59:59 +0000 UTC
   Issuer: CN=DOD ID CA-72,OU=DoD+OU=PKI,O=U.S. Government,C=US
  Subject: CN=SKYWALKER.LUKE.901082350304,OU=DoD+OU=PKI+OU=CONTRACTOR,O=U.S. Government,C=US
   Emails: luke.skywalker.ctr@us.af.mil # ⬅ CAC Email matches

Configure Git

This section explains how to configure Git user settings for global use. If you already have Git settings for other accounts or repositories, adjust these steps as needed.

1. Set global Git user configuration

2. Set global Git signing configuration

3. Paste the following in your terminal (using the ID from above)

   # Configure our Document Signing certificate as the signing key.
   git config --global user.signingkey < ID-FROM-ABOVE >
   # Configure Git to use S/MIME to sign commits and tags for all repositories.
   git config --global gpg.x509.program smimesign
   git config --global gpg.format x509
   # Configure Git to sign commits by default.
   git config --global commit.gpgsign true

Windows

Install Prerequisites

1. Open Windows Terminal. If your default profile is not PowerShell, open a new tab and select PowerShell.

2. Enter the following commands to install Git and smimesign.

   winget install Git.Git
   winget install GitHub.smimesign

3. Smimesign installation does not add itself to the PATH environmental variable. Add this manually.

   # Add smimesign to the system PATH environmental variable.
   [Environment]::SetEnvironmentVariable("PATH", $Env:PATH + ";C:\Program Files\smimesign", [EnvironmentVariableTarget]::Machine)
   
   # Reload environmental variables for current session.
   $env:Path = [System.Environment]::GetEnvironmentVariable("Path","Machine")

Identify Signing Certificate

Your CAC contains several certificates, each with its own intended purpose. This section explains how to ensure that the CAC has a certificate with the intended purpose of Document Signing and how to determine its serial number.

1. Use the following command to identify the certificate used for code signing. If the command returns no results, you may need to verify that your CAC is recognized and has the correct certificates.

   # Verify certificate exists
   Get-ChildItem Cert:\CurrentUser\My\ -EKU "Document Signing"

2. Store the certificate thumbprint in a local variable.

   # Save certificate serial to variable.
   $thumbprint = (Get-ChildItem Cert:\CurrentUser\My\ -EKU "Document Signing").Thumbprint

Configure Git and Smimesign

This section explains how to configure Git user settings for global use. If you already have Git settings for other accounts or repositories, adjust these steps as needed.

1. Check Git configuration for existing user email.

   git config --get user.email

2. Set global Git user configuration.

   # Replace text with your DoW email address associated with your CAC.
   git config --global user.e-mail "<DoW Email Address>"
   
   # Replace text with your full name.
   git config --global user.name "<Firstname Lastname>"

3. Set global Git signing configuration.

   # Configure our Document Signing certificate as the signing key
   git config --global user.signingkey $thumbprint
   
   # Verify settings
   git config list | Select-String -Pattern 'user' -CaseSensitive

Linux

WARNING

These steps have only been tested on Ubuntu 20.04 LTS. Other distributions of Linux may vary. Updates to GPG may cause issues with the detection of the card.

Prerequisites

Your computer must be CAC-enabled, and you must have sudo access. To enable the use of your CAC/smart card reader, please do the following:

1. In your command terminal, type sudo apt install libpcsclite1 pcscd pcsc-tools.

2. Plug in your CAC.

3. Type in sudo systemctl enable pcscd --now.

4. Type in pcsc_scan -r. This command is used to verify that your CAC is being read. If your CAC reader is detected, you should see something like the following figure:

If this command is successful, but stuck in a running state, press CTRL+C on your keyboard to kill the pcsc_scan. Please refer to the CAC documentation site for more information on setting up a smart card for Ubuntu.

Commit Signing with gpgsm for Linux

NOTE

Please ensure that no other GPG tools are currently installed on your system. You will need to do a fresh install of GPG using the steps in this section.

1. Install the GPG and smart card utilities by running the following command:

   sudo apt -y install gpg coolkey dirmngr gnupg2 gnupg-pkcs11-scd opensc

2. Run the command below and verify that your output is similar to what is depicted in the following figure. Brew users may need to uninstall GPG-related taps and log back in for the GPG program paths to be correct.

   # Option A
   $ gpgconf
   
   gpg:OpenPGP:/opt/homebrew/Cellar/gnupg/2.4.8/bin/gpg
   gpgsm:S/MIME:/opt/homebrew/Cellar/gnupg/2.4.8/bin/gpgsm
   keyboxd:Public Keys:/opt/homebrew/Cellar/gnupg/2.4.8/libexec/keyboxd
   gpg-agent:Private Keys:/opt/homebrew/Cellar/gnupg/2.4.8/bin/gpg-agent
   scdaemon:Smartcards:/opt/homebrew/Cellar/gnupg/2.4.8/libexec/scdaemon
   dirmngr:Network:/opt/homebrew/Cellar/gnupg/2.4.8/bin/dirmngr
   pinentry:Passphrase Entry:/opt/homebrew/opt/pinentry/bin/pinentry
   
   # Option B
   $ gpgconf
   
   gpg:OpenPGP:/usr/bin/gpg
   gpgsm:S/MIME:/usr/bin/gpgsm
   keyboxd:Public Keys:/usr/libexec/keyboxd
   gpg-agent:Private Keys:/usr/bin/gpg-agent
   scdaemon:Smartcards:/usr/libexec/scdaemon
   dirmngr:Network:/usr/bin/dirmngr
   pinentry:Passphrase Entry:/opt/homebrew/opt/pinentry/bin/pinentry

3. Create the file ~/.gnupg/gnupg-pkcs11-scd.conf with the following contents:

   providers p1
   provider-p1-library /usr/lib/pkcs11/libcoolkeypk11.so
   providers smartcardhsm
   provider-smartcardhsm-library /usr/lib/x86_64-linux-gnu/opensc-pkcs11.so

4. Create another file ~/.gnupg/gpg-agent.conf with the following contents:

   scdaemon-program /usr/bin/gnupg-pkcs11-scd

5. (OPTIONAL) If you would like to use a command line interface for entering your PIN, run the following commands:

   echo 'pinentry-program /usr/local/bin/pinentry-curses' >> ~/.gnupg/gpg-agent.conf
   echo 'export GPG_TTY=$(tty)' >> ~/.bashrc

6. Run gpg --card-status to verify that the gnupg program can detect your card.

7. Add DoW Root Certificate 3 to your system's root trust store by running the following:

   wget https://dl.dod.cyber.mil/wp-content/uploads/pki-pke/zip/unclass-certificates_pkcs7_v5-6_dod.zip
   unzip unclass-certificates_pkcs7_v5-6_dod.zip
   sudo cp Certificates_PKCS7_v5.6_DoD/DoD_PKE_CA_chain.pem /usr/local/share/ca-certificates/DoD_PKE_CA_chain.crt
   sudo cp Certificates_PKCS7_v5.6_DoD/DoD_PKE_CA_chain.pem /etc/ssl/certs/DoD_PKE_CA_chain.crt
   sudo update-ca-certificates

8. Run pkcs15-tool --list-certificates.

   #$ pkcs15-tool --list-certificates
   Using reader with a card: Identive SCR33xx v2.0 USB SC Reader
   X.509 Certificate [Certificate for PIV Authentication]
   Object Flags : [0x00]
   Authority : no
   Path :
   ID : 01
   Encoded serial : 02 03 0F0000
   
   X.509 Certificate [Certificate for Digital Signature] # ⬅ Look for "Digital Signature"
   Object Flags : [0x00]
   Authority : no
   Path :
   ID : 02 # ⬅ Note the ID of the Digital Signature
   Encoded serial : 02 03 123456
   
   X.509 Certificate [Certificate for Key Management]
   Object Flags : [0x00]
   Authority : no
   Path :
   ID : 03
   Encoded serial : 02 03 000000
   
   X.509 Certificate [Certificate for Card Authentication]
   Object Flags : [0x00]
   Authority : no
   Path :
   ID : 04
   Encoded serial : 02 03 000000

9. Run the following to import the Root CRL for your certificate, using the ID from the previous step. Additionally, replace < FILENAME > with the file downloaded in the second step.

   pkcs15-tool --read-certificate < ID > > mycert.crt
   wget $(openssl x509 -in mycert.crt -text | grep "CA Issuers" | awk '{ print $4 }' | sed 's/URI://g')

10. Note the file downloaded in the previous wget step and copy its name into the following commands.

    touch ~/.gnupg/trustlist.txt
    dirmngr --fetch-crl $(openssl x509 -inform der -in < FILENAME >.cer -text | grep crl | grep -v "CA Issuers" | sed 's/URI://g')
    gpgsm --import < FILENAME >.cer
    gpgsm --import mycert.crt

11. Restart your GPG agent to use your new settings from the previous steps.

    gpgconf --kill all

12. There are multiple commands to set up GPG signing globally. The first two commands are for a more automated approach; however, you can grab the email address and the signing key manually by running gpgsm --list-secret-keys and retrieving the email associated with your CAC key as well as the signing key, denoted by ID.

    signingEmail=$(gpgsm --list-secret-keys | grep aka | awk '{ print $2 }')
    signingkey=$( gpgsm --list-secret-keys | egrep '(key usage|ID)' | grep -B 1 digitalSignature | awk '/ID/ {print $2}')
    git config --global user.email $signingEmail
    git config --global user.signingkey $signingkey
    git config --global gpg.format x509
    git config --global gpg.x509.program gpgsm
    git config --global commit.gpgsign true

13. Commit

    Your first attempt at signing a commit may fail if the Root CA is not already trusted. You will be prompted to trust (and later confirm) the DoW Root CA with a similar message, as depicted in the following image. Elect to trust the certificate, and its fingerprint will then be added to ~/.gnupg/trustlist.txt. Once that is done, reattempting the commit should work.

    git commit -m "ticket number message"

Using Commit Signing

WARNING

If the identified CAC certificate does not have an email address associated with it:

1. Stop here. Instead, set up commit signing using a GPG key by following the How To Commit Signing with GPG Guide.
2. Visit a local ID Card office to associate an email address with your CAC. Find a location here.

1. Configure Git for commit signing. There are three scopes to choose from: repository, folder, or global.

   For Linux Users, if you have not followed the steps above to set up global signing, please note that gpg.x509.program is gpgsm, not smimesign.

   For WSL users, when defining gpg.x509.program, it should be set to the absolute path to the program on your base system, e.g., "/mnt/c/Program Files/smimesign/smimesign.exe". In addition to setting the path to your signing program, it is recommended that you set your credential manager to the Windows path.

   git config --global credential.helper "/mnt/c/Program\ Files/Git/mingw64/bin/git-credential-manager.exe"

   • Repository affects only one Git repository.

     a. In a terminal, navigate to the repository to be configured for commit signing. Then run the following commands:

     git config user.email john.doe.ctr@us.af.mil
     git config user.signingkey $signing_key
     git config gpg.x509.program smimesign
     git config gpg.format x509
     git config commit.gpgsign true

     NOTE: This repository configuration will take precedence over global configuration.

   • Folder affects all Git repositories in a folder. The steps below generate a .gitconfig-partybus file that should be placed in the home directory.

     a. In a terminal, run the following commands:

     # NOTE: The path to the folder to configure is represented below as: ~/path/to/folder cd ~
     git config --file=.gitconfig-partybus --add user.email john.doe.ctr@us.af.mil
     git config --file=.gitconfig-partybus --add user.signingkey $signing_key
     git config --file=.gitconfig-partybus --add gpg.x509.program smimesign
     git config --file=.gitconfig-partybus --add gpg.format x509
     git config --file=.gitconfig-partybus --add commit.gpgsign true # set if you do not want to set -S flag for commits
     git config --global --add includeif.gitdir:~/path/to/folder/.path .gitconfig-partybus # NOTE: .path is not part of the gitdir path specified, which is ~/path/to/folder

     Note: The last configuration value listed for a field takes precedence. In the global Git configuration (~/.gitconfig), the includeif.gitdir should be listed last if it should take precedence over values in the global Git configuration.

   • Global affects all Git repositories on a local machine.

     a. In a terminal, run the following commands:

     git config --global user.email john.doe.ctr@us.af.mil
     git config --global user.signingkey $signing_key
     git config --global gpg.x509.program smimesign
     git config --global gpg.format x509
     git config --global commit.gpgsign true

2. Verify that the Git configuration is correctly set up.

   a. In a terminal, navigate to a repository that should have the configuration applied.

   b. To list out the repository's Git configuration, run git config --list. The fields that should be listed are outlined in the following screenshot:

   INFO

   Git Configuration Precedence: When Git configurations are output using git config --list, settings listed last take precedence over those listed higher up.

   Git configurations are listed in the following order:

   1. Global (NOTE: The folder set up above is considered global. Its precedence depends on where the includeif is listed.)
   2. Repository

   In the example above, user.email is listed twice. ejay.tumacder.ctr@us.af.mil is listed second, making it take precedence over etumacder@revacomm.com.

   Note that this explanation of Git configuration and precedence only relays what is necessary for this guide. Visit Git's git config documentation to learn more.

   c. When a commit is attempted, the user should be prompted for their PIN. Run git log --show-signature to confirm that a commit has been signed.

Moving forward, commits should be viewable in the repository's "History" in GitLab, showing as "Verified." If this is not the case, refer to the FAQ.

Troubleshooting

1. If you are having any issues with the GPG agent, aside from rebooting or re-inserting your CAC, run this command to kill the gpg-agent server: gpgconf --kill all

2. Additionally, if using a pin entry program other than the GUI (i.e., pinentry-curses), it may take a few tries to sign a commit. You can run this command, which is more time-friendly, to get the initial pin entry and certificate trust prompts squared away: gpgsm --status-fd=2 -bsau $signingkey

Frequently Asked Questions

Commit Signing Questions

I can see my commit in GitLab, but it's stuck loading. When I try to view it through History, I see an error (e.g., 422 or 500). What's wrong?

A CAC certificate without an email address association was used. Choose a certificate that displays an email address when running smimesign --list-keys. If there's no email associated with the CAC being used, fall back to signing with a GPG Key.

My commit is "Unverified" in GitLab. What's wrong?

The email address associated with the CAC does not match the GitLab commit email. Please make sure that the CAC email is verified and is set to the email in the user's Git configuration.

I am able to do signed commits, but when I push, I get a "GitLab: Commit must be signed with a GPG key." What's wrong?

You may be trying to push multiple commits, and some of them are unsigned. You will need to roll back or rebase those commits and get them signed.

"Reject Signed Commits" Push Rule Questions

Will this affect merge request commits done through GitLab UI?

Merge request commits done through the UI are not affected by this change and do not need to be signed.

Will I still be able to commit changes through GitLab's Web IDE?

No.

Known Errors

Error When Signing a Commit

If you see this error, check that the DoW Certificates are installed on your machine. Refer to militarycac.com.

$ git commit -m -S 'commit message'
error: gpg failed to sign the data
fatal: failed to write commit object

If you previously signed commits using GPG, it's likely your Git user.signingkey configuration has already been set with your GPG key ID. If you've followed the directions above, you've set it as your CAC's CDS ID. You may need to remove the first configuration (i.e., the one whose value is your GPG key ID) to successfully sign commits with a CAC.

Git Push Failing

Push is failing due to mixed signed and unsigned commits. To remedy this, complete the following:

1. Reset to the previous good push.
2. Get the SHA from that push.
3. Run: git reset --soft < SHA >, which will undo commits.
4. Do a successful signed commit.
5. Push.

Related Content/References

Submit Requests to the Help Desk

• Request GitLab Commit Sign Email Validation.

Review Supporting Documentation

• Learn how to use x509-signed commits in GitLab projects.
• Learn how to install Homebrew.
• Access S/MIME Sign on GitHub.
• Download the S/MIME signing tool.
• Review the OpenSC Wiki.
• Review the Git Configuration Documentation.
• Install DoW Certificates.
• Locate an ID Card Office.