Install client tools for GPG keypair signing on GitHub
GPG signing with DigiCert® Software Trust Manager GitHub action is a streamlined GPG-based signing workflow that improves software security and seamlessly integrates with DevOps processes to sign binaries on Windows and Linux.
This action accelerates the installation and configuration of clients tools to help developers become signing-ready for GitHub action workflows.
GPG signing with DigiCert® Software Trust Manager action can be used to set up client tool tasks.
Get the latest version of GPG signing with DigiCert® Software Trust Manager from GitHub Marketplace.
User authentication
DigiCert® Software Trust Manager requires multifactor authentication. You will need to set up two credential types, namely an API token and an authentication certificate before you can access keypairs, certificates, and to sign code.
Create an API token
The API token is an authentication method used to verify the user and their permissions as set in DigiCert ONE®. The client authentication provides the first factor authentication.
To generate an API token:
Sign in to DigiCert ONE.
Select the profile icon.
Select Admin Profile.
Scroll down to API Tokens.
Select Create API token.
Nota
The information shown after creating an API token cannot be accessed again, securely store all the information specified on the screen to use it later.
Create an authentication certificate
The client authentication certificate is an authentication method used to verify the user and their permissions as set in DigiCert ONE. The client authentication certificate provides the second factor authentication.
To create a client authentication certificate:
Sign in to DigiCert ONE.
Navigate to DigiCert® Software Trust Manager > Profile icon > Admin Profile.
Scroll down to Authentication certificates.
Select Create authentication certificate.
Nota
The information shown after creating an client authentication certificate cannot be accessed again, securely store all the information specified on the screen to use it later.
Best practices for secure GitHub use
Use secrets and secure files to ensure security and accountability among your GitHub users when they use DigiCert® Software Trust Manager to sign code. The code examples later assume that you are using secrets and secure files.
GitHub Secrets
Secrets are variables in GitHub encrypted so users can input information without knowing what the value of that information is. For example, with API keys, you do not want all of your GitHub collaborators knowing what your unique API key is, but they may need to use it to use signing tools through DigiCert® Software Trust Manager. You can set up a variable where "(api_key)" is the name and the value is the API key itself.
Set your certificate file in the environment variables
To add a certificate to GitHub secrets, you need to encode the certificate to a base64 string.
On Linux, run this command in Terminal:
base64 -i <file_name>
On Windows, run this command in PowerShell:
$fileContentBytes = get-content 'YOURFILEPATH.pfx' -Encoding Byte [System.Convert]::ToBase64String($fileContentBytes)
Configure user credentials in GitHub Secrets
The client tools need these environment variables to connect with DigiCert® Software Trust Manager.
To integrate environment variables as GitHub secrets:
Access GitHub repository.
Navigate to: Settings > Secrets > Actions.
Select New repository secret.
Enter the following environment variables:
Environment variables
Description
SM_CLIENT_CERT_PASSWORD
The password from client authentication certificate setup.
SM_CLIENT_CERT_FILE_B64
The base64 encoded text of certificate downloaded from client authentication certificate setup.
SM_HOST
The path to the DigiCert® Software Trust Manager portal with client authorization.
Nota
In most cases, this path stays as it is unless you are connecting to a self-hosted instance of the DigiCert® Software Trust Manager product.
SM_API_KEY
The API token generated during API token setup.
SM_CODE_SIGNING_CERT_SHA1_HASH
The certificate fingerprint.
Nota
The SM_HOST value you use for the commands below will depend on whether you are using demo or prod.
Country | Host type | SM_HOST value |
---|---|---|
United States of America (USA) | Demo | https://clientauth.demo.one.digicert.com |
Production | https://clientauth.one.digicert.com | |
Switzerland (CH) | Demo | https://clientauth.demo.one.ch.digicert.com |
Production | https://clientauth.one.ch.digicert.com | |
Japan (JP) | Demo | https://clientauth.demo.one.digicert.co.jp |
Production | https://clientauth.one.digicert.co.jp | |
Netherlands (NL) | Demo | https://clientauth.demo.one.nl.digicert.com |
Production | https://clientauth.one.nl.digicert.com |
Commands to set environment variables
Once you save the variable, it is fully encrypted. Not even the creator of the value (you) can see the value. Make sure you save it elsewhere if it is something you will need in the future.
To set the API token as a new repository secret:
Name | SM_ SM_API_KEY |
Value | Insert the API token you created. |
To set the client authentication certificate as a new repository secret:
Name | SM_CLIENT_CERT_FILE_B64 |
Value | Insert the base64 encoded string you generated above. |
To set the client authentication certificate password as a new repository secret:
Name | SM_CLIENT_CERT_PASSWORD |
Value | Insert the password you were shown when creating the client certificate password. |
Set up environment variables
To set up the certificate file for signing, run:
- name: Setup Certificate run: | echo "${{ secrets.SM_CLIENT_CERT_FILE_B64 }}" | base64 --decode > /d/Certificate_pkcs12.p12 shell: bash
To set environment variables:
- name: Set variables id: variables run: | echo "::set-output name=version::${GITHUB_REF#refs/tags/v}" 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
Usage example
Copy and paste the following snippet into your .yml file.
- name: GPG signing with Software Trust Manager on: push jobs: build: strategy: matrix: os: [ubuntu-latest, windows-latest] runs-on: ${{ matrix.os }} steps: - name: GPG signing with Secure Software Manager uses: digicert/ssm-gpg-signing@latest-version env: SM_API_KEY: ${{secrets.SM_API_KEY}} SM_CLIENT_CERT_PASSWORD: ${{secrets.SM_CLIENT_CERT_PASSWORD}} SM_CLIENT_CERT_FILE: ${{secrets.SM_CLIENT_CERT_FILE}}
Nota
Once you save the variable, it is fully encrypted. Not even the creator of the value (you) can see the value. Make sure you save it elsewhere if it is something you will need in the future.
Software Trust Manager client tools setup
The DigiCert® Software Trust Manager client tools set up task installs and configures all the DigiCert® Software Trust Manager client tools, including the CTL client and the SCD client.
To find the client tools installation path, run:
- run: echo “installation Path ${{ steps.SSMClientToolSetup.outputs.extractPath }}”
During the task configuration step, there will be a prompt to input an API key, but you can skip this if you want to use the environment variables to add the API key.
To set the API key to GitHub secrets:
- name: GPG signing with Secure Software Manager run: | echo "SM_API_KEY=${{ secrets.SM_API_KEY }}" >> "$GITHUB_ENV" env: SM_API_KEY: ${{secrets.SM_API_KEY}}
Nota
Install the signing tools you want to use before attempting to sign.
Generate GPG master key using SMCTL
- name: generate gpg master key using smctl run: | gpg keypair generate <master key alias> --key-alg “<algorithm>” --key-size <RSA key size>|--curve “<ECDSA curve name>” --can-sign “<YES or NO>” --gpg-key-type “MASTER” --uids “name=<name>,email=<email>", “name=<name>,email=<email>"
Download GPG keyring
- name: Download GPG keyring run: | smctl gpg keyring download <gpg master key keypair id> <gpg master key keypair id>
To get a list GPG public and private keys, run:
- name: List gpg public and private keys run: | gpg –list-keys <file path to keyring> gpg --list-secret-keys <file path to keyring>
To sign using the command line interface, run:
- name: GPG signing run: | gpg --sign <unsigned file name>
Sample GitHub actions
- name: 'build and release electron installer' on: push: tags: - 'v*' jobs: release: runs-on: ${{ matrix.os }} strategy: matrix: os: [windows-latest,ubuntu-latest] steps: - name: Check out Git repository uses: actions/checkout@v2 - name: Install Node.js, NPM and Yarn uses: actions/setup-node@v2 with: node-version: 14 - name: Build/release Electron app uses: samuelmeuli/action-electron-builder@v1 with: github_token: ${{ secrets.github_token }} release: ${{ startsWith(github.ref, 'refs/tags/v') }} build_script_name: dist - name: NuGet Install uses: NuGet/setup-nuget@v1.0.5 with: nuget-version: latest - name: Setup Certificate run: | echo "${{secrets.SM_CLIENT_CERT_FILE_B64 }}" | base64 --decode > /d/Certificate_pkcs12.p12 cat /d/Certificate_pkcs12.p12 shell: bash - name: Set variables id: variables run: | echo "::set-output name=version::${GITHUB_REF#refs/tags/v}" 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" echo "C:\Program Files (x86)\Windows Kits\10\App Certification Kit" >> $GITHUB_PATH echo "C:\Program Files (x86)\Microsoft SDKs\Windows\v10.0A\bin\NETFX 4.8 Tools" >> $GITHUB_PATH echo "C:\Program Files\DigiCert\DigiCert One Signing Manager Tools" >> $GITHUB_PATH shell: bash - name: generate gpg master key using smctl run: | gpg keypair generate <master key alias> --key-alg “<algorithm>” --key-size <RSA key size>|--curve “<ECDSA curve name>” --can-sign “<YES or NO>” --gpg-key-type “MASTER” --uids “name=<name>,email=<email>", “name=<name>,email=<email>" - name: Download GPG keyring run: | smctl gpg keyring download <gpg master key keypair id> <gpg master key keypair id> - name: List gpg public and private keys run: | gpg –list-keys <file path to keyring> gpg --list-secret-keys <file path to keyring> - name: GPG signing run: | gpg --sign <unsigned file name