Install client tools for standard keypair signing on Azure DevOps

DigiCert​​®​​ KeyLocker 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.

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

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

Use secrets and secure files to ensure security and accountability among your Azure DevOps Pipeline users when they use DigiCert​​®​​ KeyLocker 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​​®​​ 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.

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

Client tools setup task

The client tools set up task installs and configures all of the DigiCert​​®​​ KeyLocker 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

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 and signtool. The task then configures these tools so you can use them with the DigiCert​​®​​ KeyLocker.

- task: SSMSigningToolsSetup@1

Set the following environment variables:

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>

Sign with SignTool

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

To configure DigiCert​​®​​ KeyLocker 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​​®​​ KeyLocker 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>

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.

Troubleshooting