Decrypt Advertising ID

Ad Exchange now supports passing the Android advertising ID in mobile application inventory bid requests.

About the advertising ID

With Google Play services v4.0, Android launched a new user-resettable identifier for advertising called the advertising ID.

The advertising ID may be used by advertisers to run remarketing campaigns and record "conversions" (purchasing or downloading). The advertising ID has two key features:

  • Users can reset the advertising ID at any time.
  • Users can opt out of interest-based ads at any time, right from the Google Settings app. This setting applies across all ad companies that use the advertising ID.

Technical definition

Advertising ID is passed via BidRequest.Mobile.encrypted_advertising_id in the real-time bidding proto:

optional bytes encrypted_advertising_id = 20;

The field is 36 bytes and contains 3 sections:

  • initialization_vector: 16 bytes.
  • ciphertext: 16 bytes, the encrypted 16-byte UUID of the advertising ID.
  • integrity_signature: 4 bytes.
{initialization_vector (16 bytes)}{ciphertext (16 bytes)}{integrity_signature (4 bytes)}

Definitions

Variable Details
initialization_vector 16 bytes - unique to the impression.
ciphertext 16 bytes - generated as: <advertising_id <xor> hmac(encryption_key, initialization_vector)>
integrity_signature 4 bytes - generated as first 4 bytes of: hmac(integrity_key, advertising_id || initialization_vector)
encryption_key 32 bytes - provided at account setup.
integrity_key 32 bytes - provided at account setup.
advertising_id 16 bytes - The original, unencrypted advertising ID, which is a UUID
final_message 36 bytes - The byte array sent via the encrypted_advertising_id field.
Operators Details
hmac(key, data) SHA-1 HMAC, using key to encrypt data.
a || b string a concatenated with string b.

Encryption scheme

The encryption scheme for advertising ID is based on the same scheme used for decrypting price confirmations.

  1. The advertising ID is stored in a byte array, which is encrypted using a custom encryption scheme designed to minimize size overhead while ensuring adequate security.
  2. The encryption scheme uses a keyed HMAC algorithm to generate a secret pad based on the initialization_vector, which is unique to the impression event.

Encryption pseudocode

advertising_id = advertising ID from mobile device
pad = hmac(encryption_key, initialization_vector) // first 16 bytes
ciphertext = pad <xor> advertising_id
integrity_signature = hmac(integrity_key, advertising_id || initialization_vector)  // first 4 bytes
final_message = initialization_vector || ciphertext || integrity_signature

Decryption scheme

Your decryption code should 1) decrypt the encrypted_advertising_id field using the encryption key, and optionally 2) verify the integrity bits with the integrity key. The keys will be provided to you during account setup. There aren't any restrictions on how you structure your implementation.

  1. Generate your pad: hmac(encryption_key, initialization_vector)
  2. XOR: Take this result and <xor> with the ciphertext to reverse the encryption.
  3. Verify: The integrity signature passes 4 bytes of HMAC(integrity_key, advertising_id || initialization_vector)

Decryption pseudocode

(initialization_vector, ciphertext, integrity_signature) = final_message // split up according to length
pad = hmac(encryption_key, initialization_vector) // first 16 bytes
advertising_id = ciphertext <xor> pad
confirmation_signature = hmac(integrity_key, advertising_id || initialization_vector) // first 4 bytes
success = (confirmation_signature == integrity_signature)

Java library

Instead of implementing the crypto algorithms to encode and decode the advertising ID, you can use DoubleClickCrypto.java. For more information, see Cryptography.

Send feedback about...

Real-Time Bidding Protocol
Real-Time Bidding Protocol