Using Fortanix Data Security Manager for Git Commit Signing

1.0 Introduction

This article describes how to use Fortanix-Data-Security-Manager (DSM) with GitHub for Git Commit signing. GitHub allows users to sign their Git commits locally using GNU Privacy Guard (GPG), Secure Shell (SSH), or Secure/Multipurpose Internet Mail Extensions (S/MIME). GitHub will verify the Commit Signature using the GPG Public key associated with the GitHub account and mark it as verified so that other users will know that those commits come from a trusted source.

For more details, refer to Managing commit signature verification - GitHub Docs.

2.0 Prerequisites

Install the Fortanix Sequoia-PGP client from here and follow the instructions in this article to install sq-dsm.

3.0 Configure Fortanix DSM

A Fortanix DSM service must be configured, and the URL must be accessible. To create a Fortanix DSM account and group, refer to the following sections:

3.1 Signing Up

To get started with the Fortanix Data Security Manager (DSM) cloud service, you must register an account at <Your_DSM_Service_URL>. For example, https://eu.smartkey.io.

For detailed steps on how to set up the Fortanix DSM, refer to the User's Guide: Sign Up for Fortanix Data Security Manager SaaS documentation.

3.2 Creating an Account

Access the <Your_DSM_Service_URL> on the web browser and enter your credentials to log in to the Fortanix DSM.

3.3 Creating a Group

Perform the following steps to create a group in the Fortanix DSM:

1. Click the Groups menu item in the DSM left navigation panel and click the + button on the Groups page to add a new group.

   

2. On the Adding new group page, enter the following details:

   • Title: Enter a title for your group.

   • Description (optional): Enter a short description for the group.

3. Click the SAVE button to create the new group.

The new group has been added to the Fortanix DSM successfully.

3.4 Creating an Application

Perform the following steps to create an application (app) in the Fortanix DSM:

1. Click the Apps menu item in the DSM left navigation panel and click the + button on the Apps page to add a new app.

   

2. On the Adding new app page, enter the following details:

   • App name: Enter the name of your application.

   • Interface (optional): Select the REST API option as interface type from the drop down menu.

   • ADD DESCRIPTION (optional): Enter a short description for the application.

   • Authentication method: Select the default API Key as the method of authentication from the drop down menu. For more information on these authentication methods, refer to User's Guide: Authentication documentation.

   • Assigning the new app to groups: Select the group created in Section 3.3: Creating a Group from the list.

3. Click the SAVE button to add the new application. 

The new application has been added to the Fortanix DSM successfully.

3.5 Copying the API Key

Perform the following steps to copy the API key from the Fortanix DSM:

1. Click the Apps menu item in the DSM left navigation panel and click the app created in Section 3.4: Creating an Application to go to the detailed view of the app.

2. On the INFO tab, click the VIEW API KEY DETAILS button.

3. From the API Key Details dialog box, copy the API Key of the app to be used in Step 1 in Section 4.0 Sign Git Commits Locally.

4.0 Sign Git Commits Locally

You can use Fortanix-DSM (through sq-dsm) to create a GPG key and sign their Git commits with the GPG key generated in DSM.

Perform the following steps to sign a Git commit locally: 

1. Set the following environment variables in your local environment:

   1. FORTANIX_API_KEY with the value of the API key.

   2. FORTANIX_API_ENDPOINT with the value of the Fortanix DSM URL.

2. Run the following sq-dsm command to create a GPG key:

   sq-dsm key generate --dsm-key="<DSM-KEY-NAME>" --cipher-suite="<CIPHER-SUITE>" --userid="<EMAIL>"

   This command will generate a new key.
   For example,

   sq-dsm key generate --dsm-key="git_key" --cipher-suite="nistp521" --userid="Alice <[email protected]>"

   

3. Run the following command to extract the certificate:

   sq-dsm key extract-cert --dsm-key="<DSM-KEY-NAME>" > gitkey.asc

   This command will convert a key to a cert and save it in gitkey.asc.
   For example,

   sq-dsm key extract-cert --dsm-key="git_key" > gitkey.asc

4. Add the generated GPG key to your GitHub account:

   1. In your GitHub account, go to Setting → Access → SSH and GPG Keys, and create a new GPG key.

   2. Enter the following details:

      • Title: The name of your GPG key.

      • Key: Paste the cert (gitkey.asc) from the Step 3.

   3. To confirm the action, authenticate with your GitHub account.  

      

5. Run the following gpg.sh script to create a .sh executable file:

   #!/bin/bash
   echo "[GNUPG:] BEGIN_SIGNING" >&2
   output=$(sq-dsm sign --detached --dsm-key "<DSM-KEY-NAME>")
   
   if echo "$output" | grep -q "approved"; then
       echo "$output" | sed '1,/approved/d'
   elif echo "$output" | grep -q "denied"; then
       exit 1;
   else
       echo "$output"
   fi
   
   echo "[GNUPG:] SIG_CREATED D" >&2
   exit 0;
   

   Or you can also use the following batch script as an alternative to the above shell script based on your requirement. Replace <DSM-KEY-NAME> with your DSM GPG key name, in the above script.

   @echo off
   setlocal enabledelayedexpansion
   echo "[GNUPG:] BEGIN_SIGNING" >&2
   (set newline=^
   %=this line is empty=%
   )
   for /f "delims=" %%i in ('sq-dsm sign --detached --dsm-key"<DSM-KEY-NAME>"') do (
       set "line=%%i"
       set "output=!output!%%i!newline!"
       echo "!line!" | findstr "approved" > nul 
       if !errorlevel! equ 0 (
         set "output="
       ) 
       echo"!line!" | findstr "denied" > nul 
       if !errorlevel! equ 0 (
         endlocal
         exit /b 1
       ) 
       echo "!line!" | findstr "BEGIN" > nul
       if !errorlevel! equ 0 (
         set "output=!output!!newline!"
       ) 
   )
   echo !output!
   echo "[GNUPG:] SIG_CREATED D" >&2
   endlocal
   exit /b 0

   Replace <DSM-KEY-NAME> with your DSM GPG key name, in the above scripts.
   For example,

   sq-dsm sign --detached --dsm-key "git_key"

6. Set the local Git configuration using the following steps.

   1. Run the following command to unset the configuration to use the default format of open pgp:

      git config --global --unset gpg.format

   2. Run the following command to set the primary GPG signing key in Git:

      git config --global user.signingkey <Key ID>

      Replace the <KEY ID> with the Key ID of the GPG key added to your GitHub account as described in Step 4 above.

   3. Set the GPG program in Git using the following command.

      git config --global gpg.program /path/to/gpg.sh

   4. Your GPG key must be associated with a GitHub-verified email linked to your GitHub account that matches your committer identity
      Set your EMAIL used for key creation in Fortanix DSM as user.email in Git using the following command, and also ensure that it is a verified email in your GitHub account.

      git config --global user.email <EMAIL>

   5. Optionally, you can use the following command to configure Git to sign all commits by default.

      git config --global commit.gpgsign true

7. When committing changes, add the -S (note that ‘S’ must be capitalized) flag to the git commit command if commit.gpgsign was not set to true.
   For example:

   git commit -S -m "commit message"

5.0 Signed Git Commit

You will now get Signed Git Commits as shown in the figure below:

6.0 References

• Managing commit signature verification - GitHub Docs