SignPath

Trusted Build Systems  ❯   Jenkins Plugin

Prerequisites

Performed checks

SignPath 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 originated from the Jenkins build

Installation

See the official plugin page on how the plugin can be installed.

Configuration

  • In the Code Signing with SignPath section of the System settings, set the Connector URL and Endpoint Slug of the installed Pipeline Connector and optionally define a default organization ID.
  • The Api Token of a SignPath user with submitter permissions needs to be available to the build pipelines of the respective projects.

Usage

Provided steps

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

General parameters

Parameter Default Value Description
apiTokenCredentialId SignPath.ApiToken ID of the credential containing the API Token. Recommended in scope “Global”.
trustedBuildSytemTokenCredentialId Configured in global plugin configuration 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 Configured in global plugin configuration ID of the SignPath organization
projectSlug (mandatory) Slug of the SignPath project
signingPolicySlug (mandatory) Slug of the SignPath signing policy
artifactConfigurationSlug   SignPath artifact configuration slug. If not specified, the default is used.
inputArtifactPath (mandatory) Relative path of the artifact to be signed
outputArtifactPath   Relative path where the signed artifact is stored after signing
waitForCompletion (mandatory) Set to true for synchronous and false for asynchronous signing requests
parameters   User-defined parameters as Map<String, String> key/value pairs
inputArtifactRetrievalUrl   Can be used to retrieve the unsigned artifact from a HTTPS URL instead of uploading it from the agent. Note: To ensure that the artifact is part of the build process, the inputArtifactPath must also be specified and reference the same file (same SHA256 hash). The HTTPS URL needs to be reachable from the SignPath installation.
inputArtifactRetrievalHttpHeaders   HTTP headers used for retrieving the artifact, as Map<String, String> key/value pairs.

Parameters for the getSignedArtifact step

Parameter Default Value Description
organizationId Configured in global plugin configuration ID of the SignPath organization
signingRequestId (mandatory) ID of the signing request (is returned by the submitSigningRequest step)
outputArtifactPath (mandatory) Relative path where the signed artifact is stored after signing

Examples

Example: Submit a synchronous signing request

stage('Sign with SignPath') {
  steps {
    submitSigningRequest(
      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 with parameters

stage('Sign with SignPath') {
  steps {
    script {
      signingRequestId = submitSigningRequest(
        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,
        parameters: [
          "version": "1.0",
          "my-param": "another param"
        ]
      )
    }
  }
}
stage('Download Signed Artifact') {
  input {
    id "WaitForSigningRequestCompleted"
    message "Has the signing request completed?"
  }
  steps{
    getSignedArtifact( 
      signingRequestId: "${signingRequestId}",
      outputArtifactPath: "build-output/my-artifact.exe"
    )
  }
}

Example: Submit a signing request, but download the unsigned artifact from a HTTPS URL

stage('Sign with SignPath') {
  steps {
    submitSigningRequest(
      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,
      inputArtifactRetrievalUrl: "https://my.download.share.com/my-artifact.exe",
      inputArtifactRetrievalHttpHeaders: [
        "Authorization": "Bearer mysupersecretauth"
      ]
    )
  }
}