idnits 2.17.1 draft-ietf-oauth-jwt-bcp-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 : ---------------------------------------------------------------------------- ** The document seems to lack a Security Considerations section. ** The abstract seems to contain references ([RFC7519]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (March 23, 2018) is 2197 days in the past. Is this intentional? Checking references for intended status: Best Current Practice ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) ** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259) == Outdated reference: A later version (-13) exists of draft-ietf-secevent-token-07 Summary: 3 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 Y. Sheffer 3 Internet-Draft Intuit 4 Intended status: Best Current Practice D. Hardt 5 Expires: September 24, 2018 Amazon 6 M. Jones 7 Microsoft 8 March 23, 2018 10 JSON Web Token Best Current Practices 11 draft-ietf-oauth-jwt-bcp-01 13 Abstract 15 JSON Web Tokens, also known as JWTs [RFC7519], are URL-safe JSON- 16 based security tokens that contain a set of claims that can be signed 17 and/or encrypted. JWTs are being widely used and deployed as a 18 simple security token format in numerous protocols and applications, 19 both in the area of digital identity, and in other application areas. 20 The goal of this Best Current Practices document is to provide 21 actionable guidance leading to secure implementation and deployment 22 of JWTs. 24 Status of This Memo 26 This Internet-Draft is submitted in full conformance with the 27 provisions of BCP 78 and BCP 79. 29 Internet-Drafts are working documents of the Internet Engineering 30 Task Force (IETF). Note that other groups may also distribute 31 working documents as Internet-Drafts. The list of current Internet- 32 Drafts is at http://datatracker.ietf.org/drafts/current/. 34 Internet-Drafts are draft documents valid for a maximum of six months 35 and may be updated, replaced, or obsoleted by other documents at any 36 time. It is inappropriate to use Internet-Drafts as reference 37 material or to cite them other than as "work in progress." 39 This Internet-Draft will expire on September 24, 2018. 41 Copyright Notice 43 Copyright (c) 2018 IETF Trust and the persons identified as the 44 document authors. All rights reserved. 46 This document is subject to BCP 78 and the IETF Trust's Legal 47 Provisions Relating to IETF Documents 48 (http://trustee.ietf.org/license-info) in effect on the date of 49 publication of this document. Please review these documents 50 carefully, as they describe your rights and restrictions with respect 51 to this document. Code Components extracted from this document must 52 include Simplified BSD License text as described in Section 4.e of 53 the Trust Legal Provisions and are provided without warranty as 54 described in the Simplified BSD License. 56 Table of Contents 58 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 59 1.1. Target Audience . . . . . . . . . . . . . . . . . . . . . 3 60 1.2. Conventions used in this document . . . . . . . . . . . . 4 61 2. Threats and Vulnerabilities . . . . . . . . . . . . . . . . . 4 62 2.1. Weak Signatures and Insufficient Signature Validation . . 4 63 2.2. Weak symmetric keys . . . . . . . . . . . . . . . . . . . 4 64 2.3. Multiplicity of JSON encodings . . . . . . . . . . . . . 5 65 2.4. Incorrect Composition of Encryption and Signature . . . . 5 66 2.5. Insecure Use of Elliptic Curve Encryption . . . . . . . . 5 67 2.6. Substitution Attacks . . . . . . . . . . . . . . . . . . 5 68 2.7. Cross-JWT Confusion . . . . . . . . . . . . . . . . . . . 5 69 3. Best Practices . . . . . . . . . . . . . . . . . . . . . . . 6 70 3.1. Perform Algorithm Verification . . . . . . . . . . . . . 6 71 3.2. Use Appropriate Algorithms . . . . . . . . . . . . . . . 6 72 3.3. Validate All Cryptographic Operations . . . . . . . . . . 6 73 3.4. Validate Cryptographic Inputs . . . . . . . . . . . . . . 7 74 3.5. Ensure Cryptographic Keys have Sufficient Entropy . . . . 7 75 3.6. Use UTF-8 . . . . . . . . . . . . . . . . . . . . . . . . 7 76 3.7. Validate Issuer and Subject . . . . . . . . . . . . . . . 7 77 3.8. Use and Validate Audience . . . . . . . . . . . . . . . . 8 78 3.9. Use Explicit Typing . . . . . . . . . . . . . . . . . . . 8 79 3.10. Use Mutually Exclusive Validation Rules for Different 80 Kinds of JWTs . . . . . . . . . . . . . . . . . . . . . . 8 81 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 82 5. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 9 83 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 9 84 6.1. Normative References . . . . . . . . . . . . . . . . . . 10 85 6.2. Informative References . . . . . . . . . . . . . . . . . 10 86 Appendix A. Document History . . . . . . . . . . . . . . . . . . 12 87 A.1. draft-ietf-oauth-jwt-bcp-01 . . . . . . . . . . . . . . . 12 88 A.2. draft-ietf-oauth-jwt-bcp-00 . . . . . . . . . . . . . . . 12 89 A.3. draft-sheffer-oauth-jwt-bcp-01 . . . . . . . . . . . . . 12 90 A.4. draft-sheffer-oauth-jwt-bcp-00 . . . . . . . . . . . . . 12 91 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 12 93 1. Introduction 95 JSON Web Tokens, also known as JWTs [RFC7519], are URL-safe JSON- 96 based security tokens that contain a set of claims that can be signed 97 and/or encrypted. The JWT specification has seen rapid adoption 98 because it encapsulates security-relevant information in one, easy to 99 protect location, and because it is easy to implement using widely- 100 available tools. One application area in which JWTs are commonly 101 used is representing digital identity information, such as OpenID 102 Connect ID Tokens [OpenID.Core] and OAuth 2.0 [RFC6749] access tokens 103 and refresh tokens, the details of which are deployment-specific. 105 Since the JWT specification was published, there have been several 106 widely published attacks on implementations and deployments. Such 107 attacks are the result of under-specified security mechanisms, as 108 well as incomplete implementations and incorrect usage by 109 applications. 111 The goal of this document is to facilitate secure implementation and 112 deployment of JWTs. Many of the recommendations in this document 113 will actually be about implementation and use of the cryptographic 114 mechanisms underlying JWTs that are defined by JSON Web Signature 115 (JWS) [RFC7515], JSON Web Encryption (JWE) [RFC7516], and JSON Web 116 Algorithms (JWA) [RFC7518]. Others will be about use of the JWT 117 claims themselves. 119 These are intended to be minimum recommendations for the use of JWTs 120 in the vast majority of implementation and deployment scenarios. 121 Other specifications that reference this document can have stricter 122 requirements related to one or more aspects of the format, based on 123 their particular circumstances; when that is the case, implementers 124 are advised to adhere to those stricter requirements. Furthermore, 125 this document provides a floor, not a ceiling, so stronger options 126 are always allowed (e.g., depending on differing evaluations of the 127 importance of cryptographic strength vs. computational load). 129 Community knowledge about the strength of various algorithms and 130 feasible attacks can change quickly, and experience shows that a Best 131 Current Practice (BCP) document about security is a point-in-time 132 statement. Readers are advised to seek out any errata or updates 133 that apply to this document. 135 1.1. Target Audience 137 The targets of this document are: 139 - Implementers of JWT libraries (and the JWS and JWE libraries used 140 by them), 142 - Implementers of code that uses such libraries (to the extent that 143 some mechanisms may not be provided by libraries, or until they 144 are), and 146 - Developers of specifications that rely on JWTs, both inside and 147 outside the IETF. 149 1.2. Conventions used in this document 151 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 152 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 153 "OPTIONAL" in this document are to be interpreted as described in 154 [RFC2119]. 156 2. Threats and Vulnerabilities 158 This section lists some known and possible problems with JWT 159 implementations and deployments. Each problem description is 160 followed by references to one or more mitigations to those problems. 162 2.1. Weak Signatures and Insufficient Signature Validation 164 Signed JSON Web Tokens carry an explicit indication of the signing 165 algorithm, in the form of the "alg" header parameter, to facilitate 166 cryptographic agility. This, in conjunction with design flaws in 167 some libraries and applications, have led to several attacks: 169 - The algorithm can be changed to "none" by an attacker, and some 170 libraries would trust this value and "validate" the JWT without 171 checking any signature. 173 - An "RS256" (RSA, 2048 bit) parameter value can be changed into 174 "HS256" (HMAC, SHA-256), and some libraries would try to validate 175 the signature using HMAC-SHA256 and using the RSA public key as 176 the HMAC shared secret. 178 For mitigations, see Section 3.1 and Section 3.2. 180 2.2. Weak symmetric keys 182 In addition, some applications sign tokens using a weak symmetric key 183 and a keyed MAC algorithm such as "HS256". In most cases, these keys 184 are human memorable passwords that are vulnerable to dictionary 185 attacks [Langkemper]. 187 For mitigations, see Section 3.5. 189 2.3. Multiplicity of JSON encodings 191 Many practitioners are not aware that JSON [RFC7159] allows several 192 different character encodings: UTF-8, UTF-16 and UTF-32. As a 193 result, the JWT might be misinterpreted by its recipient. 195 For mitigations, see Section 3.6. 197 2.4. Incorrect Composition of Encryption and Signature 199 Some libraries that decrypt a JWE-encrypted JWT to obtain a JWS- 200 signed object do not always validate the internal signature. 202 For mitigations, see Section 3.3. 204 2.5. Insecure Use of Elliptic Curve Encryption 206 Per [Sanso], several JOSE libraries fail to validate their inputs 207 correctly when performing elliptic curve key agreement (the "ECDH-ES" 208 algorithm). An attacker that is able to send JWEs of its choosing 209 that use invalid curve points and observe the cleartext outputs 210 resulting from decryption with the invalid curve points can use this 211 vulnerability to recover the recipient's private key. 213 For mitigations, see Section 3.4. 215 2.6. Substitution Attacks 217 There are attacks in which one recipient will have a JWT intended for 218 it and attempt to use it at a different recipient that it was not 219 intended for. If not caught, these attacks can result in the 220 attacker gaining access to resources that it is not entitled to 221 access. 223 For mitigations, see Section 3.7 and Section 3.8. 225 2.7. Cross-JWT Confusion 227 As JWTs are being used by more different protocols in diverse 228 application areas, it becomes increasingly important to prevent cases 229 of JWT tokens that have been issued for one purpose being subverted 230 and used for another. Note that this is a specific type of 231 substitution attack. If the JWT could be used in an application 232 context in which it could be confused with other kinds of JWTs, then 233 mitigations MUST be employed to prevent these substitution attacks. 235 For mitigations, see Section 3.7, Section 3.8, Section 3.9, and 236 Section 3.10. 238 3. Best Practices 240 The best practices listed below should be applied by practitioners to 241 mitigate the threats listed in the preceding section. 243 3.1. Perform Algorithm Verification 245 Libraries MUST enable the caller to specify a supported set of 246 algorithms and MUST NOT use any other algorithms when performing 247 cryptographic operations. The library MUST ensure that the "alg" or 248 "enc" header specifies the same algorithm that is used for the 249 cryptographic operation. Moreover, each key MUST be used with 250 exactly one algorithm, and this MUST be checked when the 251 cryptographic operation is performed. 253 3.2. Use Appropriate Algorithms 255 As Section 5.2 of [RFC7515] says, "it is an application decision 256 which algorithms may be used in a given context. Even if a JWS can 257 be successfully validated, unless the algorithm(s) used in the JWS 258 are acceptable to the application, it SHOULD consider the JWS to be 259 invalid." 261 Therefore, applications MUST only allow the use of cryptographically 262 current algorithms that meet the security requirements of the 263 application. This set will vary over time as new algorithms are 264 introduced and existing algorithms are deprecated due to discovered 265 cryptographic weaknesses. Applications must therefore be designed to 266 enable cryptographic agility. 268 That said, if a JWT is cryptographically protected by a transport 269 layer, such as TLS using cryptographically current algorithms, there 270 may be no need to apply another layer of cryptographic protections to 271 the JWT. In such cases, the use of the "none" algorithm can be 272 perfectly acceptable. JWTs using "none" are often used in 273 application contexts in which the content is optionally signed; then 274 the URL-safe claims representation and processing can be the same in 275 both the signed and unsigned cases. 277 3.3. Validate All Cryptographic Operations 279 All cryptographic operations used in the JWT MUST be validated and 280 the entire JWT MUST be rejected if any of them fail to validate. 281 This is true not only of JWTs with a single set of Header Parameters 282 but also for Nested JWTs, in which both outer and inner operations 283 MUST be validated using the keys and algorithms supplied by the 284 application. 286 3.4. Validate Cryptographic Inputs 288 Some cryptographic operations, such as Elliptic Curve Diffie-Hellman 289 key agreement ("ECDH-ES") take inputs that may contain invalid 290 values, such as points not on the specified elliptic curve or other 291 invalid points. Either the JWS/JWE library itself must validate 292 these inputs before using them or it must use underlying 293 cryptographic libraries that do so (or both!). 295 3.5. Ensure Cryptographic Keys have Sufficient Entropy 297 The Key Entropy and Random Values advice in Section 10.1 of [RFC7515] 298 and the Password Considerations in Section 8.8 of [RFC7518] MUST be 299 followed. In particular, human-memorizable passwords MUST NOT be 300 directly used as the key to a keyed-MAC algorithm such as "HS256". 302 3.6. Use UTF-8 304 [RFC7515], [RFC7516], and [RFC7519] all specify that UTF-8 be used 305 for encoding and decoding JSON used in Header Parameters and JWT 306 Claims Sets. Implementations and applications MUST do this, and not 307 use other Unicode encodings for these purposes. 309 3.7. Validate Issuer and Subject 311 When a JWT contains an "iss" (issuer) claim, the application MUST 312 validate that the cryptographic keys used for the cryptographic 313 operations in the JWT belong to the issuer. If they do not, the 314 application MUST reject the JWT. 316 The means of determining the keys owned by an issuer is application- 317 specific. As one example, OpenID Connect [OpenID.Core] issuer values 318 are "https" URLs that reference a JSON metadata document that 319 contains a "jwks_uri" value that is an "https" URL from which the 320 issuer's keys are retrieved as a JWK Set [RFC7517]. This same 321 mechanism is used by [I-D.ietf-oauth-discovery]. Other applications 322 may use different means of binding keys to issuers. 324 Similarly, when the JWT contains a "sub" (subject) claim, the 325 application MUST validate that the subject value corresponds to a 326 valid subject and/or issuer/subject pair at the application. This 327 may include confirming that the issuer is trusted by the application. 328 If the issuer, subject, or the pair are invalid, the application MUST 329 reject the JWT. 331 3.8. Use and Validate Audience 333 If the same issuer can issue JWTs that are intended for use by more 334 than one relying party or application, the JWT MUST contain an "aud" 335 (audience) claim that can be used to determine whether the JWT is 336 being used by an intended party or was substituted by an attacker at 337 an unintended party. Furthermore, the relying party or application 338 MUST validate the audience value and if the audience value is not 339 associated with the recipient, it MUST reject the JWT. 341 3.9. Use Explicit Typing 343 Confusion of one kind of JWT for another can be prevented by having 344 all the kinds of JWTs that could otherwise potentially be confused 345 include an explicit JWT type value and include checking the type 346 value in their validation rules. Explicit JWT typing is accomplished 347 by using the "typ" header parameter. For instance, the 348 [I-D.ietf-secevent-token] specification uses the "application/ 349 secevent+jwt" media type to perform explicit typing of Security Event 350 Tokens (SETs). 352 Per the definition of "typ" in Section 4.1.9 of [RFC7515], it is 353 RECOMMENDED that the "application/" prefix be omitted from the "typ" 354 value. Therefore, for example, the "typ" value used to explicitly 355 include a type for a SET SHOULD be "secevent+jwt". When explicit 356 typing is employed for a JWT, it is RECOMMENDED that a media type 357 name of the format "application/example+jwt" be used, where "example" 358 is replaced by the identifier for the specific kind of JWT. 360 When applying explicit typing to a Nested JWT, the "typ" header 361 parameter containing the explicit type value MUST be present in the 362 inner JWT of the Nested JWT (the JWT whose payload is the JWT Claims 363 Set). The same "typ" header parameter value MAY be present in the 364 outer JWT as well, to explicitly type the entire Nested JWT. 366 Note that the use of explicit typing may not achieve disambiguation 367 from existing kinds of JWTs, as the validation rules for existing 368 kinds JWTs often do not use the "typ" header parameter value. 369 Explicit typing is RECOMMENDED for new uses of JWTs. 371 3.10. Use Mutually Exclusive Validation Rules for Different Kinds of 372 JWTs 374 Each application of JWTs defines a profile specifying the required 375 and optional JWT claims and the validation rules associated with 376 them. If more than one kind of JWT can be issued by the same issuer, 377 the validation rules for those JWTs MUST be written such that they 378 are mutually exclusive, rejecting JWTs of the wrong kind. To prevent 379 substitution of JWTs from one context into another, a number of 380 strategies may be employed: 382 - Use explicit typing for different kinds of JWTs. Then the 383 distinct "typ" values can be used to differentiate between the 384 different kinds of JWTs. 386 - Use different sets of required claims or different required claim 387 values. Then the validation rules for one kind of JWT will reject 388 those with different claims or values. 390 - Use different sets of required header parameters or different 391 required header parameter values. Then the validation rules for 392 one kind of JWT will reject those with different header parameters 393 or values. 395 - Use different keys for different kinds of JWTs. Then the keys 396 used to validate one kind of JWT will fail to validate other kinds 397 of JWTs. 399 - Use different "aud" values for different uses of JWTs from the 400 same issuer. Then audience validation will reject JWTs 401 substituted into inappropriate contexts. 403 - Use different issuers for different kinds of JWTs. Then the 404 distinct "iss" values can be used to segregate the different kinds 405 of JWTs. 407 Given the broad diversity of JWT usage and applications, the best 408 combination of types, required claims, values, header parameters, key 409 usages, and issuers to differentiate among different kinds of JWTs 410 will, in general, be application specific. 412 4. IANA Considerations 414 This document requires no IANA actions. 416 5. Acknowledgements 418 Thanks to Antonio Sanso for bringing the "ECDH-ES" invalid point 419 attack to the attention of JWE and JWT implementers. Thanks to Nat 420 Sakimura for advocating the use of explicit typing. 422 6. References 423 6.1. Normative References 425 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 426 Requirement Levels", BCP 14, RFC 2119, 427 DOI 10.17487/RFC2119, March 1997, . 430 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 431 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 432 2014, . 434 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 435 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 436 2015, . 438 [RFC7516] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", 439 RFC 7516, DOI 10.17487/RFC7516, May 2015, 440 . 442 [RFC7518] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518, 443 DOI 10.17487/RFC7518, May 2015, . 446 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 447 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 448 . 450 6.2. Informative References 452 [I-D.ietf-oauth-discovery] 453 Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 454 Authorization Server Metadata", draft-ietf-oauth- 455 discovery-10 (work in progress), March 2018. 457 [I-D.ietf-secevent-token] 458 Hunt, P., Jones, M., Denniss, W., and M. Ansari, "Security 459 Event Token (SET)", draft-ietf-secevent-token-07 (work in 460 progress), March 2018. 462 [Langkemper] 463 Langkemper, S., "Attacking JWT Authentication", September 464 2016, . 467 [OpenID.Core] 468 Sakimura, N., Bradley, J., Jones, M., Medeiros, B., and C. 469 Mortimore, "OpenID Connect Core 1.0", November 2014, 470 . 472 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 473 RFC 6749, DOI 10.17487/RFC6749, October 2012, 474 . 476 [RFC7517] Jones, M., "JSON Web Key (JWK)", RFC 7517, 477 DOI 10.17487/RFC7517, May 2015, . 480 [Sanso] Sanso, A., "Critical Vulnerability Uncovered in JSON 481 Encryption", March 2017, 482 . 485 Appendix A. Document History 487 [[ to be removed by the RFC editor before publication as an RFC ]] 489 A.1. draft-ietf-oauth-jwt-bcp-01 491 - Feedback from Brian Campbell. 493 A.2. draft-ietf-oauth-jwt-bcp-00 495 - Initial WG draft. No change from the latest individual version. 497 A.3. draft-sheffer-oauth-jwt-bcp-01 499 - Added explicit typing. 501 A.4. draft-sheffer-oauth-jwt-bcp-00 503 - Initial version. 505 Authors' Addresses 507 Yaron Sheffer 508 Intuit 510 EMail: yaronf.ietf@gmail.com 512 Dick Hardt 513 Amazon 515 EMail: dick@amazon.com 517 Michael B. Jones 518 Microsoft 520 EMail: mbj@microsoft.com 521 URI: http://self-issued.info/