-
Notifications
You must be signed in to change notification settings - Fork 11
Cookies for Platforms
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.
The object encoded within this cookie is wrapped in multiple layers for maximum compatibility with web browsers and cookie encoding. It is:
- JSON encoded
- Base-64 encoded
- 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)))
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 |
{
"id":"jyEB2UHSjLo=",
"version": 2,
"producer": "1CrsdUNAo6",
"privacy":
{
"optout": false
}
}
This will take the following value when encoded as the DigiTrust.v1.identity
cookie.
eyJpZCI6Imp5RUIyVUhTakxvPSIsInZlcnNpb24iOjIsInByb2R1Y2VyIjoiMUNyc2RVTkFvNiIsInByaXZhY3kiOnsib3B0b3V0IjpmYWxzZX19
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=
.
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.
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
The following basic guidelines are provided for platforms using CNAME DNS delegation.
- Please do not set any additional cookies on the .digitru.st top-level domain or on a subdomain.
- Expect to support https on the .digitru.st subdomain in addition to http.
- Ensure that deserialization will not break if new attributes are introduced to the Identity Object.
- Identity cookies should only be created and written to the browser when no existing cookie is present.
- A high quality source of random data should be used to produce ID values.
- Platforms will take responsibility to ensure compatibility via a test suite tbd.
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
- no existing cookie present: a new cookie should be created
- existing (valid) cookie present: no cookie should be set in the response
- opt out cookie present: no cookie should be set
- badly formatted cookie present: a new cookie should be created
This test suite is currently best documented in this set of unit tests.