Permalink
Find file
d4ee092 Oct 21, 2016
@gdbelvin @cesarghali
147 lines (126 sloc) 4.03 KB

Key Transparency HTTP APIs

Introduction

This document describes the Key Transparency Server HTTP APIs. The core gRPC APIs are exposed over HTTP via a gRPC reverse proxy.

Index

PathMethodSummary
`/v1/users/{user_id}`GETGetEntry returns a user's entry in the Merkle Tree.
`/v1/users/{user_id}`PUTUpdateEntry submits a SignedEntryUpdate.
`/v1/users/{user_id}/history`GETListEntryHistory returns a list of historic GetEntry values.

GET /v1/users/{user_id}

Returns a user's set of public keys, along with various cryptographic proofs.

curl https://<host>/v1/users/user_id

Parameters

ParameterRequiredTypeDescription
user_idStringEmail address

Response

Empty proof for an entry that is not found:

{
  "vrf": "BMOmWsO0Bwj9Tk9l8czqH2jFYrmXGwM/gbHQIDXq3xaOoqrrZO7Z6R9pYONsj2nEHxckyHIH1o9mZXADatMelr4=",
  "vrf_proof": "lnDRwW6BCyv8K5AnbsTT9t50+x+WcyDigMGIuqplgAS1xQeJ9HvEm7ZRDEcCUGublzv2nu7cdwLyD51ePRTzjA==",
  "committed": {
    "key": "B4IhW09t4bYTkQZF1p7Rvw==",
    "data": "CgwKBGFwcDISBHRlc3QKDAoEYXBwMRIEdGVzdA=="
  },
  "leaf_proof": {
    "leaf_data": "CiD3g7UGE7qOyTPGnLsw9SmwCWMPzjPz65G0vv4cfVw99w==",
    "neighbors": ["", "/* 256 items */", ""]
  },
  "smh": {
    "map_head": {
      "realm": "example.com",
      "epoch": "7573",
      "root": "3MQ3sfHl1wT6iCuVvRHFRqTN587J9Npr8rz4OzyB/iE=",
      "issue_time": "2016-09-01T21:06:09.515380163Z"
    },
    "signatures": {
      "61153815": {
        "hash_algorithm": "SHA256",
        "sig_algorithm": "ECDSA",
        "signature": "MEYCIQDDIAu0UgMFTCsCqvWA15uHzc43VBYa7sRMvmxDLRiS0AIhAPiWCDBLdJFiGmkUAlyqPWgMVobONB5a25xLQSSWZaGb"
      }
    }
  },
  "smh_sct": "AN8cLsEVAJRSR6lhaDJd3Fx5Wej3xtOI/AAuC70/dNdkAAABVueQO4sAAAQDAEYwRAIgI2teJpbbjXb8Xld8Jn3jy5yu4WYY6ddeB+vGsg1eqHkCIBRqnXEq8Owg1rVUGxb3Q52UZ2y6DxQ9HJ+ZYTAQW8RQ"
}

Proof for an entry that exists:

TODO

PUT /v1/users/{user_id}

curl
-X POST
-H "Authorization: OAuth <ACCESS_TOKEN>"
https://<host>/v1/users/user_id
-d "<json below>"

Request

{
  "entry_update": {
    "update": {
      "// serialized(KeyValue{email: serialized(Entry{ commitment }})"
      "key_value": "CiAhWorzTMne08bTtf9tfha0ouSWD7hb2z8GLNwwyXVgyBIiCiAnVXbqdmof99bSQH5jieVmdAd8Ooss0gL8OPwF6DBb5A==",
      "previous": "SJT3BgccSMEbSR0ZqjLHYhcXe+P04S00g1Kmktj4z8I="
    },
    "committed": {
      "key": "BtVQb1P7Em+lTUKEH3c5lw==",
      "data": "CgwKBGFwcDESBHRlc3QKDAoEYXBwMhIEdGVzdA=="
    }
  }
}

Response

{
  "vrf": "BMOmWsO0Bwj9Tk9l8czqH2jFYrmXGwM/gbHQIDXq3xaOoqrrZO7Z6R9pYONsj2nEHxckyHIH1o9mZXADatMelr4=",
  "vrf_proof": "lnDRwW6BCyv8K5AnbsTT9t50+x+WcyDigMGIuqplgAS1xQeJ9HvEm7ZRDEcCUGublzv2nu7cdwLyD51ePRTzjA==",
  "committed": {
    "key": "B4IhW09t4bYTkQZF1p7Rvw==",
    "data": "CgwKBGFwcDISBHRlc3QKDAoEYXBwMRIEdGVzdA=="
  },
  "leaf_proof": {
    "leaf_data": "CiD3g7UGE7qOyTPGnLsw9SmwCWMPzjPz65G0vv4cfVw99w==",
    "neighbors": ["", "/* 256 items */", ""]
  },
  "smh": {
    "map_head": {
      "realm": "example.com",
      "epoch": "7573",
      "root": "3MQ3sfHl1wT6iCuVvRHFRqTN587J9Npr8rz4OzyB/iE=",
      "issue_time": "2016-09-01T21:06:09.515380163Z"
    },
    "signatures": {
      "61153815": {
        "hash_algorithm": "SHA256",
        "sig_algorithm": "ECDSA",
        "signature": "MEYCIQDDIAu0UgMFTCsCqvWA15uHzc43VBYa7sRMvmxDLRiS0AIhAPiWCDBLdJFiGmkUAlyqPWgMVobONB5a25xLQSSWZaGb"
      }
    }
  },
  "smh_sct": "AN8cLsEVAJRSR6lhaDJd3Fx5Wej3xtOI/AAuC70/dNdkAAABVueQO4sAAAQDAEYwRAIgI2teJpbbjXb8Xld8Jn3jy5yu4WYY6ddeB+vGsg1eqHkCIBRqnXEq8Owg1rVUGxb3Q52UZ2y6DxQ9HJ+ZYTAQW8RQ"
}

GET /v1/user/{user_id}/history

Request

{
  "start": "5030",
  "page_size": 1
}

Response

{
  "values": [ "/* Objects from GetUser */" ],
  "next_start": "5031"
}