Trusted Build Systems - Jenkins Plugin

Prerequisites

The Jenkins plugin has been installed on the respective Jenkins instance (Jenkins 2.359 or higher are supported).
The plugin has been registered as a custom Trusted Build System within SignPath and linked to the respective project (see the configuration section).

Performed checks

The plugin ensures that

A build was actually performed by a specific Jenkins CI instance, not by some other entity in possession of the API token
Origin metadata is provided by Jenkins CI, not the build script, and can therefore not be forged
The artifact is stored as an immutable Jenkins artifact before it is submitted for signing

Installation

The Jenkins Plugin is available for download from the GitHub releases page.
The following additional plugins must be installed:

Configuration

The Trusted Build System Token needs to be stored in a System Credential (Under Manage Jenkins / Manage Credentials)
The Api Token of a SignPath user with submitter permissions needs to be available to the build pipelines of the respective projects.

Usage

In your Jenkinsfile, make sure the artifacts to be signed are pushed to the master node by adding a stage e.g.

    stage('Archive') {
      steps {
        archiveArtifacts artifacts: "build-output/**", fingerprint: true
      }
    }

Provided steps

Include the submitSigningRequest and optionally, the getSignedArtifact steps in your build pipeline.

General parameters

Parameter	Default Value	Description
`apiUrl`	`https://app.signpath.io/Api`	SignPath API endpoint to use. Needs to be set if for self-hosted SignPath installations.
`apiTokenCredentialId`	`SignPath.ApiToken`	The ID of the credential containing the API Token. Recommended in scope “Global”.
`trustedBuildSytemTokenCredentialId`	`SignPath.TrustedBuildSystemToken`	The ID of the credential containing the Trusted Build System Token. Needs to be in scope “System”.
`serviceUnavailableTimeoutInSeconds`	`600`	Total time in seconds that the step will wait for a single service call to succeed (across several retries).
`uploadAndDownloadRequestTimeoutInSeconds`	`300`	HTTP timeout used for upload and download HTTP requests. Defaults to 300.
`waitForCompletionTimeoutInSeconds`	`600`	Maximum time in seconds that the step will wait for the signing request to complete.

Parameters for the `submitSigningRequest` step

Parameter	Default Value	Description
`organizationId`	(mandatory)	The ID of the SignPath organization
`projectSlug`	(mandatory)	The slug of the SignPath project
`signingPolicySlug`	(mandatory)	The slug of the SignPath signing policy
`artifactConfigurationSlug`		The SignPath artifact configuration slug. If not specified, the default is used.
`inputArtifactPath`	(mandatory)	The relative path of the artifact to be signed
`outputArtifactPath`		The relative path where the signed artifact is stored after signing
`waitForCompletion`	(mandatory)	Set to `true` for synchronous and `false` for asynchronous signing requests
`parameters`		A `Map<String, String>` with key/value pairs that map to user-defined parameters in the Artifact Configuration.

Parameters for the `getSignedArtifact` step

Parameter	Default Value	Description
`organizationId`	(mandatory)	The ID of the SignPath organization
`signingRequestId`	(mandatory)	The ID of the signing request (is returned by the `submitSigningRequest` step)
`outputArtifactPath`	(mandatory)	The relative path where the signed artifact is stored after signing

Examples

Example: Submit a synchronous signing request

    stage('Sign with SignPath') {
      steps {
        submitSigningRequest(
          organizationId: "${ORGANIZATION_ID}",
          projectSlug: "${PROJECT_SLUG}",
          signingPolicySlug: "${SIGNING_POLICY_SLUG}",
          artifactConfigurationSlug: "${ARTIFACT_CONFIGURATION_SLUG}",
          inputArtifactPath: "build-output/my-artifact.exe",
          outputArtifactPath: "build-output/my-artifact.signed.exe",
          waitForCompletion: true
        )
      }
    }

Example: Submit an asynchronous signing request

    stage('Sign with SignPath') {
      steps {
        script {
          signingRequestId = submitSigningRequest(
            organizationId: "${ORGANIZATION_ID}",
            projectSlug: "${PROJECT_SLUG}",
            signingPolicySlug: "${SIGNING_POLICY_SLUG}",
            artifactConfigurationSlug: "${ARTIFACT_CONFIGURATION_SLUG}",
            inputArtifactPath: "build-output/my-artifact.exe",
            outputArtifactPath: "build-output/my-artifact.signed.exe",
            waitForCompletion: false
          )
        }
      }
    }
    stage('Download Signed Artifact') {
      input {
        id "WaitForSigningRequestCompleted"
        message "Has the signing request completed?"
      }
      steps{
        getSignedArtifact( 
          organizationId: "${ORGANIZATION_ID}",
          signingRequestId: "${signingRequestId}",
          outputArtifactPath: "build-output/my-artifact.exe"
        )
      }
    }

Trusted Build Systems ❯ Jenkins Plugin