--- 1/draft-ietf-jose-json-web-signature-31.txt 2014-09-23 16:14:40.100077602 -0700 +++ 2/draft-ietf-jose-json-web-signature-32.txt 2014-09-23 16:14:40.212080329 -0700 @@ -1,21 +1,21 @@ JOSE Working Group M. Jones Internet-Draft Microsoft Intended status: Standards Track J. Bradley -Expires: January 5, 2015 Ping Identity +Expires: March 27, 2015 Ping Identity N. Sakimura NRI - July 4, 2014 + September 23, 2014 JSON Web Signature (JWS) - draft-ietf-jose-json-web-signature-31 + draft-ietf-jose-json-web-signature-32 Abstract JSON Web Signature (JWS) represents content secured with digital signatures or Message Authentication Codes (MACs) using JavaScript Object Notation (JSON) based data structures. Cryptographic algorithms and identifiers for use with this specification are described in the separate JSON Web Algorithms (JWA) specification and an IANA registry defined by that specification. Related encryption capabilities are described in the separate JSON Web Encryption (JWE) @@ -29,127 +29,134 @@ Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at http://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." - This Internet-Draft will expire on January 5, 2015. + This Internet-Draft will expire on March 27, 2015. Copyright Notice Copyright (c) 2014 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 - 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 4 + 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 4 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 3. JSON Web Signature (JWS) Overview . . . . . . . . . . . . . . 6 - 3.1. JWS Compact Serialization Overview . . . . . . . . . . . . 7 + 3.1. JWS Compact Serialization Overview . . . . . . . . . . . 7 3.2. JWS JSON Serialization Overview . . . . . . . . . . . . . 7 3.3. Example JWS . . . . . . . . . . . . . . . . . . . . . . . 8 4. JOSE Header . . . . . . . . . . . . . . . . . . . . . . . . . 9 - 4.1. Registered Header Parameter Names . . . . . . . . . . . . 10 + 4.1. Registered Header Parameter Names . . . . . . . . . . . . 9 4.1.1. "alg" (Algorithm) Header Parameter . . . . . . . . . . 10 4.1.2. "jku" (JWK Set URL) Header Parameter . . . . . . . . . 10 4.1.3. "jwk" (JSON Web Key) Header Parameter . . . . . . . . 10 - 4.1.4. "kid" (Key ID) Header Parameter . . . . . . . . . . . 11 + 4.1.4. "kid" (Key ID) Header Parameter . . . . . . . . . . . 10 4.1.5. "x5u" (X.509 URL) Header Parameter . . . . . . . . . . 11 4.1.6. "x5c" (X.509 Certificate Chain) Header Parameter . . . 11 4.1.7. "x5t" (X.509 Certificate SHA-1 Thumbprint) Header - Parameter . . . . . . . . . . . . . . . . . . . . . . 12 + Parameter . . . . . . . . . . . . . . . . . . . . . . 11 4.1.8. "x5t#S256" (X.509 Certificate SHA-256 Thumbprint) - Header Parameter . . . . . . . . . . . . . . . . . . . 12 + Header Parameter . . . . . . . . . . . . . . . . . . . 11 4.1.9. "typ" (Type) Header Parameter . . . . . . . . . . . . 12 - 4.1.10. "cty" (Content Type) Header Parameter . . . . . . . . 13 + 4.1.10. "cty" (Content Type) Header Parameter . . . . . . . . 12 4.1.11. "crit" (Critical) Header Parameter . . . . . . . . . . 13 4.2. Public Header Parameter Names . . . . . . . . . . . . . . 14 - 4.3. Private Header Parameter Names . . . . . . . . . . . . . . 14 + 4.3. Private Header Parameter Names . . . . . . . . . . . . . 14 5. Producing and Consuming JWSs . . . . . . . . . . . . . . . . . 14 - 5.1. Message Signature or MAC Computation . . . . . . . . . . . 14 + 5.1. Message Signature or MAC Computation . . . . . . . . . . 14 5.2. Message Signature or MAC Validation . . . . . . . . . . . 15 5.3. String Comparison Rules . . . . . . . . . . . . . . . . . 16 6. Key Identification . . . . . . . . . . . . . . . . . . . . . . 17 7. Serializations . . . . . . . . . . . . . . . . . . . . . . . . 17 7.1. JWS Compact Serialization . . . . . . . . . . . . . . . . 18 - 7.2. JWS JSON Serialization . . . . . . . . . . . . . . . . . . 18 - 8. TLS Requirements . . . . . . . . . . . . . . . . . . . . . . . 19 + 7.2. JWS JSON Serialization . . . . . . . . . . . . . . . . . 18 + 8. TLS Requirements . . . . . . . . . . . . . . . . . . . . . . . 20 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 20 9.1. JSON Web Signature and Encryption Header Parameters - Registry . . . . . . . . . . . . . . . . . . . . . . . . . 21 - 9.1.1. Registration Template . . . . . . . . . . . . . . . . 21 + Registry . . . . . . . . . . . . . . . . . . . . . . . . 21 + 9.1.1. Registration Template . . . . . . . . . . . . . . . . 22 9.1.2. Initial Registry Contents . . . . . . . . . . . . . . 22 - 9.2. Media Type Registration . . . . . . . . . . . . . . . . . 23 - 9.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 23 - 10. Security Considerations . . . . . . . . . . . . . . . . . . . 24 - 10.1. Key Entropy . . . . . . . . . . . . . . . . . . . . . . . 25 - 10.2. Chosen Plaintext Attacks . . . . . . . . . . . . . . . . . 25 - 10.3. Timing Attacks . . . . . . . . . . . . . . . . . . . . . . 25 - 10.4. Differences between Digital Signatures and MACs . . . . . 25 - 10.5. SHA-1 Certificate Thumbprints . . . . . . . . . . . . . . 26 - 10.6. JSON Security Considerations . . . . . . . . . . . . . . . 26 - 10.7. Unicode Comparison Security Considerations . . . . . . . . 27 - 11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 27 - 11.1. Normative References . . . . . . . . . . . . . . . . . . . 27 - 11.2. Informative References . . . . . . . . . . . . . . . . . . 29 - Appendix A. JWS Examples . . . . . . . . . . . . . . . . . . . . 30 - A.1. Example JWS using HMAC SHA-256 . . . . . . . . . . . . . . 30 - A.1.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 30 - A.1.2. Validating . . . . . . . . . . . . . . . . . . . . . . 32 - A.2. Example JWS using RSASSA-PKCS-v1_5 SHA-256 . . . . . . . . 32 - A.2.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 33 - A.2.2. Validating . . . . . . . . . . . . . . . . . . . . . . 35 - A.3. Example JWS using ECDSA P-256 SHA-256 . . . . . . . . . . 35 - A.3.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 35 - A.3.2. Validating . . . . . . . . . . . . . . . . . . . . . . 37 - A.4. Example JWS using ECDSA P-521 SHA-512 . . . . . . . . . . 38 - A.4.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 38 - A.4.2. Validating . . . . . . . . . . . . . . . . . . . . . . 40 - A.5. Example Plaintext JWS . . . . . . . . . . . . . . . . . . 40 - A.6. Example JWS Using JWS JSON Serialization . . . . . . . . . 41 - A.6.1. JWS Per-Signature Protected Headers . . . . . . . . . 41 - A.6.2. JWS Per-Signature Unprotected Headers . . . . . . . . 42 - A.6.3. Complete JOSE Header Values . . . . . . . . . . . . . 42 - A.6.4. Complete JWS JSON Serialization Representation . . . . 42 - Appendix B. "x5c" (X.509 Certificate Chain) Example . . . . . . . 43 + 9.2. Media Type Registration . . . . . . . . . . . . . . . . . 24 + 9.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 24 + 10. Security Considerations . . . . . . . . . . . . . . . . . . . 25 + 10.1. Key Entropy and Random Values . . . . . . . . . . . . . . 25 + 10.2. Key Protection . . . . . . . . . . . . . . . . . . . . . 26 + 10.3. Key Origin Authentication . . . . . . . . . . . . . . . . 26 + 10.4. Cryptographic Agility . . . . . . . . . . . . . . . . . . 26 + 10.5. Differences between Digital Signatures and MACs . . . . . 26 + 10.6. Algorithm Validation . . . . . . . . . . . . . . . . . . 27 + 10.7. Algorithm Protection . . . . . . . . . . . . . . . . . . 27 + 10.8. Chosen Plaintext Attacks . . . . . . . . . . . . . . . . 28 + 10.9. Timing Attacks . . . . . . . . . . . . . . . . . . . . . 28 + 10.10. Replay Protection . . . . . . . . . . . . . . . . . . . . 28 + 10.11. SHA-1 Certificate Thumbprints . . . . . . . . . . . . . . 28 + 10.12. JSON Security Considerations . . . . . . . . . . . . . . 28 + 10.13. Unicode Comparison Security Considerations . . . . . . . 29 + 11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 30 + 11.1. Normative References . . . . . . . . . . . . . . . . . . 30 + 11.2. Informative References . . . . . . . . . . . . . . . . . 31 + Appendix A. JWS Examples . . . . . . . . . . . . . . . . . . . . 32 + A.1. Example JWS using HMAC SHA-256 . . . . . . . . . . . . . 32 + A.1.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 33 + A.1.2. Validating . . . . . . . . . . . . . . . . . . . . . . 35 + A.2. Example JWS using RSASSA-PKCS-v1_5 SHA-256 . . . . . . . 35 + A.2.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 35 + A.2.2. Validating . . . . . . . . . . . . . . . . . . . . . . 38 + A.3. Example JWS using ECDSA P-256 SHA-256 . . . . . . . . . . 38 + A.3.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 38 + A.3.2. Validating . . . . . . . . . . . . . . . . . . . . . . 40 + A.4. Example JWS using ECDSA P-521 SHA-512 . . . . . . . . . . 41 + A.4.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 41 + A.4.2. Validating . . . . . . . . . . . . . . . . . . . . . . 43 + A.5. Example Unsecured JWS . . . . . . . . . . . . . . . . . . 43 + A.6. Example JWS Using JWS JSON Serialization . . . . . . . . 44 + A.6.1. JWS Per-Signature Protected Headers . . . . . . . . . 44 + A.6.2. JWS Per-Signature Unprotected Headers . . . . . . . . 45 + A.6.3. Complete JOSE Header Values . . . . . . . . . . . . . 45 + A.6.4. Complete JWS JSON Serialization Representation . . . . 45 + Appendix B. "x5c" (X.509 Certificate Chain) Example . . . . . . . 46 Appendix C. Notes on implementing base64url encoding without - padding . . . . . . . . . . . . . . . . . . . . . . . 45 - Appendix D. Notes on Key Selection . . . . . . . . . . . . . . . 46 - Appendix E. Negative Test Case for "crit" Header Parameter . . . 47 - Appendix F. Detached Content . . . . . . . . . . . . . . . . . . 48 - Appendix G. Acknowledgements . . . . . . . . . . . . . . . . . . 48 - Appendix H. Document History . . . . . . . . . . . . . . . . . . 49 - Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 58 + padding . . . . . . . . . . . . . . . . . . . . . . . 48 + Appendix D. Notes on Key Selection . . . . . . . . . . . . . . . 49 + Appendix E. Negative Test Case for "crit" Header Parameter . . . 50 + Appendix F. Detached Content . . . . . . . . . . . . . . . . . . 51 + Appendix G. Acknowledgements . . . . . . . . . . . . . . . . . . 51 + Appendix H. Document History . . . . . . . . . . . . . . . . . . 52 + Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 61 1. Introduction JSON Web Signature (JWS) represents content secured with digital signatures or Message Authentication Codes (MACs) using JavaScript Object Notation (JSON) [RFC7159] based data structures. The JWS cryptographic mechanisms provide integrity protection for an - arbitrary sequence of octets. + arbitrary sequence of octets. See Section 10.5 for a discussion on + the differences between Digital Signatures and MACs. Two closely related serializations for JWS objects are defined. The JWS Compact Serialization is a compact, URL-safe representation intended for space constrained environments such as HTTP Authorization headers and URI query parameters. The JWS JSON Serialization represents JWS objects as JSON objects and enables multiple signatures and/or MACs to be applied to the same content. Both share the same cryptographic underpinnings. Cryptographic algorithms and identifiers for use with this @@ -183,22 +190,22 @@ 2. Terminology These terms are defined by this specification: JSON Web Signature (JWS) A data structure representing a digitally signed or MACed message. JOSE Header JSON object containing the parameters describing the cryptographic - operations and parameters employed. The members of the JOSE - Header are Header Parameters. + operations and parameters employed. The JOSE Header is comprised + of a set of Header Parameters. JWS Payload The sequence of octets to be secured -- a.k.a., the message. The payload can contain an arbitrary sequence of octets. JWS Signature Digital signature or MAC over the JWS Protected Header and the JWS Payload. Header Parameter @@ -232,21 +239,21 @@ JWS Compact Serialization A representation of the JWS as a compact, URL-safe string. JWS JSON Serialization A representation of the JWS as a JSON object. Unlike the JWS Compact Serialization, the JWS JSON Serialization enables multiple digital signatures and/or MACs to be applied to the same content. This representation is neither optimized for compactness nor URL- safe. - Plaintext JWS + Unsecured JWS A JWS object that provides no integrity protection. Collision-Resistant Name A name in a namespace that enables names to be allocated in a manner such that they are highly unlikely to collide with other names. Examples of collision-resistant namespaces include: Domain Names, Object Identifiers (OIDs) as defined in the ITU-T X.660 and X.670 Recommendation series, and Universally Unique IDentifiers (UUIDs) [RFC4122]. When using an administratively delegated namespace, the definer of a name needs to take reasonable @@ -260,68 +267,53 @@ compared as case-sensitive strings with no transformations or canonicalizations applied. These terms defined by the JSON Web Encryption (JWE) [JWE] specification are incorporated into this specification: "JSON Web Encryption (JWE)" and "JWE Compact Serialization". 3. JSON Web Signature (JWS) Overview JWS represents digitally signed or MACed content using JSON data - structures and base64url encoding. A JWS represents these logical - values: - - JOSE Header - JSON object containing the parameters describing the cryptographic - operations and parameters employed. For a JWS object, the JOSE - Header members are the union of the members of the JWS Protected - Header and the JWS Unprotected Header, as described below. - - JWS Payload - The sequence of octets to be secured -- a.k.a., the message. The - payload can contain an arbitrary sequence of octets. - - JWS Signature - Digital signature or MAC over the JWS Protected Header and the JWS - Payload. + structures and base64url encoding. These JSON data structures MAY + contain white space and/or line breaks. A JWS represents these + logical values (each of which is defined in Section 2): - For a JWS object, the JOSE Header represents the combination of these - values: + o JOSE Header + o JWS Payload + o JWS Signature - JWS Protected Header - JSON object that contains the Header Parameters that are integrity - protected by the JWS Signature digital signature or MAC operation. + For a JWS object, the JOSE Header members are the union of the + members of these values (each of which is defined in Section 2): - JWS Unprotected Header - JSON object that contains the Header Parameters that are not - integrity protected. + o JWS Protected Header + o JWS Unprotected Header This document defines two serializations for JWS objects: a compact, URL-safe serialization called the JWS Compact Serialization and a JSON serialization called the JWS JSON Serialization. In both serializations, the JWS Protected Header, JWS Payload, and JWS Signature are base64url encoded for transmission, since JSON lacks a - way to directly represent octet sequences. + way to directly represent arbitrary octet sequences. 3.1. JWS Compact Serialization Overview In the JWS Compact Serialization, no JWS Unprotected Header is used. In this case, the JOSE Header and the JWS Protected Header are the same. In the JWS Compact Serialization, a JWS object is represented as the - combination of these three string values, - BASE64URL(UTF8(JWS Protected Header)), - BASE64URL(JWS Payload), and - BASE64URL(JWS Signature), - concatenated in that order, with the three strings being separated by - two period ('.') characters. + concatenation: + + BASE64URL(UTF8(JWS Protected Header)) || '.' || + BASE64URL(JWS Payload) || '.' || + BASE64URL(JWS Signature) 3.2. JWS JSON Serialization Overview In the JWS JSON Serialization, one or both of the JWS Protected Header and JWS Unprotected Header MUST be present. In this case, the members of the JOSE Header are the combination of the members of the JWS Protected Header and the JWS Unprotected Header values that are present. In the JWS JSON Serialization, a JWS object is represented as the @@ -425,30 +417,29 @@ below. As indicated by the common registry, JWSs and JWEs share a common Header Parameter space; when a parameter is used by both specifications, its usage must be compatible between the specifications. 4.1.1. "alg" (Algorithm) Header Parameter The "alg" (algorithm) Header Parameter identifies the cryptographic - algorithm used to secure the JWS. The signature, MAC, or plaintext - value is not valid if the "alg" value does not represent a supported - algorithm, or if there is not a key for use with that algorithm - associated with the party that digitally signed or MACed the content. - "alg" values should either be registered in the IANA JSON Web - Signature and Encryption Algorithms registry defined in [JWA] or be a - value that contains a Collision-Resistant Name. The "alg" value is a - case-sensitive string containing a StringOrURI value. This Header - Parameter MUST be present and MUST be understood and processed by - implementations. + algorithm used to secure the JWS. The JWS Signature value is not + valid if the "alg" value does not represent a supported algorithm, or + if there is not a key for use with that algorithm associated with the + party that digitally signed or MACed the content. "alg" values should + either be registered in the IANA JSON Web Signature and Encryption + Algorithms registry defined in [JWA] or be a value that contains a + Collision-Resistant Name. The "alg" value is a case-sensitive string + containing a StringOrURI value. This Header Parameter MUST be + present and MUST be understood and processed by implementations. A list of defined "alg" values for this use can be found in the IANA JSON Web Signature and Encryption Algorithms registry defined in [JWA]; the initial contents of this registry are the values defined in Section 3.1 of the JSON Web Algorithms (JWA) [JWA] specification. 4.1.2. "jku" (JWK Set URL) Header Parameter The "jku" (JWK Set URL) Header Parameter is a URI [RFC3986] that refers to a resource for a set of JSON-encoded public keys, one of @@ -683,26 +674,26 @@ Section 7.2. 5.2. Message Signature or MAC Validation When validating a JWS, the following steps MUST be taken. The order of the steps is not significant in cases where there are no dependencies between the inputs and outputs of the steps. If any of the listed steps fails, then the signature or MAC cannot be validated. - It is an application decision which signatures, MACs, or plaintext - values must successfully validate for the JWS to be accepted. In - some cases, all must successfully validate or the JWS will be - rejected. In other cases, only a specific signature, MAC, or - plaintext value needs to be successfully validated. However, in all - cases, at least one signature, MAC, or plaintext value MUST + When there are multiple JWS Signature values, it is an application + decision which of the JWS Signature values must successfully validate + for the JWS to be accepted. In some cases, all must successfully + validate or the JWS will be rejected. In other cases, only a + specific JWS signature value needs to be successfully validated. + However, in all cases, at least one JWS signature value MUST successfully validate or the JWS MUST be rejected. 1. Parse the JWS representation to extract the serialized values for the components of the JWS. When using the JWS Compact Serialization, these components are the base64url encoded representations of the JWS Protected Header, the JWS Payload, and the JWS Signature, and when using the JWS JSON Serialization, these components also include the unencoded JWS Unprotected Header value. When using the JWS Compact Serialization, the JWS Protected Header, the JWS Payload, and @@ -729,48 +721,60 @@ fields that it is required to support, whether required by this specification, by the algorithm being used, or by the "crit" Header Parameter value, and that the values of those parameters are also understood and supported. 7. The encoded representation of the JWS Payload MUST be successfully base64url decoded following the restriction that no padding characters have been used. 8. The encoded representation of the JWS Signature MUST be successfully base64url decoded following the restriction that no padding characters have been used. - 9. The JWS Signature MUST be successfully validated against the JWS - Signing Input ASCII(BASE64URL(UTF8(JWS Protected Header)) || '.' - || BASE64URL(JWS Payload)) in the manner defined for the - algorithm being used, which MUST be accurately represented by - the value of the "alg" (algorithm) Header Parameter, which MUST - be present. + 9. Validate the JWS Signature against the JWS Signing Input + ASCII(BASE64URL(UTF8(JWS Protected Header)) || '.' || + BASE64URL(JWS Payload)) in the manner defined for the algorithm + being used, which MUST be accurately represented by the value of + the "alg" (algorithm) Header Parameter, which MUST be present. + See Section 10.6 for security considerations on algorithm + validation. Record whether the validation succeeded or not. 10. If the JWS JSON Serialization is being used, repeat this process (steps 4-9) for each digital signature or MAC value contained in the representation. + 11. If none of the validations in step 9 succeeded, then the JWS + MUST be rejected. Otherwise, in the JWS JSON Serialization + case, return a result to the application indicating which of the + validations succeeded and failed. In the JWS Compact + Serialization case, the result can simply indicate whether the + JWS was accepted or rejected. + + Finally, note that it is an application decision which algorithms are + acceptable in a given context. Even if a JWS can be successfully + validated, unless the algorithm(s) used in the JWS are acceptable to + the application, it SHOULD reject the JWS. 5.3. String Comparison Rules Processing a JWS inevitably requires comparing known strings to members and values in a JSON object. For example, in checking what the algorithm is, the Unicode string "alg" will be checked against the member names in the JOSE Header to see if there is a matching Header Parameter name. The same process is then used to determine if the value of the "alg" Header Parameter represents a supported algorithm. Since the only string comparison operations that are performed are equality and inequality, the same rules can be used for comparing both member names and member values against known strings. The JSON rules for doing member name comparison are described in Section 8.3 of RFC 7159 [RFC7159]. - Also, see the JSON security considerations in Section 10.6 and the - Unicode security considerations in Section 10.7. + Also, see the JSON security considerations in Section 10.12 and the + Unicode security considerations in Section 10.13. 6. Key Identification It is necessary for the recipient of a JWS to be able to determine the key that was employed for the digital signature or MAC operation. The key employed can be identified using the Header Parameter methods described in Section 4.1 or can be identified using methods that are outside the scope of this specification. Specifically, the Header Parameters "jku", "jwk", "kid", "x5u", "x5c", "x5t", and "x5t#S256" can be used to identify the key used. These Header Parameters MUST @@ -797,25 +801,29 @@ features are used for that application. For instance, applications might specify that only the JWS JSON Serialization is used, that only JWS JSON Serialization support for a single signature or MAC value is used, or that support for multiple signatures and/or MAC values is used. JWS implementations only need to implement the features needed for the applications they are designed to support. 7.1. JWS Compact Serialization The JWS Compact Serialization represents digitally signed or MACed - content as a compact URL-safe string. This string is - BASE64URL(UTF8(JWS Protected Header)) || '.' || BASE64URL(JWS - Payload) || '.' || BASE64URL(JWS Signature). Only one signature/MAC - is supported by the JWS Compact Serialization and it provides no - syntax to represent a JWS Unprotected Header value. + content as a compact, URL-safe string. This string is: + + BASE64URL(UTF8(JWS Protected Header)) || '.' || + BASE64URL(JWS Payload) || '.' || + BASE64URL(JWS Signature) + + Only one signature/MAC is supported by the JWS Compact Serialization + and it provides no syntax to represent a JWS Unprotected Header + value. 7.2. JWS JSON Serialization The JWS JSON Serialization represents digitally signed or MACed content as a JSON object. Content using the JWS JSON Serialization can be secured with more than one digital signature and/or MAC operation. This representation is neither optimized for compactness nor URL-safe. The following members are defined for use in top-level JSON objects @@ -1118,93 +1133,181 @@ o Intended usage: COMMON o Restrictions on usage: none o Author: Michael B. Jones, mbj@microsoft.com o Change Controller: IESG 10. Security Considerations All of the security issues that are pertinent to any cryptographic application must be addressed by JWS/JWE/JWK agents. Among these issues are protecting the user's asymmetric private and symmetric - secret keys, preventing various attacks, and helping avoid mistakes - such as inadvertently encrypting a message to the wrong recipient. - The entire list of security considerations is beyond the scope of - this document, but some significant considerations are listed here. + secret keys and employing countermeasures to various attacks. All the security considerations in XML DSIG 2.0 [W3C.NOTE-xmldsig-core2-20130411], also apply to this specification, other than those that are XML specific. Likewise, many of the best practices documented in XML Signature Best Practices [W3C.NOTE-xmldsig-bestpractices-20130411] also apply to this specification, other than those that are XML specific. -10.1. Key Entropy +10.1. Key Entropy and Random Values Keys are only as strong as the amount of entropy used to generate them. A minimum of 128 bits of entropy should be used for all keys, - and depending upon the application context, more may be required. In - particular, it may be difficult to generate sufficiently random - values in some browsers and application environments. + and depending upon the application context, more may be required. -10.2. Chosen Plaintext Attacks + Implementations must randomly generate public/private key pairs, + message authentication (MAC) keys, and padding values. The use of + inadequate pseudo-random number generators (PRNGs) to generate + cryptographic keys can result in little or no security. An attacker + may find it much easier to reproduce the PRNG environment that + produced the keys, searching the resulting small set of + possibilities, rather than brute force searching the whole key space. + The generation of quality random numbers is difficult. RFC 4086 + [RFC4086] offers important guidance in this area. - Creators of JWSs should not allow third parties to insert arbitrary - content into the message without adding entropy not controlled by the - third party. +10.2. Key Protection -10.3. Timing Attacks + Implementations must protect the signer's private key. Compromise of + the signer's private key permits an attacker to masquerade as the + signer. - When cryptographic algorithms are implemented in such a way that - successful operations take a different amount of time than - unsuccessful operations, attackers may be able to use the time - difference to obtain information about the keys employed. Therefore, - such timing differences must be avoided. + Implementations must protect the message authentication (MAC) key. + Compromise of the MAC key may result in undetectable modification of + the authenticated content. -10.4. Differences between Digital Signatures and MACs +10.3. Key Origin Authentication + + The key management technique employed to obtain public keys must + authenticate the origin of the key; otherwise, it is unknown what + party signed the message. + + Likewise, the key management technique employed to distribute MAC + keys must provide data origin authentication; otherwise, the contents + are delivered with integrity from an unknown source. + +10.4. Cryptographic Agility + + See Section 8.1 of [JWA] for security considerations on cryptographic + agility. + +10.5. Differences between Digital Signatures and MACs While MACs and digital signatures can both be used for integrity checking, there are some significant differences between the security properties that each of them provides. These need to be taken into consideration when designing protocols and selecting the algorithms to be used in protocols. Both signatures and MACs provide for integrity checking -- verifying that the message has not been modified since the integrity value was computed. However, MACs provide for origination identification only under specific circumstances. It can normally be assumed that a private key used for a signature is only in the hands of a single entity (although perhaps a distributed entity, in the case of replicated servers); however, a MAC key needs to be in the hands of all the entities that use it for integrity computation and checking. This means that origination can only be determined if a MAC key is known only to two entities and the receiver knows that it did not create the message. MAC validation cannot be used to prove origination to a third party. -10.5. SHA-1 Certificate Thumbprints +10.6. Algorithm Validation + + The digital signature representations for some algorithms include + information about the algorithm used inside the signature value. For + instance, signatures produced with RSASSA-PKCS-v1_5 [RFC3447] encode + the hash function used and many libraries actually use the hash + algorithm specified inside the signature when validating the + signature. When using such libraries, as part of the algorithm + validation performed, implementations MUST ensure that the algorithm + information encoded in the signature corresponds to that specified + with the "alg" Header Parameter. If this is not done, an attacker + could claim to have used a strong hash algorithm while actually using + a weak one represented in the signature value. + +10.7. Algorithm Protection + + In some usages of JWS, there is a risk of algorithm substitution + attacks, in which an attacker can use an existing digital signature + value with a different signature algorithm to make it appear that a + signer has signed something that it has not. These attacks have been + discussed in detail in the context of CMS [RFC6211]. This risk + arises when all of the following are true: + + o Verifiers of a signature support multiple algorithms. + + o Given an existing signature, an attacker can find another payload + that produces the same signature value with a different algorithm. + + o The payload crafted by the attacker is valid in the application + context. + + There are several ways for an application to mitigate algorithm + substitution attacks: + + o Use only digital signature algorithms that are not vulnerable to + substitution attacks. Substitution attacks are only feasible if + an attacker can compute pre-images for a hash function accepted by + the recipient. All JWA-defined signature algorithms use SHA-2 + hashes, for which there are no known pre-image attacks, as of the + time of this writing. + + o Require that the "alg" Header Parameter be carried in the + protected header. (This is always the case when using the JWS + Compact Serialization and is the approach taken by CMS [RFC6211].) + + o Include a field containing the algorithm in the application + payload, and require that it be matched with the "alg" Header + Parameter during verification. (This is the approach taken by + PKIX [RFC5280].) + +10.8. Chosen Plaintext Attacks + + Creators of JWSs should not allow third parties to insert arbitrary + content into the message without adding entropy not controlled by the + third party. + +10.9. Timing Attacks + + When cryptographic algorithms are implemented in such a way that + successful operations take a different amount of time than + unsuccessful operations, attackers may be able to use the time + difference to obtain information about the keys employed. Therefore, + such timing differences must be avoided. + +10.10. Replay Protection + + While not directly in scope for this specification, note that + applications using JWS (or JWE) objects can thwart replay attacks by + including a unique message identifier as integrity-protected content + in the JWS (or JWE) message and having the recipient verify that the + message has not been previously received or acted upon. + +10.11. SHA-1 Certificate Thumbprints A SHA-1 hash is used when computing "x5t" (X.509 Certificate SHA-1 Thumbprint) values, for compatibility reasons. Should an effective means of producing SHA-1 hash collisions be developed, and should an attacker wish to interfere with the use of a known certificate on a given system, this could be accomplished by creating another certificate whose SHA-1 hash value is the same and adding it to the certificate store used by the intended victim. A prerequisite to this attack succeeding is the attacker having write access to the intended victim's certificate store. Alternatively, the "x5t#S256" (X.509 Certificate SHA-256 Thumbprint) Header Parameter could be used instead of "x5t". However, at the time of this writing, no development platform is known to support SHA-256 certificate thumbprints. -10.6. JSON Security Considerations +10.12. JSON Security Considerations Strict JSON [RFC7159] validation is a security requirement. If malformed JSON is received, then the intent of the sender is impossible to reliably discern. Ambiguous and potentially exploitable situations could arise if the JSON parser used does not reject malformed JSON syntax. In particular, any JSON inputs not conforming to the JSON-text syntax defined in RFC 7159 input MUST be rejected in their entirety. Section 4 of the JSON Data Interchange Format specification [RFC7159] @@ -1220,21 +1323,21 @@ potentially exploitable situations could arise if the JSON parser used does not enforce the uniqueness of member names or returns an unpredictable value for duplicate member names. Some JSON parsers might not reject input that contains extra significant characters after a valid input. For instance, the input "{"tag":"value"}ABCD" contains a valid JSON-text object followed by the extra characters "ABCD". Such input MUST be rejected in its entirety. -10.7. Unicode Comparison Security Considerations +10.13. Unicode Comparison Security Considerations Header Parameter names and algorithm names are Unicode strings. For security reasons, the representations of these names must be compared verbatim after performing any escape processing (as per Section 8.3 of RFC 7159 [RFC7159]). This means, for instance, that these JSON strings must compare as being equal ("sig", "\u0073ig"), whereas these must all compare as being not equal to the first set or to each other ("SIG", "Sig", "si\u0047"). JSON strings can contain characters outside the Unicode Basic @@ -1260,25 +1362,25 @@ [ITU.X690.1994] International Telecommunications Union, "Information Technology - ASN.1 encoding rules: Specification of Basic Encoding Rules (BER), Canonical Encoding Rules (CER) and Distinguished Encoding Rules (DER)", ITU-T Recommendation X.690, 1994. [JWA] Jones, M., "JSON Web Algorithms (JWA)", draft-ietf-jose-json-web-algorithms (work in progress), - July 2014. + September 2014. [JWK] Jones, M., "JSON Web Key (JWK)", draft-ietf-jose-json-web-key (work in progress), - July 2014. + September 2014. [RFC1421] Linn, J., "Privacy Enhancement for Internet Electronic Mail: Part I: Message Encryption and Authentication Procedures", RFC 1421, February 1993. [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies", RFC 2045, November 1996. [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail @@ -1327,44 +1429,54 @@ 11.2. Informative References [CanvasApp] Facebook, "Canvas Applications", 2010. [JSS] Bradley, J. and N. Sakimura (editor), "JSON Simple Sign", September 2010. [JWE] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", draft-ietf-jose-json-web-encryption (work in progress), - July 2014. + September 2014. [JWT] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token (JWT)", draft-ietf-oauth-json-web-token (work in - progress), July 2014. + progress), September 2014. [MagicSignatures] Panzer (editor), J., Laurie, B., and D. Balfanz, "Magic Signatures", January 2011. [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed- Hashing for Message Authentication", RFC 2104, February 1997. + [RFC3447] Jonsson, J. and B. Kaliski, "Public-Key Cryptography + Standards (PKCS) #1: RSA Cryptography Specifications + Version 2.1", RFC 3447, February 2003. + + [RFC4086] Eastlake, D., Schiller, J., and S. Crocker, "Randomness + Requirements for Security", BCP 106, RFC 4086, June 2005. + [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally Unique IDentifier (UUID) URN Namespace", RFC 4122, July 2005. [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an IANA Considerations Section in RFCs", BCP 26, RFC 5226, May 2008. + [RFC6211] Schaad, J., "Cryptographic Message Syntax (CMS) Algorithm + Identifier Protection Attribute", RFC 6211, April 2011. + [SHS] National Institute of Standards and Technology, "Secure - Hash Standard (SHS)", FIPS PUB 180-3, October 2008. + Hash Standard (SHS)", FIPS PUB 180-4, March 2012. [W3C.NOTE-xmldsig-bestpractices-20130411] Hirsch, F. and P. Datta, "XML Signature Best Practices", World Wide Web Consortium Note NOTE-xmldsig-bestpractices- 20130411, April 2013, . [W3C.NOTE-xmldsig-core2-20130411] Eastlake, D., Reagle, J., Solo, D., Hirsch, F., Roessler, T., Yiu, K., Datta, P., and S. Cantor, "XML Signature @@ -1861,24 +1972,24 @@ P-521 SHA-512 digital signature contained in the JWS Signature. Validating this JWS Signature is very similar to the previous example. We need to split the 132 member octet sequence of the JWS Signature into two 66 octet sequences, the first representing R and the second S. We then pass the public key (x, y), the signature (R, S), and the JWS Signing Input to an ECDSA signature verifier that has been configured to use the P-521 curve with the SHA-512 hash function. -A.5. Example Plaintext JWS +A.5. Example Unsecured JWS The following example JWS Protected Header declares that the encoded - object is a Plaintext JWS: + object is an Unsecured JWS: {"alg":"none"} Encoding this JWS Protected Header as BASE64URL(UTF8(JWS Protected Header)) gives this value: eyJhbGciOiJub25lIn0 The JWS Payload used in this example, which follows, is the same as in the previous examples. Since the BASE64URL(JWS Payload) value @@ -2273,20 +2384,29 @@ Turner. Jim Schaad and Karen O'Donoghue chaired the JOSE working group and Sean Turner, Stephen Farrell, and Kathleen Moriarty served as Security area directors during the creation of this specification. Appendix H. Document History [[ to be removed by the RFC Editor before publication as an RFC ]] + -32 + + o Addressed Gen-ART review comments by Russ Housley. + + o Addressed secdir review comments by Tero Kivinen, Stephen Kent, + and Scott Kelly. + + o Replaced the term Plaintext JWS with Unsecured JWS. + -31 o Reworded the language about JWS implementations ignoring the "typ" and "cty" parameters, explicitly saying that their processing is performed by JWS applications. o Added additional guidance on ciphersuites currently considered to be appropriate for use, including a reference to a recent update by the TLS working group.