Skip to main content

Jenkins plugin for keypair signing

Tip

As a DigiCert​​®​​ KeyLocker customer, you can use DigiCert​​®​​ Software Trust Manager plugins.

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.

Prerequisites

User authentication

DigiCert​​®​​ KeyLocker 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:

  1. Sign in to DigiCert ONE.

  2. Select the profile icon (top-right).

  3. Select Admin Profile.

  4. Scroll down to API Tokens.

  5. Select  Create API token.

    Note

    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:

  1. Sign in to DigiCert ONE.

  2. Select the profile icon (top-right).

  3. Select Admin Profile.

  4. Scroll down to Authentication certificates.

  5. Select Create authentication certificate.

    Note

    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​​®​​ KeyLocker 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​​®​​ KeyLocker. 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​​®​​ KeyLocker.

Note

Only Jenkins user's with the Credentials > Create permission can add new global credentials.

To add new global credentials:

  1. Log in to Jenkins.

  2. Navigate to: Jenkins homepage or dashboard > Manage Jenkins > Manage Credentials > Store > Jenkins > System > Global credentials (unrestricted).

  3. Select Add credentials.

  4. 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.

  5. Add the following types of credentials.

    ID

    Credential type

    Description

    SM_API_KEY

    Secret text

    Copy and paste your DigiCert​​®​​ KeyLocker API token in the Secret field.

    SM_CLIENT_CERT_FILE

    Secret file

    Select choose file and upload your DigiCert​​®​​ KeyLocker client authentication certificate.

    SM_CLIENT_CERT_PASSWORD

    Secret text

    Copy and paste your DigiCert​​®​​ KeyLocker client certificate password in the Secret field.

    SM_HOST

    Secret text

    Copy and paste your DigiCert​​®​​ KeyLocker 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​​®​​ KeyLocker 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')
    }

Note

Alternatively, integrate environment variables at an operating system environment level.

To add a stage to the pipeline script and call the plugin to perform DigiCert​​®​​ KeyLocker setup for standard keypairs:

    stages {

        stage('Set Up Software Trust Manager') {

            steps {

                    SoftwareTrustManagerSetup()

            }

        }
}

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.