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

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」は「Signing」、「C」は「Certificate generation」を指す)とサブキー(「E」のラベル付き、「Encryption」を指す)の両方が作成されます。

PGP ライブラリの構成

ペイロードの送信

  1. 署名するときは、ダイジェスト アルゴリズムとして SHA384 を使用する必要があります。SHA1MD5 は使用しないでください。
  2. 暗号化するときは、対称暗号化アルゴリズムとして AES256 を使用する必要があります。CAST5IDEA は使用しないでください。
  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 を使用する場合、パートナーは次のオプションをサポートする必要があります。

  • Compact Serialization。
  • 複数の JWE 鍵のいずれかからのペイロードの復号
  • 鍵管理用の RSA-OAEP、RSA-OAEP-256、または ECDH-ES アルゴリズム。
  • コンテンツ暗号化用の A256GCMA128GCMA128CBC-HS256A256CBC-HS512 アルゴリズム。
    • enc ヘッダーに入力されます。
  • kid ヘッダー: 公開暗号鍵を識別します。
  • JWE 暗号化を使用するメッセージ ペイロードでは、コンテンツ タイプとして application/jose; charset=utf-8 を使用する必要があります。

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

  • Compact Serialization。
  • 複数の 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 から公開鍵を受け取ります。開発時には、本番環境以外での開発とテストに使用するサンドボックス キーのみを交換する必要があります。本番環境のテストとリリースの前に、別の本番環境鍵を交換する必要があります。