GitHubの統合 –KSP

前提条件

DigiCert® Software Trust Managerのセットアップ
お使いのOSに対応する DigiCert® Software Trust Manager クライアント
DigiCert® Software Trust ManagerKSP (クライアントツール)

Client tools

DigiCert® KeyLocker clients can be downloaded in a package.

Download Client tools

Sign in to DigiCert ONE.
Navigate to DigiCert® KeyLocker > Resources > Client tool repository.
Select your operating system.
Click the download icon next to DigiCert® KeyLocker clients.

Register the KSP

To register the KSP, open a command prompt and run:

smctl windows ksp register

Verify the KSP

To verify that your KSP is configured properly, and that your client can properly authenticate to the DigiCert® KeyLocker service, run:

certutil.exe -csp "DigiCert Software Trust Manager KSP" -key -user

Synchronize certificates

For the client tools to access the private keys in the service through the Key Storage Provider (KSP), your certificates must be synchronized to the local certificate store. Only if the certificate is synchronized, the private key remains stored securely in DigiCert® KeyLocker.

To synchronize your certificates to the local certificate store, open a command prompt and run:

smctl windows certsync

To view the certificates, open Certificate Manager for the user account used to run the certificate sync utility:

certmgr.msc

If you do not see your certificates in the Certificate Manager, verify that you have opened the correct certificate store. There is a different certificate store for each Windows user account.

注記

All certificates are synched to the user store only. The certificates are not synchronized to the machine store (yet).

Set PATH environment variables

Operating systems use the environment variable called PATH to determine where executable files are stored on your system. Use the PATH environment variable to store the file path to your signing tools to ensure that the CLI can reference these signing tools.

例 1. Windows

You can set the PATH environment variable using command line or via the environment variables.

To set the path to your signing tools via command line:

set PATH=%path%;<path to DigiCert Keylocker Tools>

Command sample:

set PATH=%path%;C:\Program Files\DigiCert\DigiCert Keylocker Tools

To set the path to your signing tools for your system or account:

Search for environment variables in the Windows start menu.
Select Edit environment variables for your account or Edit system environment variables.
Double click on the Path variable.
Click New.
Select Browse.
Select the path to the signing tool.
Click OK to save the path.
Click on OK to close the dialog.

例 2. Linux

To set the path to your signing tools via command line:

Launch the Terminal application.
Open the file in an editor:
```
nano ~/.profile
```

Add any exports definitions you need:

export PATH=<Path to DigiCert Keylocker Tools>

Click CTRL+X to exit.
Click Y to save.
Click Enter to keep the same file name.
Execute the new .profile by restarting Terminal or using:
```
 source ~/.profile
```

例 3. macOS

To set the path to your signing tools via command line:

Launch the Terminal application.
Create a profile file:
```
touch ~/.zprofile
```
Open the file in an editor:
```
open ~/.zprofile
```

Add any exports definitions you need, such as:

export PATH=<Path to DigiCert Keylocker Tools>

To save the new .zprofile, click File > Save (CMD + S).
Close the terminal window and reopen to use new saved variables.

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.

Software Trust Managerのセットアップ

クライアントツールを使用し、DigiCert® Software Trust Managerに接続して操作を行うには、DigiCert ONeでのDigiCert® Software Trust Managerへのアクセス権がなければなりません。DigiCert® Software Trust Managerにアクセスできない場合は、DigiCert ONEの管理者に連絡してアクセスを要求してください。

環境変数内の証明書ファイルを設定する

証明書をDigiCert ONE > アカウントマネージャ > アクセス > <account_name> > 証明証明書の作成をダウンロードします。
ファイルを base64 にエンコードします。エンコードのコマンドを実行します。
```
base64 file_name
```
GitHub SecretSに、新しいリポジトリシークレットを追加します。
```
Name = SM_CLIENT_CERT_FILE_B64
Value = encoded value from base64 file_name
```

署名用の証明書ファイルをセットアップします。

- name: Setup Certificate
  run: |
    echo "${{ secrets.SM_CLIENT_CERT_FILE_B64 }}" | base64 --decode > /d/Certificate_pkcs12.p12
  shell: bash

GitHub 操作用の環境変数の設定

クライアントツールがDigiCert® Software Trust Managerと接続するためには、これらの環境変数が必要です。

環境変数を GitHub シークレットとして統合するには、次を行います。

GitHub リポジトリにアクセスする
の設定を選択する
シークレット > 操作を選択する
新しいリポジトリシークレットを選択する

これらの環境変数に設定する値は、以下のようになります。

Variable	Description
SM_API_KEY	Provide your API token.
SM_CLIENT_CERT_FILE_B64	The base64 encoded text of certificate downloaded from client authentication certificate setup.
SM_CLIENT_CERT_PASSWORD	Provide your client certificate password.
SM_HOST	Provide your host environment.
SM_CODE_SIGNING_CERT_SHA1_HASH	The certificate fingerprint.

環境変数を設定するコマンド:

- name: Set variables
  id: variables
  run: |
    echo "version=${GITHUB_REF#refs/tags/v}" >> $GITHUB_OUTPUT
    echo "KEYPAIR_NAME=gt-standard-keypair" >> $GITHUB_OUTPUT
    echo "CERTIFICATE_NAME=gt-certificate" >> $GITHUB_OUTPUT
    echo "SM_HOST=${{ secrets.SM_HOST }}" >> "$GITHUB_ENV"
    echo "SM_API_KEY=${{ secrets.SM_API_KEY }}" >> "$GITHUB_ENV"
    echo "SM_CLIENT_CERT_FILE=D:\\Certificate_pkcs12.p12" >> "$GITHUB_ENV"
    echo "SM_CLIENT_CERT_PASSWORD=${{ secrets.SM_CLIENT_CERT_PASSWORD }}" >> "$GITHUB_ENV"
    echo "C:\Program Files (x86)\Windows Kits\10\App Certification Kit" >> $GITHUB_PATH
    echo "C:\Program Files (x86)\Microsoft SDKs\Windows\v10.0A\bin\NETFX 4.8 Tools" >> $GITHUB_PATH
    echo "C:\Program Files\DigiCert\DigiCert Keylocker Tools" >> $GITHUB_PATH
  shell: bash

ヒント

The following tool paths are provided above:

DigiCert® KeyLocker client tools
C:\Program Files\DigiCert\DigiCert Keylocker Tools
Signtool.exe
C:\Program Files (x86)\Windows Kits\10\App Certification Kit
Mage.exe
C:\Program Files (x86)\Microsoft SDKs\Windows\v10.0A\bin\NETFX 4.8 Tools

クライアントツールの設定

Connect the KSP to GitHub actions and verify that it works.

クライアントコントロールのセットアップ

GitHub の操作からクライアントコントロールを呼び出すには、以下を実行します。

以下の curl コマンドで smtools-Windows-x64.msI をダウンロードしてインストールします。

- name: Setup SSM KSP on windows latest
  run: |
    curl -X GET  https://one.digicert.com/signingmanager/api-ui/v1/releases/Keylockertools-windows-x64.msi/download -H "x-api-key:%SM_API_KEY%" -o Keylockertools-windows-x64.msi
    msiexec /i Keylockertools-windows-x64.msi /quiet /qn
  shell: cmd

注記

"curl "コマンドは smtools-Windows-x64.msi のインストーラーを、"msiexec"は smtools-Windows-x64.msi のサイレントインストールに使用されるものである。

KSPを確認する

KSPが登録されていることを確認するには、以下を実行します。

- name: Register KSP
  run: |
    smctl windows ksp list
  shell: cmd

GitHub の操作との連携

サインツールとMageを見つける

サインツールを見つけるコマンド：

- name: Find Signtool
  run: |
    dir "C:\Program Files (x86)\Microsoft SDKs\Windows\ " /s /b | findstr /i signtool.exe
  shell: cmd

Mageを見つけるコマンド：

- name: Find Signtool
  run: |
      dir "C:\Program Files (x86)\Microsoft SDKs\Windows\ " /s /b | findstr /i mage.exe
  shell: cmd

Signing

signtool.exeを使用して署名する

Sign with Mage

To sign with Mage:

- name: Signing using mage
  run: |
    mage.exe -sign <file_name> -CertHash <hash_or_cert_fingerprint> -a sha256RSA
 shell: cmd

Sign with NuGet

To sign with NuGet:

- name: Signing using nuget
  run: |
    nuget sign <package folder> -Timestamper http://timestamp.digicert.com -outputdirectory <output folder> -Certificate Fingerprint <SHA1 Thumbprint> -HashAlgorithm SHA256 -Verbosity detailed -Overwrite
  shell: cmd

Sign with SignTool

To sign with SignTool:

- name: Signing using signtool
  run: |
    signtool.exe sign /sha1 <certificate thumbprint> /tr http://timestamp.digicert.com /td SHA256 /fd SHA256 <file to be signed>
 shell: cmd

Verify signature

You can verify a signature using Mage, NuGet, or SignTool.

Verify signature with Mage

To verify a signature with Mage:

- name: Mage verify
  run: |
    mage -Verify <Path to signed .application file>
  shell: cmd- name: Mage verify
run: |
mage -Verify <path to signed .application file>
shell: cmd

The only input required here is the path to the signed .application file.

Verify signature with NuGet

To verify a signature with NuGet:

- name: Nuget verify
  run: |
    nuget verify -All <output folder>\*
  shell: cmd- name: Nuget verify
run: |
nuget verify -All <output folder>\*
shell: cmd

The only input required here is the path to the signed folder.

Verify signature with SignTool

To verify a signature with SignTool:

- name: Signtool verify
  run: |
    signtool verify /v /pa <Path to the signed exe/DLL>
  shell: cmd- name: Signtool verify
run: |
signtool verify /v /pa <path to the signed .exe or .dll>
shell: cmd

The only input for this step is the path to the signed .exe or .dll file that needs to be verified.

GitHub操作の例

GitHub操作を使ったKSP署名

name: 'build and release electron installer'
on:
  push:
    tags:
      - 'v*'
      
jobs:
  release:
    runs-on: ${{ matrix.os }}
    
    strategy:
      matrix:
        os: [windows-latest]
        
    steps:
      - name: Check out Git repository
        uses: actions/checkout@v2

      - name: Install Node.js, NPM and Yarn
        uses: actions/setup-node@v2
        with: 
          node-version: 14
        
      - name: Build/release Electron app
        uses: samuelmeuli/action-electron-builder@v1
        with: 
          github_token: ${{ secrets.github_token }}
          release: ${{ startsWith(github.ref, 'refs/tags/v') }}
          build_script_name: dist

      - name: NuGet Install
        uses: NuGet/setup-nuget@v1.0.5
        with:
          nuget-version: latest

      - name: Setup Certificate
        run: |
          echo "${{ secrets.SM_CLIENT_CERT_FILE_B64 }}" | base64 --decode > /d/Certificate_pkcs12.p12
          cat /d/Certificate_pkcs12.p12
        shell: bash

          
      - name: Set variables
        id: variables
        run: |
          echo "version=${GITHUB_REF#refs/tags/v}" >> $GITHUB_OUTPUT
          echo "KEYPAIR_NAME=gt-standard-keypair" >> $GITHUB_OUTPUT
          echo "CERTIFICATE_NAME=gt-certificate" >> $GITHUB_OUTPUT
          echo "SM_HOST=${{ secrets.SM_HOST }}" >> "$GITHUB_ENV"
          echo "SM_API_KEY=${{ secrets.SM_API_KEY }}" >> "$GITHUB_ENV"
          echo "SM_CLIENT_CERT_FILE=D:\\Certificate_pkcs12.p12" >> "$GITHUB_ENV"
          echo "SM_CLIENT_CERT_PASSWORD=${{ secrets.SM_CLIENT_CERT_PASSWORD }}" >> "$GITHUB_ENV"
          echo "C:\Program Files (x86)\Windows Kits\10\App Certification Kit" >> $GITHUB_PATH
          echo "C:\Program Files (x86)\Microsoft SDKs\Windows\v10.0A\bin\NETFX 4.8 Tools" >> $GITHUB_PATH
          echo "C:\Program Files\DigiCert\ DigiCert Keylocker Tools" >> $GITHUB_PATH
        shell: bash

      - name: Setup SSM KSP on windows latest
        run: |
          curl -X GET  https://one.digicert.com/signingmanager/api-ui/v1/releases/Keylockertools-windows-x64.msi/download -H "x-api-key:%SM_API_KEY%" -o Keylockertools-windows-x64.msi
          msiexec /i Keylockertools-windows-x64.msi /quiet /qn
          smctl windows ksp list
          smctl.exe keypair ls
          C:\Windows\System32\certutil.exe -csp "DigiCert Signing Manager KSP" -key -user
          smctl windows certsync
        shell: cmd

      - name: Signing using Signtool
        run: |
          signtool.exe sign /sha1 ${{ secrets.SM_CODE_SIGNING_CERT_SHA1_HASH }} /tr http://timestamp.digicert.com /td SHA256 /fd SHA256 "D:\a\github-action-electron\github-action-electron\dist\my-electron-app Setup ${{ steps.variables.outputs.version }}.exe"
          signtool.exe verify /v /pa "D:\a\github-action-electron\github-action-electron\dist\my-electron-app Setup ${{ steps.variables.outputs.version }}.exe"

      - name: Signing using Nuget
        run: |
          copy D:\a\github-action-electron\github-action-electron\UNSIGNED.nupkg D:\a\github-action-electron\github-action-electron\dist\UNSIGNED.nupkg
          nuget sign "D:\a\github-action-electron\github-action-electron\dist\UNSIGNED.nupkg" -Timestamper http://timestamp.digicert.com -outputdirectory "D:\a\github-action-electron\github-action-electron\dist\Signed" -CertificateFingerprint ${{ secrets.SM_CODE_SIGNING_CERT_SHA1_HASH }} -HashAlgorithm SHA256 -Verbosity detailed -Overwrite
          nuget verify -All "D:\a\github-action-electron\github-action-electron\dist\Signed\*"

      - name: Signing using Mage
        run: |
          copy D:\a\github-action-electron\github-action-electron\UNSIGNED2.manifest D:\a\github-action-electron\github-action-electron\dist\UNSIGNED2.manifest
          mage.exe -sign "D:\a\github-action-electron\github-action-electron\dist\UNSIGNED2.manifest" -CertHash ${{ secrets.SM_CODE_SIGNING_CERT_SHA1_HASH }} -a sha256RSA
          mage -Verify "D:\a\github-action-electron\github-action-electron\dist\UNSIGNED2.manifest"

      - name: Upload artifacts
        uses: actions/upload-artifact@v2
        with:
          name: ${{ matrix.os }}
          path: |
            dist

コードの実行・ビルド方法

プロジェクトの Package.json ファイルにあるバージョンを更新します（例：1.2.3）
その変更をコミットします (git commit -am v1.2.3)
コミットにタグを付けます (git tag v1.2.3)。タグの名前の形式が v*.*.* であることを確認してください。
注記
ワークフローでは、このタグを使ってリリースを作成するタイミングを判断します。
変更内容を GitHub にプッシュします (git push && git push --tags)。

このセクションの内容:

GitHubの統合 –KSP

前提条件

Client tools

Download Client tools

Register the KSP

Verify the KSP

Synchronize certificates

注記

Set PATH environment variables

User authentication

Create an API key

Create an authentication certificate

Software Trust Managerのセットアップ

環境変数内の証明書ファイルを設定する

GitHub 操作用の環境変数の設定

ヒント

クライアントツールの設定

クライアントコントロールのセットアップ

注記

KSPを確認する

GitHub の操作との連携

サインツールとMageを見つける

Signing

Sign with Mage

Sign with NuGet

Sign with SignTool

Verify signature

Verify signature with Mage

Verify signature with NuGet

Verify signature with SignTool

GitHub操作の例

GitHub操作を使ったKSP署名

コードの実行・ビルド方法

注記

Related articles