Jenkins plugin for keypair signing
Code Signing with DigiCert® Software Trust Manager Jenkins plugin is a streamlined keypair-based signing workflow that improves software security and seamlessly integrates with DevOps processes to sign binaries on Windows and Linux.
This plugin accelerates the installation and configuration of clients and signature tools to help developers become signing-ready for Jenkins pipeline.
Code Signing with DigiCert® Software Trust Manager plugin can be used to set up client tools task.
You can download Code Signing with DigiCert® Software Trust Manager from Jenkins Marketplace or by navigating to Jenkins homepage or dashboard > Manage Jenkins > Manage Plugins.
Nota
Currently, we do not support master-slave deployment for this Jenkins plugin.
Prerequisites
DigiCert ONE account
Download Code signing with Software Trust Manager
Jenkins build system
Any agent with OS that supports Java on Jenkins
JDK installed on the agent
DigiCert® Software Trust Manager access setup (given below)
User authentication
Software Trust Manager enforces multifactor authentication for security. To access keypairs, certificates, and sign code, you need to set up two types of credentials: an API token and an authentication certificate.
Create an API token
The API token is an authentication method used to verify you as a user and your permissions assigned in DigiCert ONE. The API token provides the first factor authentication.
Follow these steps to generate an API token:
Sign in to DigiCert ONE.
Select the profile icon (top-right).
Select Admin Profile.
Scroll down to API Tokens.
Select Create API token.
Nota
The API token is only shown once, securely store the API key to use it later.
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.
Follow these steps to create a client authentication certificate:
Sign in to DigiCert ONE.
Select the profile icon (top-right).
Select Admin Profile.
Scroll down to Authentication certificates.
Select Create authentication certificate.
Nota
The client authentication certificate password shown after creating an client authentication certificate cannot be accessed again, download the certificate and securely store the password to use it later.
Best practices for secure Jenkins use
Use secret text and files to ensure security and accountability among your Jenkins users when they use DigiCert® Software Trust Manager to sign code. The code examples later assume that you are using secret text and files.
Jenkins secrets
Secrets are variables in Jenkins encrypted so users can input information without knowing what the value of that information is. For example, you do not want all of your Jenkins collaborators knowing what your unique API key is, but they may need to use it to access 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.
Configure Jenkins secrets
The client tools need these environment variables to connect with DigiCert® Software Trust Manager.
Nota
Only Jenkins user's with the Credentials > Create permission can add new global credentials.
To add new global credentials:
Log in to Jenkins.
Navigate to: Jenkins homepage or dashboard > Manage Jenkins > Manage Credentials > Store > Jenkins > System > Global credentials (unrestricted).
Select Add credentials.
Select the Scope you want to use:
Scope
Description
Global
Apply the scope of the credential/s to the Pipeline project/item "object" and all its descendant objects.
System
Apply the scope of the credential/s to a single object only.
Add the following types of credentials.
ID
Credential type
Description
SM_API_KEY
Secret text
Copy and paste your Software Trust Manager API token in the Secret field.
SM_CLIENT_CERT_FILE
Secret file
Select choose file and upload your Software Trust Manager client authentication certificate.
SM_CLIENT_CERT_PASSWORD
Secret text
Copy and paste your Software Trust Manager client certificate password in the Secret field.
SM_HOST
Secret text
Copy and paste your Software Trust Manager host environment in the Secret field.
Integration with Jenkins
Environment variables setup for Jenkins plugin in pipeline script
The client tools need these environment variables to connect with DigiCert® Software Trust Manager to provide its service.
To integrate as environment variables that are part of the pipeline:
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') }
Nota
Alternatively, 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 Manager setup for standard keypairs:
stages { stage('Set Up Software Trust Manager') { steps { SoftwareTrustManagerSetup() } } }
Create keypair and certificate
The following command may require the following inputs:
Keypair alias
Keypair ID
Certificate alias
Certificate profile ID.
The certificate profile ID used must belong to the correct profile category.
To create a keypair and default certificate, use:
stage('keypair setup') { steps { bat 'smctl keypair generate rsa <keypair alias> --cert-alias=<certificate alias> --cert-profile-id=<certificate profile ID> --generate-cert=true --key-type=<TEST or PRODUCTION>' }
To create a certificate from an existing keypair, use:
stage('keypair setup') { steps { bat 'smctl keypair generate-cert <keypair ID> --cert-alias=<certificate alias> --cert-profile-id=<certificate profile ID> --set-as-default-cert=true --key-type=<TEST or PRODUCTION>' }
Sign
To sign with the default signing tool, use:
stage('sign') { steps{ bat 'smctl sign --keypair-alias <keypair alias> --config-file <Software Trust Manager PKCS11 config file> --input <unsigned file> -v' } }
To sign using signtool.exe, use:
stage('sign') { steps { bat 'signtool.exe sign /csp "DigiCert Signing Manager KSP" /kc "<keypair alias>" /f <certificate> /tr http://timestamp.digicert.com <unsigned file>' }
The input parameters are the alias of the keypair used for signing, the name/alias of the certificate that needs to be used for signing, and the path to the file that needs to be signed.
The input parameters are the path to the file that needs to be signed, the name/alias of the certificate that needs to be used for signing, and the alias of the keypair used for signing.
To sign using nuget.exe, use:
stage('sign') { steps { bat 'nuget sign <unsigned file> -Timestamper http://timestamp.digicert.com -outputdirectory <output path for signed file> -CertificateFingerprint <certificate fingerprint> -Verbosity detailed -Overwrite' }
The input parameters are the the path to the file that needs to be signed, the path of the output signed file, and the fingerprint of the certificate that needs to be used for signing.
To sign using a jarsigner, use:
stage('sign') { steps { bat 'jarsigner -keystore NONE -storetype Windows-My -signedjar <output path for signed file> -sigalg SHA256withRSA -digestalg SHA256 <unsigned file> <keypair alias>' }
The input parameters are the path where the signed jar needs to be output, the path to the jar that needs to be signed, and the name/alias of the certificate that needs to be used for signing.
To sign using jsign, use:
stage('sign') { steps{ bat 'jsign --keystore pkcs11properties.cfg --storepass NONE --storetype PKCS11 --alias <keypair alias> <unsigned file> jsign –keystore <path to Software Trust Manager PKCS11 config file> –storepass NONE –storetype PKCS11 -alias <keypair alias>' } }
Verify signature
To verify using signtool, use:
stage('verify') { steps { bat 'signtool.exe sign verify /v /pa <signed file>' }
To verify using nuget, use:
stage('verify') { steps { bat 'nuget verify -all <signed file>' }
To verify using jarsigner, use:
stage('verify') { steps { bat 'jarsigner -verify <signed file>' }
The only input for this stage is the path to the signed file that needs to be verified.