Skip to main content

Install client tools for standard keypair signing on Azure DevOps

Tip

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

DigiCert​​®​​ Software Trust Manager for Azure DevOps Pipelines enables organizations to seamlessly integrate secure signing workflows into Azure DevOps build and release pipelines.

This production-ready Azure DevOps extension supports Windows, Linux, and macOS platforms, offering both simple and traditional signing workflows to align with diverse development and release strategies.

Note

The enhanced version 2 of the Software Trust client tools extension automatically sets up the required client and signing tools in your pipeline. It supports simple signing with no third-party tools required, as well as traditional signing using tools such as SignTool and Jarsigner through KSP and PKCS#11, with cross-platform support for Windows, Linux, and macOS.

Supported signing approaches

Simple signing

  • Uses the DigiCert SMCTL command-line tool (installed automatically by this template) to sign files directly from the pipeline.

Traditional signing:

Integrates with third-party signing tools using the following libraries:

  • JCE

  • PKCS#11

  • KSP

  • CSP

Use the Software Trust client tools extension for Azure DevOps Pipeline to perform two tasks: Set up client tools and signing tools. To do this, go to the Visual Studio Marketplace and then download the Software Trust client tools extension.

What's new?

  • Simple signing mode: Sign without third-party tools (SignTool, Jarsigner, etc.) or intermediate libraries (KSP, PKCS#11). Recommended for new implementations.

  • Cross-platform support: Windows, Linux, and macOS agents.

  • Tool caching: Installed tools are cached by SHA-256 checksum — speeds up repeated pipeline runs.

  • Checksum verification: All tools verified against cryptographic checksums before use.

  • Automatic retries: Built-in retry logic with exponential backoff for transient network failures.

  • Bulk signing: Sign multiple files in a single batch operation (bulkSignMode: true).

  • Backward compatible: Pipelines using SSMClientToolsSetup@1 need no changes

User authentication

KeyLocker enforces multi-factor authentication for security purposes. To access keypairs, certificates, and sign code, you need to set up two types of credentials: An API key and an authentication certificate.

Create an API key

The API key is an authentication method used to verify you as a user and your permissions assigned in DigiCert ONE. The API key provides the first factor authentication.

  1. In DigiCert ONE, select the profile (profile_icon.png) icon, and then select Admin Profile.

  2. Under API keys, select Create API key.

  3. For Name, enter a descriptive name for the key.

  4. For End date (optional), enter the date when the key should expire.

  5. Select Create. The API key appears this one time and can't be accessed again. Securely store the API key for future use.

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.

  1. In DigiCert ONE, select the profile (profile_icon.png) icon, and then select Admin Profile.

  2. Under Client authentication certificates, select Create client authentication certificate.

  3. For Nickname, enter a descriptive name for the key.

  4. For End date, enter the date when the certificate should expire.

  5. Select the desired Encryption and Signature hash algorithm.

  6. Select Generate certificate. The password appears this one time and can't be accessed again. Download the certificate and securely store the password for future use.

Configure the tasks in Azure

Configure your tasks in the Settings of your Azure Pipeline using:

-task: SSMClientToolsSetup@2
-task: SSMSigningToolsSetup@1

Best practices for secure Azure use

Use secrets and secure files to ensure security and accountability among your Azure DevOps Pipeline users when they use KeyLocker to sign code. The code examples later assume that you're using secrets and secure files.

Secrets

Secrets are variables in Azure DevOps Pipeline encrypted so users can input information without knowing what the value of that information is. For example, with API keys, you don't want all of your Azure collaborators knowing what your unique API key is, but they may need to use it to employ signing tools through the KeyLocker. You can set up a variable where "(api_key)" is the name and the value is the API key itself. Then, select Keep this value secret to encrypt the value. You can also use Azure Key Vault Secrets.

Note

Once you save the variable, it's fully encrypted. Not even the creator of the value (you) can see the value. Make sure you save it elsewhere if it's something you'll need in the future.

Secure files

For files that are sensitive but not meant to be fully secret, like client certificates, use the Secure files feature in Azure. Go to Pipelines > Library > Secure files and add the client certificate as a secure file. Then, you can use the secure file as a variable. You can also use:

- task: DownloadSecureFile@1
  name: SM_CLIENT_CERT_FILE
  inputs:
  secureFile: client_certificate

Migration from extension version 1 to version 2

Use this section if you currently use version 1 of the Software Trust client tools extension for Azure DevOps Pipelines. This procedure walks you through updating your existing pipeline to use version 2 of the extension.

To migrate, update your pipeline by replacing the version 1 tasks with their version 2:

- task: SSMClientToolsSetup@2

For simple signing (optional upgrade):

- task: SSMClientToolsSetup@2
  inputs:
    simpleSigningMode: true
    input: '$(Build.ArtifactStagingDirectory)'
    keypairAlias: '$(keypair_alias)'
  env:
    SM_API_KEY: $(SM_API_KEY)
    SM_CLIENT_CERT_PASSWORD: $(CLIENT_PASS)
    SM_CLIENT_CERT_FILE: $(SM_CLIENT_CERT_FILE.secureFilePath)
    SM_HOST: $(SM_HOST)

Setup tasks

Client tools setup task

The client tools setup task installs and configures all all KeyLocker client tools, including the Signing Manager Controller (SMCTL), PKCS#11 library, and KSP library. It supports Windows, Linux, and macOS, automatically writes the PKCS#11 configuration file to the task variable which you can access using <SSMClientToolsSetup.PKCS11_CONFIG> and caches installed tools using their SHA-256 checksum to accelerate subsequent pipeline runs.

- task: SSMClientToolsSetup@2

Input

Default

Description

simpleSigningMode

false

When true, installs only smctl and immediately signs the provided input. No third-party signing tools or intermediate libraries required. Recommended for new implementations.

input

-

Path to a file or directory of files to sign. Signing runs only when both input and keypairAlias are provided.

keypairAlias

-

Software Trust Manager keypair alias used to sign the input.

digestAlg

-

Digest (hash) algorithm. Leave empty to use the service default.

timestamp

true

Apply RFC 3161 timestamping to signed files.

failFast

true

Stop on the first failure when signing a directory.

unsigned

false

Sign only files that are not already signed.

bulkSignMode

false

Sign multiple files in a single batch operation. Contact your DigiCert account manager to enable this feature.

zeroExitCodeOnFailure

false

Return exit code 0 even when signing fails. Not recommended.

digicertCdn

https://pki-downloads.digicert.com/stm/latest

DigiCert CDN base URL for tool downloads.

useToolCache

true

Cache downloaded tools by checksum to speed up repeated runs.

useBinarySha256Checksum

true

Verify downloaded tools against SHA-256 checksums before use.

cacheVersion

0.0.0-0

Cache key version. Change this value to force a fresh tool download.

Note

Signing tools you want to use must already installed for the clients to work for signing. To install signing tools, refer to Integrate third-party signing tools.

Signing tools setup task

The signing tools setup task is a supplementary task mostly for use in Azure-hosted systems. This task doesn't install signing tools. The task searches your system for common signing tools already installed, such as jarsigner and signtool. The task then configures these tools so you can use them with the KeyLocker.

- task: SSMSigningToolsSetup@1

Note

For backward compatibility, the SM_API_KEY environment variable can be specified using the APIKey input of the SSMClientToolsSetup@2 task.

DigiCert​​®​​ KeyLocker environment variables

Set the following environment variables:

Variable

Description

SM_API_KEY

Provide your API token.

SM_CLIENT_CERT_FILE

Provide your client authentication certificate.

SM_CLIENT_CERT_PASSWORD

Provide your client certificate password.

SM_HOST

Provide your host environment.

PKCS11_CONFIG

Provide the path to the PKCS#11 configuration file.

SM_TLS_SKIP_VERIFY

Enter true to disable or false to enable TLS verification on the client side.

Sign

Note

To ensure proper execution of the signing commands below, you must reference the full path if:

  • You haven't used the Setup tasks described earlier, which automatically detects and adds all necessary signing tools to the system path.

  • The full path isn't set in the system path.

Simple signing (Recommended)

The simple signing approach streamlines the signing process by allowing direct code signing without relying on third-party signing utilities or intermediary libraries.

Example:

- task: SSMClientToolsSetup@2
  inputs:
    simpleSigningMode: true
    input: '$(Build.ArtifactStagingDirectory)'
    keypairAlias: '$(keypair_alias)'
  env:
    SM_API_KEY: $(SM_API_KEY)
    SM_CLIENT_CERT_PASSWORD: $(CLIENT_PASS)
    SM_CLIENT_CERT_FILE: $(SM_CLIENT_CERT_FILE.secureFilePath)
    SM_HOST: $(SM_HOST)

Sign with SMCTL (traditional signing)

After adding and configuring the signing tools setup task, you can perfom signing.

To perform Authenticode signing:

- task: CmdLine@2
  inputs:
    script: 'smctl sign --keypair-alias <keypair-alias> --input <path_to_unsignedfile>'
  env:
    SM_HOST: https://clientauth.one.digicert.com/
    SM_API_KEY: $(SM_API_KEY)
    SM_CLIENT_CERT_PASSWORD: $(SM_CLIENT_CERT_PASSWORD)
    SM_CLIENT_CERT_FILE: $(SM_CLIENT_CERT_PASSWORD.secureFilePath)

Note

  • The KSP is registered by default, but the KeyLocker client tools setup task doesn't perform the certificate sync functionality.

  • Add the keypair alias as a secret variable rather than hardcoding it into the pipeline yaml.

To perform PKCS#11 signing:

- task: CmdLine@2
  inputs:
    script: 'smctl sign --keypair-alias <keypair-alias> --input <path_to_unsignedfile> --config-file $(SSMClientToolsSetup.PKCS11_CONFIG)'
  env:
    SM_HOST: https://clientauth.one.digicert.com/
    SM_API_KEY: $(SM_API_KEY)
    SM_CLIENT_CERT_PASSWORD: $(SM_CLIENT_CERT_PASSWORD)
    SM_CLIENT_CERT_FILE: $(SM_CLIENT_CERT_PASSWORD.secureFilePath)

Note

This section describes the traditional signing approach using third-party signing tools such as jarsigner,Apksigner, and jsigner etc. If your workflow does not require these tools, we recommend using simpleSigningMode: true with the SSMClientToolsSetup@2 task for a simplified signing experience.

Debug errors in signing or tools setup

If you need to debug errors, add the environment variable SM_LOG_OUTPUT: console

This ensures errors are logged directly to the console instead of the file in the .signingmanager folder log files.

In this section: