このガイドでは、Debian 11（BullsEye）で Cloud HSM 鍵を使用するように OpenSSL を設定する手順について説明します。これらの手順は、通常、別の OS や環境を使用している場合でも適用できますが、多少異なる場合があります。
要件
まず、ライブラリのリリースをダウンロードします。PKCS #11 ライブラリの詳細については、ユーザーガイドをご覧ください。
開始する前に、libengine-pkcs11-openssl パッケージをインストールしてください。
sudo apt-get update
sudo apt-get install libengine-pkcs11-openssl
構成
PKCS11_MODULE_PATH 環境変数を設定する。
openssl で PKCS #11 ライブラリを使用するには、PKCS11_MODULE_PATH 環境変数を設定します。
export PKCS11_MODULE_PATH="/path/to/libkmsp11.so"
環境変数を永続的に設定するには、次のコマンドを実行して export PKCS11_MODULE_PATH="/path/to/libkmsp11.so" を /etc/profile に追加します。
echo 'export PKCS11_MODULE_PATH="/path/to/libkmsp11.so"' | sudo tee -a /etc/profile
PKCS #11 ライブラリの構成
PKCS #11 ライブラリには、Cloud KMS リソースを見つけるための YAML 構成ファイルが必要です。YAML は少なくとも 1 つの PKCS #11 トークンを構成する必要があります。
OpenSSL をフォークする可能性がある別のプロセス（Apache や Nginx など）で使用している場合は、refresh_interval_secs フィールドが未設定または 0 に設定されていることも確認する必要があります。
サンプル構成ファイル
---
tokens:
- key_ring: "projects/my-project/locations/us-central1/keyRings/my-keyring"
この構成では、my-keyring 内のすべての非対称署名鍵と復号鍵がライブラリで使用できます。
ファイル オーナーのみが書き込めるように、構成ファイルに権限を設定する必要があります。KMS_PKCS11_CONFIG が構成ファイルを指すように設定します。
export KMS_PKCS11_CONFIG="/path/to/pkcs11-config.yaml"
この設定も /etc/profile に追加すれば永続的なものにできます。
echo 'export KMS_PKCS11_CONFIG="/path/to/pkcs11-config.yaml"' | sudo tee -a /etc/profile
OpenSSL コマンドの実行
エンジンとライブラリが適切に構成されたら、OpenSSL コマンドでエンジンを使用できます。
非対称署名を作成する場合、Cloud KMS 鍵は 1 つのダイジェストを使用するように制限されることに注意してください。たとえば、アルゴリズム EC_SIGN_P256_SHA256 を含む暗号鍵バージョンは、常に SHA-256 ダイジェストと組み合わせて使用する必要があります。これは、OpenSSL の -sha256 フラグに対応します。SHA-384 または SHA-512 ダイジェストを必要とする鍵は、-sha384 フラグまたは -sha512 フラグとともに使用してください。
新しい署名を作成する
構成されたキーリングに foo という鍵がある場合、次のコマンドを使用して bar.txt に署名を作成します。
openssl dgst -sha256 -engine pkcs11 -keyform engine -sign pkcs11:object=foo bar.txt
このコマンドの出力は、フォーマットされていないバイナリです。
このコマンドは SHA-256 ダイジェストを使用する鍵を使用していると想定しているため、-sha256 引数が使用されました。-sha384 または -sha512 オプションは、これらのダイジェスト タイプを使用する Cloud HSM 鍵に適しています。
RSA-PSS 鍵の場合は、前述の -sigopt オプションを使用することを覚えておいてください。
新しい証明書署名リクエストを作成する
Cloud HSM 署名鍵の証明書署名リクエスト（CSR）を生成することもできます。これは、認証局が CSR をリクエストしてコード署名用の新しい証明書を生成する場合や、TLS ウェブ セッションを保護する場合に便利です。
openssl req -new -subj '/CN=test/' -sha256 -engine pkcs11 \
-keyform engine -key pkcs11:object=foo > my-request.csr
新しい自己署名証明書を生成する
ローカルでの開発とテストでは、Cloud HSM 署名鍵に自己署名証明書を使用できます。自己署名証明書は、SAML トークンの署名にも便利です。
openssl req -new -x509 -days 3650 -subj '/CN=test/' -sha256 -engine pkcs11 \
-keyform engine -key pkcs11:object=foo > my-request.crt
PKCS #11 Spy を使用したトラブルシューティング
PKCS #11 Spy は、PKCS #11 インターフェースを介したインタラクションの内容をログに記録するオープンソース ツールです。アプリケーションと PKCS #11 ライブラリの間にあるすべての呼び出しを記録します。これはトラブルシューティングに役立ちます。
PKCS #11 Spy を使用するには、opensc パッケージをインストールする必要があります。opensc パッケージには PKCS #11 Spy が含まれています。opensc がインストールされていることを確認するには、次のコマンドを実行します。
sudo apt-get install opensc
次に、以下のコマンドを実行して、OpenSSL が PKCS #11 Spy ライブラリを指すように PKCS11_MODULE_PATH 環境変数を設定します。
export PKCS11_MODULE_PATH=/usr/lib/x86_64-linux-gnu/pkcs11-spy.so
最後に、PKCS11SPY 環境変数と PKCS11SPY_OUTPUT 環境変数を設定して、PKCS #11 Spy で Cloud HSM PKCS #11 ライブラリを指定します。これらの環境変数を設定するには、次のコマンドを実行します。
export PKCS11SPY="/path/to/libkmsp11.so"
# Optional, stderr will be used for logging if not set
export PKCS11SPY_OUTPUT="/path/to/pkcs11-spy.log"