Skip to content

Latest commit

 

History

History
109 lines (87 loc) · 3.87 KB

README.md

File metadata and controls

109 lines (87 loc) · 3.87 KB
Raw

Redemption API

Description

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.

Redemption Endpoint

 POST  https://privacypass.cloudflare.com/api/redeem

Request Object

The endpoint supports one method called redeem that receives as input parameter an object with the following structure:

  • "data" : (required) an array of three base64-encoded values.
    1. A token t, which is an octet string.
    2. A tag generated as HMAC(sk,R), where sk is a shared secret previously agreed between client and server, and R is the associated information (or bindings).
    3. A base64-encoded JSON object, indicating an elliptic curve, a hash function, and a hash-to curve function. Example:
    {
    "curve": "p256",
    "hash": "sha256",
    "method": "increment"
}
  • "bindings" : (required) an array of associated strings, denoted by R in the PrivacyPass protocol.
  • "compressed" : (optional) a boolean value indicating whether the elliptic curve points are compressed. Default is false.

Example

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
}

Submitting a Request

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

Error codes

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.