Azure Key Vault を使用して GitHub Actions からコード署名を行う

TL;DR

• Windows の実行ファイルに署名する手軽なサービスとして、Azure Artifact Signing(旧 Trusted Signing )というものがある
• ベータ版から正式版になる際、なぜか日本はサービス対象地域から外されてしまった
• その代替として、Azure Key Vaultを使用する方法がある
• GitHub Actions 等から Key Vault を使用する場合、認可手段として Managed Identity を使うのがモダンで安全
  • その際 Managed Identity には当該 Key Vault の Key Vault Crypto User と Key Vault Certificate User のロールが必要
• GitHub Actions 等から Key Vault を使用して署名する場合、AzureSignTool を使用すると便利
  • Key Vault は大量呼出しに対してスロットリングを行うことがあるが、AzureSignTool はこのスロットリングに対応していない。そのため、リトライ機構を自作した上で、いちファイルずつ署名を行う必要がある

始めに

Windows には、発行者が実行ファイルなどに対して署名を行うことで、実行ファイルの真正性などを担保できる機構が存在します。
このコード署名を行うことにより、SmartScreen¹ の表示を抑止できるなどのメリットがあります。

元々コード署名を行うためには、使用する証明書を証明書プロバイダから購入し、それを HSM などを使用して適切に管理する必要がありました。
これは金銭面や運用面でコストが高く、企業であってもコード署名を気軽に行えるものではありませんでした。

2024年4月に Microsoft が Azure Trusted Signing というサービスのベータ版を開始し、これを使用することで安価かつ手軽にコード署名を行えるようになりました。
しかし、Trusted Signing が Artifact Signing という名前で正式サービスとなった際、日本国内の組織からは利用できなくなってしまいました²。

そのため筆者らは、Artifact Signing を代替する手段を急遽用意する必要に迫られました。この際に得た知見として、本記事では Artifact Signing の代替として Key Vault を使用し³、GitHub Actions 上からコード署名を行う方法を紹介します。

前提

適切なサブスクリプションとリソースグループが Azure 上に、GitHub Actions を実行するリポジトリが GitHub 上に存在することとします。

Key Vault の作成

Key Vault のトップ画面左上の "Create" を押し、入力欄を適切に埋めます。この際、 HMS へ格納するためには Pricing tier を Premium にしなければならないため、FIPS140-2 レベル2以上に準拠する必要がある場合などには注意してください。

証明書の購入と Key Vault へのインポート

お好みの証明書プロバイダから証明書を購入し、そのプロバイダの案内に従って Key Vault にインポートしてください。
（例として、GlobalSign 社のマニュアルはこちらです）

Managed Identity の作成

Managed Identity のトップ画面左上の "Create" を押し、入力欄を適宜埋めて Managed Identity を新規作成します。

ロールの割当

先ほど作成した Key Vault から、Access control(IAM) → Addを押し、上で作成した Managed Identity に対して Key Vault Crypto User と Key Vault Certificate User を割当てます。

Federated Credential の追加

GitHub Actions からのアクセスに対して認証を行うための Federated Credential を追加します。

1. 作成した Managed Identity のページを開き、左のメニューから "Settings" → "Federated credentials" を選択し、"Add Credentials" を押します
2. "Federated credential scenario" として、"Configure a GitHub issued token to impersonate this application and deploy to Azure" を選択します
3. Organization および Repository は、署名を行うリポジトリのものを入力します
4. Entity は ここでは Environment を選択します⁴。また、その名前として適切な値を設定しておきます
5. Credential details の Name に適当な名前をつけて Federated credential を作成します

GitHub の Environment の作成

GitHub の当該リポジトリを Admin 権限のあるユーザで開き、上側メニューの Settings → 左メニューの Environments → 右上の New environment を押します。
次に前項で設定した Environmen) t名を入力し、 Configure environment を押します。必要な環境変数やシークレットがあればここで設定しておきます。

署名を行う GitHub Actions ワークフローの作成

署名を行うための GitHub Actions ワークフローを当該リポジトリに作成します。
ワークフローの大まかな流れは以下のようになります。

1. ワークフロー自体や job の environment に先ほど作成した Environment を設定します
   • この際、permissions に write-all を設定しておきます
2. azure/login を使用して Azure にログインします
   • この際、AzureのSubscription ID, Tenant ID, Managed Identity の Client ID が必要となるため、Environment のシークレットなどに設定しておくとよいでしょう
3. AzureSignTool をインストールします
   • dotnet tool install --global --version 7.0.1 AzureSignTool のようなコマンドでインストールします
4. AzureSignTool を使用して署名します
   • Managed Identity を使用するため、--azure-key-vault-managed-identity フラグを付加します
   • TL;DR にも書きましたが、AzureSignTool は Key Vault のスロットリングに対応していないため、ファイル毎に AzureSignTool を呼び出すほか、リトライを自前で実装するようにします

また、このワークフローと他のワークフローのファイルの受け渡しは、actions/download-artifact や actions/upload-artifact を使うとよいでしょう。

終わりに

Artifact Signing は非常に安価で初期費用も必要なく、利用が簡単であったため、日本国内の組織から利用できなくなったのは残念でした。
日本でのサービス提供再開を祈念しつつ、Key Vault での運用を続けていきたいと思います（もう証明書買ってしまいましたし）。

本記事が GitHub Actions 等からコード署名を行いたい方の一助になれば幸いです。

1. 実行ファイルの発行者が不明だったり使用者が少なかったりした場合に、ユーザに実行が危険であることを警告する機能 ↩

2. Identity を管理する画面に "Artifact Signing is currently available to organizations in the USA, Canada, European Union & United Kingdom." と書かれており、Identity の追加や変更ができなくなってしまっています ↩

3. Artifact Signing が登場する以前によく用いられていた方法であり、その意味では若干クラシカルな方法とはなりますが ↩

4. Environment ならば、GitHub 側で柔軟な制御（許可するブランチの限定やレビューの必須化など）ができるようになるのでお勧めです ↩