アプリケーション レイヤの暗号化

Standard Payments API は、アプリケーション レイヤの暗号化に関して PGP または JWE のいずれかをサポートします。

PGP 暗号化

PGP は、暗号のプライバシーと認証を提供する、暗号化、復号、署名のアルゴリズムの標準セットです。

PGP を使用してペイロードを暗号化する場合、パートナー様は以下をサポートする必要があります。

  • 複数の PGP 鍵によるペイロードの暗号化と復号。
  • 複数の PGP 鍵を使用してペイロードに署名する。
  • 複数の署名を使用してペイロードを検証する。署名のいずれか 1 つが、Google 提供の鍵を使用した署名である場合があります。
  • ウェブセーフな Base64 でエンコードされたペイロードの復号。

Google に提供される PGP 公開鍵には、暗号化に使用するサブキーが必要です。サブキーを使用すると、マスター鍵から独立したローテーションが可能になります。マスター鍵は本人確認に使用されます。秘密鍵は、1 年で期限が切れる 2,048 ビット以上の RSA 鍵（最長有効期間は 2 年）である必要があります。

開発を始める前に、PGP 鍵を Google と交換する必要があります。このステップでは、PGP 公開鍵/秘密鍵のペアを生成し、その公開鍵を Google に提供して、Google から公開鍵を受け取ります。開発時に交換する必要があるのは、本番環境以外での開発とテストに使用するサンドボックス鍵のみです。本番環境のテストとリリースの前に、別の本番環境鍵を交換する必要があります。

新しい PGP 鍵の生成

GPG バイナリがシステムパスにある場合、次の POSIX コマンドを使用して新しい鍵ペアを作成できます。

$ gpg --full-generate-key

プロンプトが表示されたら、エントロピーが 2, 048 ビット以上、有効期限が 1 ～ 2 年の RSA 鍵を選択します。このコマンドにより、マスターキー（SC というラベル、「S」は「igning」と「C」は「Certificate generation」を意味する）とサブキー（ラベル E、「E'ncryption」）の両方が作成されます。

PGP ライブラリの構成

ペイロードの送信

  1. 署名するときは、ダイジェスト アルゴリズムとして SHA384 を使用する必要があります。SHA1 や MD5 は使用しないでください。
  2. 暗号化するときは、対称暗号化アルゴリズムとして AES256 を使用する必要があります。CAST5 や IDEA は使用しないでください。
  3. メッセージの暗号化またはメッセージへの署名では、目的に応じたサブキーを選択してください。署名には CAN_SIGN キーを使用し、暗号化には ENCRYPT_COMMS/ENCRYPT_STORAGE キーを使用してください。

ペイロードの受信

  1. ペイロードを検証する際は、ライブラリで SHA384 などの最新のハッシュ アルゴリズムがサポートされていることを確認してください。2023 年 5 月 14 日より、Google はすべての新しい鍵で SHA384 を使用します。
  2. ペイロードを復号する際は、ライブラリで AES256 などの最新の対称暗号化アルゴリズムがサポートされていることを確認してください。2023 年 5 月 14 日より、Google はすべての新しい鍵で AES256 を使用します。

GPG を使ったペイロード暗号化の例

以下のコマンドは、GPG の使用時に安全なオプションを選択する方法の例です。このオペレーションは、ユーザーが秘密鍵または機密性の高い入力ファイルにアクセスできない、信頼できる環境で行われることを想定しています。

gpg --output signed-and-encrypted.pgp \
  --sign --digest-algo SHA384 \
  --encrypt --cipher-algo AES256 \
  --armor \
  --recipient {key_id} \
  input.txt

GPG は、実行するオペレーションごとに適切な鍵をバンドルから自動的に選択します。

JWE 暗号化と JWS 署名

JSON Web Encryption（JWE）は、rfc7516 によって定義されている、アプリケーション レベルでコンテンツを暗号化するための規格です。JSON Web Signature（JWS）は、rfc7515 によって定義されている、アプリケーション レベルでコンテンツに署名するための規格です。

リクエストとレスポンスは、「Compact Serialization」オプションにより非対称（公開鍵）暗号化を使用して暗号化された JWE トークンになります。JWE トークンには、JWS トークンとして署名付きペイロードが含まれます。JWS でも非対称鍵が使用されます。秘密鍵は署名に、公開鍵は検証に使用されます。

ペイロードを送信するときは、まずペイロードに署名してから暗号化します。ペイロードを受信するときは、まずペイロードを復号してから署名を検証します。

JWE を使用する場合、パートナーは次のオプションをサポートする必要があります。

  • コンパクトなシリアル化。
  • 複数の JWE 鍵の 1 つからペイロードを復号する。
  • 鍵管理用の RSA-OAEP、RSA-OAEP-256、または ECDH-ES アルゴリズム。
  • コンテンツ暗号化用の A256GCM、A128GCM、A128CBC-HS256、A256CBC-HS512 アルゴリズム。
    • enc ヘッダーに入力されます。
  • 公開暗号鍵を識別する kid ヘッダー。
  • JWE 暗号化を使用するメッセージ ペイロードは、コンテンツ タイプ application/jose（charset=utf-8）を使用する必要があります。

JWS を使用する場合、パートナーは次のオプションをサポートする必要があります。

  • コンパクトなシリアル化。
  • 複数の JWS 鍵の 1 つからペイロードを検証する。
  • 署名作成用の HS256、HS384、HS512、RS256、RS384、RS512、ES256、PS256、PS384、または PS512 アルゴリズム。
  • 秘密鍵を識別する kid ヘッダー。

JWE/JWS 文字列は UTF-8 文字列としてエンコードされ、ペイロードは任意のバイトになります。

秘密鍵は、最長寿命が 2 年で、1 年で期限が切れる RSA 鍵/ECDH-ES 鍵である必要があります。すべての秘密鍵 ID は常にパートナーのサーバー上に保持される必要があります。したがって、すべての署名値はパートナーのサーバー上で計算される必要があります。

開発を始める前に、JWE 鍵と JWS 鍵を Google と交換する必要があります。rfc7517 で定義されているように、鍵は JWK 形式で交換する必要があります。このステップでは、公開鍵 / 秘密鍵ペアを生成し、Google にその公開鍵を提供して、Google から公開鍵を受け取ります。開発時に交換する必要があるのは、本番環境以外での開発とテストに使用するサンドボックス鍵のみです。本番環境のテストとリリースの前に、別の本番環境鍵を交換する必要があります。