idnits 2.17.00 (12 Aug 2021) /tmp/idnits41607/draft-ietf-privacypass-http-api-01.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 (12 July 2021) is 306 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 12 July 2021 5 Expires: 13 January 2022 7 Privacy Pass HTTP API 8 draft-ietf-privacypass-http-api-01 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 13 January 2022. 33 Copyright Notice 35 Copyright (c) 2021 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 . . . . . . . . . . . . . . . . . . . . . . . . . 2 52 1.3. Requirements . . . . . . . . . . . . . . . . . . . . . . 3 53 2. Privacy Pass HTTP API Wrapping . . . . . . . . . . . . . . . 3 54 3. Server key registry . . . . . . . . . . . . . . . . . . . . . 3 55 3.1. Key Registry . . . . . . . . . . . . . . . . . . . . . . 4 56 3.2. Server Configuration Retrieval . . . . . . . . . . . . . 5 57 4. Key Commitment Retrieval . . . . . . . . . . . . . . . . . . 5 58 5. Privacy Pass Issuance . . . . . . . . . . . . . . . . . . . . 7 59 6. Privacy Pass Redemption . . . . . . . . . . . . . . . . . . . 8 60 6.1. Generic Token Redemption . . . . . . . . . . . . . . . . 8 61 6.2. Direct Redemption . . . . . . . . . . . . . . . . . . . . 9 62 6.3. Delegated Redemption . . . . . . . . . . . . . . . . . . 10 63 7. Security Considerations . . . . . . . . . . . . . . . . . . . 11 64 8. Privacy considerations . . . . . . . . . . . . . . . . . . . 11 65 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 66 9.1. Well-Known URI . . . . . . . . . . . . . . . . . . . . . 11 67 10. Normative References . . . . . . . . . . . . . . . . . . . . 11 68 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 12 70 1. Introduction 72 The Privacy Pass protocol as described in 73 [draft-ietf-privacypass-protocol] can be integrated with a number of 74 different settings, from server to server communication to browsing 75 the internet. 77 In this document, we will provide an API to use for integrating 78 Privacy Pass with an HTTP framework. Providing the format of HTTP 79 requests and responses needed to implement the Privacy Pass protocol. 81 1.1. Terminology 83 We use the same definition of server and client that is used in 84 [draft-ietf-privacypass-protocol] and 85 [draft-ietf-privacypass-architecture]. 87 We assume that all protocol messages are encoded into raw byte format 88 before being sent. We use the TLS presentation language [RFC8446] to 89 describe the structure of protocol messages. 91 1.2. Layout 93 * Section 2: Describes the wrapping of messages within HTTP 94 requests/responses. 96 * Section 3: Describes how HTTP clients retrieve server 97 configurations and key commitments. 99 * Section 5: Describes how issuance requests are performed via a 100 HTTP API. 102 * Section 6: Describes how redemption requests are performed via a 103 HTTP API. 105 1.3. Requirements 107 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 108 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 109 document are to be interpreted as described in [RFC2119]. 111 2. Privacy Pass HTTP API Wrapping 113 Messages from HTTP-based clients to HTTP-based servers are performed 114 as GET and POST requests. The messages are sent via the "Sec- 115 Privacy-Pass" header. 117 "Sec-Privacy-Pass" is a Dictionary Structured Header 118 [draft-ietf-httpbis-header-structure-15]. The dictionary has two 119 keys: 121 * "type" whose value is a String conveying the function that is 122 being performed with this request. 124 * "body" whose value is a byte sequence containing a Privacy Pass 125 protocol message. 127 Note that the requests may contain addition Headers, request data and 128 URL parameters that are not specified here, these extra fields should 129 be ignored, though may be used by the server to determine whether to 130 fulfill the requested issuance/redemption. 132 3. Server key registry 134 A client SHOULD fetch a server's current public key information prior 135 to performing issuance and redemption. This configuration is 136 accessible via a "CONFIG_ENDPOINT", either provided by the server or 137 by a global registry that provides consistency and anonymization 138 guarantees. 140 3.1. Key Registry 142 To ensure that a server isn't providing different views of their 143 public key material to different users, servers are expected to write 144 their commitments to a verifiable data structure. 146 Using a verifiable log-backed map ([verifiable-data-structures]), the 147 server can publish their commitments to the log in a way that clients 148 can detect when the server is attempting to provide a split-view of 149 their key commitments to different clients. 151 The key to the map is the "server_origin", with the value being: 153 struct { 154 opaque public_key<1..2^16-1>; 155 uint64 expiry; 156 uint8 supported_methods; # 3:Issue/Redeem, 2:Redeem, 1:Issue 157 opaque signature<1..2^16-1>; 158 } KeyCommitment; 160 struct { 161 opaque server_id<1..2^16-1>; 162 uint16 ciphersuite; 163 opaque verification_key<1..2^16-1>; 164 KeyCommitment commitments<1..2^16-1>; 165 } 167 The addition to the log is made via a signed message to the log 168 operator, which verifies the authenticity against a public key 169 associated with that server origin (either via the Web PKI or a out- 170 of-band key). The signature should be computed under a long-term 171 signing key that is associated with the server identity. 173 The server SHOULD then store an inclusion proof of the current key 174 commitment so that it can present it when delivering the key 175 commitment directly to the client or when the key commitment is being 176 delivered by a delegated party (other registries/preloaded 177 configuration lists/etc). 179 The client can then perform a request for the key commitment against 180 either the global registry or the server as described in Section 4. 181 Note that the signature should be verified by the client to ensure 182 that the key material is owned by the server. This requires that the 183 client know the public verification key that is associated with the 184 server. 186 To avoid user segregation as a result of server configuration/ 187 commitment rotation, the log operator SHOULD enforce limits on how 188 many active commitments exist and how quickly the commitments are 189 being rotated. Clients SHOULD reject configurations/commitments that 190 violate their requirements for avoiding user segregation. These 191 considerations are discussed as part of 192 [draft-ietf-privacypass-architecture]. 194 3.2. Server Configuration Retrieval 196 Inputs: - "server_origin": The origin to retrieve a server 197 configuration for. 199 No outputs. 201 1. The client makes an anonymous GET request to 202 "CONFIG_ENDPOINT"/.well-known/privacy-pass with a message of type 203 "fetch-config" and a body of: 205 struct { 206 opaque server_origin<1..2^16-1>; 207 } 209 1. The server looks up the configuration associated with the origin 210 "server_origin" and responds with a message of type "config" and 211 a body of: 213 struct { 214 opaque server_id<1..2^16-1>; 215 uint16 ciphersuite; 216 opaque commitment_id<1..2^8-1>; 217 opaque verification_key<1..2^16-1>; 218 } 220 1. The client then stores the associated configuration state under 221 the corresponding "server_origin". 223 (TODO: This might be mergable with key commitment retrieval if 224 server_id = server_origin) 226 4. Key Commitment Retrieval 228 The client SHOULD retrieve server key commitments prior to both an 229 issuance and redemption to verify the consistency of the keys and to 230 monitor for key rotation between issuance and redemption events. 232 Inputs: - "server_origin": The origin to retrieve a key commitment 233 for. 235 No outputs. 237 1. The client fetches the configuration state "server_id", 238 "ciphersuite", "commitment_id" associated with "server_origin". 240 2. The client makes an anonymous GET request to 241 "CONFIG_ENDPOINT"/.well-known/privacy-pass with a message of type 242 "fetch-commitment" and a body of: 244 struct { 245 opaque server_id<1..2^16-1> = server_id; 246 opaque commitment_id<1..2^8-1> = commitment_id; 247 } 249 1. The server looks up the current configuration, and constructs a 250 list of commitments to return, noting whether a key commitment is 251 valid for issuance or redemption or both. 253 2. The server then responds with a message of type "commitment" and 254 a body of: 256 struct { 257 opaque public_key<1..2^16-1>; 258 uint64 expiry; 259 uint8 supported_methods; # 3:Issue/Redeem, 2:Redeem, 1:Issue 260 opaque signature<1..2^16-1>; 261 } KeyCommitment; 263 struct { 264 opaque server_id<1..2^16-1>; 265 uint16 ciphersuite; 266 opaque verification_key<1..2^16-1>; 267 KeyCommitment commitments<1..2^16-1>; 268 opaque inclusion_proofs<1..2^16-1>; 269 } 271 1. The client then verifies the signature for each key commitment 272 and stores the list of commitments to the current scope. The 273 client SHOULD NOT cache the commitments beyond the current scope, 274 as new commitments should be fetched for each independent 275 issuance and redemption request. The client SHOULD verify the 276 "inclusion_proofs" to confirm that the key commitment has been 277 submitted to a trusted registry. Once the client receives the 278 "ciphersuite" for the server, it should implement all Privacy 279 Pass API functions (as detailed in 280 [draft-ietf-privacypass-protocol]) using this ciphersuite. 282 5. Privacy Pass Issuance 284 Inputs: - "server_origin": The origin to request token issuance from. 285 - "count": The number of tokens to request issuance for. 287 Outputs: - "tokens": A list of tokens that have been signed via the 288 Privacy Pass protocol. 290 1. When a client wants to request tokens from a server, it should 291 first fetch a key commitment from the server via the process 292 described in Section 4 and keep the result as "commitment". 294 2. The client should then call the "Generate" function requesting 295 "count" tokens storing the resulting "input" data. 297 3. The client then makes a POST request to <"server_origin">/.well- 298 known/privacy-pass with a message of type "request-issuance" and 299 a body of: 301 enum { Normal(0) } IssuanceType; 303 struct { 304 IssuanceType type = 0; 305 opaque msg<0..2^16-1> = input.msg; 306 } 308 1. The server, upon receipt of the "request" should call the "Issue" 309 function with the "public_key", "secret_key" and the value of 310 "msg" with a result of "resp". 312 2. The server should then respond to the POST request with a message 313 of type "issue" and a body of: 315 struct { 316 IssuanceType type = request.type; 317 IssuanceResp resp = resp; 318 } 320 1. The client should then should call the "Process" function with 321 the "public_key", stored "inputs" and resulting "resp", to 322 extract a list of "redemption_tokens". 324 2. The client should store the "public_key" associated with these 325 tokens and the elements of "redemption_tokens" under storage 326 partitioned by the "server_origin", accessible only via the 327 Privacy Pass API. 329 6. Privacy Pass Redemption 331 There are two forms of Privacy Pass redemption that could function 332 under the HTTP API. Either passing along a token directly to the 333 target endpoint, which would perform its own redemption Section 6.1, 334 or the client redeeming the token and passing the result along to the 335 target endpoint. These two methods are described below. 337 In the HTTP ecosystem, redemption contexts should generally be keyed 338 by the same privacy boundary used for cookies and other local 339 storage. Generally this is the top-level origin. Any redemption 340 context should be built following the principles outlined in 341 [draft-ietf-privacypass-architecture] and later in Section 8. 343 6.1. Generic Token Redemption 345 Inputs: - "context": The request context to use. - "server_id": The 346 server ID to redeem a token against. - "ciphersuite": The ciphersuite 347 for this token. - "public_key": The public key associated with this 348 token. - "redemption_token": A Privacy Pass token. - "info": 349 Additional data to bind to this token redemption. 351 Outputs: - "result": The result of the redemption from the server. 353 1. The client should check whether the "server_id" is present in the 354 "context". If it isn't and the size of the "context" is beneath 355 the client's limit, it should be added. 357 2. The client should call the "Redeem" function with 358 "redemption_token" and additional data of "info" storing the 359 resulting "data" and "tag". 361 3. The client makes a POST request to <"server_origin">/.well-known/ 362 privacy-pass with a message of type "token-redemption" and a body 363 of: 365 struct { 366 opaque server_id<1..2^16-1> = server_id; 367 opaque data<1..2^16-1> = data; 368 opaque tag<1..2^16-1> = tag; 369 opaque info<1..2^16-1> = info; 370 } 372 1. The server, upon receipt of "request" should call the "Verify" 373 interface with "public_key", "secret_key" and the received 374 "data", "tag", "info" storing the resulting "resp". 376 2. The server should then respond to the POST request with a message 377 of type "redemption-result" and a signed body of: 379 struct { 380 opaque info<1..2^16-1> = info; 381 uint8 result = resp; 382 // signature of info and result using 383 // the server's verification key. 384 opaque signature<1..2^16-1>; 385 } 387 1. The client upon receipt of this message should verify the 388 "signature" using the "verification_key" from the configuration 389 and return the "result". 391 6.2. Direct Redemption 393 Inputs: - "context": The request context to use. - "server_origin": 394 The server origin to redeem a token for. - "target": The target 395 endpoint to send the token to. - "additional_data": Additional data 396 to bind to this redemption request. 398 1. When a client wants to redeem tokens for a server, it should 399 first fetch a key commitment from the server via the process 400 described in Section 4 and keep the result as "commitment". 402 2. The client should then look up the storage partition associated 403 with "server_origin" and fetch a "redemption_token" and 404 "public_key". 406 3. The client should verify that the "public_key" is in the current 407 "commitment". If not, it should discard the token and fail the 408 redemption attempt. 410 4. As part of the request to "target", the client will include the 411 token as part of the request in the "Sec-Privacy-Pass" header 412 along with whatever other parameters are being passed as part of 413 the request to "target". The header will contain a message of 414 type "token-redemption" with a body of: 416 struct { 417 opaque server_id<1..2^16-1> = server_id; 418 uint16 ciphersuite = ciphersuite; 419 opaque public_key<1..2^16-1> = public_key; 420 RedemptionToken token<1..2^16-1> = redemption_token; 421 opaque additional_data<1..2^16-1> = additional_data; 422 } 423 At this point, the "target" can perform a generic redemption as 424 described in Section 6.1 by forwarding the message included in the 425 request to "target". 427 6.3. Delegated Redemption 429 Inputs: - "context": The request context to use. - "server_origin": 430 The server origin to redeem a token for. - "target": The target 431 endpoint to send the token to. - "additional_data": Additional data 432 to bind to this redemption request. 434 1. When a client wants to redeem tokens for a server, it should 435 first fetch a key commitment from the server via the process 436 described in Section 4 and keep the result as "commitment". 438 2. The client should then look up the storage partition associated 439 with "server_origin" and fetch a "redemption_token" and 440 "public_key". 442 3. The client should verify that the "public_key" is in the current 443 "commitment". If not, it should discard the token and fail the 444 redemption attempt. 446 4. The client constructs a bytestring "info" made up of the 447 "target", the current "timestamp", and "additional_data": 449 struct { 450 opaque target<1..2^16-1>; 451 uint64 timestamp; 452 opaque additional_data<0..2^16-1>; 453 } 455 1. The client then performs a token redemption as described in 456 Section 6.1. Storing the resulting "redemption-result" message. 458 2. As part of the request to "target", the client will include the 459 redemption result as part of the request in the "Sec-Privacy- 460 Pass" header along with whatever other parameters are being 461 passed as part of the request to "target". The header will 462 contain a message of type "signed-redemption-result" with a body 463 of: 465 struct { 466 opaque server_origin<1..2^16-1>; 467 opaque target<1..2^16-1>; 468 uint64 timestamp; 469 opaque additional_data<1..2^16-1> = additional_data; 470 opaque signed_redemption<1..2^16-1>; 471 } 473 At this point, the "target" can verify the integrity of 474 "signed_redemption.info" based on the values of "target", 475 "timestamp", and "additional_data" and verify the signature of the 476 redemption result by querying the current configuration of the 477 Privacy Pass server. The inclusion of "target" and "timestamp" 478 proves that the server attested to the validity of the token in 479 relation to this particular request. 481 7. Security Considerations 483 Security considerations for Privacy Pass are discussed in 484 [draft-ietf-privacypass-architecture]. 486 8. Privacy considerations 488 General privacy considerations for Privacy Pass are discussed in 489 [draft-ietf-privacypass-architecture]. 491 In order to implement this API with redemption contexts, a client 492 needs to maintain strong privacy boundaries between different 493 redemption contexts to avoid privacy leakage from redemptions across 494 them. Notably in the web/HTTP world, cross-site tracking and 495 fingerprinting will need to be considered and mitigated in order to 496 maintain these privacy boundaries. 498 9. IANA Considerations 500 9.1. Well-Known URI 502 This specification registers a new well-known URI. 504 URI suffix: "privacy-pass" 506 Change controller: IETF. 508 Specification document(s): this specification 510 10. Normative References 512 [draft-ietf-httpbis-header-structure-15] 513 Nottingham, M. and P-H. Kamp, "Structured Headers for 514 HTTP", n.d., . 517 [draft-ietf-privacypass-architecture] 518 Davidson, A., "Privacy Pass: Architectural Framework", 519 n.d., . 522 [draft-ietf-privacypass-protocol] 523 Davidson, A., "Privacy Pass: The Protocol", n.d., 524 . 527 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 528 Requirement Levels", BCP 14, RFC 2119, 529 DOI 10.17487/RFC2119, March 1997, 530 . 532 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 533 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 534 . 536 [verifiable-data-structures] 537 "Verifiable Data Structures", n.d., 538 . 541 Author's Address 543 Steven Valdez 544 Google LLC 546 Email: svaldez@chromium.org