idnits 2.17.1 draft-svaldez-pp-http-api-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (9 March 2020) is 1507 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- No issues found here. Summary: 0 errors (**), 0 flaws (~~), 1 warning (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group S. Valdez 3 Internet-Draft Google LLC 4 Intended status: Informational 9 March 2020 5 Expires: 10 September 2020 7 Privacy Pass: HTTP API 8 draft-svaldez-pp-http-api-00 10 Abstract 12 This document specifies an integration for Privacy Pass over an HTTP 13 API, along with recommendations on how key commitments are stored and 14 accessed by HTTP-based consumers. 16 Status of This Memo 18 This Internet-Draft is submitted in full conformance with the 19 provisions of BCP 78 and BCP 79. 21 Internet-Drafts are working documents of the Internet Engineering 22 Task Force (IETF). Note that other groups may also distribute 23 working documents as Internet-Drafts. The list of current Internet- 24 Drafts is at https://datatracker.ietf.org/drafts/current/. 26 Internet-Drafts are draft documents valid for a maximum of six months 27 and may be updated, replaced, or obsoleted by other documents at any 28 time. It is inappropriate to use Internet-Drafts as reference 29 material or to cite them other than as "work in progress." 31 This Internet-Draft will expire on 10 September 2020. 33 Copyright Notice 35 Copyright (c) 2020 IETF Trust and the persons identified as the 36 document authors. All rights reserved. 38 This document is subject to BCP 78 and the IETF Trust's Legal 39 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 40 license-info) in effect on the date of publication of this document. 41 Please review these documents carefully, as they describe your rights 42 and restrictions with respect to this document. Code Components 43 extracted from this document must include Simplified BSD License text 44 as described in Section 4.e of the Trust Legal Provisions and are 45 provided without warranty as described in the Simplified BSD License. 47 Table of Contents 49 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 50 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 2 51 1.2. Layout . . . . . . . . . . . . . . . . . . . . . . . . . 3 52 1.3. Requirements . . . . . . . . . . . . . . . . . . . . . . 3 53 2. Privacy Pass HTTP API Wrapping . . . . . . . . . . . . . . . 3 54 3. Server Configuration/Commitments . . . . . . . . . . . . . . 4 55 3.1. Commitment Registry . . . . . . . . . . . . . . . . . . . 4 56 3.2. Server Configuration Retrieval . . . . . . . . . . . . . 5 57 4. Key Commitment Retrieval . . . . . . . . . . . . . . . . . . 5 58 5. Privacy Pass Issuance . . . . . . . . . . . . . . . . . . . . 6 59 6. Privacy Pass Redemption . . . . . . . . . . . . . . . . . . . 8 60 6.1. Generic Token Redemption . . . . . . . . . . . . . . . . 8 61 6.2. Direct Redemption . . . . . . . . . . . . . . . . . . . . 9 62 6.3. Delegated Redemption . . . . . . . . . . . . . . . . . . 9 63 7. Security Considerations . . . . . . . . . . . . . . . . . . . 11 64 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 65 8.1. Well-Known URI . . . . . . . . . . . . . . . . . . . . . 11 66 9. Normative References . . . . . . . . . . . . . . . . . . . . 11 67 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 12 69 1. Introduction 71 The Privacy Pass protocol as described in 72 [draft-davidson-pp-protocol] can be integrated with a number of 73 different settings, from server to server communication to browsing 74 the internet. 76 In this document, we will provide an API to use for integrating 77 Privacy Pass with an HTTP framework. Providing the format of HTTP 78 requests and responses needed to implement the Privacy Pass protocol. 80 1.1. Terminology 82 The following terms are used throughout this document. 84 * Server: A service that provides the server-side functionality 85 required by the protocol documented here (typically denoted S). 87 * Client: An entity that seeks authorization from a server that 88 supports interactions in the Privacy Pass protocol (typically 89 denoted C). 91 * Key: The secret key used by the Server for authorizing client 92 data. 94 * Commitment: Alternative name for Server's public key corresponding 95 to the secret key that they hold. 97 We assume that all protocol messages are encoded into raw byte format 98 before being sent. We use the TLS presentation language [RFC8446] to 99 describe the structure of protocol messages. 101 1.2. Layout 103 * Section 2: Describes the wrapping of messages within HTTP 104 requests/responses. 106 * Section 3: Describes how HTTP clients retrieve server 107 configurations and key commitments. 109 * Section 5: Describes how issuance requests are performed via a 110 HTTP API. 112 * Section 6: Describes how redemption requests are performed via a 113 HTTP API. 115 1.3. Requirements 117 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 118 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 119 document are to be interpreted as described in [RFC2119]. 121 2. Privacy Pass HTTP API Wrapping 123 Messages from HTTP-based clients to HTTP-based servers are performed 124 as GET and POST requests. The messages are sent via the "Sec- 125 Privacy-Pass" header. 127 "Sec-Privacy-Pass" is a Dictionary Structured Header 128 [draft-ietf-httpbis-header-structure-15]. The dictionary has two 129 keys: 131 * "type" whose value is a String conveying the function that is 132 being performed with this request. 134 * "body" whose value is a byte sequence containing a Privacy Pass 135 protocol message. 137 Note that the requests may contain addition Headers, request data and 138 URL parameters that are not specified here, these extra fields should 139 be ignored, though may be used by the server to determine whether to 140 fulfill the requested issuance/redemption. 142 3. Server Configuration/Commitments 144 A client SHOULD fetch the server configuration and current key 145 commitments prior to performing issuance and redemption. This 146 configuration is accessible via a "CONFIG_ENDPOINT", either provided 147 by the server or by a global registry that provides consistency and 148 anonymization guarantees. 150 3.1. Commitment Registry 152 To ensure that a server isn't providing different views of their key 153 material/commitments to different users, servers are expected to 154 write their commitments to a verifiable data structure. 156 Using a verifiable log-backed map ([verifiable-data-structures]), the 157 server can publish their commitments to the log in a way that clients 158 can detect when the server is attempting to provide a split-view of 159 their key commitments to different clients. 161 The key to the map is the "server_origin", with the value being: 163 struct { 164 opaque public_key<1..2^16-1>; 165 uint64 expiry; 166 uint8 supported_methods; # 3:Issue/Redeem, 2:Redeem, 1:Issue 167 opaque signature<1..2^16-1>; 168 } KeyCommitment; 170 struct { 171 opaque server_id<1..2^16-1>; 172 uint16 ciphersuite; 173 opaque verification_key<1..2^16-1>; 174 KeyCommitment commitments<1..2^16-1>; 175 } 177 The addition to the log is made via a signed message to the log 178 operator, which verifies the authenticity against a public key 179 associated with that server origin (either via the Web PKI or a out- 180 of-band key). 182 The server SHOULD then store an inclusion proof of the current key 183 commitment so that it can present it when delivering the key 184 commitment directly to the client or when the key commitment is being 185 delivered by a delegated party (other registries/preloaded 186 configuration lists/etc). 188 The client can then perform a request for the key commitment against 189 either the global registry or the server as described Section 4. 191 To avoid user segregation as a result of server configuration/ 192 commitment rotation, the log operator SHOULD enforce limits on how 193 many active commitments exist and how quickly the commitments are 194 being rotated. Clients SHOULD reject configurations/commitments that 195 violate their requirements for avoiding user segregation. These 196 considerations are discussed as part of 197 [draft-davidson-pp-architecture]. 199 3.2. Server Configuration Retrieval 201 Inputs: - "server_origin": The origin to retrieve a server 202 configuration for. 204 No outputs. 206 1. The client makes an anonymous GET request to 207 "CONFIG_ENDPOINT"/.well-known/privacy-pass with a message of type 208 "fetch-config" and a body of: 210 struct { 211 opaque server_origin<1..2^16-1>; 212 } 214 1. The server looks up the configuration associated with the origin 215 "server_origin" and responds with a message of type "config" and 216 a body of: 218 struct { 219 opaque server_id<1..2^16-1>; 220 uint16 ciphersuite; 221 opaque commitment_id<1..2^8-1>; 222 opaque verification_key<1..2^16-1>; 223 } 225 1. The client then stores the associated configuration state under 226 the corresponding "server_origin". 228 (TODO: This might be mergable with key commitment retrieval if 229 server_id = server_origin) 231 4. Key Commitment Retrieval 233 The client SHOULD retrieve server key commitments prior to both an 234 issuance and redemption to verify the consistency of the keys and to 235 monitor for key rotation between issuance and redemption events. 237 Inputs: - "server_origin": The origin to retrieve a key commitment 238 for. 240 No outputs. 242 1. The client fetches the configuration state "server_id", 243 "ciphersuite", "commitment_id" associated with "server_origin". 245 2. The client makes an anonymous GET request to 246 "CONFIG_ENDPOINT"/.well-known/privacy-pass with a message of type 247 "fetch-commitment" and a body of: 249 struct { 250 opaque server_id<1..2^16-1> = server_id; 251 opaque commitment_id<1..2^8-1> = commitment_id; 252 } 254 1. The server looks up the current configuration, and constructs a 255 list of commitments to return, noting whether a key commitment is 256 valid for issuance or redemption or both. 258 2. The server then responds with a message of type "commitment" and 259 a body of: 261 struct { 262 opaque public_key<1..2^16-1>; 263 uint64 expiry; 264 uint8 supported_methods; # 3:Issue/Redeem, 2:Redeem, 1:Issue 265 opaque signature<1..2^16-1>; 266 } KeyCommitment; 268 struct { 269 opaque server_id<1..2^16-1>; 270 uint16 ciphersuite; 271 opaque verification_key<1..2^16-1>; 272 KeyCommitment commitments<1..2^16-1>; 273 opaque inclusion_proofs<1..2^16-1>; 274 } 276 1. The client then verifies the signature for each key commitment 277 and stores the list of commitments to the current scope. The 278 client SHOULD NOT cache the commitments beyond the current scope, 279 as new commitments should be fetched for each independent 280 issuance and redemption request. The client SHOULD verify the 281 "inclusion_proofs" to confirm that the key commitment has been 282 submitted to a trusted registry. 284 5. Privacy Pass Issuance 286 Inputs: - "server_origin": The origin to request token issuance from. 287 - "count": The number of tokens to request issuance for. 289 Outputs: - "tokens": A list of tokens that have been signed via the 290 Privacy Pass protocol. 292 1. When a client wants to request tokens from a server, it should 293 first fetch a key commitment from the issuer via the process 294 described in Section 4 and keep the result as "commitment". 296 2. The client should then call the "CLIENT_ISSUE_GEN" interface 297 requesting "count" tokens storing the resulting "c_data", 298 "i_data", "g_data". 300 3. The client then makes a POST request to <"server_origin">/.well- 301 known/privacy-pass with a message of type "request-issuance" and 302 a body of: 304 enum { Normal(0) } IssuanceType; 306 struct { 307 IssuanceType type = 0; 308 opaque i_data<0..2^16-1> = i_data; 309 } 311 1. The server, upon receipt of the "request" should call the 312 "SERVER_ISSUE" interface with the value of "i_data" with a result 313 of "server_issue_resp". 315 2. The server should then respond to the POST request with a message 316 of type "issue" and a body of: 318 struct { 319 IssuanceType type = request.type; 320 uint16 ciphersuite = server_issue_resp.ciphersuite; 321 opaque evals<1..2^16-1> = server_issue_resp.evals; 322 opaque proof<1..2^16-1> = server_issue_resp.proof; 323 } 325 1. The client should then should call the "CLIENT_ISSUE_FINISH" 326 interface with the resulting "ciphersuite", ```evals","proof", 327 and stored"g_data"to extract a list of"tokens``. 329 2. The client should store the "public_key" associated with these 330 tokens and the elements of "tokens" under storage partitioned by 331 the "server_origin", accessible only via the Privacy Pass API. 333 6. Privacy Pass Redemption 335 There are two forms of Privacy Pass redemption that could function 336 under the HTTP API. Either passing along a token directly to the 337 target endpoint, which would perform its own redemption Section 6.1, 338 or the client redeeming the token and passing the result along to the 339 target endpoint. These two methods are described below. 341 6.1. Generic Token Redemption 343 Inputs: - "server_id": The server ID to redeem a token against. - 344 "ciphersuite": The ciphersuite for this token. - "public_key": The 345 public key associated with this token. - "token": A Privacy Pass 346 token. - "additional_data": Additional data to bind to this token 347 redemption. 349 Outputs: - "result": The result of the redemption from the server. 351 1. The client should call the "CLIENT_REDEEM" interface with 352 "server_id", "ciphersuite", "public_key", "token" and auxilary 353 data of "additional_data" storing the resulting "data" and "tag". 355 2. The client makes a POST request to <"server_origin">/.well-known/ 356 privacy-pass with a message of type "token-redemption" and a body 357 of: 359 struct { 360 opaque server_id<1..2^16-1> = server_id; 361 opaque data<1..2^16-1> = data; 362 opaque tag<1..2^16-1> = tag; 363 opaque aux<1..2^16-1> = additional_data; 364 } 366 1. The server, upon receipt of "request" should call the 367 "SERVER_REDEEM" interface with the "data", "tag", "aux" storing 368 the resulting "resp". 370 2. The server should then respond to the POST request with a message 371 of type "redemption-result" and a signed body of: 373 struct { 374 opaque aux<1..2^16-1> = aux; 375 uint8 result = resp; 376 opaque signature<1..2^16-1>; // signature of aux and result using 377 the server's verification key. 378 } 379 1. The client upon receipt of this message should verify the 380 "signature" using the "verification_key" from the configuration 381 and return the "result". 383 6.2. Direct Redemption 385 Inputs: - "server_origin": The server origin to redeem a token for. - 386 "target": The target endpoint to send the token to. - 387 "additional_data": Additional data to bind to this redemption 388 request. 390 1. When a client wants to redeem tokens for a server, it should 391 first fetch a key commitment from the issuer via the process 392 described in Section 4 and keep the result as "commitment". 394 2. The client should then look up the storage partition associated 395 with "server_origin" and fetch a "token" and "public_key". 397 3. The client should verify that the "public_key" is in the current 398 "commitment". If not, it should discard the token and fail the 399 redemption attempt. 401 4. As part of the request to "target", the client will include the 402 token as part of the request in the "Sec-Privacy-Pass" header 403 along with whatever other parameters are being passed as part of 404 the request to "target". The header will contain a message of 405 type "token-redemption" with a body of: 407 struct { 408 opaque server_id<1..2^16-1> = server_id; 409 uint16 ciphersuite = ciphersuite; 410 opaque public_key<1..2^16-1> = public_key; 411 opaque token<1..2^16-1> = token; 412 opaque additional_data<1..2^16-1> = additional_data; 413 } 415 At this point, the "target" can perform a generic redemption as 416 described in Section 6.1 by forwarding the message included in the 417 request to "target". 419 6.3. Delegated Redemption 421 Inputs: - "server_origin": The server origin to redeem a token for. - 422 "target": The target endpoint to send the token to. - 423 "additional_data": Additional data to bind to this redemption 424 request. 426 1. When a client wants to redeem tokens for a server, it should 427 first fetch a key commitment from the issuer via the process 428 described in Section 4 and keep the result as "commitment". 430 2. The client should then look up the storage partition associated 431 with "server_origin" and fetch a "token" and "public_key". 433 3. The client should verify that the "public_key" is in the current 434 "commitment". If not, it should discard the token and fail the 435 redemption attempt. 437 4. The client constructs a bytestring "aux" made up of the "target", 438 the current "timestamp", and "additional_data": 440 struct { 441 opaque target<1..2^16-1>; 442 uint64 timestamp; 443 opaque additional_data<0..2^16-1>; 444 } 446 1. The client then performs a token redemption as described in 447 Section 6.1. Storing the resulting "redemption-result" message. 449 2. As part of the request to "target", the client will include the 450 redemption result as part of the request in the "Sec-Privacy- 451 Pass" header along with whatever other parameters are being 452 passed as part of the request to "target". The header will 453 contain a message of type "signed-redemption-result" with a body 454 of: 456 struct { 457 opaque server_origin<1..2^16-1>; 458 opaque target<1..2^16-1>; 459 uint64 timestamp; 460 opaque additional_data<1..2^16-1> = additional_data; 461 opaque signed_redemption<1..2^16-1>; 462 } 464 At this point, the "target" can verify the integrity of 465 "signed_redemption.aux" based on the values of "target", "timestamp", 466 and "additional_data" and verify the signature of the redemption 467 result by querying the current configuration of the Privacy Pass 468 server. The inclusion of "target" and "timestamp" proves that the 469 server attested to the validity of the token in relation to this 470 particular request. 472 7. Security Considerations 474 Security considerations for Privacy Pass are discussed in 475 [draft-davidson-pp-architecture]. 477 8. IANA Considerations 479 8.1. Well-Known URI 481 This specification registers a new well-known URI. 483 URI suffix: "privacy-pass" 485 Change controller: IETF. 487 Specification document(s): this specification 489 9. Normative References 491 [draft-davidson-pp-architecture] 492 Davidson, A., "Privacy Pass: Architectural Framework", 493 n.d., . 496 [draft-davidson-pp-protocol] 497 Davidson, A., "Privacy Pass: The Protocol", n.d., 498 . 501 [draft-ietf-httpbis-header-structure-15] 502 Nottingham, M. and P-H. Kamp, "Structured Headers for 503 HTTP", n.d., . 506 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 507 Requirement Levels", BCP 14, RFC 2119, 508 DOI 10.17487/RFC2119, March 1997, 509 . 511 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 512 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 513 . 515 [verifiable-data-structures] 516 "Verifiable Data Structures", n.d., 517 . 520 Author's Address 522 Steven Valdez 523 Google LLC 525 Email: svaldez@chromium.org