Build system integration

Abstract

This section describes how SignPath can be integrated into automated builds using continuous integration software.
You can use the PowerShell module provided by SignPath, or directly call the Web API to submit signing requests.

All necessary IDs can be found on the signing policy details page, including a sample call for the PowerShell module.

Authorization

Before accessing the API, you have to create a CI User in the User section of the SignPath application. Make sure to keep the access token in a secure location.

PowerShell

SignPath can be integrated in your automated build process by using our API. For convenience, we provide a PowerShell module that can be used from within your build/deploy chain. The module can be downloaded here: https://app.signpath.io/API/v1/Tools/SignPath.psm1.

A signing request can be created by calling one of the following following commands via PowerShell:

Import-Module .\SignPath.psm1
  
# submits a signing request and returns a SigningRequestId 
# without waiting for the signing request to be done
Submit-SigningRequest
    -CIUserToken <CI_USER_TOKEN>
    -OrganizationId <YOUR_ORGANIZATION_ID>
    -CertificateConfigurationId <CERTIFICATE_CONFIGURATION_ID>
    -InputArtifactPath <PATH_TO_INPUT_ARTIFACT>
  
# downloads a signed artifact
Get-SignedArtifact
    -CIUserToken <CI_USER_TOKEN>
    -OrganizationId <YOUR_ORGANIZATION_ID>
    -SigningRequestId <SIGNING_REQUEST_ID>
    -OutputArtifactPath <PATH_TO_OUTPUT_ARTIFACT>
  
# submits a signing request and blocks until it is done
Submit-SigningRequest
    -CIUserToken <CI_USER_TOKEN>
    -OrganizationId <YOUR_ORGANIZATION_ID>
    -CertificateConfigurationId <CERTIFICATE_CONFIGURATION_ID>
    -InputArtifactPath <PATH_TO_INPUT_ARTIFACT>
    -OutputArtifactPath <PATH_TO_OUTPUT_ARTIFACT>
    -WaitForCompletion

HTTP REST API

In case the PowerShell module is not sufficient, you can communicate directly with our API by calling our public HTTP REST endpoints.

Authorization

The automatically created CI User token can be used to interact with the API by setting the respective HTTP Header:

Authorization: Bearer <CI_USER_TOKEN>

Submitting a Signing Request

You can create a Signing Request by calling the API, providing the following arguments:

  • <SIGNING_POLICY_ID>

    – the signing policy for which you want to create the Signing Request.

  • <ORGANIZATION_ID>

    – the Id of your organization

The server expects the HTTP POST request to be of the type multipart/form-data (denoted by the -F switch in curl).

curl
    -H "Authorization: Bearer <CI_USER_TOKEN>" \
    -F "SigningPolicyId=<SIGNING_POLICY_ID> \
    -F Artifact=@<PATH_TO_ARTIFACT> \
    -F "Description=called by curl" \
    https://app.signpath.io/API/v1/<ORGANIZATION_ID>/SigningRequests

If the creation is successful, the API returns status code 201. Additionally, a HTTP Response Header Location is returned with the URL of the created entity.

Checking the Status of a Signing Request

The current status of a SigningRequest can be retrieved by calling the API and providing the following arguments:

  • <URL_OF_THE_SIGNING_REQUEST>

    – the URL is returned in the Location header of the HTTP response when a SigningRequest is created (e.g. to

    https://app.signpath.io/API/v1/a05be341-8a85-4c06-828a-710459e325ab/SigningRequests/a15e4d4f-7e03-4b15-9e2e-f3d8daeeaa75

    )

curl
    -H "Authorization: Bearer <CI_USER_TOKEN>" \
    <URL_OF_THE_SIGNING_REQUEST>

The HTTP GET request will then return the status of the Signing Request in JSON format:

{
    "status":"Completed",
    "description":"called by curl",
    "projectId":"edd545ef-e113-48ba-aba7-de2d59ea2f26",
    "projectName":"SignPath Test Project",
    "signingPolicyId":"9ebd30b0-ef6b-4e46-a248-103516bc36fc",
    "certificateConfigurationName":"Test",
    "uploadedArtifactLink":"https://app.signpath.io/API/v1/a05be341-8a85-4c06-828a-710459e325ab/SigningRequests/a15e4d4f-7e03-4b15-9e2e-f3d8daeeaa75/UploadedArtifact",
    "signedArtifactLink":"https://app.signpath.io/API/v1/a05be341-8a85-4c06-828a-710459e325ab/SigningRequests/a15e4d4f-7e03-4b15-9e2e-f3d8daeeaa75/SignedArtifact"
}

Downloading the signed artifact

Once the Signing Request has been successfully completed, the status response contains a signedArtifactLink field with a link to the signed artifact file. It can easily be retrieved by issuing the following command:

  • <PATH_TO_DOWNLOADED_ARTIFACT>

    – the path where the signed artifact should be stored

  • <SIGNED_ARTIFACT_LINK>

    – link retrieved from status request

curl
    -H "Authorization: Bearer <CI_USER_TOKEN>" \
    -o <PATH_TO_DOWNLOADED_ARTIFACT> \
    <SIGNED_ARTIFACT_LINK>
LOGIN