A privacy-enhancing protocol and browser extension.
Once a user is in possession of tokens issued by the new Privacy Pass redemption server, any bearer of a token can redeem it through the provided redemption API. This document describes how to use a JSON-RPC endpoint for this purpose.
When a user submits a token for redemption, the server will verify whether the token and its associated data (bindings) are cryptographically valid. If so, the server will mark this token as spent and will return a sucessful response. Otherwise, the server wll return a response indicating the possible cause of the error.
POST https://privacypass.cloudflare.com/api/redeem
The endpoint supports one method called redeem
that receives as input parameter an object with the following structure:
t
, which is an octet string.HMAC(sk,R)
, where sk
is a shared secret previously agreed between client and server, and R
is the associated information (or bindings).{
"curve": "p256",
"hash": "sha256",
"method": "increment"
}
R
in the PrivacyPass protocol.false
.The following snippet shows how it looks a well-formatted object for redemption.
File: request.json
{
"jsonrpc": "2.0",
"method": "redeem",
"params": {
"data": [
"IE/CRo8sBGWRlDDwNJwWAzPryRJ7UlOTrHJdPh3GQxQ=",
"dYErmr5VLa9A4XPlj1wz2wD31h20VHKIJgz2BKv2cow=",
"eyJjdXJ2ZSI6InAyNTYiLCJoYXNoIjoic2hhMjU2IiwibWV0aG9kIjoiaW5jcmVtZW50In0="
],
"bindings": [
"q7r8rfqhodjkc4bcufs1s",
"zo3zzmvq77m3qwch82dytj"
],
"compressed": false
},
"id": 1
}
This curl
transfer shows how to use the redemption API with the previous request object stored in request.json
file.
$ curl -X POST https://privacypass.cloudflare.com/api/redeem \
-H "Content-Type: application/json" \
--data @request.json
A successful redemption is completed with a HTTP 200 status and a JSON response:
{
"jsonrpc": "2.0",
"id": 1,
"result": "success"
}
Every subsequent request with the same token will be detected as an intent of double-spending. This situation is alerted with a HTTP-403 status and with the following error response.
{
"jsonrpc": "2.0",
"id": 1,
"error": {
"message": "Redemption for token that has already been spent",
"code": -32021
}
}
Several other situations can cause error responses. The following codes are used to indicate the possible source that produced the error.
Error code | HTTP Status | Description |
---|---|---|
-32020 | 403 | When attempting to verify data, often token verification fails the specified HMAC check. |
-32021 | 403 | The request is attempting to redeem a token that was already spent. |
-32022 | 400 | Unsupported elliptic curve settings. Currently, it is supported only the NIST P-256 curve, and the SHA-256 hash function. |
-32040 | 400 | Requesting the RPC method issue . |
-32041 | 405 | Connecting to the endpoint using a method different than POST. |
-32600 | 400 | The JSON-RPC request is invalid. |
-32601 | 400 | Requesting a non-supported RPC method. |
-32602 | 400 | Indicates that the parameter object has an invalid structure. |
-32603 | 500 | Internal server error. |
-32700 | 400 | Failed to parse the JSON request. |
Last Update: October 28, 2019.