diff --git a/PVT-Registration.md b/PVT-Registration.md new file mode 100644 index 0000000..70f5fd0 --- /dev/null +++ b/PVT-Registration.md @@ -0,0 +1,45 @@ +# Private Verification Tokens Issuer Registration + +This readme describes the process of how origins (websites) can register as +issuers of Private Verification Tokens (PVTs). Registration is +required for any page that wishes to use PVTs. To apply to become an issuer the +issuer website’s operator must open a new issue on this repository using the +“New PVT Issuer” template which specifies: + +* Organization/Company Name: The entity operating the origin. +* Contact Email: An email address for the PVT team to communicate regarding the registration. +* Key Commitment URL: The full URL for the key commitment endpoint. +* Batch Size: Chrome will create token requests in batch using the batch size + specified. +* Expiry: Timestamp when the registration expires. In seconds since the unix + epoch. +* Intended Use Case: A clear description of how PVTs will be used on the + registered origin (e.g., "To reduce captchas and friction for users navigating + to the page by verifying humanness"). +* Acknowledgement: Confirmation that the origin understands and will adhere to PVT policies, + including not using PVTs for user tracking or cross-site correlation. + +Key commitment endpoint requirements are documented at +[Key Commitment Endpoint Requirements](https://github.com/GoogleChrome/private-tokens/blob/mainbug/README.md#key-commitment-endpoint-requirements) section. + +Once the response from key commitment endpoint has been verified (to make sure +that the endpoint responds with an appropriate JSON dictionary), it will be +merged into this repository and Chrome server-side infrastructure will begin +fetching those keys roughly at an hourly rate and eventually distributing those +keys to Chrome instances. Key commitments are only allowed to change every 60 +days, and any rotation faster than that will be ignored. + +Request Template: + +Organization/Company Name: {CompanyName} +Contact Email: {Email} +Key Commitment URL: {KeyCommitmentURL} +Batch Size: {BatchSize} +Expiry: {ExpiryInSecondsSinceUnixEpoch} +Intended Use Case: {UseCaseDescription} +Acknowledgement: + +By registering as an issuer, you acknowledge the following: +* I understand the technical restrictions on key rotation frequency of 60 days. +* I understand that my issuer registration will be valid for a period of six months after the key commitment is accepted, and that I will need to re-register in this repository following that six-month period. +* I understand that in the future renewing my registration may have additional requirements, to reduce the risk of abuse. diff --git a/README.md b/README.md index 8498017..758ab44 100644 --- a/README.md +++ b/README.md @@ -9,3 +9,59 @@ The supported APIs and the process for registering are listed below: For instructions on how to register a Private State Token issuer, please read [Private State Tokens Issuer Registration](https://github.com/GoogleChrome/private-tokens/blob/main/PST-Registration.md). For clarity on the Private State Token API, please read the [Private State Tokens explainer](https://github.com/WICG/trust-token-api/). + +## Private Verification Tokens + +PVTs work for the registered origins. Registration process is explained in +[PVT-Registration.md](https://github.com/GoogleChrome/private-tokens/blob/main/PVT-Registration.md). + +### Key Commtiment Endpoint Requirements + +Issuers specify a key commitment endpoint during registration. The key commitment +endpoint must return a response in the following form. + +``` +HTTP/1.1 200 OK +Content-Type: application/json +Content-Length: + + +``` + +where response is a [JSON object](https://datatracker.ietf.org/doc/html/rfc7159#section-4) +with the following name/value pairs. + +* Name `domain`, value [string](https://datatracker.ietf.org/doc/html/rfc7159#section-7). + The string must be a registrable domain of the `issuer_origin`. +* Name `issuer_origin`, value string. The value must be a valid URL. The URL must have https + scheme. The URL must have same registrable domain (eTLD+1) as the one specified in `domain`. +* Name `version`, value must be an integer. Indicates the PVT version. The value must fit + int32. The browser will ignore if the version is not supported. +* Name `public_key`, value base64 encoding of the public key. Public key is parsed based on + the crypto parameters deduced from the value of the `version`. +* Name `key_id`, value integer. Key id must fit into uint8. Key id will be used in token + requests as specified in the privacy pass specs. +* Name `expiration`, value *string*. Expiration must fit into int64. Expiration is + in number of seconds since the unix epoch. The browser will stop using the `public_key` past + expiration date. +* Name `batch_size`, value integer. Browser will send token requests in batches. Each + HTTP request to issuance endpoint will contain `batch_size` many individual + [TokenRequest](https://github.com/cathieyun/draft-athm/blob/main/draft-yun-privacypass-athm.md#client-to-issuer-request). +* Name `redeemer_origins`, value [array](https://datatracker.ietf.org/doc/html/rfc7159#section-5) + of strings. Strings must be valid web origins. The scheme must be https. + +For an example see the demo key commitment endpoint +[https://privatetokens.dev/.well-known/private-verification-token/key-commitment](https://privatetokens.dev/.well-known/private-verification-token/key-commitment), which returns (on June 8th 2026) + +``` +{ +"domain": "privatetokens.dev", +"issuer_origin": "https://pvtissuer.privatetokens.dev", +"version": 1, +"public_key": "AyuAAk7oGNcJGWeAqEr/4IeJ9XFSn8zBrM4H7qLfL8ZfA19qbrhL6pwTYRFUar2GQ8R8O0PlPp56h5a6G5JNCU4Dt/Ft8K2Cy9i9agTtQnEHrdWj1LqEDps0Gju6wdm3/hk=", +"key_id": 3, +"expiration": "184368811", +"batch_size": 10, +"redeemer_origins": ["https://privatetokens.dev"] +} +```