Permalink
Switch branches/tags
Nothing to show
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
159 lines (138 sloc) 4.55 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 PUT
-H "Authorization: OAuth <ACCESS_TOKEN>"
https://<host>/v1/users/user_id
-d "<json below>"

Request

{
  "entry_update": {
    "update": {
      "key_value": {
        "//   key: VRF Index obtained via a GET operation"
	"key": "BtVQb1P7Em+lTUKEH3c5lw==",
        "//   value: ProtoSerialize(Entry{ "
        "//      commitment: HMAC(committed.key, committed.data),"
        "//      authorized_keys: authorized_keys, "
        "//    })"
        "value": "CiAhWorzTMne08bTtf9tfha0ouSWD7hb2z8GLNwwyXVgyBIiCiAnVXbqdmof99bSQH5jieVmdAd8Ooss0gL8OPwF6DBb5A==",
      },
      "// signatures is a map from key ids to signatures on key_value"
      "signatures": {"k": "1234", "v": "SJT3BgccSMEbSR0ZqjLHYhcXe+P04S00g1Kmktj4z8I="},
      "// ObjectHash of previous entry."
      "previous": "SJT3BgccSMEbSR0ZqjLHYhcXe+P04S00g1Kmktj4z8I=" 
    },
    "committed": {
      "// key is a random 16 byte value" 
      "key": "BtVQb1P7Em+lTUKEH3c5lw==",
      "// data = ProtoSerialize(Profile(your key data))"
      "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"
}