Skip to main content

Install client tools for standard keypair signing on GitHub

Code signing with Software Trust GitHub Actions streamlines the keypair-based signing process, improving software security while seamlessly integrating with DevOps processes. This action supports signing binaries on both Windows and Linux platforms.

This GitHub action automates the installation and configuration of Software Trust Manager client tools, enabling developers to quickly become signing-ready for GitHub action workflows.

Tip

Which client tools are installed and configured?

  • Signing Manager CTL (SMCTL)

    SMCTL provides a command line interface (CLI) that facilitates manual or automated private key, certificate management, and signing without the need for human intervention.

  • PKCS#11 library

    The PKCS#11 library manages secure key generation, hash signing, and certificate requirements when signing requests don't require transferring files or intellectual property

  • KSP library

    Software Trust KSP is a Microsoft CNG (Cryptographic: Next Generation) library-based client-side tool. The KSP takes a hash-based approach when signing requests that don't require transportation of your files and intellectual property.

  • JCE library

    The JCE library is used for signing with Jarsigner and integrates with any operating system that supports Java.

Prerequisites

Get plugin

To use this plugin, follow these steps:

  1. Go to Code Signing with Software Trust Manager in GitHub Marketplace.

  2. Select Use the latest version.

  3. Select the Copy icon to copy the plugin snippet.

  4. Paste the plugin snippet into your .yml file.

  5. Run your CI/CD pipeline in GitHub.

User authentication

Software Trust enforces multi-factor authentication for security. To access keypairs, certificates, and sign code, you need to set up two types of credentials: An API key and an authentication certificate.

Create an API key

The API key is an authentication method used to verify you as a user and your permissions assigned in DigiCert ONE. The API key provides the first factor authentication.

  1. In DigiCert ONE, select the profile (profile_icon.png) icon, and then select Admin Profile.

  2. Under API keys, select Create API key.

  3. For Name, enter a descriptive name for the key.

  4. For End date (optional), enter the date when the key should expire.

  5. Select Create. The API key appears this one time and can't be accessed again. Securely store the API key for future use.

Create an authentication certificate

The client authentication certificate is an authentication method used to verify you as a user and your permissions assigned in DigiCert ONE. The client authentication certificate provides the second factor authentication.

  1. In DigiCert ONE, select the profile (profile_icon.png) icon, and then select Admin Profile.

  2. Under Client authentication certificates, select Create client authentication certificate.

  3. For Nickname, enter a descriptive name for the key.

  4. For End date, enter the date when the certificate should expire.

  5. Select the desired Encryption and Signature hash algorithm.

  6. Select Generate certificate. The password appears this one time and can't be accessed again. Download the certificate and securely store the password for future use.

Convert your client authentication certificate to a base64 string

To add a client authentication certificate to GitHub secrets, first encode it as a base64 string. Use the following command, based on your operating system.

Secure GitHub use

For secure GitHub usage with Software Trust, store credentials as secrets and secure files. This approach protects sensitive information and maintains accountability for users performing code signing.

GitHub secrets

GitHub secrets allow you to encrypt variables so users can input sensitive information without exposing the actual values. For example, you can hide your API keys while still allowing collaborators to use them for signing tools through Software Trust. GitHub secrets can be used within GitHub Actions workflows

Configure GitHub secrets

Configure your credentials to encrypt them in GitHub Secrets and connect to Software Trust.

Note

When saving credentials as a secret, the credentials becomes fully encrypted. Even the creator (you), can't access them. If you think you may need these credentials in the future, securely and separately store them.

  1. Access the desired GitHub repository, and then select Settings.

  2. Go to Secrets and variables > Actions.

  3. Select New repository secret.

  4. Create a repository secret for each of the following credentials:

    Name

    Value

    SM_CLIENT_CERT_PASSWORD

    Insert the password that you were shown when you created your client authentication certificate described earlier.

    SM_CLIENT_CERT_FILE_B64

    Insert the base64 encoded string of your client authentication certificate that you created described earlier.

    SM_HOST

    The path to the DigiCert ONE portal with client authorization.  The SM_HOST value you use depends on whether you're using demo or prod.

    Tip

    For assistance, see host environment.

    SM_API_KEY

    Insert the API token you created earlier.

    SM_CODE_SIGNING_CERT_SHA1_HASH

    The certificate fingerprint.

Set up environment variables

When you've stored your credentials in GitHub secrets, use the following code snippets to set up your environment variables.

Decode your base64-encoded client authentication certificate

Use this snippet to decode yourbBase64-encoded client authentication certificate (SM_CLIENT_CERT_FILE_B64) and save it as a PKCS#12 file named Certificate_pkcs12.p12 in the test /d/ directory.

For Windows users: 

- name: Set up certificate 

  run: | 
    echo "${{ secrets.SM_CLIENT_CERT_FILE_B64 }}" | base64 --decode > /d/Certificate_pkcs12.p12 
  shell: bash

For Linux users: 

- name: Setup Certificate
        run: |
          echo "${{ secrets.SM_CLIENT_CERT_FILE_B64 }}" | base64 --decode > /tmp/Certificate_pkcs12.p12
          ls -l /tmp/Certificate_pkcs12.p12
        shell: bash

Configure environment variables

Use this code snippet to configure the necessary environment variables that are used in the subsequent steps of this workflow to perform code signing.

For Windows users: 

- name: Set variables 
  id: variables 
  run: | 
    echo "version=${GITHUB_REF#refs/tags/v}" >> $GITHUB_OUTPUT 
    echo "SM_HOST=${{ secrets.SM_HOST }}" >> "$GITHUB_ENV" 
    echo "SM_API_KEY=${{ secrets.SM_API_KEY }}" >> "$GITHUB_ENV" 
    echo "SM_CLIENT_CERT_FILE=D:\\Certificate_pkcs12.p12" >> "$GITHUB_ENV" 
    echo "SM_CLIENT_CERT_PASSWORD=${{ secrets.SM_CLIENT_CERT_PASSWORD }}" >> "$GITHUB_ENV" 
  shell: bash

For Linux users: 

- name: Set variables 
  id: variables 
  run: | 
    echo "version=${GITHUB_REF#refs/tags/v}" >> $GITHUB_OUTPUT 
    echo "SM_HOST=${{ secrets.SM_HOST }}" >> "$GITHUB_ENV" 
    echo "SM_API_KEY=${{ secrets.SM_API_KEY }}" >> "$GITHUB_ENV" 
    echo "SM_CLIENT_CERT_FILE=/tmp/Certificate_pkcs12.p12"" >> "$GITHUB_ENV" 
    echo "SM_CLIENT_CERT_PASSWORD=${{ secrets.SM_CLIENT_CERT_PASSWORD }}" >> "$GITHUB_ENV" 
  shell: bash

Set up client tools

Note

Before you begin, make sure the desired third-party signing tools are already installed.

Initiate the client tools setup

The following code snippet installs and configures Software Trust client tools, including SMCTL, PKCS#11 library, and Software Trust KSP library.

Various signing tools, such as Mage, Nuget, Signtool, and Jarsigners, are also usable via SMCTL. It's not necessary to separately install or set up these tools.

- name: Install DigiCert Client tools from Github Custom Actions marketplace 2
  id: Plugin
  uses: digicert/ssm-code-signing@v1.1.0
  env:
    FORCE_DOWNLOAD_TOOLS: 'true'

Review the installation location for the PKCS11 library.

For Windows users: 

C:\Users\RUNNER~1\AppData\Local\Temp\smtools-windows-x64\smpkcs11.dll

For Linux users:

/tmp/DigiCert One Signing Manager Tools/smtools-linux-x64/smpkcs11.so

For macOS users:

~/DigiCert One Signing Manager Tools/smpkcs11.dylib

Review the location for the PKCS11 configuration file.

For Windows users: 

C:\Users\RUNNER~1\AppData\Local\Temp\smtools-windows-x64\pkcs11properties.cfg

For Linux users: 

/tmp/DigiCert One Signing Manager Tools/smtools-linux-x64/pkcs11properties.cfg

For macOS users:

${{ steps.<yourtaskname>.outputs.PKCS11_CONFIG}}

Note

If you encounter an error running the jsign command, then you may need to manually install jsign on your macOS runner:

- name: Install Jsign
  run: |
    brew install jsign
    echo "Jsign installed successfully"
  shell: bash

Sign using GitHub action

To sign using a certificate fingerprint:

- name: Signing using certificate fingerprint      
        run: |
           smctl sign --fingerprint ${{ secrets.SM_CODE_SIGNING_CERT_SHA1_HASH }} --input path/to/unsignedfile.extension --config-file path/to/pkcs11properties.cfg
        shell: cmd

To sign using a keypair alias:

- name: Signing using keypair alias
        run: |
           smctl sign --keypair-alias YourKeypairAlias --input path/to/unsignedfile.extension --config-file path/to/pkcs11properties.cfg
        shell: cmd

Code signing using GitHub actions custom plugin template

For Windows users: 

name: Code Signing Template
 
on: 
  workflow_dispatch:
 
jobs:
  release:
    runs-on: ${{ matrix.os }}
    
    strategy:
      matrix:
        os: [windows-latest]

    steps:
      - name: Check out Git repository
        uses: actions/checkout@v4 
     
      - name: Install DigiCert Client tools from Github Custom Actions marketplace
        id: Digicert Code Signing Snippet
        uses: digicert/ssm-code-signing@v1.0.0
   
      - name: Set up certificate 
        run: | 
          echo "${{ secrets.SM_CLIENT_CERT_FILE_B64 }}" | base64 --decode > /d/Certificate_pkcs12.p12 
        shell: bash  
        
      - name: Set variables 
        id: variables 
        run: | 
          echo "version=${GITHUB_REF#refs/tags/v}" >> $GITHUB_OUTPUT 
          echo "SM_HOST=${{ secrets.SM_HOST }}" >> "$GITHUB_ENV" 
          echo "SM_API_KEY=${{ secrets.SM_API_KEY }}" >> "$GITHUB_ENV" 
          echo "SM_CLIENT_CERT_FILE=D:\\Certificate_pkcs12.p12" >> "$GITHUB_ENV" 
          echo "SM_CLIENT_CERT_PASSWORD=${{ secrets.SM_CLIENT_CERT_PASSWORD }}" >> "$GITHUB_ENV" 
        shell: bash

      - name: Signing using certificate fingerprint      
        run: |
           smctl sign --fingerprint ${{ secrets.SM_CODE_SIGNING_CERT_SHA1_HASH }} --input path/to/unsignedfile.extension --config-file path/to/pkcs11properties.cfg
        shell: cmd

      
      - name: Signing using keypair alias
        run: |
           smctl sign --keypair-alias YourKeypairAlias --input path/to/unsignedfile.extension --config-file path/to/pkcs11properties.cfg
        shell: cmd

       

For Linux users:

name: 'Linux Signing with Software Trust Manager'
on:
  workflow_dispatch:

jobs:
  release:
    runs-on: ${{ matrix.os }}
    
    strategy:
      matrix:
        os: [ubuntu-latest]

    steps:
      - name: Check out Git repository
        uses: actions/checkout@v4 
     
      - name: Install DigiCert Client tools from Github Custom Actions marketplace
        id: Digicert Code Signing Snippet
        uses: digicert/ssm-code-signing@v1.0.0
   
      - name: Set up certificate 
        run: | 
          echo "${{ secrets.SM_CLIENT_CERT_FILE_B64 }}" | base64 --decode > /tmp/Certificate_pkcs12.p12 
        shell: bash  
        
      - name: Set variables 
        id: variables 
        run: | 
          echo "version=${GITHUB_REF#refs/tags/v}" >> $GITHUB_OUTPUT 
          echo "SM_HOST=${{ secrets.SM_HOST }}" >> "$GITHUB_ENV" 
          echo "SM_API_KEY=${{ secrets.SM_API_KEY }}" >> "$GITHUB_ENV" 
          echo "SM_CLIENT_CERT_FILE=/tmp/Certificate_pkcs12.p12" >> "$GITHUB_ENV" 
          echo "SM_CLIENT_CERT_PASSWORD=${{ secrets.SM_CLIENT_CERT_PASSWORD }}" >> "$GITHUB_ENV" 
        shell: bash

      - name: Signing using certificate fingerprint      
        run: |
           smctl sign --fingerprint ${{ secrets.SM_CODE_SIGNING_CERT_SHA1_HASH }} --input path/to/unsignedfile.extension --config-file path/to/pkcs11properties.cfg
        shell: bash

      
      - name: Signing using keypair alias
        run: |
           smctl sign --keypair-alias YourKeypairAlias --input path/to/unsignedfile.extension --config-file path/to/pkcs11properties.cfg
        shell: bash
In this section: