Encrypting Requests and Decrypting Responses
パブリッシャーで、クライアント側にUID2を実装している場合、暗号化と復号化は、Prebid.js (UID2 Client-Side Integration Guide for Prebid.js を参照してください) や JavaScript SDK (Client-Side Integration Guide for JavaScript を参照してください) などの実装によって自動的に管理されます。
ほとんどすべての UID2 endpoints では、エンドポイントに送られるリクエストは encrypted され、エンドポイントからのレスポンスは decrypted する必要があります。
唯一の例外は、POST /token/refresh エンドポイントへのリクエストは暗号化する必要がないことです。
UID2 API リクエストの暗号化と各レスポンスの復号化に ついて知っておく必要があるのは、以下のとおりです:
- API を使用するには、クライアントの API Key に加えて、クライアントシークレットが必要です。
- 独自のコードを書くことも、提供されているコード例の一つを使うこともできます: Encryption and Decryption Code Examples を参照してください。
- リクエストとレスポンスには、96 ビットの初期化ベクトルと 128 ビットの認証タグを持つ AES/GCM/NoPadding 暗号化アルゴリズムが使用されます。
- リクエストの暗号化されていない JSON ボディは、バイナリの 暗号化前リクエストデータエンベローブ にラップされ、その後 暗号化リクエストエンベローブ に従って暗号化とフォーマットが行われます。
- レスポンス JSON ボディはバイナリの 復号化済みレスポンスデータエンベローブ にラップされ、暗号化レスポンスエンベローブ に従って暗号化・整形されます。
Workflow
UID2 API のリクエストレスポンスワークフローは、以下のステップです:
- 入力パラメータを含むリクエストボディを JSON 形式で用意します。
- リクエスト JSON を暗号化前リクエストデータエンベローブ でラップします。
- AES/GCM/NoPadding アルゴリズムと秘密鍵でエンベローブを暗号化します。
- 暗号化リクエストエンベローブ を組み立てます。
- 暗号化されたリクエストを送信し、暗号化されたレスポンスを受信します。
- 暗号化レスポンスエンベローブ を解析します。
- レスポンスエンベローブのデータを復号化します。
- 得られた 復号化済みレスポンスデータエンベローブ を解析します。
- (オプション、推奨) レスポンスエンベローブの nonce がリクエストエンベローブの nonce と一致することを確認します。
- 暗号化されていないエンベローブからレスポンス JSON オブジェクトを抽出します。
encrypting requests and decrypting responses のコード例は、Step 2-10 を自動化するのに役立ち、アプリケーションでこれらのステップを実装する方法のリファレンスとなります。
各 UID2 endpoints では、JSON ボディのフォーマットの要件とパラメータを説明し、呼び出し例を含め、復号化されたレスポンスを示しています。以下のセクションでは、暗号化と復号化のコード例、フィールドレイアウトの要件、リクエストとレスポンスの例を示します。
Encrypting Requests
リクエストを暗号化するコードを自分で書くか、UID2 SDK を使うか、提供されているコード例のいずれかを使うかの選択肢があります(Encryption and Decryption Code Examples を参照してください)。自分でコードを書く場合は、unencrypted request data envelope と Encrypted Request Envelope に記載されているフィールドレイアウトの要件に従うようにしてください。
Unencrypted Request Data Envelope
次の表に、リクエスト暗号化コードのフィールドレイアウトを示します。
Offset (Bytes) | Size (Bytes) | Description |
---|---|---|
0 | 8 | Unix タイムスタンプ (ミリ秒単位) です。int64 のビッグエンディアンでなければなりません。 |
8 | 8 | Nonce: リプレイ攻撃から保護するために使用されるランダムな 64 ビットのデータです。対応する 復号化済みレスポンスデータエンベローブ には、レスポンスが有効とみなされるために同じ nonce 値が含まれていなければなりません。 |
16 | N | UTF-8 エンコーディングでシリアライズされたリクエスト JSON ドキュメントをペイロードとします。 |
Encrypted Request Envelope
次の表は、リクエスト暗号化コードのフィールドレイアウトを説明するものです。
Offset (Bytes) | Size (Bytes) | Description |
---|---|---|
0 | 1 | エンベローブフォーマットのバージョン。1 でなければなりません。 |
1 | 12 | 96 ビットの初期化ベクトル (IV)、データ暗号化のランダム化に使用されます。 |
13 | N | ペイロード(暗号化前リクエストデータエンベローブ) は AES/GCM/NoPadding アルゴリズムで暗号化されます。 |
13 + N | 16 | データの整合性を確認するために使用される 128 ビット GCM 認証タグです。 |
Decrypting Responses
レスポンスを復号化するコードを自分で書くか、UID2 SDKを使うか、提供されているコード例のいずれかを使うかの選択肢があります(Encryption and Decryption Code Examples を参照してください)。独自のコ ードを書く場合は、Encrypted Response Envelope および Encrypted Response Envelope に記載されているフィールドレイアウトの要件に従うようにしてください。
レスポンスは、サービスが HTTP ステータスコード 200 を返す場合のみ、暗号化されます。
Encrypted Response Envelope
次の表は、レスポンス復号化コードのフィールドレイアウトを説明するものです。
Offset (Bytes) | Size (Bytes) | Description |
---|---|---|
0 | 12 | 96 ビットの初期化ベクトル (IV)、データ暗号化のランダム化に使用されます。 |
12 | N | ペイロード(復号化済みレスポンスデータエンベローブ) は、AES/GCM/NoPadding アルゴリズムで暗号化されています。 |
12 + N | 16 | データの整合性を確認するために使用される 128 ビット GCM 認証タグ。 |
Unencrypted Response Data Envelope
次の表は、レスポンス復号化コードのフィールドレイアウトを説明するものです。
Offset (Bytes) | Size (Bytes) | Description |
---|---|---|
0 | 8 | Unix タイムスタンプ (ミリ秒単位) です。int64 のビッグエンディアンでなければなりません。 |
8 | 8 | Nonce: レスポンスが有効であるとみなされるためには、これは 暗号化前リクエストデータエンベローブ の nonce と一致する必要があります。 |
16 | N | UTF-8 エンコーディングでシリアライズされたレスポンス JSON ドキュメントをペイロードとします。 |
Response Example
例えば、先行例 のメールアドレスに対する POST /token/generate リクエストに対する復号されたレスポンスは、次のようになります:
{
"body": {
"advertising_token": "A4AAAABlh75XmviGJi-hkLGs96duivRhMd3a3pe7yTIwbAHudfB9wFTj2FtJTdMW5TXXd1KAb-Z3ekQ_KImZ5Mi7xP75jRNeD6Mt6opWwXCCpQxYejP0R6WnCGnWawx9rLu59LsHv6YEA_ARNIUUl9koobfA9pLmnxE3dRedDgCKm4xHXYk01Fr8rOts6iJj2AhYISR3XkyBpqzT-vqBjsHH0g",
"identity_expires": 1724899014352,
"refresh_expires": 1724981814352,
"refresh_from": 1724896314352,
"refresh_response_key": "TS0H0szacv/F3U8bQjZwjSaZJjxZbMvxqHn1l3TL/iY=",
"refresh_token": "AAAAAGYzgUszke2sV9CxXnxyFfUU+KDCJUCXNbj1/FVcCjvR7K07jYaWe44wxM6SOTwG7WQB4XfIcquMqH57iHUnAu1zacYf9g58BtbhKCYWTwrdpB0fSqTANBXOYy+yBnl6tLRwVv32LqRCj76D8meO4tw+MKlUAc2EoFzFNPSfZLpA3Jk4q68vH6VJH/WIuu1tulrVm5J8RZAZnmTlEcsPdjoOC6X4w3aAwiwtbeGw7yOO0immpVoC5KaXnT9olRPTlrt8F9SvebLIcqkYhvRMPpl1S89yeneyGo++RnD9qSHIrfu9To3VwYW018QuvyA15uv4No4BoAzyPuHqzQ8gAs6csWwZ7VwfYD7DSJXlQiIpwzjA2Hl8mgg/5fcXwKEJ"
},
"status": "success"
}
Encryption and Decryption Code Examples
このセクションには、さまざまなプログラミング言語による暗号化と復号化のコード例が示されています。
POST /token/refresh エンドポイントでは、POST /token/generate または POST /token/refresh へのコールで事前に取得した refresh_token
と refresh_response_key
の値を使用します。
Windows の場合、PowerShell の代わりに Windows コマンドプロンプトを使用している場合は、JSON を囲むシングルクォートも削除する必要があります。例えば、echo {"email": "test@example.com"}
とします。
Prerequisites and Notes
コードサンプルを使用する前に、使用している言語の前提条件と注意事項を確認してください。
- Python
- Java
- C#
以下のコードサンプルは Python を使ってリクエストを暗号化し、レスポンスを復号化します。必要なパラメータはコード例の一番上に示されており、 python3 uid2_request.py
を実行することで得ることができます。
Windowsの場合は python3
を python
に置き換えてください。
Python のコードには pycryptodomex
と requests
パッケージが必要です。これらは以下のようにしてインストールできます:
pip install pycryptodomex
pip install requests
以下のコードサンプルは、Java を使用してリクエストを暗号化し、レスポンスを復号化します。必要なパラメータは main 関数の先頭に示されています:
java -jar Uid2Request-jar-with-dependencies.jar