Install client tools for standard keypair signing on Azure DevOps
Tip
As a DigiCert® KeyLocker customer, you can use DigiCert® Software Trust Manager plugins.
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
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.
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:
Sign in to DigiCert ONE.
Select the profile icon (top-right).
Select Admin Profile.
Scroll down to API Tokens.
Select Create API token.
Note
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:
Sign in to DigiCert ONE.
Select the profile icon (top-right).
Select Admin Profile.
Scroll down to Authentication certificates.
Select Create authentication certificate.
Note
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® 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.
Note
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® 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
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 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
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 PKCS11 configuration file. |
SM_TLS_SKIP_VERIFY | Enter true to disable or false to enable TLS verification on client side. |
Sign
Note
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>Note
The KSP is registered by default, but the DigiCert® KeyLocker 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® 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>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.