Install client tools for standard keypair signing on Azure DevOps
작은 정보
As a DigiCert® KeyLocker customer, you can use DigiCert® Software Trust Manager plugins.
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.
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.
In DigiCert ONE, select the profile (
) icon, and then select Admin Profile.Under API keys, select Create API key.
For Name, enter a descriptive name for the key.
For End date (optional), enter the date when the key should expire.
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.
In DigiCert ONE, select the profile (
) icon, and then select Admin Profile.Under Client authentication certificates, select Create client authentication certificate.
For Nickname, enter a descriptive name for the key.
For End date, enter the date when the certificate should expire.
Select the desired Encryption and Signature hash algorithm.
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@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 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.
참고
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
Setup tasks
Client tools setup task
The client tools set up task installs and configures all 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 is a prompt to input an API key, which you can skip since the API key is no longer mandatory for this extension.
- task: SSMClientToolsSetup@1
참고
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
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
참고
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.
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>참고
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.
Sign with SignTool
SignTool isn't set in the system path by default for the Azure-provided agent.
To configure 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 isn't set in the system path by default for the Azure-provided agent.
To configure KeyLocker signing tools 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 ensures errors are logged directly to the console instead of the file in the .signingmanager folder log files.