diff --git a/Data Deletion Request Framework.md b/Data Deletion Request Framework.md index 61693cf..3e30a39 100644 --- a/Data Deletion Request Framework.md +++ b/Data Deletion Request Framework.md @@ -14,6 +14,11 @@ Comments +April 2026 +2.0 +Version 2.0 released + + May 2024 1.0 Version 1.0 released @@ -94,18 +99,18 @@

JSON Web Token (JWT) Implementation

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:

  1. - Identity JWT (idJWT): Generated by the 1st party, this idJWT includes the 1st party version of the ID to be deleted along with additional information used to authenticate the origin of the deletion request. The intent is to provide verifiable communication from the originating party that can be provided with tamper protection to all other participants.
    2. + Originating Requester JWT (orJWT): the orJWT is generated by the 1st party and includes information used to identify the origin of the deletion request. It's purpose is to provide, through a cryptograph signature, a verifiable proof that the request was generated by the originating party and hasn't been tampered with.
  2. Request JWT (rqJWT): - The rqJWT includes the idJWT as a claim, along with additional information for a discrete deletion request transaction between a requester and recipient. For each vendor requiring communication of a deletion request, the 1st party generates a distinct rqJWT. If a vendor needs to communicate the request to vendors they work with, they generate an additional rqJWT for each which includes a copy of the idJWT they received. 
    3. + The rqJWT includes the orJWT as a claim along with the identifier to which the deletion request applies and additional information needed to validate, authenticate and track the request. The originating 1st party will generate an rqJWT for each vendor they communicate a deletion request to. If vendors need to communicate the requests to partners they work with, they will generate an new rqJWT for each partner which includes a copy of the orJWT they received along with their identifier for the deletion request, which may be different from the identifier they received. 
  3. Acknowledgement JWT (acJWT): Generated by a recipient and returned to a requester. The acJWT includes the rqJWT alongside acknowledgement information, including success or an error status.
-

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 @@

  1. - *Data Subject - requests a data deletion from a 1st Party*
    2. + *Data Subject requests a data deletion from a 1st Party*
    1. 1st Party validates the request.
    2. 1st Party determines what identifiers are subject to the request.
    3. 1st Party determines partners that data has been shared with which the request must be communicated to.
    4. 1st party accesses the dsrdelete.json resource of each identified partner to determine how IDs must be formatted for them. 
      5. -
    5. 1st party generates an initial idJWT for each identifier that is subject to the request.
      6. +
    6. 1st party generates an orJWT for the request.
  2. - Requester - generates a deletion packet formatted as an rqJWT which includes the idJWT created in step 1.e., as well as the other values described under - - Request Data - + Requester generates a deletion packet formatted as a rqJWT which includes the orJWT created in step 1.5, as well as the other values described under Request Data below.
  3. - Requester - sends the rqJWT to the Recipient.
    4. + Requester sends the rqJWT to the Recipient.
  4. - Recipient - receives the rqJWT and verifies the signatures of the idJWT and rqJWT using public keys published on the 1st party and requester’s respective domains. 
    5. + Recipient receives the rqJWT and verifies the signatures of the orJWT and rqJWT using public keys published on the 1st party and requester’s respective domains. 
  5. - Recipient - acknowledges receipt to the requester with an acJWT. The acJWT includes the original rqJWT and additional acknowledgement values described under Recipient Acknowledgement, including a result code indicating successful receipt of the request or an error.
    6. + Recipient acknowledges receipt to the requester with an acJWT. The acJWT includes the original rqJWT and additional acknowledgement values described under Recipient Acknowledgement, including a result code indicating successful receipt of the request or an error.
  6. - Requester - verifies the signatures of the acJWT and the embedded rqJWT returned by the Recipient using a public key published on the Recipient’s domain and their own public key.
    7. + Requester verifies the signatures of the acJWT and the embedded rqJWT returned by the Recipient using a public key published on the Recipient’s domain and their own public key.
  7. - *Requester - logs the Recipient Acknowledgement acJWT.*
    8. + *Requester logs the Recipient Acknowledgement acJWT.*
  8. *Recipient logs the request rqJWT.*
    9. @@ -161,7 +156,7 @@
    1. Determining what partners the request must be forwarded to.
    2. Accessing the dsrdelete.json resource for each partner to determine how IDs must be formatted for them. 
      3. -
    3. Generating rqJWTs to be sent to partners using the original identifier idJWT they received and by following steps 2 through 8 above.  
      4. +
    4. Generating rqJWTs to be sent to partners using the original orJWT they received and by following steps 2 through 8 above.  
  9. *Recipient, in a separate flow, executes the data deletion.*
    10. @@ -172,27 +167,27 @@
  10. Step 1 and Steps 7-10.

    11. JSON Web Token (JWT) Propagation

    -

    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:

    1. - Inclusion of Original idJWT: The original idJWT, generated by the initial requester (1st Party), is included in each request to each downstream recipient.
      2. + Inclusion of orJWT: The orJWT, generated by the initial requester (1st Party), is included in each request to each downstream recipient.
    2. Verification and Processing: 
        3. -
      1. Upon receiving the rqJWT, each recipient verifies the signature of the embedded idJWT using the public key published on the domain of the initial requester. This ensures that the request originated from a trusted source at the time indicated and has not been tampered with during transmission. 
        2. +
      2. Upon receiving the rqJWT, each recipient verifies the signature of the embedded orJWT using the public key published on the domain of the 1st party from which the initial request was made. This ensures that the request originated from the claimed source at the time indicated and has not been tampered with during transmission.  
      3. Additionally, the recipient verifies the signature of the rqJWT, which may have been generated by the 1st party or an intermediary. Once the signatures are verified, the recipient processes the request based on the information contained within the rqJWT.
    3. Generation of New rqJWT: 
        4. -
      1. Should a downstream recipient need to further propagate a request, they generate a new rqJWT which includes the idJWT they received as well as any additional information specific to their relationship with the downstream recipient. 
        2. +
      2. Should a downstream recipient need to further propagate a request, they generate a new rqJWT which includes the orJWT they received as well as any additional information specific to their relationship with the downstream recipient. 

    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.

    -

    Deletion Request Data

    +

    Deletion Request Data

    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:

    -
    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. - - - - - - @@ -292,9 +279,9 @@ - + - + @@ -316,12 +303,22 @@ - - - - + + + + + + + + + + + + + + + + @@ -420,7 +417,7 @@

    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. 

    Example Request with required parameters:

    - 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.

    ``` @@ -431,14 +428,9 @@ } . { - "version": "1.0", + "version": "2.0", "jti": "unique_jwt_identifier", "iss": "publisher1.com", - "sub": { - "identifierValue": "28f6dc889e...fe167", - "identifierType": "email", - "identifierFormat": "sha256" - }, "iat": 1693459424 } ``` @@ -457,14 +449,13 @@ } . { - "version": "1.0", - "idJWT": "original_jwt_information", + "version": "2.0", + "orJWT": "base64url_header.base64url_payload.base64url_signature", "jti": "unique_jwt_identifier", "iss": "vendor1.com", - "sub": { - "identifierValue": "28f6dc889e...fe167", - "identifierType": "email", - "identifierFormat": "sha256" + "identifierValue": "28f6dc889e...fe167", + "identifierType": "email", + "identifierFormat": "sha256" }, "iat": 1693459424, "optionalParameters": {optional_parameters_information} @@ -484,64 +475,166 @@ } . { - "version": "1.0", + "version": "2.0", "rqJWT": "original_jwt_information", "jti": "6G7H8J", "iss": "vendor2.com", "iat": 1693459424, - "raResultCode": 4, - "raResultString": "Unsupported identifier type: phone" + "raResultCode": 14201, + "raResultString": "rq_unsupported_identifier_type" } ```

    Result Codes

    -

    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:

    required
    substringThe " - 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 NumericDaterequired
    idJWTorJWT stringThe 1st party "identifier" JWT or idJWT.The 1st party "originating requester" JWT or orJWT. required
    required
    substringThe " - 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.requiredidentifierValuestringThe value of the identifier to which the deletion request applies.required
    identifierTypestringThe 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
    identifierFormatstringThe format of the identifier provided in the identifierValue field. The value in this field must match a format specified in the intended recipients' dsrdelete.json file.required
    iat
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    - - Result Code - - - - Description - -
    0Successful: Recipient has acknowledged successful receipt of the deletion request.
    1Malformed Request: The deletion request is missing required fields, leading to a malformed request.
    2Invalid Signature: The signature provided in the JWT token is invalid, indicating possible issues with key or algorithm.
    3Invalid JWT Token: The JWT token provided is structurally or cryptographically invalid.
    4Unsupported Identifier Type: The identifier type in the deletion request isn't supported by the recipient's configuration.
    5Incorrect Identifier Format: The identifier in the deletion request doesn't match the expected format.
    6Invalid Timestamp: Indicates that the timestamp provided in the JWT is invalid or expired.
    + + + Result Code + Result String + Description + + + + + 10000 + success + Successful: Recipient has acknowledged successful receipt of the deletion request. + + + 10010 + unknown_error + Unknown error: An unexpected error occurred that does not correspond to any defined error condition. + + + 11101 + or_domain_connection_failed + Could not connect to the domain listed in the orJWT iss claim: {orJWT iss}. + + + 11102 + or_dsrdelete_file_not_found + Could not find the dsrdelete.json file for the orJWT issuer: {orJWT iss}. + + + 11103 + or_jwksuri_not_found + Could not find jwksUri entry in the dsrdelete.json for the orJWT issuer: {orJWT iss}. + + + 11104 + or_jwks_keys_file_not_found + Could not find keys file: {or dsrdelete.json jwksUri} identified in the jwksUri entry in the dsrdelete.json in the orJWT issuer: {orJWT iss}. + + + 11105 + or_jwks_kid_not_found + Could not find the key with kid: {or kid} in keys file identified: {or dsrdelete.json jwksUri} identified in the jwksUri entry in the dsrdelete.json for the orJWT issuer: {orJWT iss}. + + + 11201 + rq_domain_connection_failed + Could not connect to the domain listed in rqJWT iss claim: {rqJWT iss}. + + + 11202 + rq_dsrdelete_file_not_found + Could not find the dsrdelete.json file for the rqJWT issuer: {rqJWT iss}. + + + 11203 + rq_jwksuri_not_found + Could not find jwksUri entry in the dsrdelete.json for the rqJWT issuer: {rqJWT iss}. + + + 11204 + rq_jwks_keys_file_not_found + Could not find keys file: {rq dsrdelete.json jwksUri} identified in the jwksUri entry in the dsrdelete.json in the rqJWT issuer: {rqJWT iss}. + + + 11205 + rq_jwks_kid_not_found + Could not find the key with kid: {rq kid} in keys file identified: {rq dsrdelete.json jwksUri} identified in the jwksUri entry in the dsrdelete.json for the rqJWT issuer: {rqJWT iss}. + + + 12101 + or_alg_claim_mismatch + Request kid: {orJWT kid} alg claim: {orJWT alg} does not match the alg claim: {key file alg} in the keys file: {or dsrdelete.json jwksUri} for the kid. + + + 12201 + rq_alg_claim_mismatch + Request kid: {rqJWT kid} alg claim: {rqJWT alg} does not match the alg claim: {key file alg} in the keys file: {rq dsrdelete.json jwksUri} for the kid. + + + 13101 + or_invalid_token + Invalid token: The orJWT could not be successfully decoded. JSON token identifier: {orJWT jti}. + + + 13102 + or_invalid_token_signature + Invalid token signature: The signature provided in the orJWT is invalid. JSON token identifier: {orJWT jti}. + + + 13103 + or_invalid_token_timestamp + Invalid token timestamp: The timestamp provided in the orJWT is invalid: {orJWT timestamp}. The timestamp is a value which is not a positive integer. + + + 13104 + or_invalid_token_timestamp + Invalid token timestamp: The timestamp provided in the orJWT is invalid: {orJWT timestamp}. The timestamp is too far in the future: issued more than 5 minutes ahead of the token receipt. + + + 13201 + rq_invalid_token + Invalid token: The rqJWT could not be successfully decoded. JSON token identifier: {rqJWT jti}. + + + 13202 + rq_invalid_token_signature + Invalid token signature: The signature provided in the rqJWT is invalid. JSON token identifier: {rqJWT jti}. + + + 13203 + rq_invalid_token_timestamp + Invalid token timestamp: The timestamp provided in the rqJWT is invalid: {rqJWT timestamp}. The timestamp is a value which is not a positive integer. + + + 13204 + rq_invalid_token_timestamp_future + Invalid token timestamp: The timestamp provided in the rqJWT is invalid: {rqJWT timestamp}. The timestamp is too far in the future: issued more than 5 minutes ahead of the token receipt. + + + 13205 + rq_invalid_timestamp_sequence + Invalid timestamp sequence: The timestamp of rqJWT: {rqJWT timestamp} precedes the timestamp of orJWT: {orJWT timestamp}. + + + 14201 + rq_unsupported_identifier_type + Unsupported identifier type: The identifier type in the rqJWT: {rqJWT identifierType} isn't supported. + + + 14202 + rq_unsupported_identifier_format + Unsupported identifier format: The identifier format in the rqJWT {rqJWT identifierFormat} isn't supported. + + + 14203 + rq_incorrect_identifier_format + Incorrect identifier format: The identifier format in the rqJWT: {rqJT identifierFormat} does not match the format of the received rqJWT's identifierValue. + + + 14204 + rq_invalid_identifier_value + Invalid identifier value: The identifier value in the rqJWT is invalid (e.g. incorrect length). + + +

    Identifiers

    There are generally two classes of identifiers used in ad-interactions distinguished by access limitations: those which are directly accessible by 1st-parties and those which are only accessible to 3rd parties. The first class includes any identifiers available in the 1st-party context, including on web pages and 1st-party local storage. The second class includes identifiers maintained in protected 3rd-party storage, such as 3rd-party cookies. Probabilistic identifiers, which are based on constellations of data values, presumably may fall into the first, second or a combination of both classes, depending on how they are constructed.

    @@ -553,7 +646,10 @@
    Cryptographic Keys

    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.

    + ) 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 "alg" and the "kid" parameters as optional, they are required in the context of this framework to ensure all participants can easily locate verification keys.

    +
    Key Rotation and Caching
    +

    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 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

    For more information on JWKS format, please reference the following resources: