Scripts for Docker integration with Jenkins using PKCS11 library

The following process guides you through the process to download and register the DigiCert​​®​​ Software Trust Manager PKCS11 library so that Docker can pick it up.

You need to generate the Docker root key. The root key needs to have a certificate with “CN=root” in it. The following example generates it on DigiCert​​®​​ Software Trust Manager with keytool provided with Java.

A delegation key and certificate is required to sign images in Docker. You can do this in Software Trust Manager or using SMCTL:

smctl keypair generate ecdsa <Delegation Key Alias> --cert-alias=<Delegation Cert Alias> --cert-profile-id=<Certificate Profile ID> --generate-cert=true --key-type=PRODUCTION

When an image push is done with content trust enabled, Docker signs the tag using the delegation key and pushes the trust data to the remote notary server. When an image pull/run is done with content trust enabled, the image is verified.

You can only use a Linux node as an agent for the Docker Signing pipeline.

Make sure the node is setup on Jenkins to connect to the Linux machine and the user where the Docker Content Trust was setup.

In the example below, a node is defined connecting to the Linux machine where the Docker Content Trust is setup and labelled ‘Linux’.

pipeline {
    agent{ label 'linux' }
}

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

To add new global credentials:

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 {
    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')
    }

pipeline {
   environment{
       SM_CLIENT_CERT_PASSWORD='**********'
       SM_CLIENT_CERT_FILE='<Path to client Auth Cert File>'
       SM_HOST='https://clientauth.one.digicert.com'
       SM_API_KEY='<Api Token>'
       //If you want Docker Content Trust enabled for all operations in the pipeline
       DOCKER_CONTENT_TRUST=1
    }
}

Sometimes no trust data is associated with images built on other base images. When DOCKER_CONTENT_TRUST is enabled for the entire pipeline as an environment variable, the build stage or step will fail due to missing trust data in one of the base images.

To disable content trust for the specific build operation, use:

stage('Docker Build') {
    steps {
       sh 'docker build -t <Registry URL>/<Repository Name>:<Tag> --disable-content-trust=true .'
    }
}

To push signed tags when DOCKER_CONTENT_TRUST is set for the entire pipeline as an environment variable:

stage('Docker Push Signed Tags') {
   steps {
        sh 'DOCKER_CONTENT_TRUST=1 docker push <Registry URL>/<Repository Name>:<Tag>'
    }
}

The signing is automatically done with the delegation key from DigiCert​​®​​ Software Trust Manager using the PKCS11 library because we have set the DOCKER_CONTENT_TRUST environment variable for the entire pipeline.

To push signed tags with DOCKER_CONTENT_TRUST enabled only for the specific operation:

stage('Docker Push Signed Tags') {
   steps {
        sh 'DOCKER_CONTENT_TRUST=1 docker push <Registry URL>/<Repository Name>:<Tag>'
    }
}

When DOCKER_CONTENT_TRUST is enabled for the entire pipeline as an environment variable, a docker pull/run of any signed image will automatically verify the image:

stage('Docker Verify') {
    steps {
        sh 'docker pull <Registry URL>/<Repository Name>:<Tag>'
    }
}

When DOCKER_CONTENT_TRUST is not enabled for the entire pipeline as an environment variable, it can be enabled only for a specific operation:

stage('Docker Verify') {
    steps {
        sh 'DOCKER_CONTENT_TRUST=1 docker pull <Registry URL>/<Repository Name>:<Tag>'
    }
}