This specification employs the JSON Web Tokens (JWT) standard, which supports verifiable transmission of data through the use of cryptographic signatures, to assure deletion requests are valid and authentic. Requesters sign JWTs using their private keys to ensure provenance and authenticity, while recipients verify them using public keys hosted on the requester's domain.
Additionally, this specification leverages some of the registered public claims defined in the JWT standard to take advantage of the existing, generally accepted data value definitions and provide consistency across implementations. It also introduces custom private claims designed specifically for the deletion request use case.
-The specification delineates three distinct JWTs: an identity JWT (idJWT), a request JWT (rqJWT), and an acknowledgment JWT (acJWT). Each serves a unique purpose as described below:
+The specification delineates three distinct JWTs: an originating requester JWT (orJWT), a request JWT (rqJWT), and an acknowledgment JWT (acJWT). Each serves a unique purpose as described below:
This model ensures that all recipients can employ the shared idJWT from the request initiator to authenticate its validity. In addition, all recipients will be able to verify the rqJWTs they receive originated with the claimed requester and the acJWT provides requesters and recipients with common proof of a transaction and the success or failure of the communication.
+This model ensures all recipients are able validate and authenticate that the request originated with the claimed 1st party by verifying the orJWT signature using public keys retrieved from the originating domain. In addition, all recipients are able to verify the requests they receive originated with the claimed requester by verifying the rqJWT signature using public keys retrieved from the requester domain. Lastly, recipients are able to provide requesters with proof of the deletion request transaction and the success or failure of its communication with the acJWT signature that can be verified using public keys retrieved from the recipient domain.
For detailed information on JWT implementation, please refer to:
IETF RFC 7519 - JSON Web Tokens (JWT)
@@ -120,38 +125,28 @@
When a deletion request needs to be propagated to downstream recipients, idJWTs are included in the rqJWT to ensure integrity and authenticity of the original request. Each downstream recipient receives the idJWT and verifies its signature before processing the request based on the information within the rqJWT. When a deletion request needs to be propagated to downstream recipients, orJWTs are included in the rqJWT to ensure integrity and authenticity of the original request. Each downstream recipient receives the orJWT and verifies its signature before processing the request based on the information within the rqJWT. To maintain security and transparency throughout the propagation process, it's essential to follow these steps: This approach allows each downstream recipient to verify the authenticity of the original request and assures the integrity of the data deletion process, while adding any necessary additional information to the request before passing it on. Each request needs to be an atomic unit, which can be individually processed by the recipient. The deletion request JWTs will include the following values: A data deletion request is accomplished by sending a POST request to the data deletion request API, which returns a response in JSON format. This protocol is implemented via a standard API and request format with a defined JSON payload as a JWT.
- The following example includes a decoded idJWT to show the header & payload JSON.
+ The following example includes a decoded orJWT to show the header & payload JSON.
When processing requests successfully, servers are expected to respond with an HTTP 202 status code, indicating the request was accepted. In cases where errors occur, servers should respond with an HTTP 400 status code, indicating failure. Additionally, along with the HTTP status code, recipients include a result code in the acJWT response payload raResultCode claim to provide further details about the outcome of the request. In addition to the result code, responses may also contain a string with additional details about the error in the acJWT raResultString claim. When requests are processed successfully, recipients are expected to respond with an HTTP 202 status code indicating the request was accepted. In cases where an error is encountered, recipients should respond with an HTTP 400 status code to indicate the failure. Additionally, recipients should include the defined Result Code of the error encountered in the acJWT response payload raResultCode claim and optionally a string with additional details about the error in the acJWT raResultString claim. For guidelines on error handling, please refer to the following table: *Result code should be set in both rqaResultCode and oraResultCode
+ **Result code only applies to rqJWT Could not connect to the domain listed in Could not find the dsrdelete.json file for the Could not find the jwksUri entry in the dsrdelete.json for the Could not find the keys file: Could not find the key with kid: Request kid: Invalid token timestamp: The timestamp provided in the Relevant error cases: To accomplish this, this specification will use JSON Web Key Sets (JWKS). The JWKS standard (
RFC 7517
- ) establishes a way to store and manage cryptographic keys as a set of JSON objects. JWKS supports asymmetric signature with a public key and private key pair, supporting the discoverability design of the dsrdelete.json file and the signature requirements of the data deletion framework. Note that while RFC 7517 lists the Participants must support key rotation to maintain secure and reliable verification. Implementations should maintain a local cache of each participant's JWKS. Participants must refresh their cached JWKS according to the For more information on JWKS format, please reference the following resources: Participants that only support script based deletion requests, can do so by providing a property vendorScript along with a property vendorScriptRequirement in their dsrdelete.json file. A first party that wants to start the deletion process, will execute the script.
Note: Please note that supporting only script based deletion requests will limit the ability to receive deletion requests where requests are chained via endpoints. An optional discovery method will be available via access to a directory provided by the Tech Lab. The directory would live in the Tech Lab tools portal and provide participants with the location of each dsrdelete.json resource. To create the directory entries, Tech Lab will crawl dsrdelete.json resources and automatically create entries–similar to ads.txt. The results would appear in the Tools Portal and in an API. Participants might use the directory to look up primary domains for companies that operate across multiple domains, validate a vendor has adopted the standard with the established request format, or to simplify a bulk lookup of endpoints from participants. All endpoints can be looked up, but not all endpoints need to be used. An optional discovery method will be available via access to a directory provided by the Tech Lab. The directory is available in the Tech Lab tools portal and provide participants with the location of each dsrdelete.json resource. To create the directory entries, Tech Lab will crawl dsrdelete.json resources and automatically create entries–similar to ads.txt. The results would appear in the Tools Portal and in an API. Participants might use the directory to look up primary domains for companies that operate across multiple domains, validate a vendor has adopted the standard with the established request format, or to simplify a bulk lookup of endpoints from participants. All endpoints can be looked up, but not all endpoints need to be used.
JSON Web Token (JWT) Propagation
-
-
-
Deletion Request Data
+Deletion Request Data
idJWT: Issuer “identifier” JWT
+orJWT: Originating Requester JWT
@@ -242,14 +237,6 @@
" (issuer) claim identifies the principal that issued the JWT. It represents the eTLD+1 of the 1st party and can be used to locate their dsrdelete.json file.
required
-
-
sub
- string
- The "
- sub
- " (subject) claim identifies the principal that is the subject of the JWT. This field contains the identifier type and value of the identifier to which the deletion request applies.
- required
-
iat
NumericDate
@@ -292,9 +279,9 @@
required
-
idJWT
+ orJWT
string
- The 1st party "identifier" JWT or idJWT.
+ The 1st party "originating requester" JWT or orJWT.
required
@@ -316,12 +303,22 @@
required
-
+ sub
- string
- The "
- sub
- " (subject) claim identifies the principal that is the subject of the JWT. This field contains the identifier type and value of the identifier to which the deletion request applies. The value in this field may be the same as the value in the idJWT sub field or may be an intermediary’s alias for the original 1st party identifier.
- required
+ identifierValue
+ string
+ The value of the identifier to which the deletion request applies.
+ required
+
+
+ identifierType
+ string
+ The type of identifier provided in the identifierValue field. The value in this field must match a type specified in the intended recipients' dsrdelete.json file.
+ required
+
+
identifierFormat
+ string
+ The format of the identifier provided in the identifierValue field. The valur in this field must match a format specified in the intended recipients' dsrdelete.json file.
+ required
+ iat
@@ -420,7 +417,7 @@
Example Request with required parameters:
Result Codes
-
@@ -514,31 +509,59 @@
@@ -553,7 +576,10 @@
0
- Successful: Recipient has acknowledged successful receipt of the deletion request.
+ Successful: Recipient has acknowledged successful receipt of the deletion request.
1
- Malformed Request: The deletion request is missing required fields, leading to a malformed request.
+ Hosted JSON error:
+
rqJWT/orJWT iss claim: {rqJWT/orJWT iss}.rqJWT/orJWT issuer: {rqJT/orJWT iss}.rqJWT/orJWT issuer: {rqJT/orJWT iss}.{rq/or dsrdelete.json jwksUri} identified in the jwksUri entry in the dsrdelete.json for the rqJWT/orJWT issuer: {rqJT/orJWT iss}.{rqJT/orJWT kid} in keys file identified: {rq/or dsrdelete.json jwksUri} identified in the jwksUri entry in the dsrdelete.json for the rqJWT/orJWT issuer: {rqJT/orJWT iss}.{rqJT/orJWT kid} alg claim: {rqJT/orJWT alg} does not match the alg claim: {key file alg} in the keys file: {rq/or dsrdelete.json jwksUri} for the kid.
2
- Invalid Signature: The signature provided in the JWT token is invalid, indicating possible issues with key or algorithm.
+ Invalid token: The
rqJWT/orJWT could not be successfully decoded and parsed due to a structural invalidity. JSON token identifier: {rqJT/orJWT jti}
3
- Invalid JWT Token: The JWT token provided is structurally or cryptographically invalid.
+ Invalid token signature: The signature provided in the
rqJWT/orJWT is invalid, indicating possible issues with the key or algorithm. JSON token identifier: {rqJT/orJWT jti}
4
- Unsupported Identifier Type: The identifier type in the deletion request isn't supported by the recipient's configuration.
+ Malformed token: The
rqJWT/orJWT is missing required claims, leading to a malformed request. Missing field detected: {rqJT/orJWT field}
5
- Incorrect Identifier Format: The identifier in the deletion request doesn't match the expected format.
+ rqJWT/orJWT is invalid: {rqJT/orJWT timestamp}. The timestamp is {relevant error case}.
+
+
-
+ 6
- Invalid Timestamp: Indicates that the timestamp provided in the JWT is invalid or expired.
+ 6*
+ Non-sequential token timestamp: The timestamp of
+ rqJWT: {rqJWT timestamp} precedes the timestamp of orJWT: {orJWT timestamp}
+
+ 7**
+ Unsupported identifier type: The identifier type in the
+ rqJWT: {rqJT identifierType} isn't supported.
+
+ 8**
+ Unsupported identifier format: The identifier format in the
+ rqJWT {rqJT identifierFormat} isn’t supported.
+
+ 9**
+ Incorrect identifier format: The identifier format in the
+ rqJWT: {rqJT identifierFormat} does not match the format of the received rqJWT‘s identifierValue.
+
10**
+ Invalid identifier value: The identifier value in the
rqJWT is invalid (e.g. incorrect length).Cryptographic Keys
dsrdelete.json file and the signature requirements of the data deletion framework.
+ "alg" and the "kid" parameters as optional, they are required in the context of this framework. Key Rotation and Caching
+pollFrequency. When verifying a signed request, if a referenced key ID (kid) cannot be found in the cached key set, the participant must fetch a new copy of the requester's JWKS from the jwksUri location and update its cache accordingly.JWKS Resources
@@ -599,6 +625,12 @@
string
API endpoint for deletion requests.
Required
+
+
pollFrequency
+ number
+ Polling frequency, in seconds
+ Required
identifiers
@@ -607,11 +639,17 @@
Required
-
+ publicKey
- Array of object
- Key format follows the IETF JSON Web Keys (JWK) Standard https://datatracker.ietf.org/doc/html/rfc7517 - reference the standard for key format.
+ jwksUri
+ string
+ Location of the JSON Web Key Set (JWKS) endpoint which contains the JWKS used to sign all issued JSON Web Tokens (JWTs).
Required
+
publishedJwksUri
+ string
+ Location of the endpoint which contains prior JWK sets that include previously active signing keys, to facilitate signature verification of tokens issued before key rotation.
+ Optional
+
+ vendorScriptRequirement
boolean
@@ -624,38 +662,77 @@
Optional field for vendors to publish a HTML code (e.g. a <script>) if this is needed to gather an identifier for a deletion request.
Optional
+
+ dsrdeleteJsonUri
+ string
+ Optional field for partners with multiple domains who only wish for one to host the complete file.
+ Optional
+
+
optionalParameters
+ Array of objects
+ Optional field for implementers to add custom, optional fields
+ Optional
+ Example Resource for dsrdelete.json:
+Example Resource for example.com/.well-known/iabtl/dsrdelete.json:
```
https://www.publisher1.com/dsrdelete.json
{
"endpoint": "https://www.publisher1.com/api/delete/",
+ "pollFrequency": "259200", // 30 days
"identifiers": [
{ "id": 1, "type": "email", "format": "sha256" },
{ "id": 2, "type": "idfa", "format": "hash" }
],
- "publicKey": [
+ "jwksUri": "https://example.com/.well-known/iabtl/jwks.json",
+ "vendorScriptRequirement": true,
+ "vendorScript": ""
+}
+```
+
+Example Resource for example.com/.well-known/iabtl/jwks.json
+
+```
+{
+ "pollFrequency": "604800", // 7 days
+ "keys": [
{
"kty": "EC",
+ "alg": "ES256",
+ "crv": "P-256",
+ "x": "8PdtOAYA6bYKVDWZ16kzAlQkS9JEZakZ3rmXbzIl0nk",
+ "y": "D2qikPEHzo6Q9qLghINZ5nO8u8zjcRNbZnbW7M6pJr0",
+ "kid": "unique_identifier_for_1st_key"
+
+ },
+ {
+ "kty": "EC",
+ "alg": "ES256",
"crv": "P-256",
- "x": "f83OJ3D2xF1Bg8vub9tLe1gHMzV76e8Tus9uPHvRVEU",
- "y": "x_FEzRu9m36HLN_tue659LNpXW6pCyStikYjKIWI5a0",
- "kid": "Public key used in JWS spec Appendix A.3 example"
+ "x": "RyIDwX4y7tkctGt65W0WaslpQ9j9AnHcUiKhsKrcMWw",
+ "y": "kRbxhHFRLjd75Xa3Ds_U196o4lBHWkhyq-YKoCQPAfU",
+ "kid": "unique_identifier_for_2nd_key"
+ },
+ {
+ "kty": "EC",
+ "alg": "ES256",
+ "crv": "P-256",
+ "x": "SLvexvatx17wweJkO4GwhOKaa_Z7DViYarzpLIAl3dE",
+ "y": "SgP1HvjKhhqQ8nqpAKTD_WBq6EcBt40jRsbbXRfjU7E",
+ "kid": "unique_identifier_for_3rd_key"
}
- ],
- "vendorScriptRequirement": true,
- "vendorScript": ""
+ ]
}
```
-
Implementing Script-based deletion requests
Directory
-