draft-ietf-oauth-jwt-bcp-06.txt   draft-ietf-oauth-jwt-bcp-07.txt 
OAuth Working Group Y. Sheffer OAuth Working Group Y. Sheffer
Internet-Draft Intuit Internet-Draft Intuit
Intended status: Best Current Practice D. Hardt Updates: RFC 7519 (if approved) D. Hardt
Expires: December 9, 2019 Intended status: Best Current Practice
M. Jones Expires: April 15, 2020 M. Jones
Microsoft Microsoft
June 07, 2019 October 13, 2019
JSON Web Token Best Current Practices JSON Web Token Best Current Practices
draft-ietf-oauth-jwt-bcp-06 draft-ietf-oauth-jwt-bcp-07
Abstract Abstract
JSON Web Tokens, also known as JWTs, are URL-safe JSON-based security JSON Web Tokens, also known as JWTs, are URL-safe JSON-based security
tokens that contain a set of claims that can be signed and/or tokens that contain a set of claims that can be signed and/or
encrypted. JWTs are being widely used and deployed as a simple encrypted. JWTs are being widely used and deployed as a simple
security token format in numerous protocols and applications, both in security token format in numerous protocols and applications, both in
the area of digital identity, and in other application areas. The the area of digital identity, and in other application areas. The
goal of this Best Current Practices document is to provide actionable goal of this Best Current Practices document is to provide actionable
guidance leading to secure implementation and deployment of JWTs. guidance leading to secure implementation and deployment of JWTs.
skipping to change at page 1, line 39 skipping to change at page 1, line 39
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/. Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on December 9, 2019. This Internet-Draft will expire on April 15, 2020.
Copyright Notice Copyright Notice
Copyright (c) 2019 IETF Trust and the persons identified as the Copyright (c) 2019 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(https://trustee.ietf.org/license-info) in effect on the date of (https://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 2, line 17 skipping to change at page 2, line 17
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Target Audience . . . . . . . . . . . . . . . . . . . . . 4 1.1. Target Audience . . . . . . . . . . . . . . . . . . . . . 4
1.2. Conventions used in this document . . . . . . . . . . . . 4 1.2. Conventions used in this document . . . . . . . . . . . . 4
2. Threats and Vulnerabilities . . . . . . . . . . . . . . . . . 4 2. Threats and Vulnerabilities . . . . . . . . . . . . . . . . . 4
2.1. Weak Signatures and Insufficient Signature Validation . . 4 2.1. Weak Signatures and Insufficient Signature Validation . . 4
2.2. Weak symmetric keys . . . . . . . . . . . . . . . . . . . 5 2.2. Weak Symmetric Keys . . . . . . . . . . . . . . . . . . . 5
2.3. Incorrect Composition of Encryption and Signature . . . . 5 2.3. Incorrect Composition of Encryption and Signature . . . . 5
2.4. Plaintext Leakage through Analysis of Ciphertext Length . 5 2.4. Plaintext Leakage through Analysis of Ciphertext Length . 5
2.5. Insecure Use of Elliptic Curve Encryption . . . . . . . . 5 2.5. Insecure Use of Elliptic Curve Encryption . . . . . . . . 5
2.6. Multiplicity of JSON encodings . . . . . . . . . . . . . 5 2.6. Multiplicity of JSON Encodings . . . . . . . . . . . . . 6
2.7. Substitution Attacks . . . . . . . . . . . . . . . . . . 6 2.7. Substitution Attacks . . . . . . . . . . . . . . . . . . 6
2.8. Cross-JWT Confusion . . . . . . . . . . . . . . . . . . . 6 2.8. Cross-JWT Confusion . . . . . . . . . . . . . . . . . . . 6
2.9. Indirect Attacks on the Server . . . . . . . . . . . . . 6 2.9. Indirect Attacks on the Server . . . . . . . . . . . . . 6
3. Best Practices . . . . . . . . . . . . . . . . . . . . . . . 6 3. Best Practices . . . . . . . . . . . . . . . . . . . . . . . 7
3.1. Perform Algorithm Verification . . . . . . . . . . . . . 7 3.1. Perform Algorithm Verification . . . . . . . . . . . . . 7
3.2. Use Appropriate Algorithms . . . . . . . . . . . . . . . 7 3.2. Use Appropriate Algorithms . . . . . . . . . . . . . . . 7
3.3. Validate All Cryptographic Operations . . . . . . . . . . 8 3.3. Validate All Cryptographic Operations . . . . . . . . . . 8
3.4. Validate Cryptographic Inputs . . . . . . . . . . . . . . 8 3.4. Validate Cryptographic Inputs . . . . . . . . . . . . . . 8
3.5. Ensure Cryptographic Keys have Sufficient Entropy . . . . 8 3.5. Ensure Cryptographic Keys have Sufficient Entropy . . . . 8
3.6. Avoid Length-Dependent Encryption Inputs . . . . . . . . 8 3.6. Avoid Length-Dependent Encryption Inputs . . . . . . . . 9
3.7. Use UTF-8 . . . . . . . . . . . . . . . . . . . . . . . . 9 3.7. Use UTF-8 . . . . . . . . . . . . . . . . . . . . . . . . 9
3.8. Validate Issuer and Subject . . . . . . . . . . . . . . . 9 3.8. Validate Issuer and Subject . . . . . . . . . . . . . . . 9
3.9. Use and Validate Audience . . . . . . . . . . . . . . . . 9 3.9. Use and Validate Audience . . . . . . . . . . . . . . . . 9
3.10. Do Not Trust Received Claims . . . . . . . . . . . . . . 9 3.10. Do Not Trust Received Claims . . . . . . . . . . . . . . 10
3.11. Use Explicit Typing . . . . . . . . . . . . . . . . . . . 10 3.11. Use Explicit Typing . . . . . . . . . . . . . . . . . . . 10
3.12. Use Mutually Exclusive Validation Rules for Different 3.12. Use Mutually Exclusive Validation Rules for Different
Kinds of JWTs . . . . . . . . . . . . . . . . . . . . . . 10 Kinds of JWTs . . . . . . . . . . . . . . . . . . . . . . 11
4. Security Considerations . . . . . . . . . . . . . . . . . . . 11 4. Security Considerations . . . . . . . . . . . . . . . . . . . 11
5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12
6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 11 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 12
7. References . . . . . . . . . . . . . . . . . . . . . . . . . 12 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 12
7.1. Normative References . . . . . . . . . . . . . . . . . . 12 7.1. Normative References . . . . . . . . . . . . . . . . . . 12
7.2. Informative References . . . . . . . . . . . . . . . . . 13 7.2. Informative References . . . . . . . . . . . . . . . . . 13
Appendix A. Document History . . . . . . . . . . . . . . . . . . 15 Appendix A. Document History . . . . . . . . . . . . . . . . . . 15
A.1. draft-ietf-oauth-jwt-bcp-06 . . . . . . . . . . . . . . . 15 A.1. draft-ietf-oauth-jwt-bcp-07 . . . . . . . . . . . . . . . 15
A.2. draft-ietf-oauth-jwt-bcp-05 . . . . . . . . . . . . . . . 15 A.2. draft-ietf-oauth-jwt-bcp-06 . . . . . . . . . . . . . . . 15
A.3. draft-ietf-oauth-jwt-bcp-04 . . . . . . . . . . . . . . . 15 A.3. draft-ietf-oauth-jwt-bcp-05 . . . . . . . . . . . . . . . 15
A.4. draft-ietf-oauth-jwt-bcp-03 . . . . . . . . . . . . . . . 15 A.4. draft-ietf-oauth-jwt-bcp-04 . . . . . . . . . . . . . . . 15
A.5. draft-ietf-oauth-jwt-bcp-02 . . . . . . . . . . . . . . . 15 A.5. draft-ietf-oauth-jwt-bcp-03 . . . . . . . . . . . . . . . 15
A.6. draft-ietf-oauth-jwt-bcp-01 . . . . . . . . . . . . . . . 15 A.6. draft-ietf-oauth-jwt-bcp-02 . . . . . . . . . . . . . . . 15
A.7. draft-ietf-oauth-jwt-bcp-00 . . . . . . . . . . . . . . . 15 A.7. draft-ietf-oauth-jwt-bcp-01 . . . . . . . . . . . . . . . 15
A.8. draft-sheffer-oauth-jwt-bcp-01 . . . . . . . . . . . . . 15 A.8. draft-ietf-oauth-jwt-bcp-00 . . . . . . . . . . . . . . . 15
A.9. draft-sheffer-oauth-jwt-bcp-00 . . . . . . . . . . . . . 15 A.9. draft-sheffer-oauth-jwt-bcp-01 . . . . . . . . . . . . . 15
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 15 A.10. draft-sheffer-oauth-jwt-bcp-00 . . . . . . . . . . . . . 15
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 16
1. Introduction 1. Introduction
JSON Web Tokens, also known as JWTs [RFC7519], are URL-safe JSON- JSON Web Tokens, also known as JWTs [RFC7519], are URL-safe JSON-
based security tokens that contain a set of claims that can be signed based security tokens that contain a set of claims that can be signed
and/or encrypted. The JWT specification has seen rapid adoption and/or encrypted. The JWT specification has seen rapid adoption
because it encapsulates security-relevant information in one, easy to because it encapsulates security-relevant information in one easy-to-
protect location, and because it is easy to implement using widely- protect location, and because it is easy to implement using widely-
available tools. One application area in which JWTs are commonly available tools. One application area in which JWTs are commonly
used is representing digital identity information, such as OpenID used is representing digital identity information, such as OpenID
Connect ID Tokens [OpenID.Core] and OAuth 2.0 [RFC6749] access tokens Connect ID Tokens [OpenID.Core] and OAuth 2.0 [RFC6749] access tokens
and refresh tokens, the details of which are deployment-specific. and refresh tokens, the details of which are deployment-specific.
Since the JWT specification was published, there have been several Since the JWT specification was published, there have been several
widely published attacks on implementations and deployments. Such widely published attacks on implementations and deployments. Such
attacks are the result of under-specified security mechanisms, as attacks are the result of under-specified security mechanisms, as
well as incomplete implementations and incorrect usage by well as incomplete implementations and incorrect usage by
applications. applications.
The goal of this document is to facilitate secure implementation and The goal of this document is to facilitate secure implementation and
deployment of JWTs. Many of the recommendations in this document deployment of JWTs. Many of the recommendations in this document are
will actually be about implementation and use of the cryptographic about implementation and use of the cryptographic mechanisms
mechanisms underlying JWTs that are defined by JSON Web Signature underlying JWTs that are defined by JSON Web Signature (JWS)
(JWS) [RFC7515], JSON Web Encryption (JWE) [RFC7516], and JSON Web [RFC7515], JSON Web Encryption (JWE) [RFC7516], and JSON Web
Algorithms (JWA) [RFC7518]. Others will be about use of the JWT Algorithms (JWA) [RFC7518]. Others are about use of the JWT claims
claims themselves. themselves.
These are intended to be minimum recommendations for the use of JWTs These are intended to be minimum recommendations for the use of JWTs
in the vast majority of implementation and deployment scenarios. in the vast majority of implementation and deployment scenarios.
Other specifications that reference this document can have stricter Other specifications that reference this document can have stricter
requirements related to one or more aspects of the format, based on requirements related to one or more aspects of the format, based on
their particular circumstances; when that is the case, implementers their particular circumstances; when that is the case, implementers
are advised to adhere to those stricter requirements. Furthermore, are advised to adhere to those stricter requirements. Furthermore,
this document provides a floor, not a ceiling, so stronger options this document provides a floor, not a ceiling, so stronger options
are always allowed (e.g., depending on differing evaluations of the are always allowed (e.g., depending on differing evaluations of the
importance of cryptographic strength vs. computational load). importance of cryptographic strength vs. computational load).
Community knowledge about the strength of various algorithms and Community knowledge about the strength of various algorithms and
feasible attacks can change quickly, and experience shows that a Best feasible attacks can change quickly, and experience shows that a Best
Current Practice (BCP) document about security is a point-in-time Current Practice (BCP) document about security is a point-in-time
statement. Readers are advised to seek out any errata or updates statement. Readers are advised to seek out any errata or updates
that apply to this document. that apply to this document.
1.1. Target Audience 1.1. Target Audience
The targets of this document are: The intended audience of this document is:
- Implementers of JWT libraries (and the JWS and JWE libraries used - Implementers of JWT libraries (and the JWS and JWE libraries used
by them), by those libraries),
- Implementers of code that uses such libraries (to the extent that - Implementers of code that uses such libraries (to the extent that
some mechanisms may not be provided by libraries, or until they some mechanisms may not be provided by libraries, or until they
are), and are), and
- Developers of specifications that rely on JWTs, both inside and - Developers of specifications that rely on JWTs, both inside and
outside the IETF. outside the IETF.
1.2. Conventions used in this document 1.2. Conventions used in this document
skipping to change at page 5, line 5 skipping to change at page 5, line 5
libraries would trust this value and "validate" the JWT without libraries would trust this value and "validate" the JWT without
checking any signature. checking any signature.
- An "RS256" (RSA, 2048 bit) parameter value can be changed into - An "RS256" (RSA, 2048 bit) parameter value can be changed into
"HS256" (HMAC, SHA-256), and some libraries would try to validate "HS256" (HMAC, SHA-256), and some libraries would try to validate
the signature using HMAC-SHA256 and using the RSA public key as the signature using HMAC-SHA256 and using the RSA public key as
the HMAC shared secret (see [McLean] and CVE-2015-9235). the HMAC shared secret (see [McLean] and CVE-2015-9235).
For mitigations, see Section 3.1 and Section 3.2. For mitigations, see Section 3.1 and Section 3.2.
2.2. Weak symmetric keys 2.2. Weak Symmetric Keys
In addition, some applications sign tokens using a weak symmetric key In addition, some applications use a keyed MAC algorithm such as
and a keyed MAC algorithm such as "HS256". In most cases, these keys "HS256" to sign tokens, but supply a weak symmetric key with
are human memorable passwords that are vulnerable to dictionary insufficient entropy (such as a human memorable password). Such keys
attacks [Langkemper]. are vulnerable to offline brute-force or dictionary attacks once an
attacker gets hold of such a token [Langkemper].
For mitigations, see Section 3.5. For mitigations, see Section 3.5.
2.3. Incorrect Composition of Encryption and Signature 2.3. Incorrect Composition of Encryption and Signature
Some libraries that decrypt a JWE-encrypted JWT to obtain a JWS- Some libraries that decrypt a JWE-encrypted JWT to obtain a JWS-
signed object do not always validate the internal signature. signed object do not always validate the internal signature.
For mitigations, see Section 3.3. For mitigations, see Section 3.3.
2.4. Plaintext Leakage through Analysis of Ciphertext Length 2.4. Plaintext Leakage through Analysis of Ciphertext Length
Many encryption algorithms leak information about the length of the Many encryption algorithms leak information about the length of the
plaintext, with a varying amount of leakage depending on the plaintext, with a varying amount of leakage depending on the
algorithm and mode of operation. This problem is exacerbated when algorithm and mode of operation. This problem is exacerbated when
the plaintext is initially compressed, because the length of the the plaintext is initially compressed, because the length of the
compressed plaintext and thus, the ciphertext, depends not only on compressed plaintext and, thus, the ciphertext depend not only on the
the length of the original plaintext but also on its content. See length of the original plaintext but also on its content.
[Kelsey] for general background on compression and encryption, and Compression attacks are particularly powerful when there is attacker-
[Alawatugoda] for a specific example of attacks on HTTP cookies. controlled data in the same compression space as secret data, as is
the case for some attacks on HTTPS.
See [Kelsey] for general background on compression and encryption,
and [Alawatugoda] for a specific example of attacks on HTTP cookies.
For mitigations, see Section 3.6. For mitigations, see Section 3.6.
2.5. Insecure Use of Elliptic Curve Encryption 2.5. Insecure Use of Elliptic Curve Encryption
Per [Sanso], several JOSE libraries fail to validate their inputs Per [Sanso], several JOSE libraries fail to validate their inputs
correctly when performing elliptic curve key agreement (the "ECDH-ES" correctly when performing elliptic curve key agreement (the "ECDH-ES"
algorithm). An attacker that is able to send JWEs of its choosing algorithm). An attacker that is able to send JWEs of its choosing
that use invalid curve points and observe the cleartext outputs that use invalid curve points and observe the cleartext outputs
resulting from decryption with the invalid curve points can use this resulting from decryption with the invalid curve points can use this
vulnerability to recover the recipient's private key. vulnerability to recover the recipient's private key.
For mitigations, see Section 3.4. For mitigations, see Section 3.4.
2.6. Multiplicity of JSON encodings 2.6. Multiplicity of JSON Encodings
Previous versions of the JSON format such as the obsoleted [RFC7159] Previous versions of the JSON format such as the obsoleted [RFC7159]
allowed several different character encodings: UTF-8, UTF-16 and UTF- allowed several different character encodings: UTF-8, UTF-16 and UTF-
32. This is not the case anymore, with the latest standard [RFC8259] 32. This is not the case anymore, with the latest standard [RFC8259]
only allowing UTF-8. However older implementations may result in the only allowing UTF-8 except for internal use within a "closed
JWT being misinterpreted by its recipient, and this could be used by ecosystem". This ambiguity where older implementations and those
a malicious sender to bypass the recipient's validation checks. used within closed environments may generate non-standard encodings,
may result in the JWT being misinterpreted by its recipient. This in
turn could be used by a malicious sender to bypass the recipient's
validation checks.
For mitigations, see Section 3.7. For mitigations, see Section 3.7.
2.7. Substitution Attacks 2.7. Substitution Attacks
There are attacks in which one recipient will have a JWT intended for There are attacks in which one recipient will be given a JWT that was
it and attempt to use it at a different recipient that it was not intended for it, and will attempt to use it at a different recipient
intended for. If not caught, these attacks can result in the for which that JWT was not intended. For instance, if an OAuth 2.0
attacker gaining access to resources that it is not entitled to [RFC6749] access token is legitimately presented to an OAuth 2.0
access. For instance, if an OAuth 2.0 [RFC6749] access token is protected resource for which it is intended, that protected resource
presented to an OAuth 2.0 protected resource that it is intended for, might then present that same access token to a different protected
that protected resource might then attempt to gain access to a resource for which the access token is not intended, in an attempt to
different protected resource by presenting that same access token to gain access. If such situations are not caught, this can result in
the different protected resource, which the access token is not the attacker gaining access to resources that it is not entitled to
intended for. access.
For mitigations, see Section 3.8 and Section 3.9. For mitigations, see Section 3.8 and Section 3.9.
2.8. Cross-JWT Confusion 2.8. Cross-JWT Confusion
As JWTs are being used by more different protocols in diverse As JWTs are being used by more different protocols in diverse
application areas, it becomes increasingly important to prevent cases application areas, it becomes increasingly important to prevent cases
of JWT tokens that have been issued for one purpose being subverted of JWT tokens that have been issued for one purpose being subverted
and used for another. Note that this is a specific type of and used for another. Note that this is a specific type of
substitution attack. If the JWT could be used in an application substitution attack. If the JWT could be used in an application
context in which it could be confused with other kinds of JWTs, then context in which it could be confused with other kinds of JWTs, then
mitigations MUST be employed to prevent these substitution attacks. mitigations MUST be employed to prevent these substitution attacks.
For mitigations, see Section 3.8, Section 3.9, Section 3.11, and For mitigations, see Section 3.8, Section 3.9, Section 3.11, and
Section 3.12. Section 3.12.
2.9. Indirect Attacks on the Server 2.9. Indirect Attacks on the Server
Various JWT claims are used by the recipient to perform lookup Various JWT claims are used by the recipient to perform lookup
operations, e.g. database and LDAP searches. Others include URLs operations, such as database and LDAP searches. Others include URLs
that are similarly looked up by the server. Any of these claims can that are similarly looked up by the server. Any of these claims can
be used by an attacker as vectors for injection attacks or server- be used by an attacker as vectors for injection attacks or server-
side request forgery (SSRF) attacks. side request forgery (SSRF) attacks.
For mitigations, see Section 3.10. For mitigations, see Section 3.10.
3. Best Practices 3. Best Practices
The best practices listed below should be applied by practitioners to The best practices listed below should be applied by practitioners to
mitigate the threats listed in the preceding section. mitigate the threats listed in the preceding section.
skipping to change at page 7, line 30 skipping to change at page 7, line 39
are acceptable to the application, it SHOULD consider the JWS to be are acceptable to the application, it SHOULD consider the JWS to be
invalid." invalid."
Therefore, applications MUST only allow the use of cryptographically Therefore, applications MUST only allow the use of cryptographically
current algorithms that meet the security requirements of the current algorithms that meet the security requirements of the
application. This set will vary over time as new algorithms are application. This set will vary over time as new algorithms are
introduced and existing algorithms are deprecated due to discovered introduced and existing algorithms are deprecated due to discovered
cryptographic weaknesses. Applications MUST therefore be designed to cryptographic weaknesses. Applications MUST therefore be designed to
enable cryptographic agility. enable cryptographic agility.
That said, if a JWT is cryptographically protected by a transport That said, if a JWT is cryptographically protected end-to-end by a
layer, such as TLS using cryptographically current algorithms, there transport layer, such as TLS using cryptographically current
may be no need to apply another layer of cryptographic protections to algorithms, there may be no need to apply another layer of
the JWT. In such cases, the use of the "none" algorithm can be cryptographic protections to the JWT. In such cases, the use of the
perfectly acceptable. The "none" algorithm should only be used when "none" algorithm can be perfectly acceptable. The "none" algorithm
the JWT is cryptographically protected by other means. JWTs using should only be used when the JWT is cryptographically protected by
"none" are often used in application contexts in which the content is other means. JWTs using "none" are often used in application
optionally signed; then the URL-safe claims representation and contexts in which the content is optionally signed; then the URL-safe
processing can be the same in both the signed and unsigned cases. claims representation and processing can be the same in both the
JWT libraries SHOULD NOT generate JWTs using "none" unless explicitly signed and unsigned cases. JWT libraries SHOULD NOT generate JWTs
requested to do by the caller. using "none" unless explicitly requested to do by the caller.
Similarly, JWT libraries SHOULD NOT consume JWTs using "none" unless
explicitly requested by the caller.
Applications SHOULD follow these algorithm-specific recommendations: Applications SHOULD follow these algorithm-specific recommendations:
- Avoid all RSA-PKCS1 v1.5 [RFC2313] encryption algorithms, - Avoid all RSA-PKCS1 v1.5 encryption algorithms ([RFC8017], Sec.
preferring RSA-OAEP ([RFC8017], Sec. 7.1). 7.2}, preferring RSA-OAEP ([RFC8017], Sec. 7.1).
- ECDSA signatures [ANSI-X962-2005] require a unique random value - ECDSA signatures [ANSI-X962-2005] require a unique random value
for every message that is signed. If even just a few bits of the for every message that is signed. If even just a few bits of the
random value are predictable across multiple messages then the random value are predictable across multiple messages then the
security of the signature scheme may be compromised. In the worst security of the signature scheme may be compromised. In the worst
case, the private key may be recoverable by an attacker. To case, the private key may be recoverable by an attacker. To
counter these attacks, JWT libraries SHOULD implement ECDSA using counter these attacks, JWT libraries SHOULD implement ECDSA using
the deterministic approach defined in [RFC6979]. This approach is the deterministic approach defined in [RFC6979]. This approach is
completely compatible with existing ECDSA verifiers and so can be completely compatible with existing ECDSA verifiers and so can be
implemented without new algorithm identifiers being required. implemented without new algorithm identifiers being required.
skipping to change at page 8, line 22 skipping to change at page 8, line 34
This is true not only of JWTs with a single set of Header Parameters This is true not only of JWTs with a single set of Header Parameters
but also for Nested JWTs, in which both outer and inner operations but also for Nested JWTs, in which both outer and inner operations
MUST be validated using the keys and algorithms supplied by the MUST be validated using the keys and algorithms supplied by the
application. application.
3.4. Validate Cryptographic Inputs 3.4. Validate Cryptographic Inputs
Some cryptographic operations, such as Elliptic Curve Diffie-Hellman Some cryptographic operations, such as Elliptic Curve Diffie-Hellman
key agreement ("ECDH-ES") take inputs that may contain invalid key agreement ("ECDH-ES") take inputs that may contain invalid
values, such as points not on the specified elliptic curve or other values, such as points not on the specified elliptic curve or other
invalid points (see e.g. [Valenta], Sec. 7.1). Either the JWS/JWE invalid points (see, e.g. [Valenta], Sec. 7.1). The JWS/JWE library
library itself must validate these inputs before using them or it itself must validate these inputs before using them or it must use
must use underlying cryptographic libraries that do so (or both!). underlying cryptographic libraries that do so (or both!).
ECDH-ES ephemeral public key (epk) inputs should be validated ECDH-ES ephemeral public key (epk) inputs should be validated
according to the recipient's chosen elliptic curve. For the NIST according to the recipient's chosen elliptic curve. For the NIST
prime-order curves P-256, P-384 and P-521, validation MUST be prime-order curves P-256, P-384 and P-521, validation MUST be
performed according to Section 5.6.2.3.4 "ECC Partial Public-Key performed according to Section 5.6.2.3.4 "ECC Partial Public-Key
Validation Routine" of NIST Special Publication 800-56A revision 3 Validation Routine" of NIST Special Publication 800-56A revision 3
[nist-sp-800-56a-r3]. Likewise, if the "X25519" or "X448" [RFC8037] [nist-sp-800-56a-r3]. Likewise, if the "X25519" or "X448" [RFC8037]
algorithms are used, then the security considerations in [RFC8037] algorithms are used, then the security considerations in [RFC8037]
apply. apply.
skipping to change at page 8, line 41 skipping to change at page 9, line 4
[nist-sp-800-56a-r3]. Likewise, if the "X25519" or "X448" [RFC8037] [nist-sp-800-56a-r3]. Likewise, if the "X25519" or "X448" [RFC8037]
algorithms are used, then the security considerations in [RFC8037] algorithms are used, then the security considerations in [RFC8037]
apply. apply.
3.5. Ensure Cryptographic Keys have Sufficient Entropy 3.5. Ensure Cryptographic Keys have Sufficient Entropy
The Key Entropy and Random Values advice in Section 10.1 of [RFC7515] The Key Entropy and Random Values advice in Section 10.1 of [RFC7515]
and the Password Considerations in Section 8.8 of [RFC7518] MUST be and the Password Considerations in Section 8.8 of [RFC7518] MUST be
followed. In particular, human-memorizable passwords MUST NOT be followed. In particular, human-memorizable passwords MUST NOT be
directly used as the key to a keyed-MAC algorithm such as "HS256". directly used as the key to a keyed-MAC algorithm such as "HS256".
In particular, passwords should only be used to perform key In particular, passwords should only be used to perform key
encryption, rather than content encryption, as described in encryption, rather than content encryption, as described in
Section 4.8 of [RFC7518]. Note that even when used for key Section 4.8 of [RFC7518]. Note that even when used for key
encryption, password-based encryption is still subject to brute-force encryption, password-based encryption is still subject to brute-force
attacks. attacks.
3.6. Avoid Length-Dependent Encryption Inputs 3.6. Avoid Length-Dependent Encryption Inputs
It is RECOMMENDED to avoid any compression of data before encryption Compression of data SHOULD NOT be done before encryption, because
since such compression often reveals information about the plaintext. such compressed data often reveals information about the plaintext.
3.7. Use UTF-8 3.7. Use UTF-8
[RFC7515], [RFC7516], and [RFC7519] all specify that UTF-8 be used [RFC7515], [RFC7516], and [RFC7519] all specify that UTF-8 be used
for encoding and decoding JSON used in Header Parameters and JWT for encoding and decoding JSON used in Header Parameters and JWT
Claims Sets. This is also in line with the latest JSON specification Claims Sets. This is also in line with the latest JSON specification
[RFC8259]. Implementations and applications MUST do this, and not [RFC8259]. Implementations and applications MUST do this, and not
use or admit the use of other Unicode encodings for these purposes. use or admit the use of other Unicode encodings for these purposes.
3.8. Validate Issuer and Subject 3.8. Validate Issuer and Subject
skipping to change at page 9, line 41 skipping to change at page 9, line 52
may include confirming that the issuer is trusted by the application. may include confirming that the issuer is trusted by the application.
If the issuer, subject, or the pair are invalid, the application MUST If the issuer, subject, or the pair are invalid, the application MUST
reject the JWT. reject the JWT.
3.9. Use and Validate Audience 3.9. Use and Validate Audience
If the same issuer can issue JWTs that are intended for use by more If the same issuer can issue JWTs that are intended for use by more
than one relying party or application, the JWT MUST contain an "aud" than one relying party or application, the JWT MUST contain an "aud"
(audience) claim that can be used to determine whether the JWT is (audience) claim that can be used to determine whether the JWT is
being used by an intended party or was substituted by an attacker at being used by an intended party or was substituted by an attacker at
an unintended party. Furthermore, the relying party or application an unintended party.
MUST validate the audience value and if the audience value is not
present or not associated with the recipient, it MUST reject the JWT. In such cases, the relying party or application MUST validate the
audience value and if the audience value is not present or not
associated with the recipient, it MUST reject the JWT.
3.10. Do Not Trust Received Claims 3.10. Do Not Trust Received Claims
The "kid" (key ID) header is used by the relying application to The "kid" (key ID) header is used by the relying application to
perform key lookup. Applications should ensure that this does not perform key lookup. Applications should ensure that this does not
create SQL or LDAP injection vulnerabilities, by validating and/or create SQL or LDAP injection vulnerabilities, by validating and/or
sanitizing the received value. sanitizing the received value.
Similarly, blindly following a "jku" (JWK set URL) or "x5u" (X.509 Similarly, blindly following a "jku" (JWK set URL) or "x5u" (X.509
URL) header, which may contain an arbitrary URL, could result in URL) header, which may contain an arbitrary URL, could result in
server-side request forgery (SSRF) attacks. Applications should server-side request forgery (SSRF) attacks. Applications SHOULD
protect against such attacks, e.g., by matching the URL to a protect against such attacks, e.g., by matching the URL to a
whitelist of allowed locations, and ensuring no cookies are sent in whitelist of allowed locations, and ensuring no cookies are sent in
the GET request. the GET request.
3.11. Use Explicit Typing 3.11. Use Explicit Typing
Confusion of one kind of JWT for another can be prevented by having Sometimes, one kind of JWT can be confused for another. If a
all the kinds of JWTs that could otherwise potentially be confused particular kind of JWT is subject to such confusion, that JWT can
include an explicit JWT type value and include checking the type include an explicit JWT type value, and the validation rules can
value in their validation rules. Explicit JWT typing is accomplished specify checking the type. This mechanism can prevent such
by using the "typ" header parameter. For instance, the [RFC8417] confusion. Explicit JWT typing is accomplished by using the "typ"
specification uses the "application/secevent+jwt" media type to header parameter. For instance, the [RFC8417] specification uses the
perform explicit typing of Security Event Tokens (SETs). "application/secevent+jwt" media type to perform explicit typing of
Security Event Tokens (SETs).
Per the definition of "typ" in Section 4.1.9 of [RFC7515], it is Per the definition of "typ" in Section 4.1.9 of [RFC7515], it is
RECOMMENDED that the "application/" prefix be omitted from the "typ" RECOMMENDED that the "application/" prefix be omitted from the "typ"
value. Therefore, for example, the "typ" value used to explicitly value. Therefore, for example, the "typ" value used to explicitly
include a type for a SET SHOULD be "secevent+jwt". When explicit include a type for a SET SHOULD be "secevent+jwt". When explicit
typing is employed for a JWT, it is RECOMMENDED that a media type typing is employed for a JWT, it is RECOMMENDED that a media type
name of the format "application/example+jwt" be used, where "example" name of the format "application/example+jwt" be used, where "example"
is replaced by the identifier for the specific kind of JWT. is replaced by the identifier for the specific kind of JWT.
When applying explicit typing to a Nested JWT, the "typ" header When applying explicit typing to a Nested JWT, the "typ" header
parameter containing the explicit type value MUST be present in the parameter containing the explicit type value MUST be present in the
inner JWT of the Nested JWT (the JWT whose payload is the JWT Claims inner JWT of the Nested JWT (the JWT whose payload is the JWT Claims
Set). The same "typ" header parameter value MAY be present in the Set). In some cases the same "typ" header parameter value will be
outer JWT as well, to explicitly type the entire Nested JWT. present in the outer JWT as well, to explicitly type the entire
Nested JWT.
Note that the use of explicit typing may not achieve disambiguation Note that the use of explicit typing may not achieve disambiguation
from existing kinds of JWTs, as the validation rules for existing from existing kinds of JWTs, as the validation rules for existing
kinds JWTs often do not use the "typ" header parameter value. kinds JWTs often do not use the "typ" header parameter value.
Explicit typing is RECOMMENDED for new uses of JWTs. Explicit typing is RECOMMENDED for new uses of JWTs.
3.12. Use Mutually Exclusive Validation Rules for Different Kinds of 3.12. Use Mutually Exclusive Validation Rules for Different Kinds of
JWTs JWTs
Each application of JWTs defines a profile specifying the required Each application of JWTs defines a profile specifying the required
and optional JWT claims and the validation rules associated with and optional JWT claims and the validation rules associated with
them. If more than one kind of JWT can be issued by the same issuer, them. If more than one kind of JWT can be issued by the same issuer,
the validation rules for those JWTs MUST be written such that they the validation rules for those JWTs MUST be written such that they
are mutually exclusive, rejecting JWTs of the wrong kind. To prevent are mutually exclusive, rejecting JWTs of the wrong kind. To prevent
substitution of JWTs from one context into another, a number of substitution of JWTs from one context into another, application
strategies may be employed: developers may employ a number of strategies:
- Use explicit typing for different kinds of JWTs. Then the - Use explicit typing for different kinds of JWTs. Then the
distinct "typ" values can be used to differentiate between the distinct "typ" values can be used to differentiate between the
different kinds of JWTs. different kinds of JWTs.
- Use different sets of required claims or different required claim - Use different sets of required claims or different required claim
values. Then the validation rules for one kind of JWT will reject values. Then the validation rules for one kind of JWT will reject
those with different claims or values. those with different claims or values.
- Use different sets of required header parameters or different - Use different sets of required header parameters or different
skipping to change at page 11, line 33 skipping to change at page 11, line 44
same issuer. Then audience validation will reject JWTs same issuer. Then audience validation will reject JWTs
substituted into inappropriate contexts. substituted into inappropriate contexts.
- Use different issuers for different kinds of JWTs. Then the - Use different issuers for different kinds of JWTs. Then the
distinct "iss" values can be used to segregate the different kinds distinct "iss" values can be used to segregate the different kinds
of JWTs. of JWTs.
Given the broad diversity of JWT usage and applications, the best Given the broad diversity of JWT usage and applications, the best
combination of types, required claims, values, header parameters, key combination of types, required claims, values, header parameters, key
usages, and issuers to differentiate among different kinds of JWTs usages, and issuers to differentiate among different kinds of JWTs
will, in general, be application specific. For new JWT applications, will, in general, be application specific. As discussed in
the use of explicit typing is RECOMMENDED. Section 3.11, for new JWT applications, the use of explicit typing is
RECOMMENDED.
4. Security Considerations 4. Security Considerations
This entire document is about security considerations when This entire document is about security considerations when
implementing and deploying JSON Web Tokens. implementing and deploying JSON Web Tokens.
5. IANA Considerations 5. IANA Considerations
This document requires no IANA actions. This document requires no IANA actions.
6. Acknowledgements 6. Acknowledgements
Thanks to Antonio Sanso for bringing the "ECDH-ES" invalid point Thanks to Antonio Sanso for bringing the "ECDH-ES" invalid point
attack to the attention of JWE and JWT implementers. Tim McLean attack to the attention of JWE and JWT implementers. Tim McLean
[McLean] published the RSA/HMAC confusion attack. Thanks to Nat [McLean] published the RSA/HMAC confusion attack. Thanks to Nat
Sakimura for advocating the use of explicit typing. Thanks to Neil Sakimura for advocating the use of explicit typing. Thanks to Neil
Madden for his numerous comments, and to Carsten Bormann, Brian Madden for his numerous comments, and to Carsten Bormann, Brian
Campbell, Brian Carpenter, Roman Danyliw and Eric Rescorla for their Campbell, Brian Carpenter, Alissa Cooper, Roman Danyliw, Ben Kaduk,
reviews. Mirja Kuehlewind, Barry Leiba, Eric Rescorla, Adam Roach, Martin
Vigoureux, and Eric Vyncke for their reviews.
7. References 7. References
7.1. Normative References 7.1. Normative References
[nist-sp-800-56a-r3]
Barker, E., Chen, L., Keller, S., Roginsky, A., Vassilev,
A., and R. Davis, "Recommendation for Pair-Wise Key
Establishment Schemes Using Discrete Logarithm
Cryptography, Draft NIST Special Publication 800-56A
Revision 3", April 2018,
<https://doi.org/10.6028/NIST.SP.800-56Ar3>.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997, DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>. <https://www.rfc-editor.org/info/rfc2119>.
[RFC6979] Pornin, T., "Deterministic Usage of the Digital Signature [RFC6979] Pornin, T., "Deterministic Usage of the Digital Signature
Algorithm (DSA) and Elliptic Curve Digital Signature Algorithm (DSA) and Elliptic Curve Digital Signature
Algorithm (ECDSA)", RFC 6979, DOI 10.17487/RFC6979, August Algorithm (ECDSA)", RFC 6979, DOI 10.17487/RFC6979, August
2013, <https://www.rfc-editor.org/info/rfc6979>. 2013, <https://www.rfc-editor.org/info/rfc6979>.
skipping to change at page 13, line 32 skipping to change at page 13, line 50
[Kelsey] Kelsey, J., "Compression and Information Leakage of [Kelsey] Kelsey, J., "Compression and Information Leakage of
Plaintext", Fast Software Encryption pp. 263-276, Plaintext", Fast Software Encryption pp. 263-276,
DOI 10.1007/3-540-45661-9_21, 2002. DOI 10.1007/3-540-45661-9_21, 2002.
[Langkemper] [Langkemper]
Langkemper, S., "Attacking JWT Authentication", September Langkemper, S., "Attacking JWT Authentication", September
2016, <https://www.sjoerdlangkemper.nl/2016/09/28/ 2016, <https://www.sjoerdlangkemper.nl/2016/09/28/
attacking-jwt-authentication/>. attacking-jwt-authentication/>.
[McLean] McLean, T., "Critical vulnerabilities in JSON Web Token [McLean] McLean, T., "Critical vulnerabilities in JSON Web Token
libraries", March 2015, <https://auth0.com/blog/ libraries", March 2015, <https://auth0.com/blog/critical-
critical-vulnerabilities-in-json-web-token-libraries//>. vulnerabilities-in-json-web-token-libraries//>.
[nist-sp-800-56a-r3]
Barker, E., Chen, L., Keller, S., Roginsky, A., Vassilev,
A., and R. Davis, "Recommendation for Pair-Wise Key
Establishment Schemes Using Discrete Logarithm
Cryptography, Draft NIST Special Publication 800-56A
Revision 3", April 2018,
<https://doi.org/10.6028/NIST.SP.800-56Ar3>.
[OpenID.Core] [OpenID.Core]
Sakimura, N., Bradley, J., Jones, M., Medeiros, B., and C. Sakimura, N., Bradley, J., Jones, M., Medeiros, B., and C.
Mortimore, "OpenID Connect Core 1.0", November 2014, Mortimore, "OpenID Connect Core 1.0", November 2014,
<http://openid.net/specs/openid-connect-core-1_0.html>. <http://openid.net/specs/openid-connect-core-1_0.html>.
[RFC2313] Kaliski, B., "PKCS #1: RSA Encryption Version 1.5",
RFC 2313, DOI 10.17487/RFC2313, March 1998,
<https://www.rfc-editor.org/info/rfc2313>.
[RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework",
RFC 6749, DOI 10.17487/RFC6749, October 2012, RFC 6749, DOI 10.17487/RFC6749, October 2012,
<https://www.rfc-editor.org/info/rfc6749>. <https://www.rfc-editor.org/info/rfc6749>.
[RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March
2014, <https://www.rfc-editor.org/info/rfc7159>. 2014, <https://www.rfc-editor.org/info/rfc7159>.
[RFC7517] Jones, M., "JSON Web Key (JWK)", RFC 7517, [RFC7517] Jones, M., "JSON Web Key (JWK)", RFC 7517,
DOI 10.17487/RFC7517, May 2015, DOI 10.17487/RFC7517, May 2015,
skipping to change at page 14, line 29 skipping to change at page 14, line 34
DOI 10.17487/RFC8414, June 2018, DOI 10.17487/RFC8414, June 2018,
<https://www.rfc-editor.org/info/rfc8414>. <https://www.rfc-editor.org/info/rfc8414>.
[RFC8417] Hunt, P., Ed., Jones, M., Denniss, W., and M. Ansari, [RFC8417] Hunt, P., Ed., Jones, M., Denniss, W., and M. Ansari,
"Security Event Token (SET)", RFC 8417, "Security Event Token (SET)", RFC 8417,
DOI 10.17487/RFC8417, July 2018, DOI 10.17487/RFC8417, July 2018,
<https://www.rfc-editor.org/info/rfc8417>. <https://www.rfc-editor.org/info/rfc8417>.
[Sanso] Sanso, A., "Critical Vulnerability Uncovered in JSON [Sanso] Sanso, A., "Critical Vulnerability Uncovered in JSON
Encryption", March 2017, Encryption", March 2017,
<https://blogs.adobe.com/security/2017/03/ <https://blogs.adobe.com/security/2017/03/critical-
critical-vulnerability-uncovered-in-json-encryption.html>. vulnerability-uncovered-in-json-encryption.html>.
[Valenta] Valenta, L., Sullivan, N., Sanso, A., and N. Heninger, "In [Valenta] Valenta, L., Sullivan, N., Sanso, A., and N. Heninger, "In
search of CurveSwap: Measuring elliptic curve search of CurveSwap: Measuring elliptic curve
implementations in the wild", March 2018, implementations in the wild", March 2018,
<https://ia.cr/2018/298>. <https://ia.cr/2018/298>.
Appendix A. Document History Appendix A. Document History
[[ to be removed by the RFC editor before publication as an RFC ]] [[ to be removed by the RFC editor before publication as an RFC ]]
A.1. draft-ietf-oauth-jwt-bcp-06 A.1. draft-ietf-oauth-jwt-bcp-07
- IESG review comments.
A.2. draft-ietf-oauth-jwt-bcp-06
- Second AD review. - Second AD review.
- Removed unworkable recommendation to pad encrypted passwords. - Removed unworkable recommendation to pad encrypted passwords.
A.2. draft-ietf-oauth-jwt-bcp-05 A.3. draft-ietf-oauth-jwt-bcp-05
- Genart review comments. - Genart review comments.
A.3. draft-ietf-oauth-jwt-bcp-04 A.4. draft-ietf-oauth-jwt-bcp-04
- AD review comments. - AD review comments.
A.4. draft-ietf-oauth-jwt-bcp-03 A.5. draft-ietf-oauth-jwt-bcp-03
- Acknowledgements. - Acknowledgements.
A.5. draft-ietf-oauth-jwt-bcp-02 A.6. draft-ietf-oauth-jwt-bcp-02
- Implemented WGLC feedback. - Implemented WGLC feedback.
A.6. draft-ietf-oauth-jwt-bcp-01 A.7. draft-ietf-oauth-jwt-bcp-01
- Feedback from Brian Campbell. - Feedback from Brian Campbell.
A.7. draft-ietf-oauth-jwt-bcp-00 A.8. draft-ietf-oauth-jwt-bcp-00
- Initial WG draft. No change from the latest individual version. - Initial WG draft. No change from the latest individual version.
A.8. draft-sheffer-oauth-jwt-bcp-01 A.9. draft-sheffer-oauth-jwt-bcp-01
- Added explicit typing. - Added explicit typing.
A.9. draft-sheffer-oauth-jwt-bcp-00 A.10. draft-sheffer-oauth-jwt-bcp-00
- Initial version. - Initial version.
Authors' Addresses Authors' Addresses
Yaron Sheffer Yaron Sheffer
Intuit Intuit
EMail: yaronf.ietf@gmail.com EMail: yaronf.ietf@gmail.com
Dick Hardt Dick Hardt
EMail: dick.hardt@gmail.com EMail: dick.hardt@gmail.com
Michael B. Jones Michael B. Jones
Microsoft Microsoft
EMail: mbj@microsoft.com EMail: mbj@microsoft.com
URI: http://self-issued.info/ URI: http://self-issued.info/
 End of changes. 49 change blocks. 
119 lines changed or deleted 138 lines changed or added

This html diff was produced by rfcdiff 1.47. The latest version is available from http://tools.ietf.org/tools/rfcdiff/