Skip to main content

Install client tools for standard keypair signing on Azure DevOps

You can use the Software Trust Manager 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 download the Software Trust Manager client tools extension.

User authentication

Software Trust Manager enforces multifactor authentication for security. To access keypairs, certificates, and sign code, you need to set up two types of credentials: an API token and an authentication certificate.

Create an API token

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

Follow these steps to generate an API token:

  1. Sign in to DigiCert ONE.

  2. Select the profile icon (top-right).

  3. Select Admin Profile.

  4. Scroll down to API Tokens.

  5. Select  Create API token.

    Anmerkung

    The API token is only shown once, securely store the API key to use it later.

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.

Follow these steps to create a client authentication certificate:

  1. Sign in to DigiCert ONE.

  2. Select the profile icon (top-right).

  3. Select Admin Profile.

  4. Scroll down to Authentication certificates.

  5. Select Create authentication certificate.

    Anmerkung

    The client authentication certificate password shown after creating an client authentication certificate cannot be accessed again, download the certificate and securely store the password to use it later.

Configure the tasks in Azure

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

-task: SSMClientToolsSetup@1
-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 DigiCert​​®​​ Software Trust Manager to sign code. The code examples later assume that you are 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 do not 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 DigiCert​​®​​ Software Trust Manager. 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.

Anmerkung

Once you save the variable, it is fully encrypted. Not even the creator of the value (you) can see the value. Make sure you save it elsewhere if it is something you will 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

Setup tasks

Client tools setup task

The client tools set up task installs and configures all of the DigiCert​​®​​ Software Trust Manager client tools, including: Signing Manager Controller (SMCTL), PKCS11 library, and the KSP library. The task also automatically writes the PKCS11 config file into the task variable, which you can access using <SSMClientToolsSetup.PKCS11_CONFIG>.

During the task configuration step, there will be a prompt to input an API key, but you can skip this as the API key is no longer mandatory for this extension.

- task: SSMClientToolsSetup@1

Anmerkung

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 does not install signing tools. The task searches your system for common signing tools already installed, such as jarsigner, apksigner, and signtool. The task then configures these tools so you can use them with the DigiCert​​®​​ Software Trust Manager.

- task: SSMSigningToolsSetup@1

DigiCert​​®​​ Software Trust Manager 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 PKCS11 configuration file.

SM_TLS_SKIP_VERIFY

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

Sign

Anmerkung

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

  • You have not utilized the Setup tasks as shown above, which will automatically detect and add all the necessary signing tools to the system path.

  • The full path is not set in the system path.

Sign with SMCTL

After adding and configuring the signing tools setup task, you can sign code easily through Azure using the certificate file.

To download the certificate in the yaml:

- task: CmdLine@2
  inputs:
    script: 'smctl certificate download --keypair-alias=FLTest-1 --name=KeyCert.pem --out=<Agent.TempDirectory>'
  env:
    SM_HOST:<Prod host or demo host>
    SM_API_KEY:<API key>
    SM_CLIENT_CERT_PASSWORD:<client certificate password>
    SM_CLIENT_CERT_FILE:<client certificate secure file path>
    SM_TLS_SKIP_VERIFY:<true or false>

To sign:

- task: CmdLine@2
  inputs:
    script: 'smctl sign --keypair-alias=$(keypair alias) --certificate=$(Agent.TempDirectory)\KeyCert.pem  --config-file $(SSMClientToolsSetup.PKCS11_CONFIG) --input $(Build.SourcesDirectory)\build'
  env:
    SM_HOST:<Prod host or demo host>
    SM_API_KEY:<API key>
    SM_CLIENT_CERT_PASSWORD:<client certificate password>
    SM_CLIENT_CERT_FILE:<client certificate secure file path>
    SM_TLS_SKIP_VERIFY:<true or false>

Anmerkung

  • The KSP is registered by default, but the DigiCert​​®​​ Software Trust Manager client tools setup task does not perform the certificate sync functionality.

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

Sign with SignTool

SignTool is not set in the system path by default for the Azure-provided agent.

To configure DigiCert​​®​​ Software Trust Manager signing tools setup task and accommodate SignTool:

task: CmdLine@2 inputs: script: 'signtool sign /tr http://timestamp.digicert.com /td SHA256 /fd SHA256 /csp "DigiCert Signing Manager KSP" /kc "$(keypair_alias)" /f $(Agent.TempDirectory)\KeyCert.pem $(Build.SourcesDirectory)\build\smctl1.exe' env: SM_HOST: SM_API_KEY: SM_CLIENT_CERT_PASSWORD: SM_CLIENT_CERT_FILE: SM_TLS_SKIP_VERIFY

Sign with jarsigner

To sign with jarsigner, use

task: CmdLine@2 inputs: script: 'jarsigner -keystore NONE -storepass NONE -storetype PKCS11 -providerClass sun.security.pkcs11.SunPKCS11 -providerArg $(SSMClientToolsSetup.PKCS11_CONFIG) -digestalg SHA-256 -signedjar $(System.DefaultWorkingDirectory)/build/sample.war $(System.DefaultWorkingDirectory)/build/sample.war $(keypair_alias) -tsa http://timestamp.digicert.com -tsadigestalg SHA-256' env: SM_HOST: SM_API_KEY: SM_CLIENT_CERT_PASSWORD: SM_CLIENT_CERT_FILE: SM_TLS_SKIP_VERIFY

Sign with Apksigner

The Apksigner is not set in the system path by default for the Azure-provided agent.

To configure DigiCert​​®​​ Software Trust Manager signing tools setup task and accommodate Apksigner:

- task: CmdLine@2
  inputs:
    script: 'apksigner sign --provider-class sun.security.pkcs11.SunPKCS11 --provider-arg $(SSMClientToolsSetup.PKCS11_CONFIG) --ks NONE --ks-type PKCS11 --ks-key-alias $(keypair_alias) --in $(Build.SourcesDirectory)\build\UNSIGNED_APK.apk --out $(Build.SourcesDirectory)\build\UNSIGNED_APK.apk  --ks-pass pass:abcd --min-sdk-version=18'
  env:
    SM_HOST:<Prod host or demo host>
    SM_API_KEY:<API key>
    SM_CLIENT_CERT_PASSWORD:<client certificate password>
    SM_CLIENT_CERT_FILE:<client certificate secure file path>
    SM_TLS_SKIP_VERIFY: <true or false>

Debug errors in signing or tools setup

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

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