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

ヒント

As a DigiCert® KeyLocker customer, you can use DigiCert® Software Trust Manager plugins.

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

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.

Azureのタスクを設定する

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

-task: SSMClientToolsSetup@1
-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

タスクのセットアップ

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

STMクライアントツールセットアップタスクは、CTL クライアント、PKCS#11ライブラリ、およびKSPクライアントなど、DigiCert® Software Trust Managerクライアントツールをすべてインストールして設定します。また、このタスクは自動的にPKCS11設定ファイルをタスク変数に書き込み、<STMClientToolsSetup.PKCS11_CONFIG> でアクセスできるようにします。

タスクの設定ステップで、APIキーを入力するプロンプトが表示されますが、この拡張機能ではAPIキーはもう必須ではありませんので、スキップできます。

- task: SSMClientToolsSetup@1

注記

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

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

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

- task: SSMSigningToolsSetup@1

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 で署名する

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

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>

次に、smctl using で署名します。

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

注記

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

SignTool で署名する

デフォルトでは、Azure 提供のエージェントは、システムパスに SignTool が設定されていません。STM 署名ツールのセットアップタスクで、SignTool に対応するように設定しなければなりません。これを行うには、以下を使用します。

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

jarsignerを使用して署名する

jarsignerで署名するには、以下を使用します。

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

APKsignerで署名する

デフォルトでは、Azure提供のエージェントは、システムパスにAPKsignerが設定されていません。STM署名ツールのセットアップタスクで、jarsignerに対応するように以下のように設定しなければなりません。

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>

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

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

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

このセクションの内容: