Install client tools for GPG keypair signing on Jenkins
GPG signing with DigiCert® Software Trust Manager is a Jenkins plugin that streamlines keypair-based signing workflows to improve software security and integrates with DevOps processes to sign binaries.
This plugin accelerates the installation and configuration of clients and signature tools to help developers become signing-ready for Jenkins pipelines on Windows and Linux. It can also be used to set up client tools tasks.
You can download the plugin from Jenkins Marketplace or by navigating to Jenkins homepage or dashboard > Manage Jenkins > Manage Plugins.
Prerequisites
DigiCert ONE account
DigiCert ONE client authentication certificate
Download GPG signing with Software Trust
Jenkins build system
Any agent with OS that supports Java on Jenkins
JDK installed on the agent
Software Trust access setup
Before you begin
When running this plugin on a remote agent, the path environment variable for the installed tools isn't automatically set. You must manually configure the path as an environment variable in your pipeline script.
For example, on a Linux environment, add the following script to your pipeline script:
pipeline {
agent any
environment {
PATH = "/root/smtools-linux-x64:${env.PATH}"
}
// other pipeline steps...
}For Linux, review the paths that the plugin sets up:
/<Jenkins user directory>/smtools-linux-x64
For Windows, review the paths that the plugin sets up:
C:\Program Files\DigiCert\DigiCert One Signing Manager Tools C:\Program Files (x86)\GnuPG\bin
User authentication
Software Trust enforces multi-factor authentication for security purposes. 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.
In DigiCert ONE, select the profile (
) icon, and then select Admin Profile.Under API keys, select Create API key.
For Name, enter a descriptive name for the key.
For End date (optional), enter the date when the key should expire.
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.
In DigiCert ONE, select the profile (
) icon, and then select Admin Profile.Under Client authentication certificates, select Create client authentication certificate.
For Nickname, enter a descriptive name for the key.
For End date, enter the date when the certificate should expire.
Select the desired Encryption and Signature hash algorithm.
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.
Best practices for secure Jenkins use
To sign code using Software Trust, use secret text and files to ensure security and accountability among your Jenkins users.
Secrets are encrypted variables in Jenkins where users can input information without knowing the specific value. For example, you may not want your Jenkins collaborators to know your unique API key, but they may need it to access signing tools. As a result, you can set up a variable where "(api_key)" is the name and the value is the API key itself.
The client tools requires environment variables to connect to Software Trust, which this document explains.
Configure Jenkins secrets
注意
To perform this action, you must be a Jenkins user with the Credentials > Create permission.
The client tools requires environment variables to connect to Software Trust, which this document explains.
Sign in to Jenkins.
Go to Jenkins homepage or dashboard > Manage Jenkins > Manage Credentials > Store > Jenkins > System > Global credentials (unrestricted).
Select Add credentials.
Select the desired Scope:
Scope
Description
Global
Apply the scope of the credentials to the Pipeline project/item "object" and all its descendant objects.
System
Apply the scope of the credentials to a single object.
Add the following types of credentials.
ID
Credential type
Description
SM_API_KEY
Secret text
Copy and paste your Software Trust API token in Secret.
SM_CLIENT_CERT_FILE
Secret file
Select Choose file, and then upload your Software Trust client authentication certificate.
SM_CLIENT_CERT_PASSWORD
Secret text
Copy and paste your Software Trust client certificate password in Secret.
SM_HOST
Secret text
Copy and paste your Software Trust host environment in Secret.
Integrate with Jenkins
Set up environment variables in your Jenkins pipeline script so that the client tools can connect to Software Trust and provide its services.
Review the following script:
pipeline {
agent any
environment {
SM_API_KEY = credentials('SM_API_KEY')
SM_HOST = credentials('SM_HOST')
SM_CLIENT_CERT_PASSWORD = credentials('SM_CLIENT_CERT_PASSWORD')
SM_CLIENT_CERT_FILE = credentials('SM_CLIENT_CERT_FILE')
}
注意
Alternatively, you can integrate environment variables at an operating system environment level.
To add a stage to the pipeline script and call the plugin to perform Software Trust setup for standard keypairs, review the following script:
stages {
stage('GPG set up using Software Trust Manager') {
steps {
SoftwareTrustManagerGPGSetup()
}
}
}Generate and manage GPG keys
To generate a GPG master key, run the following script:
stage ('generate gpg master key using smctl '){
steps {
bat '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>" '
}
}To download GPG keyring, run the following script:
stage ('Download GPG keyring'){
steps {
bat 'smctl gpg keyring download <GPG master key keypair ID> <GPG master key keypair ID>'
}
}To list GPG public and private keys, run the following script:
stage ('List gpg public and private keys'){
steps {
bat 'gpg –list-keys <file path to keyring> '
bat 'gpg --list-secret-keys <file path to keyring> '
}
}Sign
Before you attempt to sign, be sure to install the desired signing tools.
To sign using SMCTL, run the following script:
stage ('GPG signing '){
steps {
bat 'gpg --sign <unsigned file name>'
}
}