Encrypting Requests and Decrypting Responses
For almost all UID2 endpoints, requests sent to the endpoint must be encrypted and responses from the endpoint must be decrypted.
The only exception is that requests to the POST /token/refresh endpoint do not need to be encrypted.
Here's what you need to know about encrypting UID2 API requests and decrypting respective responses:
- To use the APIs, in addition to your client API key, you need your client secret
- You can write your own custom code or use one of the code examples provided: see Encryption and Decryption Code Examples.
- Request and response use AES/GCM/NoPadding encryption algorithm with 96-bit initialization vector and 128-bit authentication tag.
- The raw, unencrypted JSON body of the request is wrapped in a binary Unencrypted Request Data Envelope which then gets encrypted and formatted according to the Encrypted Request Envelope.
- Response JSON body is wrapped in a binary Unencrypted Response Data Envelope which is encrypted and formatted according to the Encrypted Response Envelope.
Workflow
The high-level request-response workflow for the UID2 APIs includes the following steps:
- Prepare the request body with input parameters in the JSON format.
- Wrap the request JSON in an Unencrypted Request Data Envelope.
- Encrypt the envelope using AES/GCM/NoPadding algorithm and your secret key.
- Assemble the Encrypted Request Envelope.
- Send the encrypted request and receive the encrypted response.
- Parse the Encrypted Response Envelope.
- Decrypt the data in the response envelope.
- Parse the resulting Unencrypted Response Data Envelope.
- (Optional, recommended) Ensure the nonce the in the response envelope matches the nonce in the request envelope.
- Extract the response JSON object from the unencrypted envelope.
A code example for encrypting requests and decrypting responses can help with automating steps 2-10 and serve as a reference of how to implement these steps in your application.
The individual UID2 endpoints explain the respective JSON body format requirements and parameters, include call examples, and show decrypted responses. The following sections provide encryption and decryption code examples, field layout requirements, and request and response examples.
Encrypting Requests
You have the option of writing your own code for encrypting requests, using a UID2 SDK, or using one of the provided code examples (see Encryption and Decryption Code Examples). If you choose to write your own code, be sure to follow the field layout requirements listed in Unencrypted Request Data Envelope and Encrypted Request Envelope.
Unencrypted Request Data Envelope
The following table describes the field layout for request encryption code.
Offset (Bytes) | Size (Bytes) | Description |
---|---|---|
0 | 8 | The UNIX timestamp (in milliseconds). Must be int64 big endian. |
8 | 8 | Nonce: Random 64 bits of data used to protect against replay attacks. The corresponding Unencrypted Response Data Envelope should contain the same nonce value for the response to be considered valid. |
16 | N | Payload, which is a request JSON document serialized in UTF-8 encoding. |
Encrypted Request Envelope
The following table describes the field layout for request encryption code.
Offset (Bytes) | Size (Bytes) | Description |
---|---|---|
0 | 1 | The version of the envelope format. Must be 1 . |
1 | 12 | 96-bit initialization vector (IV), which is used to randomize data encryption. |
13 | N | Payload (Unencrypted Request Data Envelope) encrypted using the AES/GCM/NoPadding algorithm. |
13 + N | 16 | 128-bit GCM authentication tag used to verify data integrity. |
Decrypting Responses
You have the option of writing your own code for decrypting responses, using a UID2 SDK, or using one of the provided code examples (see Encryption and Decryption Code Examples). If you choose to write your own code, be sure to follow the field layout requirements listed in Encrypted Response Envelope and Unencrypted Response Data Envelope.
The response encrypted only if the service returns HTTP status code 200.
Encrypted Response Envelope
The following table describes the field layout for response decryption code.
Offset (Bytes) | Size (Bytes) | Description |
---|---|---|
0 | 12 | 96-bit initialization vector (IV), which is used to randomize data encryption. |
12 | N | Payload (Unencrypted Response Data Envelope) encrypted using the AES/GCM/NoPadding algorithm. |
12 + N | 16 | 128-bit GCM authentication tag used to verify data integrity. |
Unencrypted Response Data Envelope
The following table describes the field layout for response decryption code.
Offset (Bytes) | Size (Bytes) | Description |
---|---|---|
0 | 8 | The UNIX timestamp (in milliseconds). Must be int64 big endian. |
8 | 8 | Nonce. For the response to be considered valid, this should match the nonce in the Unencrypted Request Data Envelope. |
16 | N | Payload, which is a response JSON document serialized in UTF-8 encoding. |
Response Example
For example, a decrypted response to the POST /token/generate request for an email address in the preceding example, may look like this:
{
"body": {
"advertising_token": "AgAAAQFt3aNLXKXEyWS8Tpezcymk1Acv3n+ClOHLdAgqR0kt0Y+pQWSOVaW0tsKZI4FOv9K/rZH9+c4lpm2DBpmFJqjdF6FAaAzva5vxDIX/67UOspsYtiwxH73zU7Fj8PhVf1JcpsxUHRHzuk3vHF+ODrM13A8NAVlO1p0Wkb+cccIIhQ==",
"user_token": "AgAAAPpTqz7/Z+40Ue5G3XOM2RiyU6RS9Q5yj1n7Tlg7PN1K1LZWejvo8Er7A+Q8KxdXdj0OrKRf/XEGWsyUJscRNu1bg/MK+5AozvoJKUca8b10eQdYU86ZOHPH7pFnFhD5WHs=",
"refresh_token": "AAAAAQLMcnV+YE6/xoPDZBJvJtWyPyhF9QTV4242kFdT+DE/OfKsQ3IEkgCqD5jmP9HuR4O3PNSVnCnzYq2BiDDz8SLsKOo6wZsoMIn95jVWBaA6oLq7uUGY5/g9SUOfFmX5uDXUvO0w2UCKi+j9OQhlMfxTsyUQUzC1VQOx6ed/gZjqH/Sw6Kyk0XH7AlziqSyyXA438JHqyJphGVwsPl2LGCH1K2MPxkLmyzMZ2ghTzrr0IgIOXPsL4lXqSPkl/UJqnO3iqbihd66eLeYNmyd1Xblr3DwYnwWdAUXEufLoJbbxifGYc+fPF+8DpykpyL9neq3oquxQWpyHsftnwYaZT5EBZHQJqAttHUZ4yQ==",
"identity_expires": 1654623500142,
"refresh_expires": 1657214600142,
"refresh_from": 1654622900142,
"refresh_response_key": "wR5t6HKMfJ2r4J7fEGX9Gw=="
},
"status": "success"
}
Encryption and Decryption Code Examples
This section includes an encryption and decryption code example in different programming languages.
For the POST /token/refresh endpoint, the code takes the values for refresh_token
and refresh_response_key
that were obtained from a prior call to POST /token/generate or POST /token/refresh.
For Windows, if you're using Windows Command Prompt instead of PowerShell, you must also remove the single quotes surrounding the JSON. For example, use echo {"email": "test@example.com"}
.
Prerequisites and Notes
Before using the code example, check the prerequisites and notes for the language you're using.
- Python
- C#
The Python code example for encrypting requests and decrypting responses is uid2_request.py
. The required parameters are shown at the top of the code example, or by running python3 uid2_request.py
.
The Python code requires the pycryptodomex
and requests
packages. You can install these as follows:
pip install pycryptodomex
pip install requests
The C# code example for encrypting requests and decrypting responses is uid2_request.cs
. The required parameters are shown at the top of the file, or by building and running .\uid2_request
.
This file requires .NET 7.0. You can use an earlier version if required, but it must be .NET Core 3.0 or later. To change the version, replace the top-level statements with a Main method and the using declarations with using statements.
Code Example
Choose the code example you want to use. Remember to review the Prerequisites and Notes.
- Python
- C#
"""
Usage:
echo '<json>' | python3 uid2_request.py <url> <api_key> <client_secret>
Example:
echo '{"email": "test@example.com"}' | python3 uid2_request.py https://prod.uidapi.com/v2/token/generate PRODGwJ0hP19QU4hmpB64Y3fV2dAed8t/mupw3sjN5jNRFzg= wJ0hP19QU4hmpB64Y3fV2dAed8t/mupw3sjN5jNRFzg=
Refresh Token Usage:
python3 uid2_request.py <url> --refresh-token <refresh_token> <refresh_response_key>
Refresh Token Usage example:
python3 uid2_request.py https://prod.uidapi.com/v2/token/refresh --refresh-token AAAAAxxJ...(truncated, total 388 chars) v2ixfQv8eaYNBpDsk5ktJ1yT4445eT47iKC66YJfb1s=
"""
import base64
import os
import sys
import time
import json
import requests
from Cryptodome.Cipher import AES
def b64decode(b64string, param):
try:
return base64.b64decode(b64string)
except Exception:
print(f"Error: <{param}> is not base64 encoded")
sys.exit()
if len(sys.argv) != 4 and len(sys.argv) != 5:
print(__doc__)
sys.exit()
url = sys.argv[1]
is_refresh = 1 if sys.argv[2] == '--refresh-token' else 0
if is_refresh:
refresh_token = sys.argv[3]
secret = b64decode(sys.argv[4], "refresh_response_key")
print(f"\nRequest: Sending refresh_token to {url}\n")
http_response = requests.post(url, refresh_token)
else:
api_key = sys.argv[2]
secret = b64decode(sys.argv[3], "client_secret")
payload = "".join(sys.stdin.readlines())
iv = os.urandom(12)
cipher = AES.new(secret, AES.MODE_GCM, nonce=iv)
millisec = int(time.time() * 1000)
request_nonce = os.urandom(8)
print(f"\nRequest: Encrypting and sending to {url} : {payload}")
body = bytearray(millisec.to_bytes(8, 'big'))
body += bytearray(request_nonce)
body += bytearray(bytes(payload, 'utf-8'))
ciphertext, tag = cipher.encrypt_and_digest(body)
envelope = bytearray(b'\x01')
envelope += bytearray(iv)
envelope += bytearray(ciphertext)
envelope += bytearray(tag)
base64Envelope = base64.b64encode(bytes(envelope)).decode()
http_response = requests.post(url, base64Envelope, headers={"Authorization": "Bearer " + api_key})
# Decryption
response = http_response.content
if http_response.status_code != 200:
print(f"Response: Error HTTP status code {http_response.status_code}", end=", check api_key\n" if http_response.status_code == 401 else "\n")
print(response.decode("utf-8"))
else:
resp_bytes = base64.b64decode(response)
iv = resp_bytes[:12]
data = resp_bytes[12:len(resp_bytes) - 16]
tag = resp_bytes[len(resp_bytes) - 16:]
cipher = AES.new(secret, AES.MODE_GCM, nonce=iv)
decrypted = cipher.decrypt_and_verify(data, tag)
if is_refresh != 1:
json_resp = json.loads(decrypted[16:].decode("utf-8"))
else:
json_resp = json.loads(decrypted.decode("utf-8"))
print("Response JSON:")
print(json.dumps(json_resp, indent=4))
using System.Buffers.Binary;
using System.Net;
using System.Security.Cryptography;
using System.Text;
using System.Text.Json;
if (args.Length != 3 && args.Length != 4)
{
Console.WriteLine("""
Usage:
echo '<json>' | .\uid2_request <url> <api_key> <client_secret>
Example:
echo '{"email": "test@example.com"}' | .\uid2_request https://prod.uidapi.com/v2/token/generate UID2-C-L-999-fCXrMM.fsR3mDqAXELtWWMS+xG1s7RdgRTMqdOH2qaAo= wJ0hP19QU4hmpB64Y3fV2dAed8t/mupw3sjN5jNRFzg=
Refresh Token Usage:
.\uid2_request <url> --refresh-token <refresh_token> <refresh_response_key>
Refresh Token Usage example:
.\uid2_request https://prod.uidapi.com/v2/token/refresh --refresh-token AAAAAxxJ...(truncated, total 388 chars) v2ixfQv8eaYNBpDsk5ktJ1yT4445eT47iKC66YJfb1s=
""");
Environment.Exit(1);
}
const int GCM_IV_LENGTH = 12;
string url = args[0];
byte[] secret;
HttpResponseMessage? response;
bool isRefresh = args[1] == "--refresh-token";
if (isRefresh)
{
string refreshToken = args[2];
secret = Convert.FromBase64String(args[3]);
Console.WriteLine($"\nRequest: Sending refresh_token to {url}\n");
using HttpClient httpClient = new HttpClient();
var content = new StringContent(refreshToken, Encoding.UTF8);
response = await httpClient.PostAsync(url, content);
}
else
{
string apiKey = args[1];
secret = Convert.FromBase64String(args[2]);
string payload = Console.In.ReadToEnd();
var request = new HttpRequestMessage(HttpMethod.Post, url);
request.Headers.Add("Authorization", $"Bearer {apiKey}");
var unixTimestamp = new byte[8];
BinaryPrimitives.WriteInt64BigEndian(unixTimestamp, DateTimeOffset.UtcNow.ToUnixTimeMilliseconds());
var nonce = new byte[8];
var rnd = new Random();
rnd.NextBytes(nonce);
var payloadBytes = Encoding.UTF8.GetBytes(payload);
var unencryptedRequestDataEnvelope = new byte[unixTimestamp.Length + nonce.Length + payloadBytes.Length];
unixTimestamp.CopyTo(unencryptedRequestDataEnvelope, 0);
nonce.CopyTo(unencryptedRequestDataEnvelope, unixTimestamp.Length);
payloadBytes.CopyTo(unencryptedRequestDataEnvelope, unixTimestamp.Length + nonce.Length);
var iv = new byte[GCM_IV_LENGTH];
rnd.NextBytes(iv);
var encryptedPayload = new byte[unencryptedRequestDataEnvelope.Length];
var tag = new byte[AesGcm.TagByteSizes.MaxSize];
using AesGcm aesGcm = new AesGcm(secret);
aesGcm.Encrypt(iv, unencryptedRequestDataEnvelope, encryptedPayload, tag);
var envelopeMemoryStream = new MemoryStream(1 + iv.Length + encryptedPayload.Length + AesGcm.TagByteSizes.MaxSize);
envelopeMemoryStream.WriteByte(1); //version of the envelope format
envelopeMemoryStream.Write(iv);
envelopeMemoryStream.Write(encryptedPayload);
envelopeMemoryStream.Write(tag);
var envelope = Convert.ToBase64String(envelopeMemoryStream.ToArray());
request.Content = new StringContent(envelope, Encoding.UTF8);
var client = new HttpClient();
response = await client.SendAsync(request);
}
var responseStream = await response.Content.ReadAsStreamAsync();
using var reader = new StreamReader(responseStream);
var responseBody = await reader.ReadToEndAsync();
if (response.StatusCode != HttpStatusCode.OK)
{
Console.WriteLine($"Response: Error HTTP status code {(int)response.StatusCode}" + ((response.StatusCode == HttpStatusCode.Unauthorized) ? ", check api_key" : ""));
Console.WriteLine(responseBody);
}
else
{
var encryptedResponseEnvelope = Convert.FromBase64String(responseBody);
var responseMemoryStream = new MemoryStream(encryptedResponseEnvelope);
byte[] iv = new byte[GCM_IV_LENGTH];
responseMemoryStream.Read(iv);
int encryptedPayloadLength = encryptedResponseEnvelope.Length - GCM_IV_LENGTH - AesGcm.TagByteSizes.MaxSize;
byte[] encryptedPayload = new byte[encryptedPayloadLength];
responseMemoryStream.Read(encryptedPayload);
byte[] tag = new byte[AesGcm.TagByteSizes.MaxSize];
responseMemoryStream.Read(tag);
using AesGcm aesGcm = new AesGcm(secret);
byte[] unencryptedResponseDataEnvelope = new byte[encryptedPayload.Length];
aesGcm.Decrypt(iv, encryptedPayload, tag, unencryptedResponseDataEnvelope);
int offset = isRefresh ? 0 : 16; //8 bytes for timestamp + 8 bytes for nonce
var json = Encoding.UTF8.GetString(unencryptedResponseDataEnvelope, offset, unencryptedResponseDataEnvelope.Length - offset);
Console.WriteLine("Response JSON:");
using var jDoc = JsonDocument.Parse(json);
Console.WriteLine(JsonSerializer.Serialize(jDoc, new JsonSerializerOptions { WriteIndented = true }));
}