idnits 2.17.1 draft-ietf-oauth-signed-http-request-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 (July 21, 2014) is 3559 days in the past. Is this intentional? Checking references for intended status: Experimental ---------------------------------------------------------------------------- == Outdated reference: A later version (-41) exists of draft-ietf-jose-json-web-signature-31 Summary: 0 errors (**), 0 flaws (~~), 2 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 OAuth Working Group J. Richer, Ed. 3 Internet-Draft The MITRE Corporation 4 Intended status: Experimental J. Bradley 5 Expires: January 22, 2015 Ping Identity 6 H. Tschofenig 7 ARM Limited 8 July 21, 2014 10 A Method for Signing an HTTP Requests for OAuth 11 draft-ietf-oauth-signed-http-request-00.txt 13 Abstract 15 This document a method for offering data origin authentication and 16 integrity protection of HTTP requests. To convey the relevant data 17 items in the request a JSON-based encapsulation is used and the JSON 18 Web Signature (JWS) technique is re-used. JWS offers integrity 19 protection using symmetric as well as asymmetric cryptography. 21 Status of This Memo 23 This Internet-Draft is submitted in full conformance with the 24 provisions of BCP 78 and BCP 79. 26 Internet-Drafts are working documents of the Internet Engineering 27 Task Force (IETF). Note that other groups may also distribute 28 working documents as Internet-Drafts. The list of current Internet- 29 Drafts is at http://datatracker.ietf.org/drafts/current/. 31 Internet-Drafts are draft documents valid for a maximum of six months 32 and may be updated, replaced, or obsoleted by other documents at any 33 time. It is inappropriate to use Internet-Drafts as reference 34 material or to cite them other than as "work in progress." 36 This Internet-Draft will expire on January 22, 2015. 38 Copyright Notice 40 Copyright (c) 2014 IETF Trust and the persons identified as the 41 document authors. All rights reserved. 43 This document is subject to BCP 78 and the IETF Trust's Legal 44 Provisions Relating to IETF Documents 45 (http://trustee.ietf.org/license-info) in effect on the date of 46 publication of this document. Please review these documents 47 carefully, as they describe your rights and restrictions with respect 48 to this document. Code Components extracted from this document must 49 include Simplified BSD License text as described in Section 4.e of 50 the Trust Legal Provisions and are provided without warranty as 51 described in the Simplified BSD License. 53 Table of Contents 55 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 56 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 57 3. Generating a JSON Object from an HTTP Request . . . . . . . . 3 58 3.1. Selection of a hashing algorithm and size . . . . . . . . 4 59 3.2. Calculating the query parameter list and hash . . . . . . 4 60 3.3. Calculating the header list and hash . . . . . . . . . . 5 61 4. Verifying the Hashes . . . . . . . . . . . . . . . . . . . . 5 62 4.1. Validating the query parameter list and hash . . . . . . 6 63 4.2. Validating the header list and hash . . . . . . . . . . . 6 64 5. Example . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 65 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 66 6.1. The 'pop' OAuth Access Token Type . . . . . . . . . . . . 7 67 6.2. JSON Web Signature and Encryption Type Values 68 Registration . . . . . . . . . . . . . . . . . . . . . . 8 69 7. Security Considerations . . . . . . . . . . . . . . . . . . . 8 70 7.1. Offering Confidentiality Protection for Access to 71 Protected Resources . . . . . . . . . . . . . . . . 8 72 7.2. Authentication of Resource Servers . . . . . . . . . . . 8 73 7.3. Plaintext Storage of Credentials . . . . . . . . . . . . 9 74 7.4. Entropy of Keys . . . . . . . . . . . . . . . . . . . . . 9 75 7.5. Denial of Service . . . . . . . . . . . . . . . . . . . . 9 76 7.6. Protecting HTTP Header Fields . . . . . . . . . . . . . . 10 77 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 10 78 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 10 79 9.1. Normative References . . . . . . . . . . . . . . . . . . 10 80 9.2. Informative References . . . . . . . . . . . . . . . . . 11 81 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 11 83 1. Introduction 85 In order to protect an HTTP request with a signature, a method for 86 conveying various parameters and to compute a signature is needed. 87 Ideally, this should be done without replicating the information 88 already present in the HTTP request. This version of the document 89 still replicates most of the headers though. 91 The keying material required for this signature calculation is 92 distributed via mechanisms described in companion documents (see 93 [I-D.bradley-oauth-pop-key-distribution] and 94 [I-D.hunt-oauth-pop-architecture]). The JSON Web Signature (JWS) 95 specification [I-D.ietf-jose-json-web-signature] is re-used for 96 computing a digital signature (which uses asymmetric cryptography) or 97 a keyed message digest (in case of symmetric cryptography). 99 The scope of the mechanism described in this document is shown in 100 Figure 1 where a client in possession of keying material that is tied 101 to the access token creates a JSON object, signs it, and issues an 102 request to a resource server for access to a protected resource. 104 +-----------+ +------------+ 105 | |--(1)- HTTP Request ->| Resource | 106 | Client | (+Signature, +Access Token)->| Server | 107 | | | | 108 | |<-(2)- HTTP Response ---------------| | 109 +-----------+ +------------+ 111 Figure 1: Message Flow. 113 Many HTTP application frameworks insert extra headers, query 114 parameters, and otherwise manipulate the HTTP request on its way from 115 the web server into the application code itself. It is the goal of 116 this draft to have a signature protection mechanism that is 117 sufficiently robust against such deployment constraints (while still 118 providing sufficient security benefits). 120 The method of conveying the token and signed request to the protected 121 resource server is undefined by this document, but [RFC6750] could be 122 re-used. 124 The mechanism described in this document does not provide 125 authentication of the resource server to the client. This version of 126 the document does not provide a cryptographic binding to Transport 127 Layer Security (TLS) used underneath the an HTTPS request. 129 2. Terminology 131 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 132 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 133 document are to be interpreted as described in RFC 2119 [RFC2119]. 135 We use the term 'sign' (or 'signature') to denote both a keyed 136 message digest and a digital signature operation. 138 3. Generating a JSON Object from an HTTP Request 140 This section describes how to generate a JSON object below is 141 included as a member of the JSON object. All members are OPTIONAL. 143 m The HTTP Method used to make this request. This MUST be the 144 uppercase HTTP verb as a JSON string. 146 u The HTTP URL host component as a JSON string. This MAY include 147 the port separated from the host by a colon in host:port format. 149 p The HTTP URL path component of the request as an HTTP string. 151 q The hashed HTTP URL query parameter map of the request as a two- 152 part JSON array. The first part of this array is a JSON array 153 listing all query parameters that were used in the calculation of 154 the hash in the order that they were added to the hashed value as 155 described below. The second part of this array is a JSON string 156 containing the Base64URL encoded hash itself, calculated as 157 described below. 159 h The hashed HTTP request headers as a two-part JSON array. The 160 first part of this array is a JSON array listing all headers that 161 were used in the calculation of the hash in the order that they 162 were added to the hashed value as described below. The second 163 part of this array is a JSON string containing the Base64URL 164 encoded hash itself, calculated as described below. 166 b The base64URL encoded hash of the HTTP Request body, calculated as 167 the HMAC of the byte array of the body. 169 ts The "ts" (timestamp) element provides replay protection of the 170 JSON object. Its value MUST be a number containing an IntDate 171 value representing number of whole integer seconds from midnight, 172 January 1, 1970 GMT. 174 3.1. Selection of a hashing algorithm and size 176 The hashes SHALL be calculated using the HMAC algorithm using a hash 177 size equal to the size of the surrounding JWT's alg header field. 178 That is, if the JWT uses HS256 or RS256, the HMAC here uses a 256-bit 179 HMAC. If the JWT uses RS512, the HMAC here uses 512-bit HMAC, and so 180 forth. 182 3.2. Calculating the query parameter list and hash 184 To generate the query parameter list and hash, the client creates two 185 data objects: an ordered list of strings to hold the query parameter 186 names and a string buffer to hold the data to be hashed. 188 The client iterates through all query parameters in whatever order it 189 chooses and for each query parameter it does the following: 191 1. Adds the name of the query parameter to the end of the list. 193 2. Encodes the name and value of the query parameter as "name=value" 194 and appends it to the string buffer. [[Separated by an 195 ampersand? Alternatively we could have this also pulled into an 196 ordered list and post-process the concatenation, but that might 197 be too deep into the weeds. ]] 199 Repeated parameter names are processed separately with no special 200 handling. Parameters MAY be skipped by the client if they are not 201 required (or desired) to be covered by the signature. 203 The client then calculates the HMAC hash over the resulting string 204 buffer. The list and the hash result are added as the value of the 205 "p" member. 207 3.3. Calculating the header list and hash 209 To generate the header list and hash, the client creates two data 210 objects: an ordered list of strings to hold the header names and a 211 string buffer to hold the data to be hashed. 213 The client iterates through all query parameters in whatever order it 214 chooses and for each query parameter it does the following: 216 1. Adds the name of the header to the end of the list. 218 2. Encodes the name and value of the header as "name: value" and 219 appends it to the string buffer. [[Separated by a newline? 220 Alternatively we could have this also pulled into an ordered list 221 and post-process the concatenation, but that might be too deep 222 into the weeds. ]] 224 Repeated header names are processed separately with no special 225 handling. Headers MAY be skipped by the client if they are not 226 required (or desired) to be covered by the signature. 228 The client then calculates the HMAC hash over the resulting string 229 buffer. The list and the hash result are added as the value of the 230 "h" member. 232 4. Verifying the Hashes 234 Validation of the overall signature is done using the standard JWS 235 mechanisms for JSON structures. However, in order to trust any of 236 the hashed mechanisms above, an application MUST re-create and verify 237 a hash for each component. Additionally, an application MUST compare 238 the replicated values included in various JSON fields with the actual 239 header fields of the request. Failure to-do so will allow an 240 attacker to modify the underlying request, connect do different 241 resources while at the same time having the application layer verify 242 the signature correctly. 244 4.1. Validating the query parameter list and hash 246 The client has at its disposal a map that indexes the query parameter 247 names to the values given. The client creates a string buffer for 248 calculating the hash. The client then iterates through the "list" 249 portion of the "p" parameter. For each item in the list (in the 250 order of the list) it does the following: 252 1. Fetch the value of the parameter from the HTTP request parameter 253 map. If a parameter is found in the list of signed parameters 254 but not in the map, the validation fails. 256 2. Encode the parameter as "name=value" and concatenate it to the 257 end of the string buffer. [[same separator issue as above.]] 259 The client calculates the hash of the string buffer and base64url 260 encodes it. The client compares that string to the string passed in 261 as the hash. If the two match, the hash validates, and all named 262 parameters and their values are considered covered by the signature. 264 There MAY be additional query parameters that are not listed in the 265 list and are therefore not covered by the signature. The client MUST 266 decide whether or not to accept a request with these uncovered 267 parameters. 269 4.2. Validating the header list and hash 271 The client has at its disposal a map that indexes the header names to 272 the values given. The client creates a string buffer for calculating 273 the hash. The client then iterates through the "list" portion of the 274 "h" parameter. For each item in the list (in the order of the list) 275 it does the following: 277 1. Fetch the value of the header from the HTTP request header map. 278 If a header is found in the list of signed parameters but not in 279 the map, the validation fails. 281 2. Encode the parameter as "name: value" and concatenate it to the 282 end of the string buffer. [[same separator issue as above.]] 284 The client calculates the hash of the string buffer and base64url 285 encodes it. The client compares that string to the string passed in 286 as the hash. If the two match, the hash validates, and all named 287 headers and their values are considered covered by the signature. 289 There MAY be additional headers that are not listed in the list and 290 are therefore not covered by the signature. The client MUST decide 291 whether or not to accept a request with these uncovered headers. 293 5. Example 295 Example goes in here but will look like something like this 296 (symmetric key case). 298 1) HTTP Request (plain) 300 POST /request?b5=%3D%253D&a3=a&c%40=&a2=r%20b&c2 HTTP/1.1 301 Host: example.com 303 2) JWS protected JSON object 305 {"typ":"pop", 306 "alg":"HS256", 307 "kid":"client12345@example.com"} 308 . 309 {"m":"POST", 310 "u":"example.com", 311 "p":"request", 312 "q":[["a3", "b5", "a2"], "m2398f32i2o3roiu2313aa"], 313 "ts":1300819380 314 } 315 . 316 dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk 318 Figure 2: Message Flow. 320 6. IANA Considerations 322 6.1. The 'pop' OAuth Access Token Type 324 Section 11.1 of [RFC6749] defines the OAuth Access Token Type 325 Registry and this document adds another token type to this registry. 327 Type name: pop 329 Additional Token Endpoint Response Parameters: (none) 331 HTTP Authentication Scheme(s): Proof-of-possession access token for 332 use with OAuth 2.0 334 Change controller: IETF 336 Specification document(s): [[ this document ]] 338 6.2. JSON Web Signature and Encryption Type Values Registration 340 This specification registers the "pop" type value in the IANA JSON 341 Web Signature and Encryption Type Values registry 342 [I-D.ietf-jose-json-web-signature]: 344 o "typ" Header Parameter Value: "pop" 346 o Abbreviation for MIME Type: None 348 o Change Controller: IETF 350 o Specification Document(s): [[ this document ]] 352 7. Security Considerations 354 7.1. Offering Confidentiality Protection for Access to Protected 355 Resources 357 This specification can be used with and without Transport Layer 358 Security (TLS). 360 Without TLS this protocol provides a mechanism for verifying the 361 integrity of requests, it provides no confidentiality protection. 362 Consequently, eavesdroppers will have full access to communication 363 content and any further messages exchanged between the client and the 364 resource server. This could be problematic when data is exchanged 365 that requires care, such as personal data. 367 When TLS is used then confidentiality can be ensured; this version of 368 the specification does, however, not provide the TLS channel binding 369 feature, which ensures that the TLS channel is cryptographically 370 bound to the application layer protocol authentication defined in 371 this document. 373 The use of TLS in combination with the signed HTTP request mechanism 374 is highly recommended to ensure the confidentiality of the user's 375 data. 377 7.2. Authentication of Resource Servers 379 This protocol allows clients to verify the authenticity of resource 380 servers only when TLS is used. With TLS the resource server is 381 authenticated as part of the TLS handshake. The mechanism described 382 in this document does not provide any mechanism for the client to 383 authenticate the resource server at the application layer. 385 7.3. Plaintext Storage of Credentials 387 The mechanism described in this document works similar to many three 388 party authentication and key exchange mechanisms. In order to 389 compute the signature over the HTTP request, the client must have 390 access to a key bound to the access token (in plaintext form). 392 If an attacker were to gain access to these stored secrets at the 393 client or (in case of symmetric keys) at the resource server he or 394 she would be able to perform any action on behalf of any client. 396 It is therefore paramount to the security of the protocol that the 397 private keys associated with the access tokens are protected from 398 unauthorized access. 400 7.4. Entropy of Keys 402 Unless TLS is used between the client and the resource server, 403 eavesdroppers will have full access to requests sent by the client. 404 They will thus be able to mount off-line brute-force attacks to 405 recover the session key or private key used to compute the keyed 406 message digest or digital signature, respectively. 408 This specification assumes that the keying material for use with the 409 described HTTP signing mechanism has been distributed via other 410 mechanisms, such as [I-D.bradley-oauth-pop-key-distribution]. Hence, 411 it is the responsibility of the authorization server and or the 412 client to be careful when generating fresh and unique keys with 413 sufficient entropy to resist such attacks for at least the length of 414 time that the session keys (and the access tokens) are valid. 416 For example, if the key bound to the access token is valid for one 417 day, authorization servers must ensure that it is not possible to 418 mount a brute force attack that recovers that key in less than one 419 day. Of course, servers are urged to err on the side of caution, and 420 use the longest key length reasonable. 422 7.5. Denial of Service 424 This specification includes a number of features which may make 425 resource exhaustion attacks against resource servers possible. For 426 example, a resource server may need to need to the resource server 427 has to process the incoming request, verify the access token, perform 428 signature verification, and might have (in certain circumstances) 429 consult back-end databases or the authorization server before 430 granting access to the protected resource. 432 An attacker may exploit this to perform a denial of service attack by 433 sending a large number of invalid requests to the server. The 434 computational overhead of verifying the keyed message digest alone 435 is, however, not sufficient to mount a denial of service attack since 436 keyed message digest functions belong to the computationally fastest 437 cryptographic algorithms. The situation may, however, be different 438 when using asymmetric cryptography, which is also supported by the 439 JWS. 441 7.6. Protecting HTTP Header Fields 443 This specification provides flexibility for selectively protecting 444 header fields and even the body of the message. Since all components 445 of the HTTP request are only optionally protected by this method, and 446 even some components may be protected only in part (e.g., some 447 headers but not others) it is up to application developers to verify 448 that any parameters in a request are actually covered by the 449 signature. 451 The application verifying this signature MUST NOT assume that any 452 particular parameter is appropriately covered by the signature. Any 453 applications that are sensitive of header or query parameter order 454 MUST verify the order of the parameters on their own. The 455 application MUST also compare the values in the JSON container with 456 the actual parameters received with the HTTP request. Failure to 457 make this comparison will render the signature mechanism useless. 459 8. Acknowledgements 461 The authors acknowledge the OAuth Working Group and submit this draft 462 for feedback and input into the ongoing work of signed HTTP requests 463 for the interaction between clients and resource servers. 465 9. References 467 9.1. Normative References 469 [I-D.ietf-jose-json-web-signature] 470 Jones, M., Bradley, J., and N. Sakimura, "JSON Web 471 Signature (JWS)", draft-ietf-jose-json-web-signature-31 472 (work in progress), July 2014. 474 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 475 Requirement Levels", BCP 14, RFC 2119, March 1997. 477 [RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", RFC 478 6749, October 2012. 480 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 481 Framework: Bearer Token Usage", RFC 6750, October 2012. 483 9.2. Informative References 485 [I-D.bradley-oauth-pop-key-distribution] 486 Bradley, J., Hunt, P., Jones, M., and H. Tschofenig, 487 "OAuth 2.0 Proof-of-Possession: Authorization Server to 488 Client Key Distribution", draft-bradley-oauth-pop-key- 489 distribution-01 (work in progress), June 2014. 491 [I-D.hunt-oauth-pop-architecture] 492 Hunt, P., Richer, J., Mills, W., Mishra, P., and H. 493 Tschofenig, "OAuth 2.0 Proof-of-Possession (PoP) Security 494 Architecture", draft-hunt-oauth-pop-architecture-02 (work 495 in progress), June 2014. 497 Authors' Addresses 499 Justin Richer (editor) 500 The MITRE Corporation 502 Email: jricher@mitre.org 504 John Bradley 505 Ping Identity 507 Email: ve7jtb@ve7jtb.com 508 URI: http://www.thread-safe.com/ 510 Hannes Tschofenig 511 ARM Limited 512 Austria 514 Email: Hannes.Tschofenig@gmx.net 515 URI: http://www.tschofenig.priv.at