KEM を使用してカプセル化とカプセル化解除を行う

このドキュメントでは、Cloud KMS 鍵で鍵カプセル化メカニズム（KEM）を使用して共有シークレットを確立する方法について説明します。

カプセル化では KEM 鍵ペアの公開鍵が使用され、カプセル化解除では鍵ペアの秘密鍵が使用されます。Cloud KMS では、公開鍵を取得できます。この公開鍵は、標準ライブラリで使用して共有シークレットをカプセル化できます。共有シークレットをカプセル化解除するには、Cloud KMS のカプセル化解除メソッドを使用します。秘密鍵マテリアルを Cloud KMS の外部で使用することはできません。

始める前に

  • このドキュメントでは、コマンドラインでの実行例を示します。例をわかりやすくするため、Cloud Shell を使用します。この暗号化の例では、Cloud Shell にプリインストールされている OpenSSL が使用されています。インストールされていない場合は、マシンに OpenSSL をインストールします。
  • KEY_ENCAPSULATION を鍵の目的とするKEM 鍵を作成します。鍵の目的 KEY_ENCAPSULATION でサポートされているアルゴリズムについては、鍵カプセル化アルゴリズムをご覧ください。

鍵に対する権限を付与する

  • シークレットをカプセル化するために公開鍵を取得する必要がある各ユーザーまたはプリンシパルに、鍵に対する roles/cloudkms.publicKeyViewer ロールを付与します。
  • この鍵でシークレットをカプセル化解除する必要がある各ユーザーまたはプリンシパルに、鍵に対する roles/cloudkms.decapsulator ロールを付与します。

Cloud KMS の権限とロールの詳細については、権限とロールをご覧ください。

カプセル化

KEM 鍵を使用してカプセル化するには、公開鍵を取得し、その公開鍵を使用してカプセル化します。

gcloud

このサンプルでは、ローカル システムに OpenSSL をインストールする必要があります。

公開鍵をダウンロードする

gcloud kms keys versions get-public-key KEY_VERSION \
    --key KEY_NAME \
    --keyring KEY_RING \
    --location LOCATION  \
    --output-file PUBLIC_KEY_FILE \
    --public-key-format PUBLIC_KEY_FORMAT

次のように置き換えます。

  • KEY_VERSION: カプセル化に使用する鍵のバージョン番号（例: 2）。
  • KEY_NAME: カプセル化に使用する鍵の名前。
  • KEY_RING: 鍵を含むキーリングの名前
  • LOCATION: キーリングの Cloud KMS のロケーション
  • PUBLIC_KEY_FILE: 公開鍵が保存されるローカル ファイルパス。
  • PUBLIC_KEY_FORMAT: 公開鍵のターゲット形式（例: nist-pqc）。デフォルトの形式は pem です。

カプセル化

共有シークレットと暗号文を作成するには、次のコマンドを使用します。

openssl pkeyutl \
    -encap \
    -pubin \
    -inkey PEM_PUBLIC_KEY_FILE \
    -out CIPHERTEXT_FILE \
    -secret SHARED_SECRET_FILE

次のように置き換えます。

  • PEM_PUBLIC_KEY_FILE: ダウンロードした公開鍵ファイルのパス（PEM 形式）。
  • CIPHERTEXT_FILE: 結果の暗号テキストを保存するパス。
  • SHARED_SECRET_FILE: 結果の共有シークレットを保存するパス。
{ echo -n "MIIEsjALBglghkgBZQMEBAIDggShAA==" | base64 -d ; cat PUBLIC_KEY_FILE; } | \
openssl pkey -inform DER -pubin -pubout -out PEM_PUBLIC_KEY_FILE

次のように置き換えます。

  • PUBLIC_KEY_FILE: ダウンロードした公開鍵ファイルのパス（未加工形式）。
  • PEM_PUBLIC_KEY_FILE: 公開鍵を PEM 形式で保存するパスとファイル名。

カプセル化解除

Cloud KMS を使用して暗号テキストをカプセル化解除します。

gcloud

コマンドラインで Cloud KMS を使用するには、まず Google Cloud CLI の最新バージョンをインストールまたはアップグレードします。

gcloud kms decapsulate \
    --version KEY_VERSION \
    --key KEY_NAME \
    --keyring KEY_RING \
    --location LOCATION  \
    --ciphertext-file CIPHERTEXT_FILE \
    --shared-secret-file SHARED_SECRET_FILE

次のように置き換えます。

  • KEY_VERSION: カプセル化解除に使用する鍵のバージョン（例: 3）。
  • KEY_NAME: カプセル化解除に使用する鍵の名前。
  • KEY_RING: 鍵が配置されているキーリングの名前。
  • LOCATION: キーリングの Cloud KMS のロケーション。
  • CIPHERTEXT_FILE: 入力暗号テキストのローカル ファイルパス。
  • SHARED_SECRET_FILE: 出力共有シークレットを保存するローカル ファイルパス。

API

これらの例では、HTTP クライアントとして curl を使用して API の使用例を示しています。アクセス制御の詳細については、Cloud KMS API へのアクセスをご覧ください。

CryptoKeyVersions.decapsulate メソッドを使用します。

curl "https://cloudkms.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY_NAME/cryptoKeyVersions/KEY_VERSION:decapsulate" \
  --request "POST" \
  --header "authorization: Bearer TOKEN" \
  --header "content-type: application/json" \
  --data '{"ciphertext": "CIPHERTEXT"}'

次のように置き換えます。

  • PROJECT_ID: キーリングを含むプロジェクトの ID。
  • LOCATION: キーリングの Cloud KMS のロケーション
  • KEY_RING: 鍵を含むキーリングの名前
  • KEY_NAME: 暗号化に使用する鍵の名前。
  • KEY_VERSION: 暗号化に使用する鍵バージョンの ID
  • CIPHERTEXT: カプセル化解除する base64 でエンコードされた暗号テキスト。