Azure DevOpsクライアントツール拡張

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.

注記

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

Azure DevOps Pipeline用のDigiCert® Software Trust Managerクライアントツール拡張を使用して、クライアントツールと署名ツールのセットアップという2つの作業を行うことができます。これを行うには、Visual Studio Marketplace にアクセスし、DigiCert® Software Trust Managerクライアントツール拡張をダウンロードします。

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

Software Trust 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.

Azureのタスクを設定する

Azure Pipelineの [設定] で、以下を使用して、タスクを構成します。

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

Azure　を安全に利用するためのベストプラクティス

Azure DevOps PipelineのユーザーがDigiCert® Software Trust Managerを使用してコードに署名する際には、セキュリティと説明責任を確保するために、シークレットとセキュアファイルを使用してください。この後にあるコード例では、シークレットとセキュアファイルを使用することを前提としています。

シークレット

シークレットは　Azure DevOps Pipelineの変数を暗号化したもので、ユーザーはその情報の値を知ることなく情報を入力することができます。たとえば、APIキーの場合、Azureのすべての協力者があなたに固有の　APIキーが何であるかを知って欲しくはありませんが、彼らはDigiCert® Software Trust Managerを通じて署名ツールを採用する際にそれを使用する必要が出てくるかもしれません。"(api_key)"が名前で値がAPIキーそのものである変数をセットアップすることができます。次に、 この値を秘密にするを選択して、値を暗号化します。また、 Azure Key Vault Secrets を使用することもできます。

注記

変数を保存すると、完全に暗号化されます。値の作成者（ご本人）であっても、値を見ることはできません。将来的に必要となるようであれば、必ず別の場所に保存しておいてください。

安全なファイル

クライアント証明書など、機密性は高いけれど完全には秘匿できないファイルについては、Azureの セキュアファイル機能を利用してください。 パイプライン > ライブラリ > セキュアファイルと進み、クライアント証明書をセキュアファイルとして追加します。その後、セキュアファイルを変数として使用することができます。以下を使用することもできます。

- 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)

タスクのセットアップ

STMクライアントツールセットアップタスク

The client tools setup task installs and configures all all Software Trust 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.

注記

クライアントが署名動作できるようにするためには、使用したい署名ツールが既にインストールされていなければなりません。

STM 署名ツールセットアップタスク

STM 署名ツールセットアップタスクは、主にAzureでホストされたシステムで使用するための補助的なタスクです。このタスクは、署名ツールをインストールしません。代わりに、タスクは jarsigner、signtool、apksigner などの一般的な署名ツールをシステムで検索します。次に、これらのツールを迅速に設定し、DigiCert® Software Trust Managerで使用できるようにします。

- task: SSMSigningToolsSetup@1

注記

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

DigiCert® Software Trust Managerのセットアップ

システム変数として設定することで、環境変数が永続的に残るようにしてください。

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.

Signing

注記

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.

Smctl で署名する

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)

Smctl で署名する

署名ツールのセットアップタスクを追加して設定した後には、証明書ファイルを使用して Azure から簡単にコードに署名することができます。yaml で、以下を使用してSmctl証明書のダウンロードを実行します。

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)

注記

KSP がデフォルトで登録されていますが、STMクライアントツールセットアップタスクは、証明書の同期機能を実行しません。また、keypair_alias はパイプラインの yaml にハードコードするのではなく、シークレットの変数として保管しておく必要があります。
Add the keypair alias as a secret variable rather than hardcoding it into the pipeline yaml.

SignTool で署名する

- 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)

注記

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.

署名またはSTMツールのセットアップでエラーをデバッグする（オプション）

エラーのデバッグが必要な場合は、環境変数 SM_LOG_OUTPUT: console を追加してください

これにより、.signingmanager フォルダのログファイルではなく、コンソールに直接,エラーがログされるようになります。

このセクションの内容: