Cookies for Platforms

Context

A single cookie named DigiTrust.v1.identity is used to encode the anonymous DigiTrust identifier and associated data. The attributes of this object are described below.

This cookie is written to the .digitru.st domain. While it is not expected, it is possible to see another cookie of the same name written to a .digitru.st subdomain such as cdn.digitru.st.

Note that the object described here represents the "private" cookie exposed only to platform members via CNAME DNS delegation. It differs in important ways from the "public" cookie and Identity Object which is described in the Integration Guide.

The lifetime of new cookies is expected to be five years including leap years, or at most 1,830 days.

Encoding

The object encoded within this cookie is wrapped in multiple layers for maximum compatibility with web browsers and cookie encoding. It is:

1. JSON encoded
2. Base-64 encoded
3. URL encoded

In javascript, the following code is used to encode the cookie.

encodeURIComponent(btoa(JSON.stringify(object)))

And the following is used to decode.

JSON.parse(atob(decodeURIComponent(value)))

Identity Object

Attributes

Name	Description	Type	Always Provided	Example(s)
id	Unique device identifier	64 bits of crypto-quality random data, base-64 encoded (string)	no	VJ+TjrjhnvU=
version	ID version	integer	yes	2
producer	Member ID responsible for creating this cookie	string	no	1CrsdUNAo6
privacy	Privacy settings	Privacy object	yes	Currently only privacy.optout
privacy.optout	Opt out state	boolean	yes	false

Example

{
 "id":"jyEB2UHSjLo=",
 "version": 2,
 "producer": "1CrsdUNAo6",
 "privacy":
  {
   "optout": false
  }
}

This will take the following value when encoded as the DigiTrust.v1.identity cookie.

eyJpZCI6Imp5RUIyVUhTakxvPSIsInZlcnNpb24iOjIsInByb2R1Y2VyIjoiMUNyc2RVTkFvNiIsInByaXZhY3kiOnsib3B0b3V0IjpmYWxzZX19

ID Values

When produced in the browser the id field is generated with approximately the following code using a WebCrypto API for random data.

var buffer = new Uint8Array(8);
crypto.getRandomValues(buffer);
return arrayBufferToBase64String(buffer);

Note that

• this is intended to provide 64 bits of entropy
• values may exceed Long.MAX_VALUE in java or similar constructs in other languages
• this value should be encrypted at all times outside of the digitru.st cookie space

The canonical representation of this ID is the base-64 encoded string version.

jyEB2UHSjLo=

Other possible representations include

Type	Value
byte array	[-113, 33, 1, -39, 65, -46, -116, -70]
64 bit signed integer	-5004393905660026481
64 bit hex encoded integer	ba8cd241d901218f

All of these may used as internal representations for data storage. However for all purposes of data exchange or other communication such as RTB bid requests, the canonical (string) representation should be used: jyEB2UHSjLo=.

ID Versions

The version field is intended to allow for changes in ID size and encodings. The following versions have seen production usage in some form or another.

• 2: 64 bits of random data, base-64 encoded.

Examples

A minimal (opt out) identity object consists of the following.

{
 "id":null,
 "version":2,
 "privacy": {
  "optout": true
 }
}

Which encodes to the following browser cookie.

eyJpZCI6bnVsbCwidmVyc2lvbiI6MiwicHJpdmFjeSI6eyJvcHRvdXQiOnRydWV9fQ%3D%3D

A more typical identity object includes a non-null id value and false for privacy.optout.

{
 "id": "qCj9pfSbEug=",
 "version": 2,
 "producer": "1CrsdUNAo6",
 "privacy": {
  "optout": false
 }
}

Which is encoded as the following.

eyJpZCI6InFDajlwZlNiRXVnPSIsInZlcnNpb24iOjIsInByb2R1Y2VyIjoiMUNyc2RVTkFvNiIsInByaXZhY3kiOnsib3B0b3V0IjpmYWxzZX19

Guidelines

The following basic guidelines are provided for platforms using CNAME DNS delegation.

1. Please do not set any additional cookies on the .digitru.st top-level domain or on a subdomain.
2. Expect to support https on the .digitru.st subdomain in addition to http.
3. Ensure that deserialization will not break if new attributes are introduced to the Identity Object.
4. Identity cookies should only be created and written to the browser when no existing cookie is present.
5. A high quality source of random data should be used to produce ID values.
6. Platforms will take responsibility to ensure compatibility via a test suite tbd.

Required Use Cases

In order to use a .digitru.st subdomain, platforms will be expected to comply with an automated test suite. This suite covers approximately the following use cases

1. no existing cookie present: a new cookie should be created
2. existing (valid) cookie present: no cookie should be set in the response
3. opt out cookie present: no cookie should be set
4. badly formatted cookie present: a new cookie should be created

This test suite is currently best documented in this set of unit tests.