Draft: draft-svaldez-pp-http-api

Commentary: cc for review . Mainly just removing the interfaces that were previously present and using the API functions from the protocol directly . I 've also changed some of the wording around the key registry , and replaced client  and server -Server . Let me know if there is anything that you think I 've missed . 
 We currently have interfaces in the architecture document that lay out how messages should be sent and received . I think the architecture document should be solely focused on the building of the ecosystem in a way that maintains the utility of the privacy and security guarantees made by the protocol . The interfaces are mainly used by the HTTP API doc , and so I think this will be a better home for them . 
 I 've removed the interfaces from the architecture doc ( ) and used the protocol API directly in the HTTP doc ( )
The following terms are used throughout this document.
Server: A service that provides the server-side functionality
required by the protocol documented here (typically denoted S).
Client: An entity that seeks authorization from a server that
supports interactions in the Privacy Pass protocol (typically
denoted C).
Key: The secret key used by the Server for authorizing client
data.
Commitment: Alternative name for Server's public key corresponding
to the secret key that they hold.
We use the same definition of Server and Client that is used in
draft-davidson-pp-protocol and draft-davidson-pp-architecture.
A client SHOULD fetch the server configuration and current key
commitments prior to performing issuance and redemption.  This
configuration is accessible via a "CONFIG_ENDPOINT", either provided
by the server or by a global registry that provides consistency and
anonymization guarantees.
To ensure that a server isn't providing different views of their key
material/commitments to different users, servers are expected to
write their commitments to a verifiable data structure.
The addition to the log is made via a signed message to the log
operator, which verifies the authenticity against a public key
associated with that server origin (either via the Web PKI or a out-
of-band key).
The client can then perform a request for the key commitment against
either the global registry or the server as described key-commitment.
A Client SHOULD fetch the Server configuration and current public key
commitments prior to performing issuance and redemption.  This
configuration is accessible via a "CONFIG_ENDPOINT", either provided
by the Server or by a global registry that provides consistency and
anonymization guarantees.
To ensure that a Server isn't providing different views of their
public key material to different users, Servers are expected to write
their commitments to a verifiable data structure.
The addition to the log is made via a signed message to the log
operator, which verifies the authenticity against a public key
associated with that Server origin (either via the Web PKI or a out-
of-band key).  The signature should be computed under a long-term
signing key that is associated with the Server identity.
The Client can then perform a request for the key commitment against
either the global registry or the Server as described in key-
commitment.  Note that the signature should be verified by the Client
to ensure that the key material is owned by the Server.  This
requires that the Client know the public verification key that is
associated with the Server.
The client then verifies the signature for each key commitment and
stores the list of commitments to the current scope.  The client
SHOULD NOT cache the commitments beyond the current scope, as new
commitments should be fetched for each independent issuance and
redemption request.  The client SHOULD verify the
"inclusion_proofs" to confirm that the key commitment has been
submitted to a trusted registry.
The Client then verifies the signature for each key commitment and
stores the list of commitments to the current scope.  The Client
SHOULD NOT cache the commitments beyond the current scope, as new
commitments should be fetched for each independent issuance and
redemption request.  The Client SHOULD verify the
"inclusion_proofs" to confirm that the key commitment has been
submitted to a trusted registry.  Once the Client receives the
"ciphersuite" for the Server, it should implement all Privacy Pass
API functions (as detailed in draft-davidson-pp-protocol) using
this ciphersuite.
The client should then call the "CLIENT_ISSUE_GEN" interface
requesting "count" tokens storing the resulting "c_data",
"i_data", "g_data".
The server, upon receipt of the "request" should call the
"SERVER_ISSUE" interface with the value of "i_data" with a result
of "server_issue_resp".
The client should then should call the "CLIENT_ISSUE_FINISH"
interface with the resulting "ciphersuite", ```evals","proof", and
stored"g_data"to extract a list of"tokens``.
The client should store the "public_key" associated with these
tokens and the elements of "tokens" under storage partitioned by
the "server_origin", accessible only via the Privacy Pass API.
Inputs: - "server_id": The server ID to redeem a token against.  -
"ciphersuite": The ciphersuite for this token.  - "public_key": The
public key associated with this token.  - "token": A Privacy Pass
token.  - "additional_data": Additional data to bind to this token
redemption.
The client should call the "CLIENT_REDEEM" interface with
"server_id", "ciphersuite", "public_key", "token" and auxiliary
data of "additional_data" storing the resulting "data" and "tag".
The server, upon receipt of "request" should call the
"SERVER_REDEEM" interface with the "data", "tag", "aux" storing
the resulting "resp".
The Client should then call the "Generate" function requesting
"count" tokens storing the resulting "input" data.
The server, upon receipt of the "request" should call the "Issue"
function with the "public_key", "secret_key" and the value of
"msg" with a result of "resp".
The Client should then should call the "Process" function with the
"public_key", stored "inputs" and resulting "resp", to extract a
list of "redemption_tokens".
The Client should store the "public_key" associated with these
tokens and the elements of "redemption_tokens" under storage
partitioned by the "server_origin", accessible only via the
Privacy Pass API.
Inputs: - "server_id": The Server ID to redeem a token against.  -
"ciphersuite": The ciphersuite for this token.  - "public_key": The
public key associated with this token.  - "redemption_token": A
Privacy Pass token.  - "info": Additional data to bind to this token
redemption.
The Client should call the "Redeem" function with
"redemption_token" and additional data of "info" storing the
resulting "data" and "tag".
The server, upon receipt of "request" should call the "Verify"
interface with "public_key", "secret_key" and the received "data",
"tag", "info" storing the resulting "resp".
At this point, the "target" can verify the integrity of
"signed_redemption.aux" based on the values of "target", "timestamp",
and "additional_data" and verify the signature of the redemption
result by querying the current configuration of the Privacy Pass
server.  The inclusion of "target" and "timestamp" proves that the
server attested to the validity of the token in relation to this
particular request.
At this point, the "target" can verify the integrity of
"signed_redemption.info" based on the values of "target",
"timestamp", and "additional_data" and verify the signature of the
redemption result by querying the current configuration of the
Privacy Pass server.  The inclusion of "target" and "timestamp"
proves that the Server attested to the validity of the token in
relation to this particular request.