diff --git a/rfc/rfc7515.txt b/rfc/rfc7515.txt deleted file mode 100644 index 5ffc978..0000000 --- a/rfc/rfc7515.txt +++ /dev/null @@ -1,3307 +0,0 @@ - - - - - - -Internet Engineering Task Force (IETF) M. Jones -Request for Comments: 7515 Microsoft -Category: Standards Track J. Bradley -ISSN: 2070-1721 Ping Identity - N. Sakimura - NRI - May 2015 - - - JSON Web Signature (JWS) - -Abstract - - JSON Web Signature (JWS) represents content secured with digital - signatures or Message Authentication Codes (MACs) using 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) specification. - -Status of This Memo - - This is an Internet Standards Track document. - - This document is a product of the Internet Engineering Task Force - (IETF). It represents the consensus of the IETF community. It has - received public review and has been approved for publication by the - Internet Engineering Steering Group (IESG). Further information on - Internet Standards is available in Section 2 of RFC 5741. - - Information about the current status of this document, any errata, - and how to provide feedback on it may be obtained at - http://www.rfc-editor.org/info/rfc7515. - - - - - - - - - - - - - - - - - -Jones, et al. Standards Track [Page 1] - -RFC 7515 JSON Web Signature (JWS) May 2015 - - -Copyright Notice - - Copyright (c) 2015 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 - 2. Terminology .....................................................5 - 3. JSON Web Signature (JWS) Overview ...............................7 - 3.1. JWS Compact Serialization Overview .........................7 - 3.2. JWS JSON Serialization Overview ............................8 - 3.3. Example JWS ................................................8 - 4. JOSE Header .....................................................9 - 4.1. Registered Header Parameter Names .........................10 - 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 ..............11 - 4.1.4. "kid" (Key ID) Header Parameter ....................11 - 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 - 4.1.8. "x5t#S256" (X.509 Certificate SHA-256 - Thumbprint) Header Parameter .......................12 - 4.1.9. "typ" (Type) Header Parameter ......................12 - 4.1.10. "cty" (Content Type) Header Parameter .............13 - 4.1.11. "crit" (Critical) Header Parameter ................14 - 4.2. Public Header Parameter Names .............................14 - 4.3. Private Header Parameter Names ............................14 - 5. Producing and Consuming JWSs ...................................15 - 5.1. Message Signature or MAC Computation ......................15 - 5.2. Message Signature or MAC Validation .......................16 - 5.3. String Comparison Rules ...................................17 - 6. Key Identification .............................................18 - - - - - -Jones, et al. Standards Track [Page 2] - -RFC 7515 JSON Web Signature (JWS) May 2015 - - - 7. Serializations .................................................19 - 7.1. JWS Compact Serialization .................................19 - 7.2. JWS JSON Serialization ....................................19 - 7.2.1. General JWS JSON Serialization Syntax ..............20 - 7.2.2. Flattened JWS JSON Serialization Syntax ............21 - 8. TLS Requirements ...............................................22 - 9. IANA Considerations ............................................22 - 9.1. JSON Web Signature and Encryption Header - Parameters Registry .......................................23 - 9.1.1. Registration Template ..............................23 - 9.1.2. Initial Registry Contents ..........................24 - 9.2. Media Type Registration ...................................26 - 9.2.1. Registry Contents ..................................26 - 10. Security Considerations .......................................27 - 10.1. Key Entropy and Random Values ............................27 - 10.2. Key Protection ...........................................28 - 10.3. Key Origin Authentication ................................28 - 10.4. Cryptographic Agility ....................................28 - 10.5. Differences between Digital Signatures and MACs ..........28 - 10.6. Algorithm Validation .....................................29 - 10.7. Algorithm Protection .....................................29 - 10.8. Chosen Plaintext Attacks .................................30 - 10.9. Timing Attacks ...........................................30 - 10.10. Replay Protection .......................................30 - 10.11. SHA-1 Certificate Thumbprints ...........................30 - 10.12. JSON Security Considerations ............................31 - 10.13. Unicode Comparison Security Considerations ..............31 - 11. References ....................................................32 - 11.1. Normative References .....................................32 - 11.2. Informative References ...................................34 - Appendix A. JWS Examples .........................................36 - A.1. Example JWS Using HMAC SHA-256 ............................36 - A.1.1. Encoding ..............................................36 - A.1.2. Validating ............................................38 - A.2. Example JWS Using RSASSA-PKCS1-v1_5 SHA-256 ...............38 - A.2.1. Encoding ..............................................38 - A.2.2. Validating ............................................42 - A.3. Example JWS Using ECDSA P-256 SHA-256 .....................42 - A.3.1. Encoding ..............................................42 - A.3.2. Validating ............................................44 - A.4. Example JWS Using ECDSA P-521 SHA-512 .....................45 - A.4.1. Encoding ..............................................45 - A.4.2. Validating ............................................47 - A.5. Example Unsecured JWS .....................................47 - A.6. Example JWS Using General JWS JSON Serialization ..........48 - A.6.1. JWS Per-Signature Protected Headers ...................48 - A.6.2. JWS Per-Signature Unprotected Headers .................49 - A.6.3. Complete JOSE Header Values ...........................49 - - - -Jones, et al. Standards Track [Page 3] - -RFC 7515 JSON Web Signature (JWS) May 2015 - - - A.6.4. Complete JWS JSON Serialization Representation ........50 - A.7. Example JWS Using Flattened JWS JSON Serialization ........51 - Appendix B. "x5c" (X.509 Certificate Chain) Example ..............52 - Appendix C. Notes on Implementing base64url Encoding without - Padding ..............................................54 - Appendix D. Notes on Key Selection ...............................55 - Appendix E. Negative Test Case for "crit" Header Parameter .......57 - Appendix F. Detached Content .....................................57 - Acknowledgements ..................................................58 - Authors' Addresses ................................................58 - -1. Introduction - - JSON Web Signature (JWS) represents content secured with digital - signatures or Message Authentication Codes (MACs) using JSON-based - [RFC7159] data structures. The JWS cryptographic mechanisms provide - integrity protection for an arbitrary sequence of octets. See - Section 10.5 for a discussion on the differences between digital - signatures and MACs. - - Two closely related serializations for JWSs 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 JWSs - 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 - specification are described in the separate JSON Web Algorithms (JWA) - [JWA] specification and an IANA registry defined by that - specification. Related encryption capabilities are described in the - separate JSON Web Encryption (JWE) [JWE] specification. - - Names defined by this specification are short because a core goal is - for the resulting representations to be compact. - -1.1. Notational Conventions - - The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", - "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and - "OPTIONAL" in this document are to be interpreted as described in - "Key words for use in RFCs to Indicate Requirement Levels" [RFC2119]. - The interpretation should only be applied when the terms appear in - all capital letters. - - BASE64URL(OCTETS) denotes the base64url encoding of OCTETS, per - Section 2. - - - -Jones, et al. Standards Track [Page 4] - -RFC 7515 JSON Web Signature (JWS) May 2015 - - - UTF8(STRING) denotes the octets of the UTF-8 [RFC3629] representation - of STRING, where STRING is a sequence of zero or more Unicode - [UNICODE] characters. - - ASCII(STRING) denotes the octets of the ASCII [RFC20] representation - of STRING, where STRING is a sequence of zero or more ASCII - characters. - - The concatenation of two values A and B is denoted as A || B. - -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 JOSE (JSON Object Signing - and Encryption) 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 - A name/value pair that is member of the JOSE Header. - - JWS Protected Header - JSON object that contains the Header Parameters that are integrity - protected by the JWS Signature digital signature or MAC operation. - For the JWS Compact Serialization, this comprises the entire JOSE - Header. For the JWS JSON Serialization, this is one component of - the JOSE Header. - - JWS Unprotected Header - JSON object that contains the Header Parameters that are not - integrity protected. This can only be present when using the JWS - JSON Serialization. - - - - - - - -Jones, et al. Standards Track [Page 5] - -RFC 7515 JSON Web Signature (JWS) May 2015 - - - Base64url Encoding - Base64 encoding using the URL- and filename-safe character set - defined in Section 5 of RFC 4648 [RFC4648], with all trailing '=' - characters omitted (as permitted by Section 3.2) and without the - inclusion of any line breaks, whitespace, or other additional - characters. Note that the base64url encoding of the empty octet - sequence is the empty string. (See Appendix C for notes on - implementing base64url encoding without padding.) - - JWS Signing Input - The input to the digital signature or MAC computation. Its value - is ASCII(BASE64URL(UTF8(JWS Protected Header)) || '.' || - BASE64URL(JWS Payload)). - - 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. - - Unsecured JWS - A JWS that provides no integrity protection. Unsecured JWSs use - the "alg" value "none". - - 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 - precautions to ensure they are in control of the portion of the - namespace they use to define the name. - - StringOrURI - A JSON string value, with the additional requirement that while - arbitrary string values MAY be used, any value containing a ":" - character MUST be a URI [RFC3986]. StringOrURI values are - compared as case-sensitive strings with no transformations or - canonicalizations applied. - - - - - - -Jones, et al. Standards Track [Page 6] - -RFC 7515 JSON Web Signature (JWS) May 2015 - - - The terms "JSON Web Encryption (JWE)", "JWE Compact Serialization", - and "JWE JSON Serialization" are defined by the JWE specification - [JWE]. - - The terms "Digital Signature" and "Message Authentication Code (MAC)" - are defined by the "Internet Security Glossary, Version 2" [RFC4949]. - -3. JSON Web Signature (JWS) Overview - - JWS represents digitally signed or MACed content using JSON data - structures and base64url encoding. These JSON data structures MAY - contain whitespace and/or line breaks before or after any JSON values - or structural characters, in accordance with Section 2 of RFC 7159 - [RFC7159]. A JWS represents these logical values (each of which is - defined in Section 2): - - o JOSE Header - o JWS Payload - o JWS Signature - - For a JWS, the JOSE Header members are the union of the members of - these values (each of which is defined in Section 2): - - o JWS Protected Header - o JWS Unprotected Header - - This document defines two serializations for JWSs: 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, since JSON lacks a 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 is represented as the - concatenation: - - BASE64URL(UTF8(JWS Protected Header)) || '.' || - BASE64URL(JWS Payload) || '.' || - BASE64URL(JWS Signature) - - See Section 7.1 for more information about the JWS Compact - Serialization. - - - -Jones, et al. Standards Track [Page 7] - -RFC 7515 JSON Web Signature (JWS) May 2015 - - -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 union of the members of the JWS - Protected Header and the JWS Unprotected Header values that are - present. - - In the JWS JSON Serialization, a JWS is represented as a JSON object - containing some or all of these four members: - - o "protected", with the value BASE64URL(UTF8(JWS Protected Header)) - o "header", with the value JWS Unprotected Header - o "payload", with the value BASE64URL(JWS Payload) - o "signature", with the value BASE64URL(JWS Signature) - - The three base64url-encoded result strings and the JWS Unprotected - Header value are represented as members within a JSON object. The - inclusion of some of these values is OPTIONAL. The JWS JSON - Serialization can also represent multiple signature and/or MAC - values, rather than just one. See Section 7.2 for more information - about the JWS JSON Serialization. - -3.3. Example JWS - - This section provides an example of a JWS. Its computation is - described in more detail in Appendix A.1, including specifying the - exact octet sequences representing the JSON values used and the key - value used. - - The following example JWS Protected Header declares that the encoded - object is a JSON Web Token [JWT] and the JWS Protected Header and the - JWS Payload are secured using the HMAC SHA-256 [RFC2104] [SHS] - algorithm: - - {"typ":"JWT", - "alg":"HS256"} - - Encoding this JWS Protected Header as BASE64URL(UTF8(JWS Protected - Header)) gives this value: - - eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9 - - The UTF-8 representation of the following JSON object is used as the - JWS Payload. (Note that the payload can be any content and need not - be a representation of a JSON object.) - - - - - -Jones, et al. Standards Track [Page 8] - -RFC 7515 JSON Web Signature (JWS) May 2015 - - - {"iss":"joe", - "exp":1300819380, - "http://example.com/is_root":true} - - Encoding this JWS Payload as BASE64URL(JWS Payload) gives this value - (with line breaks for display purposes only): - - eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt - cGxlLmNvbS9pc19yb290Ijp0cnVlfQ - - Computing the HMAC of the JWS Signing Input ASCII(BASE64URL(UTF8(JWS - Protected Header)) || '.' || BASE64URL(JWS Payload)) with the HMAC - SHA-256 algorithm using the key specified in Appendix A.1 and - base64url-encoding the result yields this BASE64URL(JWS Signature) - value: - - dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk - - Concatenating these values in the order Header.Payload.Signature with - period ('.') characters between the parts yields this complete JWS - representation using the JWS Compact Serialization (with line breaks - for display purposes only): - - eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9 - . - eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt - cGxlLmNvbS9pc19yb290Ijp0cnVlfQ - . - dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk - - See Appendix A for additional examples, including examples using the - JWS JSON Serialization in Sections A.6 and A.7. - -4. JOSE Header - - For a JWS, the members of the JSON object(s) representing the JOSE - Header describe the digital signature or MAC applied to the JWS - Protected Header and the JWS Payload and optionally additional - properties of the JWS. The Header Parameter names within the JOSE - Header MUST be unique; JWS parsers MUST either reject JWSs with - duplicate Header Parameter names or use a JSON parser that returns - only the lexically last duplicate member name, as specified in - Section 15.12 ("The JSON Object") of ECMAScript 5.1 [ECMAScript]. - - Implementations are required to understand the specific Header - Parameters defined by this specification that are designated as "MUST - be understood" and process them in the manner defined in this - specification. All other Header Parameters defined by this - - - -Jones, et al. Standards Track [Page 9] - -RFC 7515 JSON Web Signature (JWS) May 2015 - - - specification that are not so designated MUST be ignored when not - understood. Unless listed as a critical Header Parameter, per - Section 4.1.11, all Header Parameters not defined by this - specification MUST be ignored when not understood. - - There are three classes of Header Parameter names: Registered Header - Parameter names, Public Header Parameter names, and Private Header - Parameter names. - -4.1. Registered Header Parameter Names - - The following Header Parameter names for use in JWSs are registered - in the IANA "JSON Web Signature and Encryption Header Parameters" - registry established by Section 9.1, with meanings as defined in the - subsections 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 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 established by [JWA] or be a value - that contains a Collision-Resistant Name. The "alg" value is a case- - sensitive ASCII 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 established - by [JWA]; the initial contents of this registry are the values - defined in Section 3.1 of [JWA]. - -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 - which corresponds to the key used to digitally sign the JWS. The - keys MUST be encoded as a JWK Set [JWK]. The protocol used to - acquire the resource MUST provide integrity protection; an HTTP GET - request to retrieve the JWK Set MUST use Transport Layer Security - - - -Jones, et al. Standards Track [Page 10] - -RFC 7515 JSON Web Signature (JWS) May 2015 - - - (TLS) [RFC2818] [RFC5246]; and the identity of the server MUST be - validated, as per Section 6 of RFC 6125 [RFC6125]. Also, see - Section 8 on TLS requirements. Use of this Header Parameter is - OPTIONAL. - -4.1.3. "jwk" (JSON Web Key) Header Parameter - - The "jwk" (JSON Web Key) Header Parameter is the public key that - corresponds to the key used to digitally sign the JWS. This key is - represented as a JSON Web Key [JWK]. Use of this Header Parameter is - OPTIONAL. - -4.1.4. "kid" (Key ID) Header Parameter - - The "kid" (key ID) Header Parameter is a hint indicating which key - was used to secure the JWS. This parameter allows originators to - explicitly signal a change of key to recipients. The structure of - the "kid" value is unspecified. Its value MUST be a case-sensitive - string. Use of this Header Parameter is OPTIONAL. - - When used with a JWK, the "kid" value is used to match a JWK "kid" - parameter value. - -4.1.5. "x5u" (X.509 URL) Header Parameter - - The "x5u" (X.509 URL) Header Parameter is a URI [RFC3986] that refers - to a resource for the X.509 public key certificate or certificate - chain [RFC5280] corresponding to the key used to digitally sign the - JWS. The identified resource MUST provide a representation of the - certificate or certificate chain that conforms to RFC 5280 [RFC5280] - in PEM-encoded form, with each certificate delimited as specified in - Section 6.1 of RFC 4945 [RFC4945]. The certificate containing the - public key corresponding to the key used to digitally sign the JWS - MUST be the first certificate. This MAY be followed by additional - certificates, with each subsequent certificate being the one used to - certify the previous one. The protocol used to acquire the resource - MUST provide integrity protection; an HTTP GET request to retrieve - the certificate MUST use TLS [RFC2818] [RFC5246]; and the identity of - the server MUST be validated, as per Section 6 of RFC 6125 [RFC6125]. - Also, see Section 8 on TLS requirements. Use of this Header - Parameter is OPTIONAL. - -4.1.6. "x5c" (X.509 Certificate Chain) Header Parameter - - The "x5c" (X.509 certificate chain) Header Parameter contains the - X.509 public key certificate or certificate chain [RFC5280] - corresponding to the key used to digitally sign the JWS. The - certificate or certificate chain is represented as a JSON array of - - - -Jones, et al. Standards Track [Page 11] - -RFC 7515 JSON Web Signature (JWS) May 2015 - - - certificate value strings. Each string in the array is a - base64-encoded (Section 4 of [RFC4648] -- not base64url-encoded) DER - [ITU.X690.2008] PKIX certificate value. The certificate containing - the public key corresponding to the key used to digitally sign the - JWS MUST be the first certificate. This MAY be followed by - additional certificates, with each subsequent certificate being the - one used to certify the previous one. The recipient MUST validate - the certificate chain according to RFC 5280 [RFC5280] and consider - the certificate or certificate chain to be invalid if any validation - failure occurs. Use of this Header Parameter is OPTIONAL. - - See Appendix B for an example "x5c" value. - -4.1.7. "x5t" (X.509 Certificate SHA-1 Thumbprint) Header Parameter - - The "x5t" (X.509 certificate SHA-1 thumbprint) Header Parameter is a - base64url-encoded SHA-1 thumbprint (a.k.a. digest) of the DER - encoding of the X.509 certificate [RFC5280] corresponding to the key - used to digitally sign the JWS. Note that certificate thumbprints - are also sometimes known as certificate fingerprints. Use of this - Header Parameter is OPTIONAL. - -4.1.8. "x5t#S256" (X.509 Certificate SHA-256 Thumbprint) Header - Parameter - - The "x5t#S256" (X.509 certificate SHA-256 thumbprint) Header - Parameter is a base64url-encoded SHA-256 thumbprint (a.k.a. digest) - of the DER encoding of the X.509 certificate [RFC5280] corresponding - to the key used to digitally sign the JWS. Note that certificate - thumbprints are also sometimes known as certificate fingerprints. - Use of this Header Parameter is OPTIONAL. - -4.1.9. "typ" (Type) Header Parameter - - The "typ" (type) Header Parameter is used by JWS applications to - declare the media type [IANA.MediaTypes] of this complete JWS. This - is intended for use by the application when more than one kind of - object could be present in an application data structure that can - contain a JWS; the application can use this value to disambiguate - among the different kinds of objects that might be present. It will - typically not be used by applications when the kind of object is - already known. This parameter is ignored by JWS implementations; any - processing of this parameter is performed by the JWS application. - Use of this Header Parameter is OPTIONAL. - - Per RFC 2045 [RFC2045], all media type values, subtype values, and - parameter names are case insensitive. However, parameter values are - case sensitive unless otherwise specified for the specific parameter. - - - -Jones, et al. Standards Track [Page 12] - -RFC 7515 JSON Web Signature (JWS) May 2015 - - - To keep messages compact in common situations, it is RECOMMENDED that - producers omit an "application/" prefix of a media type value in a - "typ" Header Parameter when no other '/' appears in the media type - value. A recipient using the media type value MUST treat it as if - "application/" were prepended to any "typ" value not containing a - '/'. For instance, a "typ" value of "example" SHOULD be used to - represent the "application/example" media type, whereas the media - type "application/example;part="1/2"" cannot be shortened to - "example;part="1/2"". - - The "typ" value "JOSE" can be used by applications to indicate that - this object is a JWS or JWE using the JWS Compact Serialization or - the JWE Compact Serialization. The "typ" value "JOSE+JSON" can be - used by applications to indicate that this object is a JWS or JWE - using the JWS JSON Serialization or the JWE JSON Serialization. - Other type values can also be used by applications. - -4.1.10. "cty" (Content Type) Header Parameter - - The "cty" (content type) Header Parameter is used by JWS applications - to declare the media type [IANA.MediaTypes] of the secured content - (the payload). This is intended for use by the application when more - than one kind of object could be present in the JWS Payload; the - application can use this value to disambiguate among the different - kinds of objects that might be present. It will typically not be - used by applications when the kind of object is already known. This - parameter is ignored by JWS implementations; any processing of this - parameter is performed by the JWS application. Use of this Header - Parameter is OPTIONAL. - - Per RFC 2045 [RFC2045], all media type values, subtype values, and - parameter names are case insensitive. However, parameter values are - case sensitive unless otherwise specified for the specific parameter. - - To keep messages compact in common situations, it is RECOMMENDED that - producers omit an "application/" prefix of a media type value in a - "cty" Header Parameter when no other '/' appears in the media type - value. A recipient using the media type value MUST treat it as if - "application/" were prepended to any "cty" value not containing a - '/'. For instance, a "cty" value of "example" SHOULD be used to - represent the "application/example" media type, whereas the media - type "application/example;part="1/2"" cannot be shortened to - "example;part="1/2"". - - - - - - - - -Jones, et al. Standards Track [Page 13] - -RFC 7515 JSON Web Signature (JWS) May 2015 - - -4.1.11. "crit" (Critical) Header Parameter - - The "crit" (critical) Header Parameter indicates that extensions to - this specification and/or [JWA] are being used that MUST be - understood and processed. Its value is an array listing the Header - Parameter names present in the JOSE Header that use those extensions. - If any of the listed extension Header Parameters are not understood - and supported by the recipient, then the JWS is invalid. Producers - MUST NOT include Header Parameter names defined by this specification - or [JWA] for use with JWS, duplicate names, or names that do not - occur as Header Parameter names within the JOSE Header in the "crit" - list. Producers MUST NOT use the empty list "[]" as the "crit" - value. Recipients MAY consider the JWS to be invalid if the critical - list contains any Header Parameter names defined by this - specification or [JWA] for use with JWS or if any other constraints - on its use are violated. When used, this Header Parameter MUST be - integrity protected; therefore, it MUST occur only within the JWS - Protected Header. Use of this Header Parameter is OPTIONAL. This - Header Parameter MUST be understood and processed by implementations. - - An example use, along with a hypothetical "exp" (expiration time) - field is: - - {"alg":"ES256", - "crit":["exp"], - "exp":1363284000 - } - -4.2. Public Header Parameter Names - - Additional Header Parameter names can be defined by those using JWSs. - However, in order to prevent collisions, any new Header Parameter - name should either be registered in the IANA "JSON Web Signature and - Encryption Header Parameters" registry established by Section 9.1 or - be a Public Name (a value that contains a Collision-Resistant Name). - In each case, the definer of the name or value needs to take - reasonable precautions to make sure they are in control of the part - of the namespace they use to define the Header Parameter name. - - New Header Parameters should be introduced sparingly, as they can - result in non-interoperable JWSs. - -4.3. Private Header Parameter Names - - A producer and consumer of a JWS may agree to use Header Parameter - names that are Private Names (names that are not Registered Header - Parameter names (Section 4.1)) or Public Header Parameter names - - - - -Jones, et al. Standards Track [Page 14] - -RFC 7515 JSON Web Signature (JWS) May 2015 - - - (Section 4.2). Unlike Public Header Parameter names, Private Header - Parameter names are subject to collision and should be used with - caution. - -5. Producing and Consuming JWSs - -5.1. Message Signature or MAC Computation - - To create a JWS, the following steps are performed. The order of the - steps is not significant in cases where there are no dependencies - between the inputs and outputs of the steps. - - 1. Create the content to be used as the JWS Payload. - - 2. Compute the encoded payload value BASE64URL(JWS Payload). - - 3. Create the JSON object(s) containing the desired set of Header - Parameters, which together comprise the JOSE Header (the JWS - Protected Header and/or the JWS Unprotected Header). - - 4. Compute the encoded header value BASE64URL(UTF8(JWS Protected - Header)). If the JWS Protected Header is not present (which can - only happen when using the JWS JSON Serialization and no - "protected" member is present), let this value be the empty - string. - - 5. Compute the JWS Signature in the manner defined for the - particular algorithm being used over the JWS Signing Input - ASCII(BASE64URL(UTF8(JWS Protected Header)) || '.' || - BASE64URL(JWS Payload)). The "alg" (algorithm) Header Parameter - MUST be present in the JOSE Header, with the algorithm value - accurately representing the algorithm used to construct the JWS - Signature. - - 6. Compute the encoded signature value BASE64URL(JWS Signature). - - 7. If the JWS JSON Serialization is being used, repeat this process - (steps 3-6) for each digital signature or MAC operation being - performed. - - 8. Create the desired serialized output. The JWS Compact - Serialization of this result is BASE64URL(UTF8(JWS Protected - Header)) || '.' || BASE64URL(JWS Payload) || '.' || BASE64URL(JWS - Signature). The JWS JSON Serialization is described in - Section 7.2. - - - - - - -Jones, et al. Standards Track [Page 15] - -RFC 7515 JSON Web Signature (JWS) May 2015 - - -5.2. Message Signature or MAC Validation - - When validating a JWS, the following steps are performed. 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. - - 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 considered invalid. 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 considered invalid. - - 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 the JWS Signature are - represented as base64url-encoded values in that order, with each - value being separated from the next by a single period ('.') - character, resulting in exactly two delimiting period characters - being used. The JWS JSON Serialization is described in - Section 7.2. - - 2. Base64url-decode the encoded representation of the JWS Protected - Header, following the restriction that no line breaks, - whitespace, or other additional characters have been used. - - 3. Verify that the resulting octet sequence is a UTF-8-encoded - representation of a completely valid JSON object conforming to - RFC 7159 [RFC7159]; let the JWS Protected Header be this JSON - object. - - 4. If using the JWS Compact Serialization, let the JOSE Header be - the JWS Protected Header. Otherwise, when using the JWS JSON - Serialization, let the JOSE Header be the union of the members of - the corresponding JWS Protected Header and JWS Unprotected - Header, all of which must be completely valid JSON objects. - During this step, verify that the resulting JOSE Header does not - contain duplicate Header Parameter names. When using the JWS - - - - - -Jones, et al. Standards Track [Page 16] - -RFC 7515 JSON Web Signature (JWS) May 2015 - - - JSON Serialization, this restriction includes that the same - Header Parameter name also MUST NOT occur in distinct JSON object - values that together comprise the JOSE Header. - - 5. Verify that the implementation understands and can process all - 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. - - 6. Base64url-decode the encoded representation of the JWS Payload, - following the restriction that no line breaks, whitespace, or - other additional characters have been used. - - 7. Base64url-decode the encoded representation of the JWS Signature, - following the restriction that no line breaks, whitespace, or - other additional characters have been used. - - 8. 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. - - 9. If the JWS JSON Serialization is being used, repeat this process - (steps 4-8) for each digital signature or MAC value contained in - the representation. - - 10. If none of the validations in step 9 succeeded, then the JWS MUST - be considered invalid. 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 or not - the JWS was successfully validated. - - Finally, note that it is an application decision which algorithms may - be used 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 consider the JWS to be invalid. - -5.3. String Comparison Rules - - Processing a JWS inevitably requires comparing known strings to - members and values in JSON objects. 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 - - - -Jones, et al. Standards Track [Page 17] - -RFC 7515 JSON Web Signature (JWS) May 2015 - - - Header Parameter name. The same process is then used to determine if - the value of the "alg" Header Parameter represents a supported - algorithm. - - The JSON rules for doing member name comparison are described in - Section 8.3 of RFC 7159 [RFC7159]. 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. - - These comparison rules MUST be used for all JSON string comparisons - except in cases where the definition of the member explicitly calls - out that a different comparison rule is to be used for that member - value. Only the "typ" and "cty" member values defined in this - specification do not use these comparison rules. - - Some applications may include case-insensitive information in a case- - sensitive value, such as including a DNS name as part of a "kid" (key - ID) value. In those cases, the application may need to define a - convention for the canonical case to use for representing the case- - insensitive portions, such as lowercasing them, if more than one - party might need to produce the same value so that they can be - compared. (However, if all other parties consume whatever value the - producing party emitted verbatim without attempting to compare it to - an independently produced value, then the case used by the producer - will not matter.) - - 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 - be integrity protected if the information that they convey is to be - utilized in a trust decision; however, if the only information used - in the trust decision is a key, these parameters need not be - integrity protected, since changing them in a way that causes a - different key to be used will cause the validation to fail. - - The producer SHOULD include sufficient information in the Header - Parameters to identify the key used, unless the application uses - another means or convention to determine the key used. Validation of - - - -Jones, et al. Standards Track [Page 18] - -RFC 7515 JSON Web Signature (JWS) May 2015 - - - the signature or MAC fails when the algorithm used requires a key - (which is true of all algorithms except for "none") and the key used - cannot be determined. - - The means of exchanging any shared symmetric keys used is outside the - scope of this specification. - - Also, see Appendix D for notes on possible key selection algorithms. - -7. Serializations - - JWSs use one of two serializations: the JWS Compact Serialization or - the JWS JSON Serialization. Applications using this specification - need to specify what serialization and serialization 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. - -7.2. JWS JSON Serialization - - The JWS JSON Serialization represents digitally signed or MACed - content as a JSON object. This representation is neither optimized - for compactness nor URL-safe. - - Two closely related syntaxes are defined for the JWS JSON - Serialization: a fully general syntax, with which content can be - secured with more than one digital signature and/or MAC operation, - and a flattened syntax, which is optimized for the single digital - signature or MAC case. - - - - - - -Jones, et al. Standards Track [Page 19] - -RFC 7515 JSON Web Signature (JWS) May 2015 - - -7.2.1. General JWS JSON Serialization Syntax - - The following members are defined for use in top-level JSON objects - used for the fully general JWS JSON Serialization syntax: - - payload - The "payload" member MUST be present and contain the value - BASE64URL(JWS Payload). - - signatures - The "signatures" member value MUST be an array of JSON objects. - Each object represents a signature or MAC over the JWS Payload and - the JWS Protected Header. - - The following members are defined for use in the JSON objects that - are elements of the "signatures" array: - - protected - The "protected" member MUST be present and contain the value - BASE64URL(UTF8(JWS Protected Header)) when the JWS Protected - Header value is non-empty; otherwise, it MUST be absent. These - Header Parameter values are integrity protected. - - header - The "header" member MUST be present and contain the value JWS - Unprotected Header when the JWS Unprotected Header value is non- - empty; otherwise, it MUST be absent. This value is represented as - an unencoded JSON object, rather than as a string. These Header - Parameter values are not integrity protected. - - signature - The "signature" member MUST be present and contain the value - BASE64URL(JWS Signature). - - At least one of the "protected" and "header" members MUST be present - for each signature/MAC computation so that an "alg" Header Parameter - value is conveyed. - - Additional members can be present in both the JSON objects defined - above; if not understood by implementations encountering them, they - MUST be ignored. - - The Header Parameter values used when creating or validating - individual signature or MAC values are the union of the two sets of - Header Parameter values that may be present: (1) the JWS Protected - Header represented in the "protected" member of the signature/MAC's - array element, and (2) the JWS Unprotected Header in the "header" - - - - -Jones, et al. Standards Track [Page 20] - -RFC 7515 JSON Web Signature (JWS) May 2015 - - - member of the signature/MAC's array element. The union of these sets - of Header Parameters comprises the JOSE Header. The Header Parameter - names in the two locations MUST be disjoint. - - Each JWS Signature value is computed using the parameters of the - corresponding JOSE Header value in the same manner as for the JWS - Compact Serialization. This has the desirable property that each JWS - Signature value represented in the "signatures" array is identical to - the value that would have been computed for the same parameter in the - JWS Compact Serialization, provided that the JWS Protected Header - value for that signature/MAC computation (which represents the - integrity-protected Header Parameter values) matches that used in the - JWS Compact Serialization. - - In summary, the syntax of a JWS using the general JWS JSON - Serialization is as follows: - - { - "payload":"", - "signatures":[ - {"protected":"", - "header":, - "signature":""}, - ... - {"protected":"", - "header":, - "signature":""}] - } - - See Appendix A.6 for an example JWS using the general JWS JSON - Serialization syntax. - -7.2.2. Flattened JWS JSON Serialization Syntax - - The flattened JWS JSON Serialization syntax is based upon the general - syntax but flattens it, optimizing it for the single digital - signature/MAC case. It flattens it by removing the "signatures" - member and instead placing those members defined for use in the - "signatures" array (the "protected", "header", and "signature" - members) in the top-level JSON object (at the same level as the - "payload" member). - - The "signatures" member MUST NOT be present when using this syntax. - Other than this syntax difference, JWS JSON Serialization objects - using the flattened syntax are processed identically to those using - the general syntax. - - - - - -Jones, et al. Standards Track [Page 21] - -RFC 7515 JSON Web Signature (JWS) May 2015 - - - In summary, the syntax of a JWS using the flattened JWS JSON - Serialization is as follows: - - { - "payload":"", - "protected":"", - "header":, - "signature":"" - } - - See Appendix A.7 for an example JWS using the flattened JWS JSON - Serialization syntax. - -8. TLS Requirements - - Implementations supporting the "jku" and/or "x5u" Header Parameters - MUST support TLS. Which TLS version(s) ought to be implemented will - vary over time and depend on the widespread deployment and known - security vulnerabilities at the time of implementation. At the time - of this writing, TLS version 1.2 [RFC5246] is the most recent - version. - - To protect against information disclosure and tampering, - confidentiality protection MUST be applied using TLS with a - ciphersuite that provides confidentiality and integrity protection. - See current publications by the IETF TLS working group, including RFC - 6176 [RFC6176], for guidance on the ciphersuites currently considered - to be appropriate for use. Also, see "Recommendations for Secure Use - of Transport Layer Security (TLS) and Datagram Transport Layer - Security (DTLS)" [RFC7525] for recommendations on improving the - security of software and services using TLS. - - Whenever TLS is used, the identity of the service provider encoded in - the TLS server certificate MUST be verified using the procedures - described in Section 6 of RFC 6125 [RFC6125]. - -9. IANA Considerations - - The following registration procedure is used for all the registries - established by this specification. - - Values are registered on a Specification Required [RFC5226] basis - after a three-week review period on the jose-reg-review@ietf.org - mailing list, on the advice of one or more Designated Experts. - However, to allow for the allocation of values prior to publication, - the Designated Experts may approve registration once they are - satisfied that such a specification will be published. - - - - -Jones, et al. Standards Track [Page 22] - -RFC 7515 JSON Web Signature (JWS) May 2015 - - - Registration requests sent to the mailing list for review should use - an appropriate subject (e.g., "Request to register header parameter: - example"). - - Within the review period, the Designated Experts will either approve - or deny the registration request, communicating this decision to the - review list and IANA. Denials should include an explanation and, if - applicable, suggestions as to how to make the request successful. - Registration requests that are undetermined for a period longer than - 21 days can be brought to the IESG's attention (using the - iesg@ietf.org mailing list) for resolution. - - Criteria that should be applied by the Designated Experts includes - determining whether the proposed registration duplicates existing - functionality, whether it is likely to be of general applicability or - useful only for a single application, and whether the registration - description is clear. - - IANA must only accept registry updates from the Designated Experts - and should direct all requests for registration to the review mailing - list. - - It is suggested that multiple Designated Experts be appointed who are - able to represent the perspectives of different applications using - this specification, in order to enable broadly informed review of - registration decisions. In cases where a registration decision could - be perceived as creating a conflict of interest for a particular - Expert, that Expert should defer to the judgment of the other - Experts. - -9.1. JSON Web Signature and Encryption Header Parameters Registry - - This specification establishes the IANA "JSON Web Signature and - Encryption Header Parameters" registry for Header Parameter names. - The registry records the Header Parameter name and a reference to the - specification that defines it. The same Header Parameter name can be - registered multiple times, provided that the parameter usage is - compatible between the specifications. Different registrations of - the same Header Parameter name will typically use different Header - Parameter Usage Locations values. - -9.1.1. Registration Template - - Header Parameter Name: - The name requested (e.g., "kid"). Because a core goal of this - specification is for the resulting representations to be compact, - it is RECOMMENDED that the name be short -- not to exceed 8 - characters without a compelling reason to do so. This name is - - - -Jones, et al. Standards Track [Page 23] - -RFC 7515 JSON Web Signature (JWS) May 2015 - - - case sensitive. Names may not match other registered names in a - case-insensitive manner unless the Designated Experts state that - there is a compelling reason to allow an exception. - - Header Parameter Description: - Brief description of the Header Parameter (e.g., "Key ID"). - - Header Parameter Usage Location(s): - The Header Parameter usage locations, which should be one or more - of the values "JWS" or "JWE". - - Change Controller: - For Standards Track RFCs, list the "IESG". For others, give the - name of the responsible party. Other details (e.g., postal - address, email address, home page URI) may also be included. - - Specification Document(s): - Reference to the document or documents that specify the parameter, - preferably including URIs that can be used to retrieve copies of - the documents. An indication of the relevant sections may also be - included but is not required. - -9.1.2. Initial Registry Contents - - This section registers the Header Parameter names defined in - Section 4.1 in this registry. - - o Header Parameter Name: "alg" - o Header Parameter Description: Algorithm - o Header Parameter Usage Location(s): JWS - o Change Controller: IESG - o Specification Document(s): Section 4.1.1 of RFC 7515 - - o Header Parameter Name: "jku" - o Header Parameter Description: JWK Set URL - o Header Parameter Usage Location(s): JWS - o Change Controller: IESG - o Specification Document(s): Section 4.1.2 of RFC 7515 - - o Header Parameter Name: "jwk" - o Header Parameter Description: JSON Web Key - o Header Parameter Usage Location(s): JWS - o Change Controller: IESG - o Specification Document(s): Section 4.1.3 of RFC 7515 - - - - - - - -Jones, et al. Standards Track [Page 24] - -RFC 7515 JSON Web Signature (JWS) May 2015 - - - o Header Parameter Name: "kid" - o Header Parameter Description: Key ID - o Header Parameter Usage Location(s): JWS - o Change Controller: IESG - o Specification Document(s): Section 4.1.4 of RFC 7515 - - o Header Parameter Name: "x5u" - o Header Parameter Description: X.509 URL - o Header Parameter Usage Location(s): JWS - o Change Controller: IESG - o Specification Document(s): Section 4.1.5 of RFC 7515 - - o Header Parameter Name: "x5c" - o Header Parameter Description: X.509 Certificate Chain - o Header Parameter Usage Location(s): JWS - o Change Controller: IESG - o Specification Document(s): Section 4.1.6 of RFC 7515 - - o Header Parameter Name: "x5t" - o Header Parameter Description: X.509 Certificate SHA-1 Thumbprint - o Header Parameter Usage Location(s): JWS - o Change Controller: IESG - o Specification Document(s): Section 4.1.7 of RFC 7515 - - o Header Parameter Name: "x5t#S256" - o Header Parameter Description: X.509 Certificate SHA-256 Thumbprint - o Header Parameter Usage Location(s): JWS - o Change Controller: IESG - o Specification Document(s): Section 4.1.8 of RFC 7515 - - o Header Parameter Name: "typ" - o Header Parameter Description: Type - o Header Parameter Usage Location(s): JWS - o Change Controller: IESG - o Specification Document(s): Section 4.1.9 of RFC 7515 - - o Header Parameter Name: "cty" - o Header Parameter Description: Content Type - o Header Parameter Usage Location(s): JWS - o Change Controller: IESG - o Specification Document(s): Section 4.1.10 of RFC 7515 - - o Header Parameter Name: "crit" - o Header Parameter Description: Critical - o Header Parameter Usage Location(s): JWS - o Change Controller: IESG - o Specification Document(s): Section 4.1.11 of RFC 7515 - - - - -Jones, et al. Standards Track [Page 25] - -RFC 7515 JSON Web Signature (JWS) May 2015 - - -9.2. Media Type Registration - -9.2.1. Registry Contents - - This section registers the "application/jose" media type [RFC2046] in - the "Media Types" registry [IANA.MediaTypes] in the manner described - in RFC 6838 [RFC6838], which can be used to indicate that the content - is a JWS or JWE using the JWS Compact Serialization or the JWE - Compact Serialization. This section also registers the "application/ - jose+json" media type in the "Media Types" registry, which can be - used to indicate that the content is a JWS or JWE using the JWS JSON - Serialization or the JWE JSON Serialization. - - o Type name: application - o Subtype name: jose - o Required parameters: n/a - o Optional parameters: n/a - o Encoding considerations: 8bit; application/jose values are encoded - as a series of base64url-encoded values (some of which may be the - empty string), each separated from the next by a single period - ('.') character. - o Security considerations: See the Security Considerations section - of RFC 7515. - o Interoperability considerations: n/a - o Published specification: RFC 7515 - o Applications that use this media type: OpenID Connect, Mozilla - Persona, Salesforce, Google, Android, Windows Azure, Xbox One, - Amazon Web Services, and numerous others that use JWTs - o Fragment identifier considerations: n/a - o Additional information: - - Magic number(s): n/a - File extension(s): n/a - Macintosh file type code(s): n/a - - o Person & email address to contact for further information: - Michael B. Jones, mbj@microsoft.com - o Intended usage: COMMON - o Restrictions on usage: none - o Author: Michael B. Jones, mbj@microsoft.com - o Change Controller: IESG - o Provisional registration? No - - - - - - - - - -Jones, et al. Standards Track [Page 26] - -RFC 7515 JSON Web Signature (JWS) May 2015 - - - o Type name: application - o Subtype name: jose+json - o Required parameters: n/a - o Optional parameters: n/a - o Encoding considerations: 8bit; application/jose+json values are - represented as a JSON Object; UTF-8 encoding SHOULD be employed - for the JSON object. - o Security considerations: See the Security Considerations section - of RFC 7515 - o Interoperability considerations: n/a - o Published specification: RFC 7515 - o Applications that use this media type: Nimbus JOSE + JWT library - o Fragment identifier considerations: n/a - o Additional information: - - Magic number(s): n/a - File extension(s): n/a - Macintosh file type code(s): n/a - - o Person & email address to contact for further information: - Michael B. Jones, mbj@microsoft.com - o Intended usage: COMMON - o Restrictions on usage: none - o Author: Michael B. Jones, mbj@microsoft.com - o Change Controller: IESG - o Provisional registration? No - -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 and employing countermeasures to various attacks. - - All the security considerations in "XML Signature Syntax and - Processing Version 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 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. - - - - - -Jones, et al. Standards Track [Page 27] - -RFC 7515 JSON Web Signature (JWS) May 2015 - - - Implementations must randomly generate public/private key pairs, MAC - keys, and padding values. The use of inadequate pseudorandom 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. - -10.2. Key Protection - - Implementations must protect the signer's private key. Compromise of - the signer's private key permits an attacker to masquerade as the - signer. - - Implementations must protect the MAC key. Compromise of the MAC key - may result in undetectable modification of the authenticated content. - -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 - - - -Jones, et al. Standards Track [Page 28] - -RFC 7515 JSON Web Signature (JWS) May 2015 - - - replicated servers); however, a MAC key needs to be in the hands of - all the entities that use it for integrity computation and checking. - Validation of a MAC only provides corroboration that the message was - generated by one of the parties that knows the symmetric MAC key. - This means that origination can only be determined if a MAC key is - known only to two entities and the recipient knows that it did not - create the message. MAC validation cannot be used to prove - origination to a third party. - -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-PKCS1-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 Cryptographic Message Syntax - (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 - - - - -Jones, et al. Standards Track [Page 29] - -RFC 7515 JSON Web Signature (JWS) May 2015 - - - 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 JWS - 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. - - - - - -Jones, et al. Standards Track [Page 30] - -RFC 7515 JSON Web Signature (JWS) May 2015 - - - 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.12. JSON Security Considerations - - Strict JSON [RFC7159] validation is a security requirement. If - malformed JSON is received, then the intent of the producer 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 MUST be - rejected in their entirety by JSON parsers. - - Section 4 of "The JavaScript Object Notation (JSON) Data Interchange - Format" [RFC7159] states, "The names within an object SHOULD be - unique", whereas this specification states that - - The Header Parameter names within the JOSE Header MUST be unique; - JWS parsers MUST either reject JWSs with duplicate Header - Parameter names or use a JSON parser that returns only the - lexically last duplicate member name, as specified in - Section 15.12 ("The JSON Object") of ECMAScript 5.1 [ECMAScript]. - - Thus, this specification requires that the "SHOULD" in Section 4 of - [RFC7159] be treated as a "MUST" by producers and that it be either - treated as a "MUST" or treated in the manner specified in ECMAScript - 5.1 by consumers. Ambiguous and 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". Implementations MUST consider JWSs - containing such input to be invalid. - -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"). - - - -Jones, et al. Standards Track [Page 31] - -RFC 7515 JSON Web Signature (JWS) May 2015 - - - JSON strings can contain characters outside the Unicode Basic - Multilingual Plane. For instance, the G clef character (U+1D11E) may - be represented in a JSON string as "\uD834\uDD1E". Ideally, JWS - implementations SHOULD ensure that characters outside the Basic - Multilingual Plane are preserved and compared correctly; - alternatively, if this is not possible due to these characters - exercising limitations present in the underlying JSON implementation, - then input containing them MUST be rejected. - -11. References - -11.1. Normative References - - [ECMAScript] Ecma International, "ECMAScript Language Specification, - 5.1 Edition", ECMA 262, June 2011, - . - - [IANA.MediaTypes] - IANA, "Media Types", - . - - [ITU.X690.2008] - 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, 2008. - - [JWA] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518, - DOI 10.17487/RFC7518, May 2015, - . - - [JWK] Jones, M., "JSON Web Key (JWK)", RFC 7517, - DOI 10.17487/RFC7517, May 2015, - . - - [RFC20] Cerf, V., "ASCII format for Network Interchange", - STD 80, RFC 20, DOI 10.17487/RFC0020, October 1969, - . - - [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail - Extensions (MIME) Part One: Format of Internet Message - Bodies", RFC 2045, DOI 10.17487/RFC2045, November 1996, - . - - - - - - -Jones, et al. Standards Track [Page 32] - -RFC 7515 JSON Web Signature (JWS) May 2015 - - - [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail - Extensions (MIME) Part Two: Media Types", RFC 2046, - DOI 10.17487/RFC2046, November 1996, - . - - [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate - Requirement Levels", BCP 14, RFC 2119, - DOI 10.17487/RFC2119, March 1997, - . - - [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, - DOI 10.17487/RFC2818, May 2000, - . - - [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO - 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November - 2003, . - - [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform - Resource Identifier (URI): Generic Syntax", STD 66, - RFC 3986, DOI 10.17487/RFC3986, January 2005, - . - - [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data - Encodings", RFC 4648, DOI 10.17487/RFC4648, October - 2006, . - - [RFC4945] Korver, B., "The Internet IP Security PKI Profile of - IKEv1/ISAKMP, IKEv2, and PKIX", RFC 4945, - DOI 10.17487/RFC4945, August 2007, - . - - [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", - FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007, - . - - [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer - Security (TLS) Protocol Version 1.2", RFC 5246, - DOI 10.17487/RFC5246, August 2008, - . - - [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., - Housley, R., and W. Polk, "Internet X.509 Public Key - Infrastructure Certificate and Certificate Revocation - List (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May - 2008, . - - - - - -Jones, et al. Standards Track [Page 33] - -RFC 7515 JSON Web Signature (JWS) May 2015 - - - [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and - Verification of Domain-Based Application Service - Identity within Internet Public Key Infrastructure Using - X.509 (PKIX) Certificates in the Context of Transport - Layer Security (TLS)", RFC 6125, DOI 10.17487/RFC6125, - March 2011, . - - [RFC6176] Turner, S. and T. Polk, "Prohibiting Secure Sockets - Layer (SSL) Version 2.0", RFC 6176, - DOI 10.17487/RFC6176, March 2011, - . - - [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) - Data Interchange Format", RFC 7159, - DOI 10.17487/RFC7159, March 2014, - . - - [UNICODE] The Unicode Consortium, "The Unicode Standard", - . - -11.2. Informative References - - [CanvasApp] Facebook, "Canvas Applications", - . - - [JSS] Bradley, J. and N. Sakimura, Ed., "JSON Simple Sign", - September 2010, . - - [JWE] Jones, M. and J. Hildebrand, "JSON Web Encryption - (JWE)", RFC 7516, DOI 10.17487/RFC7516, May 2015, - . - - [JWT] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token - (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, - . - - [MagicSignatures] - Panzer, J., Ed., 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, - DOI 10.17487/RFC2104, February 1997, - . - - - - -Jones, et al. Standards Track [Page 34] - -RFC 7515 JSON Web Signature (JWS) May 2015 - - - [RFC3447] Jonsson, J. and B. Kaliski, "Public-Key Cryptography - Standards (PKCS) #1: RSA Cryptography Specifications - Version 2.1", RFC 3447, DOI 10.17487/RFC3447, February - 2003, . - - [RFC4086] Eastlake 3rd, D., Schiller, J., and S. Crocker, - "Randomness Requirements for Security", BCP 106, - RFC 4086, DOI 10.17487/RFC4086, June 2005, - . - - [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally - Unique IDentifier (UUID) URN Namespace", RFC 4122, - DOI 10.17487/RFC4122, July 2005, - . - - [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an - IANA Considerations Section in RFCs", BCP 26, RFC 5226, - DOI 10.17487/RFC5226, May 2008, - . - - [RFC6211] Schaad, J., "Cryptographic Message Syntax (CMS) - Algorithm Identifier Protection Attribute", RFC 6211, - DOI 10.17487/RFC6211, April 2011, - . - - [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type - Specifications and Registration Procedures", BCP 13, - RFC 6838, DOI 10.17487/RFC6838, January 2013, - . - - [RFC7525] Sheffer, Y., Holz, R., and P. Saint-Andre, - "Recommendations for Secure Use of Transport Layer - Security (TLS) and Datagram Transport Layer Security - (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May - 2015, . - - [SHS] National Institute of Standards and Technology, "Secure - 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, - . - - - - -Jones, et al. Standards Track [Page 35] - -RFC 7515 JSON Web Signature (JWS) May 2015 - - - [W3C.NOTE-xmldsig-core2-20130411] - Eastlake, D., Reagle, J., Solo, D., Hirsch, F., - Roessler, T., Yiu, K., Datta, P., and S. Cantor, "XML - Signature Syntax and Processing Version 2.0", World Wide - Web Consortium Note NOTE-xmldsig-core2-20130411, April - 2013, - . - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Jones, et al. Standards Track [Page 36] - -RFC 7515 JSON Web Signature (JWS) May 2015 - - -Appendix A. JWS Examples - - This section provides several examples of JWSs. While the first - three examples all represent JSON Web Tokens (JWTs) [JWT], the - payload can be any octet sequence, as shown in Appendix A.4. - -A.1. Example JWS Using HMAC SHA-256 - -A.1.1. Encoding - - The following example JWS Protected Header declares that the data - structure is a JWT [JWT] and the JWS Signing Input is secured using - the HMAC SHA-256 algorithm. - - {"typ":"JWT", - "alg":"HS256"} - - To remove potential ambiguities in the representation of the JSON - object above, the actual octet sequence representing UTF8(JWS - Protected Header) used in this example is also included below. (Note - that ambiguities can arise due to differing platform representations - of line breaks (CRLF versus LF), differing spacing at the beginning - and ends of lines, whether the last line has a terminating line break - or not, and other causes. In the representation used in this - example, the first line has no leading or trailing spaces, a CRLF - line break (13, 10) occurs between the first and second lines, the - second line has one leading space (32) and no trailing spaces, and - the last line does not have a terminating line break.) The octets - representing UTF8(JWS Protected Header) in this example (using JSON - array notation) are: - - [123, 34, 116, 121, 112, 34, 58, 34, 74, 87, 84, 34, 44, 13, 10, 32, - 34, 97, 108, 103, 34, 58, 34, 72, 83, 50, 53, 54, 34, 125] - - Encoding this JWS Protected Header as BASE64URL(UTF8(JWS Protected - Header)) gives this value: - - eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9 - - The JWS Payload used in this example is the octets of the UTF-8 - representation of the JSON object below. (Note that the payload can - be any base64url-encoded octet sequence and need not be a base64url- - encoded JSON object.) - - {"iss":"joe", - "exp":1300819380, - "http://example.com/is_root":true} - - - - -Jones, et al. Standards Track [Page 37] - -RFC 7515 JSON Web Signature (JWS) May 2015 - - - The following octet sequence, which is the UTF-8 representation used - in this example for the JSON object above, is the JWS Payload: - - [123, 34, 105, 115, 115, 34, 58, 34, 106, 111, 101, 34, 44, 13, 10, - 32, 34, 101, 120, 112, 34, 58, 49, 51, 48, 48, 56, 49, 57, 51, 56, - 48, 44, 13, 10, 32, 34, 104, 116, 116, 112, 58, 47, 47, 101, 120, 97, - 109, 112, 108, 101, 46, 99, 111, 109, 47, 105, 115, 95, 114, 111, - 111, 116, 34, 58, 116, 114, 117, 101, 125] - - Encoding this JWS Payload as BASE64URL(UTF8(JWS Payload)) gives this - value (with line breaks for display purposes only): - - eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt - cGxlLmNvbS9pc19yb290Ijp0cnVlfQ - - Combining these as BASE64URL(UTF8(JWS Protected Header)) || '.' || - BASE64URL(JWS Payload) gives this string (with line breaks for - display purposes only): - - eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9 - . - eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt - cGxlLmNvbS9pc19yb290Ijp0cnVlfQ - - The resulting JWS Signing Input value, which is the ASCII - representation of above string, is the following octet sequence - (using JSON array notation): - - [101, 121, 74, 48, 101, 88, 65, 105, 79, 105, 74, 75, 86, 49, 81, - 105, 76, 65, 48, 75, 73, 67, 74, 104, 98, 71, 99, 105, 79, 105, 74, - 73, 85, 122, 73, 49, 78, 105, 74, 57, 46, 101, 121, 74, 112, 99, 51, - 77, 105, 79, 105, 74, 113, 98, 50, 85, 105, 76, 65, 48, 75, 73, 67, - 74, 108, 101, 72, 65, 105, 79, 106, 69, 122, 77, 68, 65, 52, 77, 84, - 107, 122, 79, 68, 65, 115, 68, 81, 111, 103, 73, 109, 104, 48, 100, - 72, 65, 54, 76, 121, 57, 108, 101, 71, 70, 116, 99, 71, 120, 108, 76, - 109, 78, 118, 98, 83, 57, 112, 99, 49, 57, 121, 98, 50, 57, 48, 73, - 106, 112, 48, 99, 110, 86, 108, 102, 81] - - HMACs are generated using keys. This example uses the symmetric key - represented in JSON Web Key [JWK] format below (with line breaks - within values for display purposes only): - - {"kty":"oct", - "k":"AyM1SysPpbyDfgZld3umj1qzKObwVMkoqQ-EstJQLr_T-1qS0gZH75 - aKtMN3Yj0iPS4hcgUuTwjAzZr1Z9CAow" - } - - - - - -Jones, et al. Standards Track [Page 38] - -RFC 7515 JSON Web Signature (JWS) May 2015 - - - Running the HMAC SHA-256 algorithm on the JWS Signing Input with this - key yields this JWS Signature octet sequence: - - [116, 24, 223, 180, 151, 153, 224, 37, 79, 250, 96, 125, 216, 173, - 187, 186, 22, 212, 37, 77, 105, 214, 191, 240, 91, 88, 5, 88, 83, - 132, 141, 121] - - Encoding this JWS Signature as BASE64URL(JWS Signature) gives this - value: - - dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk - - Concatenating these values in the order Header.Payload.Signature with - period ('.') characters between the parts yields this complete JWS - representation using the JWS Compact Serialization (with line breaks - for display purposes only): - - eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9 - . - eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt - cGxlLmNvbS9pc19yb290Ijp0cnVlfQ - . - dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk - -A.1.2. Validating - - Since the "alg" Header Parameter is "HS256", we validate the HMAC - SHA-256 value contained in the JWS Signature. - - To validate the HMAC value, we repeat the previous process of using - the correct key and the JWS Signing Input (which is the initial - substring of the JWS Compact Serialization representation up until - but not including the second period character) as input to the HMAC - SHA-256 function and then taking the output and determining if it - matches the JWS Signature (which is base64url decoded from the value - encoded in the JWS representation). If it matches exactly, the HMAC - has been validated. - -A.2. Example JWS Using RSASSA-PKCS1-v1_5 SHA-256 - -A.2.1. Encoding - - The JWS Protected Header in this example is different from the - previous example in two ways. First, because a different algorithm - is being used, the "alg" value is different. Second, for - illustration purposes only, the optional "typ" (type) Header - Parameter is not used. (This difference is not related to the - algorithm employed.) The JWS Protected Header used is: - - - -Jones, et al. Standards Track [Page 39] - -RFC 7515 JSON Web Signature (JWS) May 2015 - - - {"alg":"RS256"} - - The octets representing UTF8(JWS Protected Header) in this example - (using JSON array notation) are: - - [123, 34, 97, 108, 103, 34, 58, 34, 82, 83, 50, 53, 54, 34, 125] - - Encoding this JWS Protected Header as BASE64URL(UTF8(JWS Protected - Header)) gives this value: - - eyJhbGciOiJSUzI1NiJ9 - - The JWS Payload used in this example, which follows, is the same as - in the previous example. Since the BASE64URL(JWS Payload) value will - therefore be the same, its computation is not repeated here. - - {"iss":"joe", - "exp":1300819380, - "http://example.com/is_root":true} - - Combining these as BASE64URL(UTF8(JWS Protected Header)) || '.' || - BASE64URL(JWS Payload) gives this string (with line breaks for - display purposes only): - - eyJhbGciOiJSUzI1NiJ9 - . - eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt - cGxlLmNvbS9pc19yb290Ijp0cnVlfQ - - The resulting JWS Signing Input value, which is the ASCII - representation of above string, is the following octet sequence: - - [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 83, 85, 122, 73, - 49, 78, 105, 74, 57, 46, 101, 121, 74, 112, 99, 51, 77, 105, 79, 105, - 74, 113, 98, 50, 85, 105, 76, 65, 48, 75, 73, 67, 74, 108, 101, 72, - 65, 105, 79, 106, 69, 122, 77, 68, 65, 52, 77, 84, 107, 122, 79, 68, - 65, 115, 68, 81, 111, 103, 73, 109, 104, 48, 100, 72, 65, 54, 76, - 121, 57, 108, 101, 71, 70, 116, 99, 71, 120, 108, 76, 109, 78, 118, - 98, 83, 57, 112, 99, 49, 57, 121, 98, 50, 57, 48, 73, 106, 112, 48, - 99, 110, 86, 108, 102, 81] - - - - - - - - - - - -Jones, et al. Standards Track [Page 40] - -RFC 7515 JSON Web Signature (JWS) May 2015 - - - This example uses the RSA key represented in JSON Web Key [JWK] - format below (with line breaks within values for display purposes - only): - - {"kty":"RSA", - "n":"ofgWCuLjybRlzo0tZWJjNiuSfb4p4fAkd_wWJcyQoTbji9k0l8W26mPddx - HmfHQp-Vaw-4qPCJrcS2mJPMEzP1Pt0Bm4d4QlL-yRT-SFd2lZS-pCgNMs - D1W_YpRPEwOWvG6b32690r2jZ47soMZo9wGzjb_7OMg0LOL-bSf63kpaSH - SXndS5z5rexMdbBYUsLA9e-KXBdQOS-UTo7WTBEMa2R2CapHg665xsmtdV - MTBQY4uDZlxvb3qCo5ZwKh9kG4LT6_I5IhlJH7aGhyxXFvUK-DWNmoudF8 - NAco9_h9iaGNj8q2ethFkMLs91kzk2PAcDTW9gb54h4FRWyuXpoQ", - "e":"AQAB", - "d":"Eq5xpGnNCivDflJsRQBXHx1hdR1k6Ulwe2JZD50LpXyWPEAeP88vLNO97I - jlA7_GQ5sLKMgvfTeXZx9SE-7YwVol2NXOoAJe46sui395IW_GO-pWJ1O0 - BkTGoVEn2bKVRUCgu-GjBVaYLU6f3l9kJfFNS3E0QbVdxzubSu3Mkqzjkn - 439X0M_V51gfpRLI9JYanrC4D4qAdGcopV_0ZHHzQlBjudU2QvXt4ehNYT - CBr6XCLQUShb1juUO1ZdiYoFaFQT5Tw8bGUl_x_jTj3ccPDVZFD9pIuhLh - BOneufuBiB4cS98l2SR_RQyGWSeWjnczT0QU91p1DhOVRuOopznQ", - "p":"4BzEEOtIpmVdVEZNCqS7baC4crd0pqnRH_5IB3jw3bcxGn6QLvnEtfdUdi - YrqBdss1l58BQ3KhooKeQTa9AB0Hw_Py5PJdTJNPY8cQn7ouZ2KKDcmnPG - BY5t7yLc1QlQ5xHdwW1VhvKn-nXqhJTBgIPgtldC-KDV5z-y2XDwGUc", - "q":"uQPEfgmVtjL0Uyyx88GZFF1fOunH3-7cepKmtH4pxhtCoHqpWmT8YAmZxa - ewHgHAjLYsp1ZSe7zFYHj7C6ul7TjeLQeZD_YwD66t62wDmpe_HlB-TnBA - -njbglfIsRLtXlnDzQkv5dTltRJ11BKBBypeeF6689rjcJIDEz9RWdc", - "dp":"BwKfV3Akq5_MFZDFZCnW-wzl-CCo83WoZvnLQwCTeDv8uzluRSnm71I3Q - CLdhrqE2e9YkxvuxdBfpT_PI7Yz-FOKnu1R6HsJeDCjn12Sk3vmAktV2zb - 34MCdy7cpdTh_YVr7tss2u6vneTwrA86rZtu5Mbr1C1XsmvkxHQAdYo0", - "dq":"h_96-mK1R_7glhsum81dZxjTnYynPbZpHziZjeeHcXYsXaaMwkOlODsWa - 7I9xXDoRwbKgB719rrmI2oKr6N3Do9U0ajaHF-NKJnwgjMd2w9cjz3_-ky - NlxAr2v4IKhGNpmM5iIgOS1VZnOZ68m6_pbLBSp3nssTdlqvd0tIiTHU", - "qi":"IYd7DHOhrWvxkwPQsRM2tOgrjbcrfvtQJipd-DlcxyVuuM9sQLdgjVk2o - y26F0EmpScGLq2MowX7fhd_QJQ3ydy5cY7YIBi87w93IKLEdfnbJtoOPLU - W0ITrJReOgo1cq9SbsxYawBgfp_gh6A5603k2-ZQwVK0JKSHuLFkuQ3U" - } - - - - - - - - - - - - - - - - - -Jones, et al. Standards Track [Page 41] - -RFC 7515 JSON Web Signature (JWS) May 2015 - - - The RSA private key is then passed to the RSA signing function, which - also takes the hash type, SHA-256, and the JWS Signing Input as - inputs. The result of the digital signature is an octet sequence, - which represents a big-endian integer. In this example, it is: - - [112, 46, 33, 137, 67, 232, 143, 209, 30, 181, 216, 45, 191, 120, 69, - 243, 65, 6, 174, 27, 129, 255, 247, 115, 17, 22, 173, 209, 113, 125, - 131, 101, 109, 66, 10, 253, 60, 150, 238, 221, 115, 162, 102, 62, 81, - 102, 104, 123, 0, 11, 135, 34, 110, 1, 135, 237, 16, 115, 249, 69, - 229, 130, 173, 252, 239, 22, 216, 90, 121, 142, 232, 198, 109, 219, - 61, 184, 151, 91, 23, 208, 148, 2, 190, 237, 213, 217, 217, 112, 7, - 16, 141, 178, 129, 96, 213, 248, 4, 12, 167, 68, 87, 98, 184, 31, - 190, 127, 249, 217, 46, 10, 231, 111, 36, 242, 91, 51, 187, 230, 244, - 74, 230, 30, 177, 4, 10, 203, 32, 4, 77, 62, 249, 18, 142, 212, 1, - 48, 121, 91, 212, 189, 59, 65, 238, 202, 208, 102, 171, 101, 25, 129, - 253, 228, 141, 247, 127, 55, 45, 195, 139, 159, 175, 221, 59, 239, - 177, 139, 93, 163, 204, 60, 46, 176, 47, 158, 58, 65, 214, 18, 202, - 173, 21, 145, 18, 115, 160, 95, 35, 185, 232, 56, 250, 175, 132, 157, - 105, 132, 41, 239, 90, 30, 136, 121, 130, 54, 195, 212, 14, 96, 69, - 34, 165, 68, 200, 242, 122, 122, 45, 184, 6, 99, 209, 108, 247, 202, - 234, 86, 222, 64, 92, 178, 33, 90, 69, 178, 194, 85, 102, 181, 90, - 193, 167, 72, 160, 112, 223, 200, 163, 42, 70, 149, 67, 208, 25, 238, - 251, 71] - - Encoding the signature as BASE64URL(JWS Signature) produces this - value (with line breaks for display purposes only): - - cC4hiUPoj9Eetdgtv3hF80EGrhuB__dzERat0XF9g2VtQgr9PJbu3XOiZj5RZmh7 - AAuHIm4Bh-0Qc_lF5YKt_O8W2Fp5jujGbds9uJdbF9CUAr7t1dnZcAcQjbKBYNX4 - BAynRFdiuB--f_nZLgrnbyTyWzO75vRK5h6xBArLIARNPvkSjtQBMHlb1L07Qe7K - 0GarZRmB_eSN9383LcOLn6_dO--xi12jzDwusC-eOkHWEsqtFZESc6BfI7noOPqv - hJ1phCnvWh6IeYI2w9QOYEUipUTI8np6LbgGY9Fs98rqVt5AXLIhWkWywlVmtVrB - p0igcN_IoypGlUPQGe77Rw - - - - - - - - - - - - - - - - - - -Jones, et al. Standards Track [Page 42] - -RFC 7515 JSON Web Signature (JWS) May 2015 - - - Concatenating these values in the order Header.Payload.Signature with - period ('.') characters between the parts yields this complete JWS - representation using the JWS Compact Serialization (with line breaks - for display purposes only): - - eyJhbGciOiJSUzI1NiJ9 - . - eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt - cGxlLmNvbS9pc19yb290Ijp0cnVlfQ - . - cC4hiUPoj9Eetdgtv3hF80EGrhuB__dzERat0XF9g2VtQgr9PJbu3XOiZj5RZmh7 - AAuHIm4Bh-0Qc_lF5YKt_O8W2Fp5jujGbds9uJdbF9CUAr7t1dnZcAcQjbKBYNX4 - BAynRFdiuB--f_nZLgrnbyTyWzO75vRK5h6xBArLIARNPvkSjtQBMHlb1L07Qe7K - 0GarZRmB_eSN9383LcOLn6_dO--xi12jzDwusC-eOkHWEsqtFZESc6BfI7noOPqv - hJ1phCnvWh6IeYI2w9QOYEUipUTI8np6LbgGY9Fs98rqVt5AXLIhWkWywlVmtVrB - p0igcN_IoypGlUPQGe77Rw - -A.2.2. Validating - - Since the "alg" Header Parameter is "RS256", we validate the RSASSA- - PKCS1-v1_5 SHA-256 digital signature contained in the JWS Signature. - - Validating the JWS Signature is a bit different from the previous - example. We pass the public key (n, e), the JWS Signature (which is - base64url decoded from the value encoded in the JWS representation), - and the JWS Signing Input (which is the initial substring of the JWS - Compact Serialization representation up until but not including the - second period character) to an RSASSA-PKCS1-v1_5 signature verifier - that has been configured to use the SHA-256 hash function. - -A.3. Example JWS Using ECDSA P-256 SHA-256 - -A.3.1. Encoding - - The JWS Protected Header for this example differs from the previous - example because a different algorithm is being used. The JWS - Protected Header used is: - - {"alg":"ES256"} - - The octets representing UTF8(JWS Protected Header) in this example - (using JSON array notation) are: - - [123, 34, 97, 108, 103, 34, 58, 34, 69, 83, 50, 53, 54, 34, 125] - - - - - - - -Jones, et al. Standards Track [Page 43] - -RFC 7515 JSON Web Signature (JWS) May 2015 - - - Encoding this JWS Protected Header as BASE64URL(UTF8(JWS Protected - Header)) gives this value: - - eyJhbGciOiJFUzI1NiJ9 - - The JWS Payload used in this example, which follows, is the same as - in the previous examples. Since the BASE64URL(JWS Payload) value - will therefore be the same, its computation is not repeated here. - - {"iss":"joe", - "exp":1300819380, - "http://example.com/is_root":true} - - Combining these as BASE64URL(UTF8(JWS Protected Header)) || '.' || - BASE64URL(JWS Payload) gives this string (with line breaks for - display purposes only): - - eyJhbGciOiJFUzI1NiJ9 - . - eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt - cGxlLmNvbS9pc19yb290Ijp0cnVlfQ - - The resulting JWS Signing Input value, which is the ASCII - representation of above string, is the following octet sequence: - - [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 70, 85, 122, 73, - 49, 78, 105, 74, 57, 46, 101, 121, 74, 112, 99, 51, 77, 105, 79, 105, - 74, 113, 98, 50, 85, 105, 76, 65, 48, 75, 73, 67, 74, 108, 101, 72, - 65, 105, 79, 106, 69, 122, 77, 68, 65, 52, 77, 84, 107, 122, 79, 68, - 65, 115, 68, 81, 111, 103, 73, 109, 104, 48, 100, 72, 65, 54, 76, - 121, 57, 108, 101, 71, 70, 116, 99, 71, 120, 108, 76, 109, 78, 118, - 98, 83, 57, 112, 99, 49, 57, 121, 98, 50, 57, 48, 73, 106, 112, 48, - 99, 110, 86, 108, 102, 81] - - This example uses the Elliptic Curve key represented in JSON Web Key - [JWK] format below: - - {"kty":"EC", - "crv":"P-256", - "x":"f83OJ3D2xF1Bg8vub9tLe1gHMzV76e8Tus9uPHvRVEU", - "y":"x_FEzRu9m36HLN_tue659LNpXW6pCyStikYjKIWI5a0", - "d":"jpsQnnGQmL-YBIffH1136cspYG6-0iY7X1fCE9-E9LI" - } - - The Elliptic Curve Digital Signature Algorithm (ECDSA) private part d - is then passed to an ECDSA signing function, which also takes the - curve type, P-256, the hash type, SHA-256, and the JWS Signing Input - as inputs. The result of the digital signature is the Elliptic Curve - - - -Jones, et al. Standards Track [Page 44] - -RFC 7515 JSON Web Signature (JWS) May 2015 - - - (EC) point (R, S), where R and S are unsigned integers. In this - example, the R and S values, given as octet sequences representing - big-endian integers are: - - +--------+----------------------------------------------------------+ - | Result | Value | - | Name | | - +--------+----------------------------------------------------------+ - | R | [14, 209, 33, 83, 121, 99, 108, 72, 60, 47, 127, 21, 88, | - | | 7, 212, 2, 163, 178, 40, 3, 58, 249, 124, 126, 23, 129, | - | | 154, 195, 22, 158, 166, 101] | - | S | [197, 10, 7, 211, 140, 60, 112, 229, 216, 241, 45, 175, | - | | 8, 74, 84, 128, 166, 101, 144, 197, 242, 147, 80, 154, | - | | 143, 63, 127, 138, 131, 163, 84, 213] | - +--------+----------------------------------------------------------+ - - The JWS Signature is the value R || S. Encoding the signature as - BASE64URL(JWS Signature) produces this value (with line breaks for - display purposes only): - - DtEhU3ljbEg8L38VWAfUAqOyKAM6-Xx-F4GawxaepmXFCgfTjDxw5djxLa8ISlSA - pmWQxfKTUJqPP3-Kg6NU1Q - - Concatenating these values in the order Header.Payload.Signature with - period ('.') characters between the parts yields this complete JWS - representation using the JWS Compact Serialization (with line breaks - for display purposes only): - - eyJhbGciOiJFUzI1NiJ9 - . - eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt - cGxlLmNvbS9pc19yb290Ijp0cnVlfQ - . - DtEhU3ljbEg8L38VWAfUAqOyKAM6-Xx-F4GawxaepmXFCgfTjDxw5djxLa8ISlSA - pmWQxfKTUJqPP3-Kg6NU1Q - -A.3.2. Validating - - Since the "alg" Header Parameter is "ES256", we validate the ECDSA - P-256 SHA-256 digital signature contained in the JWS Signature. - - Validating the JWS Signature is a bit different from the previous - examples. We need to split the 64 member octet sequence of the JWS - Signature (which is base64url decoded from the value encoded in the - JWS representation) into two 32 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 (which is the initial - substring of the JWS Compact Serialization representation up until - - - -Jones, et al. Standards Track [Page 45] - -RFC 7515 JSON Web Signature (JWS) May 2015 - - - but not including the second period character) to an ECDSA signature - verifier that has been configured to use the P-256 curve with the - SHA-256 hash function. - -A.4. Example JWS Using ECDSA P-521 SHA-512 - -A.4.1. Encoding - - The JWS Protected Header for this example differs from the previous - example because different ECDSA curves and hash functions are used. - The JWS Protected Header used is: - - {"alg":"ES512"} - - The octets representing UTF8(JWS Protected Header) in this example - (using JSON array notation) are: - - [123, 34, 97, 108, 103, 34, 58, 34, 69, 83, 53, 49, 50, 34, 125] - - Encoding this JWS Protected Header as BASE64URL(UTF8(JWS Protected - Header)) gives this value: - - eyJhbGciOiJFUzUxMiJ9 - - The JWS Payload used in this example is the ASCII string "Payload". - The representation of this string is the following octet sequence: - - [80, 97, 121, 108, 111, 97, 100] - - Encoding this JWS Payload as BASE64URL(JWS Payload) gives this value: - - UGF5bG9hZA - - Combining these as BASE64URL(UTF8(JWS Protected Header)) || '.' || - BASE64URL(JWS Payload) gives this string: - - eyJhbGciOiJFUzUxMiJ9.UGF5bG9hZA - - The resulting JWS Signing Input value, which is the ASCII - representation of above string, is the following octet sequence: - - [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 70, 85, 122, 85, - 120, 77, 105, 74, 57, 46, 85, 71, 70, 53, 98, 71, 57, 104, 90, 65] - - - - - - - - -Jones, et al. Standards Track [Page 46] - -RFC 7515 JSON Web Signature (JWS) May 2015 - - - This example uses the Elliptic Curve key represented in JSON Web Key - [JWK] format below (with line breaks within values for display - purposes only): - - {"kty":"EC", - "crv":"P-521", - "x":"AekpBQ8ST8a8VcfVOTNl353vSrDCLLJXmPk06wTjxrrjcBpXp5EOnYG_ - NjFZ6OvLFV1jSfS9tsz4qUxcWceqwQGk", - "y":"ADSmRA43Z1DSNx_RvcLI87cdL07l6jQyyBXMoxVg_l2Th-x3S1WDhjDl - y79ajL4Kkd0AZMaZmh9ubmf63e3kyMj2", - "d":"AY5pb7A0UFiB3RELSD64fTLOSV_jazdF7fLYyuTw8lOfRhWg6Y6rUrPA - xerEzgdRhajnu0ferB0d53vM9mE15j2C" - } - - The ECDSA private part d is then passed to an ECDSA signing function, - which also takes the curve type, P-521, the hash type, SHA-512, and - the JWS Signing Input as inputs. The result of the digital signature - is the EC point (R, S), where R and S are unsigned integers. In this - example, the R and S values, given as octet sequences representing - big-endian integers are: - - +--------+----------------------------------------------------------+ - | Result | Value | - | Name | | - +--------+----------------------------------------------------------+ - | R | [1, 220, 12, 129, 231, 171, 194, 209, 232, 135, 233, | - | | 117, 247, 105, 122, 210, 26, 125, 192, 1, 217, 21, 82, | - | | 91, 45, 240, 255, 83, 19, 34, 239, 71, 48, 157, 147, | - | | 152, 105, 18, 53, 108, 163, 214, 68, 231, 62, 153, 150, | - | | 106, 194, 164, 246, 72, 143, 138, 24, 50, 129, 223, 133, | - | | 206, 209, 172, 63, 237, 119, 109] | - | S | [0, 111, 6, 105, 44, 5, 41, 208, 128, 61, 152, 40, 92, | - | | 61, 152, 4, 150, 66, 60, 69, 247, 196, 170, 81, 193, | - | | 199, 78, 59, 194, 169, 16, 124, 9, 143, 42, 142, 131, | - | | 48, 206, 238, 34, 175, 83, 203, 220, 159, 3, 107, 155, | - | | 22, 27, 73, 111, 68, 68, 21, 238, 144, 229, 232, 148, | - | | 188, 222, 59, 242, 103] | - +--------+----------------------------------------------------------+ - - The JWS Signature is the value R || S. Encoding the signature as - BASE64URL(JWS Signature) produces this value (with line breaks for - display purposes only): - - AdwMgeerwtHoh-l192l60hp9wAHZFVJbLfD_UxMi70cwnZOYaRI1bKPWROc-mZZq - wqT2SI-KGDKB34XO0aw_7XdtAG8GaSwFKdCAPZgoXD2YBJZCPEX3xKpRwcdOO8Kp - EHwJjyqOgzDO7iKvU8vcnwNrmxYbSW9ERBXukOXolLzeO_Jn - - - - - -Jones, et al. Standards Track [Page 47] - -RFC 7515 JSON Web Signature (JWS) May 2015 - - - Concatenating these values in the order Header.Payload.Signature with - period ('.') characters between the parts yields this complete JWS - representation using the JWS Compact Serialization (with line breaks - for display purposes only): - - eyJhbGciOiJFUzUxMiJ9 - . - UGF5bG9hZA - . - AdwMgeerwtHoh-l192l60hp9wAHZFVJbLfD_UxMi70cwnZOYaRI1bKPWROc-mZZq - wqT2SI-KGDKB34XO0aw_7XdtAG8GaSwFKdCAPZgoXD2YBJZCPEX3xKpRwcdOO8Kp - EHwJjyqOgzDO7iKvU8vcnwNrmxYbSW9ERBXukOXolLzeO_Jn - -A.4.2. Validating - - Since the "alg" Header Parameter is "ES512", we validate the ECDSA - 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 Unsecured JWS - - The following example JWS Protected Header declares that the encoded - 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 - will therefore be the same, its computation is not repeated here. - - {"iss":"joe", - "exp":1300819380, - "http://example.com/is_root":true} - - The JWS Signature is the empty octet string and BASE64URL(JWS - Signature) is the empty string. - - - -Jones, et al. Standards Track [Page 48] - -RFC 7515 JSON Web Signature (JWS) May 2015 - - - Concatenating these values in the order Header.Payload.Signature with - period ('.') characters between the parts yields this complete JWS - representation using the JWS Compact Serialization (with line breaks - for display purposes only): - - eyJhbGciOiJub25lIn0 - . - eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt - cGxlLmNvbS9pc19yb290Ijp0cnVlfQ - . - -A.6. Example JWS Using General JWS JSON Serialization - - This section contains an example using the general JWS JSON - Serialization syntax. This example demonstrates the capability for - conveying multiple digital signatures and/or MACs for the same - payload. - - The JWS Payload used in this example is the same as that used in the - examples in Appendix A.2 and Appendix A.3 (with line breaks for - display purposes only): - - eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt - cGxlLmNvbS9pc19yb290Ijp0cnVlfQ - - Two digital signatures are used in this example: the first using - RSASSA-PKCS1-v1_5 SHA-256 and the second using ECDSA P-256 SHA-256. - For the first, the JWS Protected Header and key are the same as in - Appendix A.2, resulting in the same JWS Signature value; therefore, - its computation is not repeated here. For the second, the JWS - Protected Header and key are the same as in Appendix A.3, resulting - in the same JWS Signature value; therefore, its computation is not - repeated here. - -A.6.1. JWS Per-Signature Protected Headers - - The JWS Protected Header value used for the first signature is: - - {"alg":"RS256"} - - Encoding this JWS Protected Header as BASE64URL(UTF8(JWS Protected - Header)) gives this value: - - eyJhbGciOiJSUzI1NiJ9 - - The JWS Protected Header value used for the second signature is: - - {"alg":"ES256"} - - - -Jones, et al. Standards Track [Page 49] - -RFC 7515 JSON Web Signature (JWS) May 2015 - - - Encoding this JWS Protected Header as BASE64URL(UTF8(JWS Protected - Header)) gives this value: - - eyJhbGciOiJFUzI1NiJ9 - -A.6.2. JWS Per-Signature Unprotected Headers - - Key ID values are supplied for both keys using per-signature Header - Parameters. The two JWS Unprotected Header values used to represent - these key IDs are: - - {"kid":"2010-12-29"} - - and - - {"kid":"e9bc097a-ce51-4036-9562-d2ade882db0d"} - -A.6.3. Complete JOSE Header Values - - Combining the JWS Protected Header and JWS Unprotected Header values - supplied, the JOSE Header values used for the first and second - signatures, respectively, are: - - {"alg":"RS256", - "kid":"2010-12-29"} - - and - - {"alg":"ES256", - "kid":"e9bc097a-ce51-4036-9562-d2ade882db0d"} - - - - - - - - - - - - - - - - - - - - - -Jones, et al. Standards Track [Page 50] - -RFC 7515 JSON Web Signature (JWS) May 2015 - - -A.6.4. Complete JWS JSON Serialization Representation - - The complete JWS JSON Serialization for these values is as follows - (with line breaks within values for display purposes only): - - { - "payload": - "eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGF - tcGxlLmNvbS9pc19yb290Ijp0cnVlfQ", - "signatures":[ - {"protected":"eyJhbGciOiJSUzI1NiJ9", - "header": - {"kid":"2010-12-29"}, - "signature": - "cC4hiUPoj9Eetdgtv3hF80EGrhuB__dzERat0XF9g2VtQgr9PJbu3XOiZj5RZ - mh7AAuHIm4Bh-0Qc_lF5YKt_O8W2Fp5jujGbds9uJdbF9CUAr7t1dnZcAcQjb - KBYNX4BAynRFdiuB--f_nZLgrnbyTyWzO75vRK5h6xBArLIARNPvkSjtQBMHl - b1L07Qe7K0GarZRmB_eSN9383LcOLn6_dO--xi12jzDwusC-eOkHWEsqtFZES - c6BfI7noOPqvhJ1phCnvWh6IeYI2w9QOYEUipUTI8np6LbgGY9Fs98rqVt5AX - LIhWkWywlVmtVrBp0igcN_IoypGlUPQGe77Rw"}, - {"protected":"eyJhbGciOiJFUzI1NiJ9", - "header": - {"kid":"e9bc097a-ce51-4036-9562-d2ade882db0d"}, - "signature": - "DtEhU3ljbEg8L38VWAfUAqOyKAM6-Xx-F4GawxaepmXFCgfTjDxw5djxLa8IS - lSApmWQxfKTUJqPP3-Kg6NU1Q"}] - } - - - - - - - - - - - - - - - - - - - - - - - - -Jones, et al. Standards Track [Page 51] - -RFC 7515 JSON Web Signature (JWS) May 2015 - - -A.7. Example JWS Using Flattened JWS JSON Serialization - - This section contains an example using the flattened JWS JSON - Serialization syntax. This example demonstrates the capability for - conveying a single digital signature or MAC in a flattened JSON - structure. - - The values in this example are the same as those in the second - signature of the previous example in Appendix A.6. - - The complete JWS JSON Serialization for these values is as follows - (with line breaks within values for display purposes only): - - { - "payload": - "eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGF - tcGxlLmNvbS9pc19yb290Ijp0cnVlfQ", - "protected":"eyJhbGciOiJFUzI1NiJ9", - "header": - {"kid":"e9bc097a-ce51-4036-9562-d2ade882db0d"}, - "signature": - "DtEhU3ljbEg8L38VWAfUAqOyKAM6-Xx-F4GawxaepmXFCgfTjDxw5djxLa8IS - lSApmWQxfKTUJqPP3-Kg6NU1Q" - } - - - - - - - - - - - - - - - - - - - - - - - - - - - -Jones, et al. Standards Track [Page 52] - -RFC 7515 JSON Web Signature (JWS) May 2015 - - -Appendix B. "x5c" (X.509 Certificate Chain) Example - - The JSON array below is an example of a certificate chain that could - be used as the value of an "x5c" (X.509 certificate chain) Header - Parameter, per Section 4.1.6 (with line breaks within values for - display purposes only): - - ["MIIE3jCCA8agAwIBAgICAwEwDQYJKoZIhvcNAQEFBQAwYzELMAkGA1UEBhMCVVM - xITAfBgNVBAoTGFRoZSBHbyBEYWRkeSBHcm91cCwgSW5jLjExMC8GA1UECxMoR2 - 8gRGFkZHkgQ2xhc3MgMiBDZXJ0aWZpY2F0aW9uIEF1dGhvcml0eTAeFw0wNjExM - TYwMTU0MzdaFw0yNjExMTYwMTU0MzdaMIHKMQswCQYDVQQGEwJVUzEQMA4GA1UE - CBMHQXJpem9uYTETMBEGA1UEBxMKU2NvdHRzZGFsZTEaMBgGA1UEChMRR29EYWR - keS5jb20sIEluYy4xMzAxBgNVBAsTKmh0dHA6Ly9jZXJ0aWZpY2F0ZXMuZ29kYW - RkeS5jb20vcmVwb3NpdG9yeTEwMC4GA1UEAxMnR28gRGFkZHkgU2VjdXJlIENlc - nRpZmljYXRpb24gQXV0aG9yaXR5MREwDwYDVQQFEwgwNzk2OTI4NzCCASIwDQYJ - KoZIhvcNAQEBBQADggEPADCCAQoCggEBAMQt1RWMnCZM7DI161+4WQFapmGBWTt - wY6vj3D3HKrjJM9N55DrtPDAjhI6zMBS2sofDPZVUBJ7fmd0LJR4h3mUpfjWoqV - Tr9vcyOdQmVZWt7/v+WIbXnvQAjYwqDL1CBM6nPwT27oDyqu9SoWlm2r4arV3aL - GbqGmu75RpRSgAvSMeYddi5Kcju+GZtCpyz8/x4fKL4o/K1w/O5epHBp+YlLpyo - 7RJlbmr2EkRTcDCVw5wrWCs9CHRK8r5RsL+H0EwnWGu1NcWdrxcx+AuP7q2BNgW - JCJjPOq8lh8BJ6qf9Z/dFjpfMFDniNoW1fho3/Rb2cRGadDAW/hOUoz+EDU8CAw - EAAaOCATIwggEuMB0GA1UdDgQWBBT9rGEyk2xF1uLuhV+auud2mWjM5zAfBgNVH - SMEGDAWgBTSxLDSkdRMEXGzYcs9of7dqGrU4zASBgNVHRMBAf8ECDAGAQH/AgEA - MDMGCCsGAQUFBwEBBCcwJTAjBggrBgEFBQcwAYYXaHR0cDovL29jc3AuZ29kYWR - keS5jb20wRgYDVR0fBD8wPTA7oDmgN4Y1aHR0cDovL2NlcnRpZmljYXRlcy5nb2 - RhZGR5LmNvbS9yZXBvc2l0b3J5L2dkcm9vdC5jcmwwSwYDVR0gBEQwQjBABgRVH - SAAMDgwNgYIKwYBBQUHAgEWKmh0dHA6Ly9jZXJ0aWZpY2F0ZXMuZ29kYWRkeS5j - b20vcmVwb3NpdG9yeTAOBgNVHQ8BAf8EBAMCAQYwDQYJKoZIhvcNAQEFBQADggE - BANKGwOy9+aG2Z+5mC6IGOgRQjhVyrEp0lVPLN8tESe8HkGsz2ZbwlFalEzAFPI - UyIXvJxwqoJKSQ3kbTJSMUA2fCENZvD117esyfxVgqwcSeIaha86ykRvOe5GPLL - 5CkKSkB2XIsKd83ASe8T+5o0yGPwLPk9Qnt0hCqU7S+8MxZC9Y7lhyVJEnfzuz9 - p0iRFEUOOjZv2kWzRaJBydTXRE4+uXR21aITVSzGh6O1mawGhId/dQb8vxRMDsx - uxN89txJx9OjxUUAiKEngHUuHqDTMBqLdElrRhjZkAzVvb3du6/KFUJheqwNTrZ - EjYx8WnM25sgVjOuH0aBsXBTWVU+4=", - "MIIE+zCCBGSgAwIBAgICAQ0wDQYJKoZIhvcNAQEFBQAwgbsxJDAiBgNVBAcTG1Z - hbGlDZXJ0IFZhbGlkYXRpb24gTmV0d29yazEXMBUGA1UEChMOVmFsaUNlcnQsIE - luYy4xNTAzBgNVBAsTLFZhbGlDZXJ0IENsYXNzIDIgUG9saWN5IFZhbGlkYXRpb - 24gQXV0aG9yaXR5MSEwHwYDVQQDExhodHRwOi8vd3d3LnZhbGljZXJ0LmNvbS8x - IDAeBgkqhkiG9w0BCQEWEWluZm9AdmFsaWNlcnQuY29tMB4XDTA0MDYyOTE3MDY - yMFoXDTI0MDYyOTE3MDYyMFowYzELMAkGA1UEBhMCVVMxITAfBgNVBAoTGFRoZS - BHbyBEYWRkeSBHcm91cCwgSW5jLjExMC8GA1UECxMoR28gRGFkZHkgQ2xhc3MgM - iBDZXJ0aWZpY2F0aW9uIEF1dGhvcml0eTCCASAwDQYJKoZIhvcNAQEBBQADggEN - ADCCAQgCggEBAN6d1+pXGEmhW+vXX0iG6r7d/+TvZxz0ZWizV3GgXne77ZtJ6XC - APVYYYwhv2vLM0D9/AlQiVBDYsoHUwHU9S3/Hd8M+eKsaA7Ugay9qK7HFiH7Eux - 6wwdhFJ2+qN1j3hybX2C32qRe3H3I2TqYXP2WYktsqbl2i/ojgC95/5Y0V4evLO - tXiEqITLdiOr18SPaAIBQi2XKVlOARFmR6jYGB0xUGlcmIbYsUfb18aQr4CUWWo - riMYavx4A6lNf4DD+qta/KFApMoZFv6yyO9ecw3ud72a9nmYvLEHZ6IVDd2gWMZ - Eewo+YihfukEHU1jPEX44dMX4/7VpkI+EdOqXG68CAQOjggHhMIIB3TAdBgNVHQ - - - -Jones, et al. Standards Track [Page 53] - -RFC 7515 JSON Web Signature (JWS) May 2015 - - - 4EFgQU0sSw0pHUTBFxs2HLPaH+3ahq1OMwgdIGA1UdIwSByjCBx6GBwaSBvjCBu - zEkMCIGA1UEBxMbVmFsaUNlcnQgVmFsaWRhdGlvbiBOZXR3b3JrMRcwFQYDVQQK - Ew5WYWxpQ2VydCwgSW5jLjE1MDMGA1UECxMsVmFsaUNlcnQgQ2xhc3MgMiBQb2x - pY3kgVmFsaWRhdGlvbiBBdXRob3JpdHkxITAfBgNVBAMTGGh0dHA6Ly93d3cudm - FsaWNlcnQuY29tLzEgMB4GCSqGSIb3DQEJARYRaW5mb0B2YWxpY2VydC5jb22CA - QEwDwYDVR0TAQH/BAUwAwEB/zAzBggrBgEFBQcBAQQnMCUwIwYIKwYBBQUHMAGG - F2h0dHA6Ly9vY3NwLmdvZGFkZHkuY29tMEQGA1UdHwQ9MDswOaA3oDWGM2h0dHA - 6Ly9jZXJ0aWZpY2F0ZXMuZ29kYWRkeS5jb20vcmVwb3NpdG9yeS9yb290LmNybD - BLBgNVHSAERDBCMEAGBFUdIAAwODA2BggrBgEFBQcCARYqaHR0cDovL2NlcnRpZ - mljYXRlcy5nb2RhZGR5LmNvbS9yZXBvc2l0b3J5MA4GA1UdDwEB/wQEAwIBBjAN - BgkqhkiG9w0BAQUFAAOBgQC1QPmnHfbq/qQaQlpE9xXUhUaJwL6e4+PrxeNYiY+ - Sn1eocSxI0YGyeR+sBjUZsE4OWBsUs5iB0QQeyAfJg594RAoYC5jcdnplDQ1tgM - QLARzLrUc+cb53S8wGd9D0VmsfSxOaFIqII6hR8INMqzW/Rn453HWkrugp++85j - 09VZw==", - "MIIC5zCCAlACAQEwDQYJKoZIhvcNAQEFBQAwgbsxJDAiBgNVBAcTG1ZhbGlDZXJ - 0IFZhbGlkYXRpb24gTmV0d29yazEXMBUGA1UEChMOVmFsaUNlcnQsIEluYy4xNT - AzBgNVBAsTLFZhbGlDZXJ0IENsYXNzIDIgUG9saWN5IFZhbGlkYXRpb24gQXV0a - G9yaXR5MSEwHwYDVQQDExhodHRwOi8vd3d3LnZhbGljZXJ0LmNvbS8xIDAeBgkq - hkiG9w0BCQEWEWluZm9AdmFsaWNlcnQuY29tMB4XDTk5MDYyNjAwMTk1NFoXDTE - 5MDYyNjAwMTk1NFowgbsxJDAiBgNVBAcTG1ZhbGlDZXJ0IFZhbGlkYXRpb24gTm - V0d29yazEXMBUGA1UEChMOVmFsaUNlcnQsIEluYy4xNTAzBgNVBAsTLFZhbGlDZ - XJ0IENsYXNzIDIgUG9saWN5IFZhbGlkYXRpb24gQXV0aG9yaXR5MSEwHwYDVQQD - ExhodHRwOi8vd3d3LnZhbGljZXJ0LmNvbS8xIDAeBgkqhkiG9w0BCQEWEWluZm9 - AdmFsaWNlcnQuY29tMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDOOnHK5a - vIWZJV16vYdA757tn2VUdZZUcOBVXc65g2PFxTXdMwzzjsvUGJ7SVCCSRrCl6zf - N1SLUzm1NZ9WlmpZdRJEy0kTRxQb7XBhVQ7/nHk01xC+YDgkRoKWzk2Z/M/VXwb - P7RfZHM047QSv4dk+NoS/zcnwbNDu+97bi5p9wIDAQABMA0GCSqGSIb3DQEBBQU - AA4GBADt/UG9vUJSZSWI4OB9L+KXIPqeCgfYrx+jFzug6EILLGACOTb2oWH+heQ - C1u+mNr0HZDzTuIYEZoDJJKPTEjlbVUjP9UNV+mWwD5MlM/Mtsq2azSiGM5bUMM - j4QssxsodyamEwCW/POuZ6lcg5Ktz885hZo+L7tdEy8W9ViH0Pd"] - - - - - - - - - - - - - - - - - - - - - -Jones, et al. Standards Track [Page 54] - -RFC 7515 JSON Web Signature (JWS) May 2015 - - -Appendix C. Notes on Implementing base64url Encoding without Padding - - This appendix describes how to implement base64url encoding and - decoding functions without padding based upon standard base64 - encoding and decoding functions that do use padding. - - To be concrete, example C# code implementing these functions is shown - below. Similar code could be used in other languages. - - static string base64urlencode(byte [] arg) - { - string s = Convert.ToBase64String(arg); // Regular base64 encoder - s = s.Split('=')[0]; // Remove any trailing '='s - s = s.Replace('+', '-'); // 62nd char of encoding - s = s.Replace('/', '_'); // 63rd char of encoding - return s; - } - - static byte [] base64urldecode(string arg) - { - string s = arg; - s = s.Replace('-', '+'); // 62nd char of encoding - s = s.Replace('_', '/'); // 63rd char of encoding - switch (s.Length % 4) // Pad with trailing '='s - { - case 0: break; // No pad chars in this case - case 2: s += "=="; break; // Two pad chars - case 3: s += "="; break; // One pad char - default: throw new System.Exception( - "Illegal base64url string!"); - } - return Convert.FromBase64String(s); // Standard base64 decoder - } - - As per the example code above, the number of '=' padding characters - that needs to be added to the end of a base64url-encoded string - without padding to turn it into one with padding is a deterministic - function of the length of the encoded string. Specifically, if the - length mod 4 is 0, no padding is added; if the length mod 4 is 2, two - '=' padding characters are added; if the length mod 4 is 3, one '=' - padding character is added; if the length mod 4 is 1, the input is - malformed. - - - - - - - - - -Jones, et al. Standards Track [Page 55] - -RFC 7515 JSON Web Signature (JWS) May 2015 - - - An example correspondence between unencoded and encoded values - follows. The octet sequence below encodes into the string below, - which when decoded, reproduces the octet sequence. - - 3 236 255 224 193 - A-z_4ME - -Appendix D. Notes on Key Selection - - This appendix describes a set of possible algorithms for selecting - the key to be used to validate the digital signature or MAC of a JWS - or for selecting the key to be used to decrypt a JWE. This guidance - describes a family of possible algorithms rather than a single - algorithm, because in different contexts, not all the sources of keys - will be used, they can be tried in different orders, and sometimes - not all the collected keys will be tried; hence, different algorithms - will be used in different application contexts. - - The steps below are described for illustration purposes only; - specific applications can and are likely to use different algorithms - or perform some of the steps in different orders. Specific - applications will frequently have a much simpler method of - determining the keys to use, as there may be one or two key selection - methods that are profiled for the application's use. This appendix - supplements the normative information on key location in Section 6. - - These algorithms include the following steps. Note that the steps - can be performed in any order and do not need to be treated as - distinct. For example, keys can be tried as soon as they are found, - rather than collecting all the keys before trying any. - - 1. Collect the set of potentially applicable keys. Sources of keys - may include: - - * Keys supplied by the application protocol being used. - - * Keys referenced by the "jku" (JWK Set URL) Header Parameter. - - * The key provided by the "jwk" (JSON Web Key) Header Parameter. - - * The key referenced by the "x5u" (X.509 URL) Header Parameter. - - * The key provided by the "x5c" (X.509 certificate chain) Header - Parameter. - - * Other applicable keys available to the application. - - - - - -Jones, et al. Standards Track [Page 56] - -RFC 7515 JSON Web Signature (JWS) May 2015 - - - The order for collecting and trying keys from different key - sources is typically application dependent. For example, - frequently, all keys from a one set of locations, such as local - caches, will be tried before collecting and trying keys from - other locations. - - 2. Filter the set of collected keys. For instance, some - applications will use only keys referenced by "kid" (key ID) or - "x5t" (X.509 certificate SHA-1 thumbprint) parameters. If the - application uses the JWK "alg" (algorithm), "use" (public key - use), or "key_ops" (key operations) parameters, keys with - inappropriate values of those parameters would be excluded. - Additionally, keys might be filtered to include or exclude keys - with certain other member values in an application-specific - manner. For some applications, no filtering will be applied. - - 3. Order the set of collected keys. For instance, keys referenced - by "kid" (key ID) or "x5t" (X.509 certificate SHA-1 thumbprint) - parameters might be tried before keys with neither of these - values. Likewise, keys with certain member values might be - ordered before keys with other member values. For some - applications, no ordering will be applied. - - 4. Make trust decisions about the keys. Signatures made with keys - not meeting the application's trust criteria would not be - accepted. Such criteria might include, but is not limited to, - the source of the key, whether the TLS certificate validates for - keys retrieved from URLs, whether a key in an X.509 certificate - is backed by a valid certificate chain, and other information - known by the application. - - 5. Attempt signature or MAC validation for a JWS or decryption of a - JWE with some or all of the collected and possibly filtered and/ - or ordered keys. A limit on the number of keys to be tried might - be applied. This process will normally terminate following a - successful validation or decryption. - - Note that it is reasonable for some applications to perform signature - or MAC validation prior to making a trust decision about a key, since - keys for which the validation fails need no trust decision. - - - - - - - - - - - -Jones, et al. Standards Track [Page 57] - -RFC 7515 JSON Web Signature (JWS) May 2015 - - -Appendix E. Negative Test Case for "crit" Header Parameter - - Conforming implementations must reject input containing critical - extensions that are not understood or cannot be processed. The - following JWS must be rejected by all implementations, because it - uses an extension Header Parameter name "http://example.invalid/ - UNDEFINED" that they do not understand. Any other similar input, in - which the use of the value "http://example.invalid/UNDEFINED" is - substituted for any other Header Parameter name not understood by the - implementation, must also be rejected. - - The JWS Protected Header value for this JWS is: - - {"alg":"none", - "crit":["http://example.invalid/UNDEFINED"], - "http://example.invalid/UNDEFINED":true - } - - The complete JWS that must be rejected is as follows (with line - breaks for display purposes only): - - eyJhbGciOiJub25lIiwNCiAiY3JpdCI6WyJodHRwOi8vZXhhbXBsZS5jb20vVU5ERU - ZJTkVEIl0sDQogImh0dHA6Ly9leGFtcGxlLmNvbS9VTkRFRklORUQiOnRydWUNCn0. - RkFJTA. - -Appendix F. Detached Content - - In some contexts, it is useful to integrity-protect content that is - not itself contained in a JWS. One way to do this is to create a JWS - in the normal fashion using a representation of the content as the - payload but then delete the payload representation from the JWS and - send this modified object to the recipient rather than the JWS. When - using the JWS Compact Serialization, the deletion is accomplished by - replacing the second field (which contains BASE64URL(JWS Payload)) - value with the empty string; when using the JWS JSON Serialization, - the deletion is accomplished by deleting the "payload" member. This - method assumes that the recipient can reconstruct the exact payload - used in the JWS. To use the modified object, the recipient - reconstructs the JWS by re-inserting the payload representation into - the modified object and uses the resulting JWS in the usual manner. - Note that this method needs no support from JWS libraries, as - applications can use this method by modifying the inputs and outputs - of standard JWS libraries. - - - - - - - - -Jones, et al. Standards Track [Page 58] - -RFC 7515 JSON Web Signature (JWS) May 2015 - - -Acknowledgements - - Solutions for signing JSON content were previously explored by Magic - Signatures [MagicSignatures], JSON Simple Sign [JSS], and Canvas - Applications [CanvasApp], all of which influenced this document. - - Thanks to Axel Nennker for his early implementation and feedback on - the JWS and JWE specifications. - - This specification is the work of the JOSE working group, which - includes dozens of active and dedicated participants. In particular, - the following individuals contributed ideas, feedback, and wording - that influenced this specification: - - Dirk Balfanz, Richard Barnes, Brian Campbell, Alissa Cooper, Breno de - Medeiros, Stephen Farrell, Yaron Y. Goland, Dick Hardt, Joe - Hildebrand, Jeff Hodges, Russ Housley, Edmund Jay, Tero Kivinen, Ben - Laurie, Ted Lemon, James Manger, Matt Miller, Kathleen Moriarty, Tony - Nadalin, Hideki Nara, Axel Nennker, John Panzer, Ray Polk, Emmanuel - Raviart, Eric Rescorla, Pete Resnick, Jim Schaad, Paul Tarjan, Hannes - Tschofenig, and Sean 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. - -Authors' Addresses - - Michael B. Jones - Microsoft - - EMail: mbj@microsoft.com - URI: http://self-issued.info/ - - - John Bradley - Ping Identity - - EMail: ve7jtb@ve7jtb.com - URI: http://www.thread-safe.com/ - - - Nat Sakimura - Nomura Research Institute - - EMail: n-sakimura@nri.co.jp - URI: http://nat.sakimura.org/ - - - - -Jones, et al. Standards Track [Page 59] - diff --git a/rfc/rfc7518.txt b/rfc/rfc7518.txt deleted file mode 100644 index e649cc2..0000000 --- a/rfc/rfc7518.txt +++ /dev/null @@ -1,3867 +0,0 @@ - - - - - - -Internet Engineering Task Force (IETF) M. Jones -Request for Comments: 7518 Microsoft -Category: Standards Track May 2015 -ISSN: 2070-1721 - - - JSON Web Algorithms (JWA) - -Abstract - - This specification registers cryptographic algorithms and identifiers - to be used with the JSON Web Signature (JWS), JSON Web Encryption - (JWE), and JSON Web Key (JWK) specifications. It defines several - IANA registries for these identifiers. - -Status of This Memo - - This is an Internet Standards Track document. - - This document is a product of the Internet Engineering Task Force - (IETF). It represents the consensus of the IETF community. It has - received public review and has been approved for publication by the - Internet Engineering Steering Group (IESG). Further information on - Internet Standards is available in Section 2 of RFC 5741. - - Information about the current status of this document, any errata, - and how to provide feedback on it may be obtained at - http://www.rfc-editor.org/info/rfc7518. - -Copyright Notice - - Copyright (c) 2015 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. - - - - - - - - -Jones Standards Track [Page 1] - -RFC 7518 JSON Web Algorithms (JWA) May 2015 - - -Table of Contents - - 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 - 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 4 - 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 - 3. Cryptographic Algorithms for Digital Signatures and MACs . . 6 - 3.1. "alg" (Algorithm) Header Parameter Values for JWS . . . . 6 - 3.2. HMAC with SHA-2 Functions . . . . . . . . . . . . . . . . 7 - 3.3. Digital Signature with RSASSA-PKCS1-v1_5 . . . . . . . . 8 - 3.4. Digital Signature with ECDSA . . . . . . . . . . . . . . 9 - 3.5. Digital Signature with RSASSA-PSS . . . . . . . . . . . . 10 - 3.6. Using the Algorithm "none" . . . . . . . . . . . . . . . 11 - 4. Cryptographic Algorithms for Key Management . . . . . . . . . 11 - 4.1. "alg" (Algorithm) Header Parameter Values for JWE . . . . 12 - 4.2. Key Encryption with RSAES-PKCS1-v1_5 . . . . . . . . . . 13 - 4.3. Key Encryption with RSAES OAEP . . . . . . . . . . . . . 14 - 4.4. Key Wrapping with AES Key Wrap . . . . . . . . . . . . . 14 - 4.5. Direct Encryption with a Shared Symmetric Key . . . . . . 15 - 4.6. Key Agreement with Elliptic Curve Diffie-Hellman - Ephemeral Static (ECDH-ES) . . . . . . . . . . . . . . . 15 - 4.6.1. Header Parameters Used for ECDH Key Agreement . . . . 16 - 4.6.1.1. "epk" (Ephemeral Public Key) Header Parameter . . 16 - 4.6.1.2. "apu" (Agreement PartyUInfo) Header Parameter . . 17 - 4.6.1.3. "apv" (Agreement PartyVInfo) Header Parameter . . 17 - 4.6.2. Key Derivation for ECDH Key Agreement . . . . . . . . 17 - 4.7. Key Encryption with AES GCM . . . . . . . . . . . . . . . 18 - 4.7.1. Header Parameters Used for AES GCM Key Encryption . . 19 - 4.7.1.1. "iv" (Initialization Vector) Header Parameter . . 19 - 4.7.1.2. "tag" (Authentication Tag) Header Parameter . . . 19 - 4.8. Key Encryption with PBES2 . . . . . . . . . . . . . . . . 20 - 4.8.1. Header Parameters Used for PBES2 Key Encryption . . . 20 - 4.8.1.1. "p2s" (PBES2 Salt Input) Header Parameter . . . . 21 - 4.8.1.2. "p2c" (PBES2 Count) Header Parameter . . . . . . 21 - 5. Cryptographic Algorithms for Content Encryption . . . . . . . 21 - 5.1. "enc" (Encryption Algorithm) Header Parameter Values for - JWE . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 - 5.2. AES_CBC_HMAC_SHA2 Algorithms . . . . . . . . . . . . . . 22 - 5.2.1. Conventions Used in Defining AES_CBC_HMAC_SHA2 . . . 23 - 5.2.2. Generic AES_CBC_HMAC_SHA2 Algorithm . . . . . . . . . 23 - 5.2.2.1. AES_CBC_HMAC_SHA2 Encryption . . . . . . . . . . 23 - 5.2.2.2. AES_CBC_HMAC_SHA2 Decryption . . . . . . . . . . 25 - 5.2.3. AES_128_CBC_HMAC_SHA_256 . . . . . . . . . . . . . . 25 - 5.2.4. AES_192_CBC_HMAC_SHA_384 . . . . . . . . . . . . . . 26 - 5.2.5. AES_256_CBC_HMAC_SHA_512 . . . . . . . . . . . . . . 26 - 5.2.6. Content Encryption with AES_CBC_HMAC_SHA2 . . . . . . 26 - 5.3. Content Encryption with AES GCM . . . . . . . . . . . . . 27 - 6. Cryptographic Algorithms for Keys . . . . . . . . . . . . . . 27 - 6.1. "kty" (Key Type) Parameter Values . . . . . . . . . . . . 28 - - - -Jones Standards Track [Page 2] - -RFC 7518 JSON Web Algorithms (JWA) May 2015 - - - 6.2. Parameters for Elliptic Curve Keys . . . . . . . . . . . 28 - 6.2.1. Parameters for Elliptic Curve Public Keys . . . . . . 28 - 6.2.1.1. "crv" (Curve) Parameter . . . . . . . . . . . . . 28 - 6.2.1.2. "x" (X Coordinate) Parameter . . . . . . . . . . 29 - 6.2.1.3. "y" (Y Coordinate) Parameter . . . . . . . . . . 29 - 6.2.2. Parameters for Elliptic Curve Private Keys . . . . . 29 - 6.2.2.1. "d" (ECC Private Key) Parameter . . . . . . . . . 29 - 6.3. Parameters for RSA Keys . . . . . . . . . . . . . . . . . 30 - 6.3.1. Parameters for RSA Public Keys . . . . . . . . . . . 30 - 6.3.1.1. "n" (Modulus) Parameter . . . . . . . . . . . . . 30 - 6.3.1.2. "e" (Exponent) Parameter . . . . . . . . . . . . 30 - 6.3.2. Parameters for RSA Private Keys . . . . . . . . . . . 30 - 6.3.2.1. "d" (Private Exponent) Parameter . . . . . . . . 30 - 6.3.2.2. "p" (First Prime Factor) Parameter . . . . . . . 31 - 6.3.2.3. "q" (Second Prime Factor) Parameter . . . . . . . 31 - 6.3.2.4. "dp" (First Factor CRT Exponent) Parameter . . . 31 - 6.3.2.5. "dq" (Second Factor CRT Exponent) Parameter . . . 31 - 6.3.2.6. "qi" (First CRT Coefficient) Parameter . . . . . 31 - 6.3.2.7. "oth" (Other Primes Info) Parameter . . . . . . . 31 - 6.4. Parameters for Symmetric Keys . . . . . . . . . . . . . . 32 - 6.4.1. "k" (Key Value) Parameter . . . . . . . . . . . . . . 32 - 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 32 - 7.1. JSON Web Signature and Encryption Algorithms Registry . . 33 - 7.1.1. Registration Template . . . . . . . . . . . . . . . . 34 - 7.1.2. Initial Registry Contents . . . . . . . . . . . . . . 35 - 7.2. Header Parameter Names Registration . . . . . . . . . . . 42 - 7.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 42 - 7.3. JSON Web Encryption Compression Algorithms Registry . . . 43 - 7.3.1. Registration Template . . . . . . . . . . . . . . . . 43 - 7.3.2. Initial Registry Contents . . . . . . . . . . . . . . 44 - 7.4. JSON Web Key Types Registry . . . . . . . . . . . . . . . 44 - 7.4.1. Registration Template . . . . . . . . . . . . . . . . 44 - 7.4.2. Initial Registry Contents . . . . . . . . . . . . . . 45 - 7.5. JSON Web Key Parameters Registration . . . . . . . . . . 45 - 7.5.1. Registry Contents . . . . . . . . . . . . . . . . . . 46 - 7.6. JSON Web Key Elliptic Curve Registry . . . . . . . . . . 48 - 7.6.1. Registration Template . . . . . . . . . . . . . . . . 48 - 7.6.2. Initial Registry Contents . . . . . . . . . . . . . . 49 - 8. Security Considerations . . . . . . . . . . . . . . . . . . . 49 - 8.1. Cryptographic Agility . . . . . . . . . . . . . . . . . . 50 - 8.2. Key Lifetimes . . . . . . . . . . . . . . . . . . . . . . 50 - 8.3. RSAES-PKCS1-v1_5 Security Considerations . . . . . . . . 50 - 8.4. AES GCM Security Considerations . . . . . . . . . . . . . 50 - 8.5. Unsecured JWS Security Considerations . . . . . . . . . . 51 - 8.6. Denial-of-Service Attacks . . . . . . . . . . . . . . . . 51 - 8.7. Reusing Key Material when Encrypting Keys . . . . . . . . 51 - 8.8. Password Considerations . . . . . . . . . . . . . . . . . 52 - 8.9. Key Entropy and Random Values . . . . . . . . . . . . . . 52 - - - -Jones Standards Track [Page 3] - -RFC 7518 JSON Web Algorithms (JWA) May 2015 - - - 8.10. Differences between Digital Signatures and MACs . . . . . 52 - 8.11. Using Matching Algorithm Strengths . . . . . . . . . . . 53 - 8.12. Adaptive Chosen-Ciphertext Attacks . . . . . . . . . . . 53 - 8.13. Timing Attacks . . . . . . . . . . . . . . . . . . . . . 53 - 8.14. RSA Private Key Representations and Blinding . . . . . . 53 - 9. Internationalization Considerations . . . . . . . . . . . . . 53 - 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 53 - 10.1. Normative References . . . . . . . . . . . . . . . . . . 53 - 10.2. Informative References . . . . . . . . . . . . . . . . . 56 - Appendix A. Algorithm Identifier Cross-Reference . . . . . . . . 59 - A.1. Digital Signature/MAC Algorithm Identifier Cross- - Reference . . . . . . . . . . . . . . . . . . . . . . . . 60 - A.2. Key Management Algorithm Identifier Cross-Reference . . . 61 - A.3. Content Encryption Algorithm Identifier Cross-Reference . 62 - Appendix B. Test Cases for AES_CBC_HMAC_SHA2 Algorithms . . . . 62 - B.1. Test Cases for AES_128_CBC_HMAC_SHA_256 . . . . . . . . . 63 - B.2. Test Cases for AES_192_CBC_HMAC_SHA_384 . . . . . . . . . 64 - B.3. Test Cases for AES_256_CBC_HMAC_SHA_512 . . . . . . . . . 65 - Appendix C. Example ECDH-ES Key Agreement Computation . . . . . 66 - Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 69 - Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 69 - -1. Introduction - - This specification registers cryptographic algorithms and identifiers - to be used with the JSON Web Signature (JWS) [JWS], JSON Web - Encryption (JWE) [JWE], and JSON Web Key (JWK) [JWK] specifications. - It defines several IANA registries for these identifiers. All these - specifications utilize JSON-based [RFC7159] data structures. This - specification also describes the semantics and operations that are - specific to these algorithms and key types. - - Registering the algorithms and identifiers here, rather than in the - JWS, JWE, and JWK specifications, is intended to allow them to remain - unchanged in the face of changes in the set of Required, Recommended, - Optional, and Deprecated algorithms over time. This also allows - changes to the JWS, JWE, and JWK specifications without changing this - document. - - Names defined by this specification are short because a core goal is - for the resulting representations to be compact. - -1.1. Notational Conventions - - The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", - "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and - "OPTIONAL" in this document are to be interpreted as described in - "Key words for use in RFCs to Indicate Requirement Levels" [RFC2119]. - - - -Jones Standards Track [Page 4] - -RFC 7518 JSON Web Algorithms (JWA) May 2015 - - - The interpretation should only be applied when the terms appear in - all capital letters. - - BASE64URL(OCTETS) denotes the base64url encoding of OCTETS, per - Section 2 of [JWS]. - - UTF8(STRING) denotes the octets of the UTF-8 [RFC3629] representation - of STRING, where STRING is a sequence of zero or more Unicode - [UNICODE] characters. - - ASCII(STRING) denotes the octets of the ASCII [RFC20] representation - of STRING, where STRING is a sequence of zero or more ASCII - characters. - - The concatenation of two values A and B is denoted as A || B. - -2. Terminology - - The terms "JSON Web Signature (JWS)", "Base64url Encoding", "Header - Parameter", "JOSE Header", "JWS Payload", "JWS Protected Header", - "JWS Signature", "JWS Signing Input", and "Unsecured JWS" are defined - by the JWS specification [JWS]. - - The terms "JSON Web Encryption (JWE)", "Additional Authenticated Data - (AAD)", "Authentication Tag", "Content Encryption Key (CEK)", "Direct - Encryption", "Direct Key Agreement", "JWE Authentication Tag", "JWE - Ciphertext", "JWE Encrypted Key", "JWE Initialization Vector", "JWE - Protected Header", "Key Agreement with Key Wrapping", "Key - Encryption", "Key Management Mode", and "Key Wrapping" are defined by - the JWE specification [JWE]. - - The terms "JSON Web Key (JWK)" and "JWK Set" are defined by the JWK - specification [JWK]. - - The terms "Ciphertext", "Digital Signature", "Initialization Vector", - "Message Authentication Code (MAC)", and "Plaintext" are defined by - the "Internet Security Glossary, Version 2" [RFC4949]. - - This term is defined by this specification: - - Base64urlUInt - The representation of a positive or zero integer value as the - base64url encoding of the value's unsigned big-endian - representation as an octet sequence. The octet sequence MUST - utilize the minimum number of octets needed to represent the - value. Zero is represented as BASE64URL(single zero-valued - octet), which is "AA". - - - - -Jones Standards Track [Page 5] - -RFC 7518 JSON Web Algorithms (JWA) May 2015 - - -3. Cryptographic Algorithms for Digital Signatures and MACs - - JWS uses cryptographic algorithms to digitally sign or create a MAC - of the contents of the JWS Protected Header and the JWS Payload. - -3.1. "alg" (Algorithm) Header Parameter Values for JWS - - The table below is the set of "alg" (algorithm) Header Parameter - values defined by this specification for use with JWS, each of which - is explained in more detail in the following sections: - - +--------------+-------------------------------+--------------------+ - | "alg" Param | Digital Signature or MAC | Implementation | - | Value | Algorithm | Requirements | - +--------------+-------------------------------+--------------------+ - | HS256 | HMAC using SHA-256 | Required | - | HS384 | HMAC using SHA-384 | Optional | - | HS512 | HMAC using SHA-512 | Optional | - | RS256 | RSASSA-PKCS1-v1_5 using | Recommended | - | | SHA-256 | | - | RS384 | RSASSA-PKCS1-v1_5 using | Optional | - | | SHA-384 | | - | RS512 | RSASSA-PKCS1-v1_5 using | Optional | - | | SHA-512 | | - | ES256 | ECDSA using P-256 and SHA-256 | Recommended+ | - | ES384 | ECDSA using P-384 and SHA-384 | Optional | - | ES512 | ECDSA using P-521 and SHA-512 | Optional | - | PS256 | RSASSA-PSS using SHA-256 and | Optional | - | | MGF1 with SHA-256 | | - | PS384 | RSASSA-PSS using SHA-384 and | Optional | - | | MGF1 with SHA-384 | | - | PS512 | RSASSA-PSS using SHA-512 and | Optional | - | | MGF1 with SHA-512 | | - | none | No digital signature or MAC | Optional | - | | performed | | - +--------------+-------------------------------+--------------------+ - - The use of "+" in the Implementation Requirements column indicates - that the requirement strength is likely to be increased in a future - version of the specification. - - See Appendix A.1 for a table cross-referencing the JWS digital - signature and MAC "alg" (algorithm) values defined in this - specification with the equivalent identifiers used by other standards - and software packages. - - - - - - -Jones Standards Track [Page 6] - -RFC 7518 JSON Web Algorithms (JWA) May 2015 - - -3.2. HMAC with SHA-2 Functions - - Hash-based Message Authentication Codes (HMACs) enable one to use a - secret plus a cryptographic hash function to generate a MAC. This - can be used to demonstrate that whoever generated the MAC was in - possession of the MAC key. The algorithm for implementing and - validating HMACs is provided in RFC 2104 [RFC2104]. - - A key of the same size as the hash output (for instance, 256 bits for - "HS256") or larger MUST be used with this algorithm. (This - requirement is based on Section 5.3.4 (Security Effect of the HMAC - Key) of NIST SP 800-117 [NIST.800-107], which states that the - effective security strength is the minimum of the security strength - of the key and two times the size of the internal hash value.) - - The HMAC SHA-256 MAC is generated per RFC 2104, using SHA-256 as the - hash algorithm "H", using the JWS Signing Input as the "text" value, - and using the shared key. The HMAC output value is the JWS - Signature. - - The following "alg" (algorithm) Header Parameter values are used to - indicate that the JWS Signature is an HMAC value computed using the - corresponding algorithm: - - +-------------------+--------------------+ - | "alg" Param Value | MAC Algorithm | - +-------------------+--------------------+ - | HS256 | HMAC using SHA-256 | - | HS384 | HMAC using SHA-384 | - | HS512 | HMAC using SHA-512 | - +-------------------+--------------------+ - - The HMAC SHA-256 MAC for a JWS is validated by computing an HMAC - value per RFC 2104, using SHA-256 as the hash algorithm "H", using - the received JWS Signing Input as the "text" value, and using the - shared key. This computed HMAC value is then compared to the result - of base64url decoding the received encoded JWS Signature value. The - comparison of the computed HMAC value to the JWS Signature value MUST - be done in a constant-time manner to thwart timing attacks. - Alternatively, the computed HMAC value can be base64url encoded and - compared to the received encoded JWS Signature value (also in a - constant-time manner), as this comparison produces the same result as - comparing the unencoded values. In either case, if the values match, - the HMAC has been validated. - - - - - - - -Jones Standards Track [Page 7] - -RFC 7518 JSON Web Algorithms (JWA) May 2015 - - - Securing content and validation with the HMAC SHA-384 and HMAC - SHA-512 algorithms is performed identically to the procedure for HMAC - SHA-256 -- just using the corresponding hash algorithms with - correspondingly larger minimum key sizes and result values: 384 bits - each for HMAC SHA-384 and 512 bits each for HMAC SHA-512. - - An example using this algorithm is shown in Appendix A.1 of [JWS]. - -3.3. Digital Signature with RSASSA-PKCS1-v1_5 - - This section defines the use of the RSASSA-PKCS1-v1_5 digital - signature algorithm as defined in Section 8.2 of RFC 3447 [RFC3447] - (commonly known as PKCS #1), using SHA-2 [SHS] hash functions. - - A key of size 2048 bits or larger MUST be used with these algorithms. - - The RSASSA-PKCS1-v1_5 SHA-256 digital signature is generated as - follows: generate a digital signature of the JWS Signing Input using - RSASSA-PKCS1-v1_5-SIGN and the SHA-256 hash function with the desired - private key. This is the JWS Signature value. - - The following "alg" (algorithm) Header Parameter values are used to - indicate that the JWS Signature is a digital signature value computed - using the corresponding algorithm: - - +-------------------+---------------------------------+ - | "alg" Param Value | Digital Signature Algorithm | - +-------------------+---------------------------------+ - | RS256 | RSASSA-PKCS1-v1_5 using SHA-256 | - | RS384 | RSASSA-PKCS1-v1_5 using SHA-384 | - | RS512 | RSASSA-PKCS1-v1_5 using SHA-512 | - +-------------------+---------------------------------+ - - The RSASSA-PKCS1-v1_5 SHA-256 digital signature for a JWS is - validated as follows: submit the JWS Signing Input, the JWS - Signature, and the public key corresponding to the private key used - by the signer to the RSASSA-PKCS1-v1_5-VERIFY algorithm using SHA-256 - as the hash function. - - Signing and validation with the RSASSA-PKCS1-v1_5 SHA-384 and RSASSA- - PKCS1-v1_5 SHA-512 algorithms is performed identically to the - procedure for RSASSA-PKCS1-v1_5 SHA-256 -- just using the - corresponding hash algorithms instead of SHA-256. - - An example using this algorithm is shown in Appendix A.2 of [JWS]. - - - - - - -Jones Standards Track [Page 8] - -RFC 7518 JSON Web Algorithms (JWA) May 2015 - - -3.4. Digital Signature with ECDSA - - The Elliptic Curve Digital Signature Algorithm (ECDSA) [DSS] provides - for the use of Elliptic Curve Cryptography, which is able to provide - equivalent security to RSA cryptography but using shorter key sizes - and with greater processing speed for many operations. This means - that ECDSA digital signatures will be substantially smaller in terms - of length than equivalently strong RSA digital signatures. - - This specification defines the use of ECDSA with the P-256 curve and - the SHA-256 cryptographic hash function, ECDSA with the P-384 curve - and the SHA-384 hash function, and ECDSA with the P-521 curve and the - SHA-512 hash function. The P-256, P-384, and P-521 curves are - defined in [DSS]. - - The ECDSA P-256 SHA-256 digital signature is generated as follows: - - 1. Generate a digital signature of the JWS Signing Input using ECDSA - P-256 SHA-256 with the desired private key. The output will be - the pair (R, S), where R and S are 256-bit unsigned integers. - - 2. Turn R and S into octet sequences in big-endian order, with each - array being be 32 octets long. The octet sequence - representations MUST NOT be shortened to omit any leading zero - octets contained in the values. - - 3. Concatenate the two octet sequences in the order R and then S. - (Note that many ECDSA implementations will directly produce this - concatenation as their output.) - - 4. The resulting 64-octet sequence is the JWS Signature value. - - The following "alg" (algorithm) Header Parameter values are used to - indicate that the JWS Signature is a digital signature value computed - using the corresponding algorithm: - - +-------------------+-------------------------------+ - | "alg" Param Value | Digital Signature Algorithm | - +-------------------+-------------------------------+ - | ES256 | ECDSA using P-256 and SHA-256 | - | ES384 | ECDSA using P-384 and SHA-384 | - | ES512 | ECDSA using P-521 and SHA-512 | - +-------------------+-------------------------------+ - - - - - - - - -Jones Standards Track [Page 9] - -RFC 7518 JSON Web Algorithms (JWA) May 2015 - - - The ECDSA P-256 SHA-256 digital signature for a JWS is validated as - follows: - - 1. The JWS Signature value MUST be a 64-octet sequence. If it is - not a 64-octet sequence, the validation has failed. - - 2. Split the 64-octet sequence into two 32-octet sequences. The - first octet sequence represents R and the second S. The values R - and S are represented as octet sequences using the Integer-to- - OctetString Conversion defined in Section 2.3.7 of SEC1 [SEC1] - (in big-endian octet order). - - 3. Submit the JWS Signing Input, R, S, and the public key (x, y) to - the ECDSA P-256 SHA-256 validator. - - Signing and validation with the ECDSA P-384 SHA-384 and ECDSA P-521 - SHA-512 algorithms is performed identically to the procedure for - ECDSA P-256 SHA-256 -- just using the corresponding hash algorithms - with correspondingly larger result values. For ECDSA P-384 SHA-384, - R and S will be 384 bits each, resulting in a 96-octet sequence. For - ECDSA P-521 SHA-512, R and S will be 521 bits each, resulting in a - 132-octet sequence. (Note that the Integer-to-OctetString Conversion - defined in Section 2.3.7 of SEC1 [SEC1] used to represent R and S as - octet sequences adds zero-valued high-order padding bits when needed - to round the size up to a multiple of 8 bits; thus, each 521-bit - integer is represented using 528 bits in 66 octets.) - - Examples using these algorithms are shown in Appendices A.3 and A.4 - of [JWS]. - -3.5. Digital Signature with RSASSA-PSS - - This section defines the use of the RSASSA-PSS digital signature - algorithm as defined in Section 8.1 of RFC 3447 [RFC3447] with the - MGF1 mask generation function and SHA-2 hash functions, always using - the same hash function for both the RSASSA-PSS hash function and the - MGF1 hash function. The size of the salt value is the same size as - the hash function output. All other algorithm parameters use the - defaults specified in Appendix A.2.3 of RFC 3447. - - A key of size 2048 bits or larger MUST be used with this algorithm. - - The RSASSA-PSS SHA-256 digital signature is generated as follows: - generate a digital signature of the JWS Signing Input using RSASSA- - PSS-SIGN, the SHA-256 hash function, and the MGF1 mask generation - function with SHA-256 with the desired private key. This is the JWS - Signature value. - - - - -Jones Standards Track [Page 10] - -RFC 7518 JSON Web Algorithms (JWA) May 2015 - - - The following "alg" (algorithm) Header Parameter values are used to - indicate that the JWS Signature is a digital signature value computed - using the corresponding algorithm: - - +-------------------+-----------------------------------------------+ - | "alg" Param Value | Digital Signature Algorithm | - +-------------------+-----------------------------------------------+ - | PS256 | RSASSA-PSS using SHA-256 and MGF1 with | - | | SHA-256 | - | PS384 | RSASSA-PSS using SHA-384 and MGF1 with | - | | SHA-384 | - | PS512 | RSASSA-PSS using SHA-512 and MGF1 with | - | | SHA-512 | - +-------------------+-----------------------------------------------+ - - The RSASSA-PSS SHA-256 digital signature for a JWS is validated as - follows: submit the JWS Signing Input, the JWS Signature, and the - public key corresponding to the private key used by the signer to the - RSASSA-PSS-VERIFY algorithm using SHA-256 as the hash function and - using MGF1 as the mask generation function with SHA-256. - - Signing and validation with the RSASSA-PSS SHA-384 and RSASSA-PSS - SHA-512 algorithms is performed identically to the procedure for - RSASSA-PSS SHA-256 -- just using the alternative hash algorithm in - both roles. - -3.6. Using the Algorithm "none" - - JWSs MAY also be created that do not provide integrity protection. - Such a JWS is called an Unsecured JWS. An Unsecured JWS uses the - "alg" value "none" and is formatted identically to other JWSs, but - MUST use the empty octet sequence as its JWS Signature value. - Recipients MUST verify that the JWS Signature value is the empty - octet sequence. - - Implementations that support Unsecured JWSs MUST NOT accept such - objects as valid unless the application specifies that it is - acceptable for a specific object to not be integrity protected. - Implementations MUST NOT accept Unsecured JWSs by default. In order - to mitigate downgrade attacks, applications MUST NOT signal - acceptance of Unsecured JWSs at a global level, and SHOULD signal - acceptance on a per-object basis. See Section 8.5 for security - considerations associated with using this algorithm. - -4. Cryptographic Algorithms for Key Management - - JWE uses cryptographic algorithms to encrypt or determine the Content - Encryption Key (CEK). - - - -Jones Standards Track [Page 11] - -RFC 7518 JSON Web Algorithms (JWA) May 2015 - - -4.1. "alg" (Algorithm) Header Parameter Values for JWE - - The table below is the set of "alg" (algorithm) Header Parameter - values that are defined by this specification for use with JWE. - These algorithms are used to encrypt the CEK, producing the JWE - Encrypted Key, or to use key agreement to agree upon the CEK. - - +--------------------+--------------------+--------+----------------+ - | "alg" Param Value | Key Management | More | Implementation | - | | Algorithm | Header | Requirements | - | | | Params | | - +--------------------+--------------------+--------+----------------+ - | RSA1_5 | RSAES-PKCS1-v1_5 | (none) | Recommended- | - | RSA-OAEP | RSAES OAEP using | (none) | Recommended+ | - | | default parameters | | | - | RSA-OAEP-256 | RSAES OAEP using | (none) | Optional | - | | SHA-256 and MGF1 | | | - | | with SHA-256 | | | - | A128KW | AES Key Wrap with | (none) | Recommended | - | | default initial | | | - | | value using | | | - | | 128-bit key | | | - | A192KW | AES Key Wrap with | (none) | Optional | - | | default initial | | | - | | value using | | | - | | 192-bit key | | | - | A256KW | AES Key Wrap with | (none) | Recommended | - | | default initial | | | - | | value using | | | - | | 256-bit key | | | - | dir | Direct use of a | (none) | Recommended | - | | shared symmetric | | | - | | key as the CEK | | | - | ECDH-ES | Elliptic Curve | "epk", | Recommended+ | - | | Diffie-Hellman | "apu", | | - | | Ephemeral Static | "apv" | | - | | key agreement | | | - | | using Concat KDF | | | - | ECDH-ES+A128KW | ECDH-ES using | "epk", | Recommended | - | | Concat KDF and CEK | "apu", | | - | | wrapped with | "apv" | | - | | "A128KW" | | | - | ECDH-ES+A192KW | ECDH-ES using | "epk", | Optional | - | | Concat KDF and CEK | "apu", | | - | | wrapped with | "apv" | | - | | "A192KW" | | | - - - - - -Jones Standards Track [Page 12] - -RFC 7518 JSON Web Algorithms (JWA) May 2015 - - - | ECDH-ES+A256KW | ECDH-ES using | "epk", | Recommended | - | | Concat KDF and CEK | "apu", | | - | | wrapped with | "apv" | | - | | "A256KW" | | | - | A128GCMKW | Key wrapping with | "iv", | Optional | - | | AES GCM using | "tag" | | - | | 128-bit key | | | - | A192GCMKW | Key wrapping with | "iv", | Optional | - | | AES GCM using | "tag" | | - | | 192-bit key | | | - | A256GCMKW | Key wrapping with | "iv", | Optional | - | | AES GCM using | "tag" | | - | | 256-bit key | | | - | PBES2-HS256+A128KW | PBES2 with HMAC | "p2s", | Optional | - | | SHA-256 and | "p2c" | | - | | "A128KW" wrapping | | | - | PBES2-HS384+A192KW | PBES2 with HMAC | "p2s", | Optional | - | | SHA-384 and | "p2c" | | - | | "A192KW" wrapping | | | - | PBES2-HS512+A256KW | PBES2 with HMAC | "p2s", | Optional | - | | SHA-512 and | "p2c" | | - | | "A256KW" wrapping | | | - +--------------------+--------------------+--------+----------------+ - - The More Header Params column indicates what additional Header - Parameters are used by the algorithm, beyond "alg", which all use. - All but "dir" and "ECDH-ES" also produce a JWE Encrypted Key value. - - The use of "+" in the Implementation Requirements column indicates - that the requirement strength is likely to be increased in a future - version of the specification. The use of "-" indicates that the - requirement strength is likely to be decreased in a future version of - the specification. - - See Appendix A.2 for a table cross-referencing the JWE "alg" - (algorithm) values defined in this specification with the equivalent - identifiers used by other standards and software packages. - -4.2. Key Encryption with RSAES-PKCS1-v1_5 - - This section defines the specifics of encrypting a JWE CEK with - RSAES-PKCS1-v1_5 [RFC3447]. The "alg" (algorithm) Header Parameter - value "RSA1_5" is used for this algorithm. - - A key of size 2048 bits or larger MUST be used with this algorithm. - - An example using this algorithm is shown in Appendix A.2 of [JWE]. - - - - -Jones Standards Track [Page 13] - -RFC 7518 JSON Web Algorithms (JWA) May 2015 - - -4.3. Key Encryption with RSAES OAEP - - This section defines the specifics of encrypting a JWE CEK with RSAES - using Optimal Asymmetric Encryption Padding (OAEP) [RFC3447]. Two - sets of parameters for using OAEP are defined, which use different - hash functions. In the first case, the default parameters specified - in Appendix A.2.1 of RFC 3447 are used. (Those default parameters - are the SHA-1 hash function and the MGF1 with SHA-1 mask generation - function.) In the second case, the SHA-256 hash function and the - MGF1 with SHA-256 mask generation function are used. - - The following "alg" (algorithm) Header Parameter values are used to - indicate that the JWE Encrypted Key is the result of encrypting the - CEK using the corresponding algorithm: - - +-------------------+-----------------------------------------------+ - | "alg" Param Value | Key Management Algorithm | - +-------------------+-----------------------------------------------+ - | RSA-OAEP | RSAES OAEP using default parameters | - | RSA-OAEP-256 | RSAES OAEP using SHA-256 and MGF1 with | - | | SHA-256 | - +-------------------+-----------------------------------------------+ - - A key of size 2048 bits or larger MUST be used with these algorithms. - (This requirement is based on Table 4 (Security-strength time frames) - of NIST SP 800-57 [NIST.800-57], which requires 112 bits of security - for new uses, and Table 2 (Comparable strengths) of the same, which - states that 2048-bit RSA keys provide 112 bits of security.) - - An example using RSAES OAEP with the default parameters is shown in - Appendix A.1 of [JWE]. - -4.4. Key Wrapping with AES Key Wrap - - This section defines the specifics of encrypting a JWE CEK with the - Advanced Encryption Standard (AES) Key Wrap Algorithm [RFC3394] using - the default initial value specified in Section 2.2.3.1 of that - document. - - - - - - - - - - - - - -Jones Standards Track [Page 14] - -RFC 7518 JSON Web Algorithms (JWA) May 2015 - - - The following "alg" (algorithm) Header Parameter values are used to - indicate that the JWE Encrypted Key is the result of encrypting the - CEK using the corresponding algorithm and key size: - - +-----------------+-------------------------------------------------+ - | "alg" Param | Key Management Algorithm | - | Value | | - +-----------------+-------------------------------------------------+ - | A128KW | AES Key Wrap with default initial value using | - | | 128-bit key | - | A192KW | AES Key Wrap with default initial value using | - | | 192-bit key | - | A256KW | AES Key Wrap with default initial value using | - | | 256-bit key | - +-----------------+-------------------------------------------------+ - - An example using this algorithm is shown in Appendix A.3 of [JWE]. - -4.5. Direct Encryption with a Shared Symmetric Key - - This section defines the specifics of directly performing symmetric - key encryption without performing a key wrapping step. In this case, - the shared symmetric key is used directly as the Content Encryption - Key (CEK) value for the "enc" algorithm. An empty octet sequence is - used as the JWE Encrypted Key value. The "alg" (algorithm) Header - Parameter value "dir" is used in this case. - - Refer to the security considerations on key lifetimes in Section 8.2 - and AES GCM in Section 8.4 when considering utilizing direct - encryption. - -4.6. Key Agreement with Elliptic Curve Diffie-Hellman Ephemeral Static - (ECDH-ES) - - This section defines the specifics of key agreement with Elliptic - Curve Diffie-Hellman Ephemeral Static [RFC6090], in combination with - the Concat KDF, as defined in Section 5.8.1 of [NIST.800-56A]. The - key agreement result can be used in one of two ways: - - 1. directly as the Content Encryption Key (CEK) for the "enc" - algorithm, in the Direct Key Agreement mode, or - - 2. as a symmetric key used to wrap the CEK with the "A128KW", - "A192KW", or "A256KW" algorithms, in the Key Agreement with Key - Wrapping mode. - - A new ephemeral public key value MUST be generated for each key - agreement operation. - - - -Jones Standards Track [Page 15] - -RFC 7518 JSON Web Algorithms (JWA) May 2015 - - - In Direct Key Agreement mode, the output of the Concat KDF MUST be a - key of the same length as that used by the "enc" algorithm. In this - case, the empty octet sequence is used as the JWE Encrypted Key - value. The "alg" (algorithm) Header Parameter value "ECDH-ES" is - used in the Direct Key Agreement mode. - - In Key Agreement with Key Wrapping mode, the output of the Concat KDF - MUST be a key of the length needed for the specified key wrapping - algorithm. In this case, the JWE Encrypted Key is the CEK wrapped - with the agreed-upon key. - - The following "alg" (algorithm) Header Parameter values are used to - indicate that the JWE Encrypted Key is the result of encrypting the - CEK using the result of the key agreement algorithm as the key - encryption key for the corresponding key wrapping algorithm: - - +-----------------+-------------------------------------------------+ - | "alg" Param | Key Management Algorithm | - | Value | | - +-----------------+-------------------------------------------------+ - | ECDH-ES+A128KW | ECDH-ES using Concat KDF and CEK wrapped with | - | | "A128KW" | - | ECDH-ES+A192KW | ECDH-ES using Concat KDF and CEK wrapped with | - | | "A192KW" | - | ECDH-ES+A256KW | ECDH-ES using Concat KDF and CEK wrapped with | - | | "A256KW" | - +-----------------+-------------------------------------------------+ - -4.6.1. Header Parameters Used for ECDH Key Agreement - - The following Header Parameter names are used for key agreement as - defined below. - -4.6.1.1. "epk" (Ephemeral Public Key) Header Parameter - - The "epk" (ephemeral public key) value created by the originator for - the use in key agreement algorithms. This key is represented as a - JSON Web Key [JWK] public key value. It MUST contain only public key - parameters and SHOULD contain only the minimum JWK parameters - necessary to represent the key; other JWK parameters included can be - checked for consistency and honored, or they can be ignored. This - Header Parameter MUST be present and MUST be understood and processed - by implementations when these algorithms are used. - - - - - - - - -Jones Standards Track [Page 16] - -RFC 7518 JSON Web Algorithms (JWA) May 2015 - - -4.6.1.2. "apu" (Agreement PartyUInfo) Header Parameter - - The "apu" (agreement PartyUInfo) value for key agreement algorithms - using it (such as "ECDH-ES"), represented as a base64url-encoded - string. When used, the PartyUInfo value contains information about - the producer. Use of this Header Parameter is OPTIONAL. This Header - Parameter MUST be understood and processed by implementations when - these algorithms are used. - -4.6.1.3. "apv" (Agreement PartyVInfo) Header Parameter - - The "apv" (agreement PartyVInfo) value for key agreement algorithms - using it (such as "ECDH-ES"), represented as a base64url encoded - string. When used, the PartyVInfo value contains information about - the recipient. Use of this Header Parameter is OPTIONAL. This - Header Parameter MUST be understood and processed by implementations - when these algorithms are used. - -4.6.2. Key Derivation for ECDH Key Agreement - - The key derivation process derives the agreed-upon key from the - shared secret Z established through the ECDH algorithm, per - Section 6.2.2.2 of [NIST.800-56A]. - - Key derivation is performed using the Concat KDF, as defined in - Section 5.8.1 of [NIST.800-56A], where the Digest Method is SHA-256. - The Concat KDF parameters are set as follows: - - Z - This is set to the representation of the shared secret Z as an - octet sequence. - - keydatalen - This is set to the number of bits in the desired output key. For - "ECDH-ES", this is length of the key used by the "enc" algorithm. - For "ECDH-ES+A128KW", "ECDH-ES+A192KW", and "ECDH-ES+A256KW", this - is 128, 192, and 256, respectively. - - AlgorithmID - The AlgorithmID value is of the form Datalen || Data, where Data - is a variable-length string of zero or more octets, and Datalen is - a fixed-length, big-endian 32-bit counter that indicates the - length (in octets) of Data. In the Direct Key Agreement case, - Data is set to the octets of the ASCII representation of the "enc" - Header Parameter value. In the Key Agreement with Key Wrapping - case, Data is set to the octets of the ASCII representation of the - "alg" (algorithm) Header Parameter value. - - - - -Jones Standards Track [Page 17] - -RFC 7518 JSON Web Algorithms (JWA) May 2015 - - - PartyUInfo - The PartyUInfo value is of the form Datalen || Data, where Data is - a variable-length string of zero or more octets, and Datalen is a - fixed-length, big-endian 32-bit counter that indicates the length - (in octets) of Data. If an "apu" (agreement PartyUInfo) Header - Parameter is present, Data is set to the result of base64url - decoding the "apu" value and Datalen is set to the number of - octets in Data. Otherwise, Datalen is set to 0 and Data is set to - the empty octet sequence. - - PartyVInfo - The PartyVInfo value is of the form Datalen || Data, where Data is - a variable-length string of zero or more octets, and Datalen is a - fixed-length, big-endian 32-bit counter that indicates the length - (in octets) of Data. If an "apv" (agreement PartyVInfo) Header - Parameter is present, Data is set to the result of base64url - decoding the "apv" value and Datalen is set to the number of - octets in Data. Otherwise, Datalen is set to 0 and Data is set to - the empty octet sequence. - - SuppPubInfo - This is set to the keydatalen represented as a 32-bit big-endian - integer. - - SuppPrivInfo - This is set to the empty octet sequence. - - Applications need to specify how the "apu" and "apv" Header - Parameters are used for that application. The "apu" and "apv" values - MUST be distinct, when used. Applications wishing to conform to - [NIST.800-56A] need to provide values that meet the requirements of - that document, e.g., by using values that identify the producer and - consumer. Alternatively, applications MAY conduct key derivation in - a manner similar to "Diffie-Hellman Key Agreement Method" [RFC2631]: - in that case, the "apu" parameter MAY either be omitted or represent - a random 512-bit value (analogous to PartyAInfo in Ephemeral-Static - mode in RFC 2631) and the "apv" parameter SHOULD NOT be present. - - See Appendix C for an example key agreement computation using this - method. - -4.7. Key Encryption with AES GCM - - This section defines the specifics of encrypting a JWE Content - Encryption Key (CEK) with Advanced Encryption Standard (AES) in - Galois/Counter Mode (GCM) ([AES] and [NIST.800-38D]). - - - - - -Jones Standards Track [Page 18] - -RFC 7518 JSON Web Algorithms (JWA) May 2015 - - - Use of an Initialization Vector (IV) of size 96 bits is REQUIRED with - this algorithm. The IV is represented in base64url-encoded form as - the "iv" (initialization vector) Header Parameter value. - - The Additional Authenticated Data value used is the empty octet - string. - - The requested size of the Authentication Tag output MUST be 128 bits, - regardless of the key size. - - The JWE Encrypted Key value is the ciphertext output. - - The Authentication Tag output is represented in base64url-encoded - form as the "tag" (authentication tag) Header Parameter value. - - The following "alg" (algorithm) Header Parameter values are used to - indicate that the JWE Encrypted Key is the result of encrypting the - CEK using the corresponding algorithm and key size: - - +-------------------+---------------------------------------------+ - | "alg" Param Value | Key Management Algorithm | - +-------------------+---------------------------------------------+ - | A128GCMKW | Key wrapping with AES GCM using 128-bit key | - | A192GCMKW | Key wrapping with AES GCM using 192-bit key | - | A256GCMKW | Key wrapping with AES GCM using 256-bit key | - +-------------------+---------------------------------------------+ - -4.7.1. Header Parameters Used for AES GCM Key Encryption - - The following Header Parameters are used for AES GCM key encryption. - -4.7.1.1. "iv" (Initialization Vector) Header Parameter - - The "iv" (initialization vector) Header Parameter value is the - base64url-encoded representation of the 96-bit IV value used for the - key encryption operation. This Header Parameter MUST be present and - MUST be understood and processed by implementations when these - algorithms are used. - -4.7.1.2. "tag" (Authentication Tag) Header Parameter - - The "tag" (authentication tag) Header Parameter value is the - base64url-encoded representation of the 128-bit Authentication Tag - value resulting from the key encryption operation. This Header - Parameter MUST be present and MUST be understood and processed by - implementations when these algorithms are used. - - - - - -Jones Standards Track [Page 19] - -RFC 7518 JSON Web Algorithms (JWA) May 2015 - - -4.8. Key Encryption with PBES2 - - This section defines the specifics of performing password-based - encryption of a JWE CEK, by first deriving a key encryption key from - a user-supplied password using PBES2 schemes as specified in - Section 6.2 of [RFC2898], then by encrypting the JWE CEK using the - derived key. - - These algorithms use HMAC SHA-2 algorithms as the Pseudorandom - Function (PRF) for the PBKDF2 key derivation and AES Key Wrap - [RFC3394] for the encryption scheme. The PBES2 password input is an - octet sequence; if the password to be used is represented as a text - string rather than an octet sequence, the UTF-8 encoding of the text - string MUST be used as the octet sequence. The salt parameter MUST - be computed from the "p2s" (PBES2 salt input) Header Parameter value - and the "alg" (algorithm) Header Parameter value as specified in the - "p2s" definition below. The iteration count parameter MUST be - provided as the "p2c" (PBES2 count) Header Parameter value. The - algorithms respectively use HMAC SHA-256, HMAC SHA-384, and HMAC - SHA-512 as the PRF and use 128-, 192-, and 256-bit AES Key Wrap keys. - Their derived-key lengths respectively are 16, 24, and 32 octets. - - The following "alg" (algorithm) Header Parameter values are used to - indicate that the JWE Encrypted Key is the result of encrypting the - CEK using the result of the corresponding password-based encryption - algorithm as the key encryption key for the corresponding key - wrapping algorithm: - - +--------------------+----------------------------------------------+ - | "alg" Param Value | Key Management Algorithm | - +--------------------+----------------------------------------------+ - | PBES2-HS256+A128KW | PBES2 with HMAC SHA-256 and "A128KW" | - | | wrapping | - | PBES2-HS384+A192KW | PBES2 with HMAC SHA-384 and "A192KW" | - | | wrapping | - | PBES2-HS512+A256KW | PBES2 with HMAC SHA-512 and "A256KW" | - | | wrapping | - +--------------------+----------------------------------------------+ - - See Appendix C of the JWK specification [JWK] for an example key - encryption computation using "PBES2-HS256+A128KW". - -4.8.1. Header Parameters Used for PBES2 Key Encryption - - The following Header Parameters are used for Key Encryption with - PBES2. - - - - - -Jones Standards Track [Page 20] - -RFC 7518 JSON Web Algorithms (JWA) May 2015 - - -4.8.1.1. "p2s" (PBES2 Salt Input) Header Parameter - - The "p2s" (PBES2 salt input) Header Parameter encodes a Salt Input - value, which is used as part of the PBKDF2 salt value. The "p2s" - value is BASE64URL(Salt Input). This Header Parameter MUST be - present and MUST be understood and processed by implementations when - these algorithms are used. - - The salt expands the possible keys that can be derived from a given - password. A Salt Input value containing 8 or more octets MUST be - used. A new Salt Input value MUST be generated randomly for every - encryption operation; see RFC 4086 [RFC4086] for considerations on - generating random values. The salt value used is (UTF8(Alg) || 0x00 - || Salt Input), where Alg is the "alg" (algorithm) Header Parameter - value. - -4.8.1.2. "p2c" (PBES2 Count) Header Parameter - - The "p2c" (PBES2 count) Header Parameter contains the PBKDF2 - iteration count, represented as a positive JSON integer. This Header - Parameter MUST be present and MUST be understood and processed by - implementations when these algorithms are used. - - The iteration count adds computational expense, ideally compounded by - the possible range of keys introduced by the salt. A minimum - iteration count of 1000 is RECOMMENDED. - -5. Cryptographic Algorithms for Content Encryption - - JWE uses cryptographic algorithms to encrypt and integrity-protect - the plaintext and to integrity-protect the Additional Authenticated - Data. - - - - - - - - - - - - - - - - - - - -Jones Standards Track [Page 21] - -RFC 7518 JSON Web Algorithms (JWA) May 2015 - - -5.1. "enc" (Encryption Algorithm) Header Parameter Values for JWE - - The table below is the set of "enc" (encryption algorithm) Header - Parameter values that are defined by this specification for use with - JWE. - - +---------------+----------------------------------+----------------+ - | "enc" Param | Content Encryption Algorithm | Implementation | - | Value | | Requirements | - +---------------+----------------------------------+----------------+ - | A128CBC-HS256 | AES_128_CBC_HMAC_SHA_256 | Required | - | | authenticated encryption | | - | | algorithm, as defined in Section | | - | | 5.2.3 | | - | A192CBC-HS384 | AES_192_CBC_HMAC_SHA_384 | Optional | - | | authenticated encryption | | - | | algorithm, as defined in Section | | - | | 5.2.4 | | - | A256CBC-HS512 | AES_256_CBC_HMAC_SHA_512 | Required | - | | authenticated encryption | | - | | algorithm, as defined in Section | | - | | 5.2.5 | | - | A128GCM | AES GCM using 128-bit key | Recommended | - | A192GCM | AES GCM using 192-bit key | Optional | - | A256GCM | AES GCM using 256-bit key | Recommended | - +---------------+----------------------------------+----------------+ - - All also use a JWE Initialization Vector value and produce JWE - Ciphertext and JWE Authentication Tag values. - - See Appendix A.3 for a table cross-referencing the JWE "enc" - (encryption algorithm) values defined in this specification with the - equivalent identifiers used by other standards and software packages. - -5.2. AES_CBC_HMAC_SHA2 Algorithms - - This section defines a family of authenticated encryption algorithms - built using a composition of AES [AES] in Cipher Block Chaining (CBC) - mode [NIST.800-38A] with PKCS #7 padding operations per Section 6.3 - of [RFC5652] and HMAC ([RFC2104] and [SHS]) operations. This - algorithm family is called AES_CBC_HMAC_SHA2. It also defines three - instances of this family: the first using 128-bit CBC keys and HMAC - SHA-256, the second using 192-bit CBC keys and HMAC SHA-384, and the - third using 256-bit CBC keys and HMAC SHA-512. Test cases for these - algorithms can be found in Appendix B. - - - - - - -Jones Standards Track [Page 22] - -RFC 7518 JSON Web Algorithms (JWA) May 2015 - - - These algorithms are based upon "Authenticated Encryption with AES- - CBC and HMAC-SHA" [AEAD-CBC-SHA], performing the same cryptographic - computations, but with the Initialization Vector (IV) and - Authentication Tag values remaining separate, rather than being - concatenated with the ciphertext value in the output representation. - This option is discussed in Appendix B of that specification. This - algorithm family is a generalization of the algorithm family in - [AEAD-CBC-SHA] and can be used to implement those algorithms. - -5.2.1. Conventions Used in Defining AES_CBC_HMAC_SHA2 - - We use the following notational conventions. - - CBC-PKCS7-ENC(X, P) denotes the AES-CBC encryption of P using PKCS - #7 padding utilizing the cipher with the key X. - MAC(Y, M) denotes the application of the MAC to the message M - using the key Y. - -5.2.2. Generic AES_CBC_HMAC_SHA2 Algorithm - - This section defines AES_CBC_HMAC_SHA2 in a manner that is - independent of the AES-CBC key size or hash function to be used. - Sections 5.2.2.1 and 5.2.2.2 define the generic encryption and - decryption algorithms. Sections 5.2.3 through 5.2.5 define instances - of AES_CBC_HMAC_SHA2 that specify those details. - -5.2.2.1. AES_CBC_HMAC_SHA2 Encryption - - The authenticated encryption algorithm takes as input four octet - strings: a secret key K, a plaintext P, Additional Authenticated Data - A, and an Initialization Vector IV. The authenticated ciphertext - value E and the Authentication Tag value T are provided as outputs. - The data in the plaintext are encrypted and authenticated, and the - Additional Authenticated Data are authenticated, but not encrypted. - - The encryption process is as follows, or uses an equivalent set of - steps: - - 1. The secondary keys MAC_KEY and ENC_KEY are generated from the - input key K as follows. Each of these two keys is an octet - string. - - MAC_KEY consists of the initial MAC_KEY_LEN octets of K, in - order. - ENC_KEY consists of the final ENC_KEY_LEN octets of K, in - order. - - - - - -Jones Standards Track [Page 23] - -RFC 7518 JSON Web Algorithms (JWA) May 2015 - - - The number of octets in the input key K MUST be the sum of - MAC_KEY_LEN and ENC_KEY_LEN. The values of these parameters are - specified by the Authenticated Encryption algorithms in Sections - 5.2.3 through 5.2.5. Note that the MAC key comes before the - encryption key in the input key K; this is in the opposite order - of the algorithm names in the identifier "AES_CBC_HMAC_SHA2". - - 2. The IV used is a 128-bit value generated randomly or - pseudorandomly for use in the cipher. - - 3. The plaintext is CBC encrypted using PKCS #7 padding using - ENC_KEY as the key and the IV. We denote the ciphertext output - from this step as E. - - 4. The octet string AL is equal to the number of bits in the - Additional Authenticated Data A expressed as a 64-bit unsigned - big-endian integer. - - 5. A message Authentication Tag T is computed by applying HMAC - [RFC2104] to the following data, in order: - - the Additional Authenticated Data A, - the Initialization Vector IV, - the ciphertext E computed in the previous step, and - the octet string AL defined above. - - The string MAC_KEY is used as the MAC key. We denote the output - of the MAC computed in this step as M. The first T_LEN octets of - M are used as T. - - 6. The ciphertext E and the Authentication Tag T are returned as the - outputs of the authenticated encryption. - - The encryption process can be illustrated as follows. Here K, P, A, - IV, and E denote the key, plaintext, Additional Authenticated Data, - Initialization Vector, and ciphertext, respectively. - - MAC_KEY = initial MAC_KEY_LEN octets of K, - ENC_KEY = final ENC_KEY_LEN octets of K, - E = CBC-PKCS7-ENC(ENC_KEY, P), - M = MAC(MAC_KEY, A || IV || E || AL), - T = initial T_LEN octets of M. - - - - - - - - - -Jones Standards Track [Page 24] - -RFC 7518 JSON Web Algorithms (JWA) May 2015 - - -5.2.2.2. AES_CBC_HMAC_SHA2 Decryption - - The authenticated decryption operation has five inputs: K, A, IV, E, - and T as defined above. It has only a single output: either a - plaintext value P or a special symbol FAIL that indicates that the - inputs are not authentic. The authenticated decryption algorithm is - as follows, or uses an equivalent set of steps: - - 1. The secondary keys MAC_KEY and ENC_KEY are generated from the - input key K as in Step 1 of Section 5.2.2.1. - - 2. The integrity and authenticity of A and E are checked by - computing an HMAC with the inputs as in Step 5 of - Section 5.2.2.1. The value T, from the previous step, is - compared to the first MAC_KEY length bits of the HMAC output. If - those values are identical, then A and E are considered valid, - and processing is continued. Otherwise, all of the data used in - the MAC validation are discarded, and the authenticated - decryption operation returns an indication that it failed, and - the operation halts. (But see Section 11.5 of [JWE] for security - considerations on thwarting timing attacks.) - - 3. The value E is decrypted and the PKCS #7 padding is checked and - removed. The value IV is used as the Initialization Vector. The - value ENC_KEY is used as the decryption key. - - 4. The plaintext value is returned. - -5.2.3. AES_128_CBC_HMAC_SHA_256 - - This algorithm is a concrete instantiation of the generic - AES_CBC_HMAC_SHA2 algorithm above. It uses the HMAC message - authentication code [RFC2104] with the SHA-256 hash function [SHS] to - provide message authentication, with the HMAC output truncated to 128 - bits, corresponding to the HMAC-SHA-256-128 algorithm defined in - [RFC4868]. For encryption, it uses AES in the CBC mode of operation - as defined in Section 6.2 of [NIST.800-38A], with PKCS #7 padding and - a 128-bit IV value. - - The AES_CBC_HMAC_SHA2 parameters specific to AES_128_CBC_HMAC_SHA_256 - are: - - The input key K is 32 octets long. - ENC_KEY_LEN is 16 octets. - MAC_KEY_LEN is 16 octets. - The SHA-256 hash algorithm is used for the HMAC. - The HMAC-SHA-256 output is truncated to T_LEN=16 octets, by - stripping off the final 16 octets. - - - -Jones Standards Track [Page 25] - -RFC 7518 JSON Web Algorithms (JWA) May 2015 - - -5.2.4. AES_192_CBC_HMAC_SHA_384 - - AES_192_CBC_HMAC_SHA_384 is based on AES_128_CBC_HMAC_SHA_256, but - with the following differences: - - The input key K is 48 octets long instead of 32. - ENC_KEY_LEN is 24 octets instead of 16. - MAC_KEY_LEN is 24 octets instead of 16. - SHA-384 is used for the HMAC instead of SHA-256. - The HMAC SHA-384 value is truncated to T_LEN=24 octets instead of - 16. - -5.2.5. AES_256_CBC_HMAC_SHA_512 - - AES_256_CBC_HMAC_SHA_512 is based on AES_128_CBC_HMAC_SHA_256, but - with the following differences: - - The input key K is 64 octets long instead of 32. - ENC_KEY_LEN is 32 octets instead of 16. - MAC_KEY_LEN is 32 octets instead of 16. - SHA-512 is used for the HMAC instead of SHA-256. - The HMAC SHA-512 value is truncated to T_LEN=32 octets instead of - 16. - -5.2.6. Content Encryption with AES_CBC_HMAC_SHA2 - - This section defines the specifics of performing authenticated - encryption with the AES_CBC_HMAC_SHA2 algorithms. - - The CEK is used as the secret key K. - - The following "enc" (encryption algorithm) Header Parameter values - are used to indicate that the JWE Ciphertext and JWE Authentication - Tag values have been computed using the corresponding algorithm: - - +---------------+---------------------------------------------------+ - | "enc" Param | Content Encryption Algorithm | - | Value | | - +---------------+---------------------------------------------------+ - | A128CBC-HS256 | AES_128_CBC_HMAC_SHA_256 authenticated encryption | - | | algorithm, as defined in Section 5.2.3 | - | A192CBC-HS384 | AES_192_CBC_HMAC_SHA_384 authenticated encryption | - | | algorithm, as defined in Section 5.2.4 | - | A256CBC-HS512 | AES_256_CBC_HMAC_SHA_512 authenticated encryption | - | | algorithm, as defined in Section 5.2.5 | - +---------------+---------------------------------------------------+ - - - - - -Jones Standards Track [Page 26] - -RFC 7518 JSON Web Algorithms (JWA) May 2015 - - -5.3. Content Encryption with AES GCM - - This section defines the specifics of performing authenticated - encryption with AES in Galois/Counter Mode (GCM) ([AES] and - [NIST.800-38D]). - - The CEK is used as the encryption key. - - Use of an IV of size 96 bits is REQUIRED with this algorithm. - - The requested size of the Authentication Tag output MUST be 128 bits, - regardless of the key size. - - The following "enc" (encryption algorithm) Header Parameter values - are used to indicate that the JWE Ciphertext and JWE Authentication - Tag values have been computed using the corresponding algorithm and - key size: - - +-------------------+------------------------------+ - | "enc" Param Value | Content Encryption Algorithm | - +-------------------+------------------------------+ - | A128GCM | AES GCM using 128-bit key | - | A192GCM | AES GCM using 192-bit key | - | A256GCM | AES GCM using 256-bit key | - +-------------------+------------------------------+ - - An example using this algorithm is shown in Appendix A.1 of [JWE]. - -6. Cryptographic Algorithms for Keys - - A JSON Web Key (JWK) [JWK] is a JSON data structure that represents a - cryptographic key. These keys can be either asymmetric or symmetric. - They can hold both public and private information about the key. - This section defines the parameters for keys using the algorithms - specified by this document. - - - - - - - - - - - - - - - - -Jones Standards Track [Page 27] - -RFC 7518 JSON Web Algorithms (JWA) May 2015 - - -6.1. "kty" (Key Type) Parameter Values - - The table below is the set of "kty" (key type) parameter values that - are defined by this specification for use in JWKs. - - +-------------+--------------------------------+--------------------+ - | "kty" Param | Key Type | Implementation | - | Value | | Requirements | - +-------------+--------------------------------+--------------------+ - | EC | Elliptic Curve [DSS] | Recommended+ | - | RSA | RSA [RFC3447] | Required | - | oct | Octet sequence (used to | Required | - | | represent symmetric keys) | | - +-------------+--------------------------------+--------------------+ - - The use of "+" in the Implementation Requirements column indicates - that the requirement strength is likely to be increased in a future - version of the specification. - -6.2. Parameters for Elliptic Curve Keys - - JWKs can represent Elliptic Curve [DSS] keys. In this case, the - "kty" member value is "EC". - -6.2.1. Parameters for Elliptic Curve Public Keys - - An Elliptic Curve public key is represented by a pair of coordinates - drawn from a finite field, which together define a point on an - Elliptic Curve. The following members MUST be present for all - Elliptic Curve public keys: - - o "crv" - o "x" - - The following member MUST also be present for Elliptic Curve public - keys for the three curves defined in the following section: - - o "y" - -6.2.1.1. "crv" (Curve) Parameter - - The "crv" (curve) parameter identifies the cryptographic curve used - with the key. Curve values from [DSS] used by this specification - are: - - o "P-256" - o "P-384" - o "P-521" - - - -Jones Standards Track [Page 28] - -RFC 7518 JSON Web Algorithms (JWA) May 2015 - - - These values are registered in the IANA "JSON Web Key Elliptic Curve" - registry defined in Section 7.6. Additional "crv" values can be - registered by other specifications. Specifications registering - additional curves must define what parameters are used to represent - keys for the curves registered. The "crv" value is a case-sensitive - string. - - SEC1 [SEC1] point compression is not supported for any of these three - curves. - -6.2.1.2. "x" (X Coordinate) Parameter - - The "x" (x coordinate) parameter contains the x coordinate for the - Elliptic Curve point. It is represented as the base64url encoding of - the octet string representation of the coordinate, as defined in - Section 2.3.5 of SEC1 [SEC1]. The length of this octet string MUST - be the full size of a coordinate for the curve specified in the "crv" - parameter. For example, if the value of "crv" is "P-521", the octet - string must be 66 octets long. - -6.2.1.3. "y" (Y Coordinate) Parameter - - The "y" (y coordinate) parameter contains the y coordinate for the - Elliptic Curve point. It is represented as the base64url encoding of - the octet string representation of the coordinate, as defined in - Section 2.3.5 of SEC1 [SEC1]. The length of this octet string MUST - be the full size of a coordinate for the curve specified in the "crv" - parameter. For example, if the value of "crv" is "P-521", the octet - string must be 66 octets long. - -6.2.2. Parameters for Elliptic Curve Private Keys - - In addition to the members used to represent Elliptic Curve public - keys, the following member MUST be present to represent Elliptic - Curve private keys. - -6.2.2.1. "d" (ECC Private Key) Parameter - - The "d" (ECC private key) parameter contains the Elliptic Curve - private key value. It is represented as the base64url encoding of - the octet string representation of the private key value, as defined - in Section 2.3.7 of SEC1 [SEC1]. The length of this octet string - MUST be ceiling(log-base-2(n)/8) octets (where n is the order of the - curve). - - - - - - - -Jones Standards Track [Page 29] - -RFC 7518 JSON Web Algorithms (JWA) May 2015 - - -6.3. Parameters for RSA Keys - - JWKs can represent RSA [RFC3447] keys. In this case, the "kty" - member value is "RSA". The semantics of the parameters defined below - are the same as those defined in Sections 3.1 and 3.2 of RFC 3447. - -6.3.1. Parameters for RSA Public Keys - - The following members MUST be present for RSA public keys. - -6.3.1.1. "n" (Modulus) Parameter - - The "n" (modulus) parameter contains the modulus value for the RSA - public key. It is represented as a Base64urlUInt-encoded value. - - Note that implementers have found that some cryptographic libraries - prefix an extra zero-valued octet to the modulus representations they - return, for instance, returning 257 octets for a 2048-bit key, rather - than 256. Implementations using such libraries will need to take - care to omit the extra octet from the base64url-encoded - representation. - -6.3.1.2. "e" (Exponent) Parameter - - The "e" (exponent) parameter contains the exponent value for the RSA - public key. It is represented as a Base64urlUInt-encoded value. - - For instance, when representing the value 65537, the octet sequence - to be base64url-encoded MUST consist of the three octets [1, 0, 1]; - the resulting representation for this value is "AQAB". - -6.3.2. Parameters for RSA Private Keys - - In addition to the members used to represent RSA public keys, the - following members are used to represent RSA private keys. The - parameter "d" is REQUIRED for RSA private keys. The others enable - optimizations and SHOULD be included by producers of JWKs - representing RSA private keys. If the producer includes any of the - other private key parameters, then all of the others MUST be present, - with the exception of "oth", which MUST only be present when more - than two prime factors were used. - -6.3.2.1. "d" (Private Exponent) Parameter - - The "d" (private exponent) parameter contains the private exponent - value for the RSA private key. It is represented as a Base64urlUInt- - encoded value. - - - - -Jones Standards Track [Page 30] - -RFC 7518 JSON Web Algorithms (JWA) May 2015 - - -6.3.2.2. "p" (First Prime Factor) Parameter - - The "p" (first prime factor) parameter contains the first prime - factor. It is represented as a Base64urlUInt-encoded value. - -6.3.2.3. "q" (Second Prime Factor) Parameter - - The "q" (second prime factor) parameter contains the second prime - factor. It is represented as a Base64urlUInt-encoded value. - -6.3.2.4. "dp" (First Factor CRT Exponent) Parameter - - The "dp" (first factor CRT exponent) parameter contains the Chinese - Remainder Theorem (CRT) exponent of the first factor. It is - represented as a Base64urlUInt-encoded value. - -6.3.2.5. "dq" (Second Factor CRT Exponent) Parameter - - The "dq" (second factor CRT exponent) parameter contains the CRT - exponent of the second factor. It is represented as a Base64urlUInt- - encoded value. - -6.3.2.6. "qi" (First CRT Coefficient) Parameter - - The "qi" (first CRT coefficient) parameter contains the CRT - coefficient of the second factor. It is represented as a - Base64urlUInt-encoded value. - -6.3.2.7. "oth" (Other Primes Info) Parameter - - The "oth" (other primes info) parameter contains an array of - information about any third and subsequent primes, should they exist. - When only two primes have been used (the normal case), this parameter - MUST be omitted. When three or more primes have been used, the - number of array elements MUST be the number of primes used minus two. - For more information on this case, see the description of the - OtherPrimeInfo parameters in Appendix A.1.2 of RFC 3447 [RFC3447], - upon which the following parameters are modeled. If the consumer of - a JWK does not support private keys with more than two primes and it - encounters a private key that includes the "oth" parameter, then it - MUST NOT use the key. Each array element MUST be an object with the - following members. - -6.3.2.7.1. "r" (Prime Factor) - - The "r" (prime factor) parameter within an "oth" array member - represents the value of a subsequent prime factor. It is represented - as a Base64urlUInt-encoded value. - - - -Jones Standards Track [Page 31] - -RFC 7518 JSON Web Algorithms (JWA) May 2015 - - -6.3.2.7.2. "d" (Factor CRT Exponent) - - The "d" (factor CRT exponent) parameter within an "oth" array member - represents the CRT exponent of the corresponding prime factor. It is - represented as a Base64urlUInt-encoded value. - -6.3.2.7.3. "t" (Factor CRT Coefficient) - - The "t" (factor CRT coefficient) parameter within an "oth" array - member represents the CRT coefficient of the corresponding prime - factor. It is represented as a Base64urlUInt-encoded value. - -6.4. Parameters for Symmetric Keys - - When the JWK "kty" member value is "oct" (octet sequence), the member - "k" (see Section 6.4.1) is used to represent a symmetric key (or - another key whose value is a single octet sequence). An "alg" member - SHOULD also be present to identify the algorithm intended to be used - with the key, unless the application uses another means or convention - to determine the algorithm used. - -6.4.1. "k" (Key Value) Parameter - - The "k" (key value) parameter contains the value of the symmetric (or - other single-valued) key. It is represented as the base64url - encoding of the octet sequence containing the key value. - -7. IANA Considerations - - The following registration procedure is used for all the registries - established by this specification. - - The registration procedure for values is Specification Required - [RFC5226] after a three-week review period on the - jose-reg-review@ietf.org mailing list, on the advice of one or more - Designated Experts. However, to allow for the allocation of values - prior to publication, the Designated Experts may approve registration - once they are satisfied that such a specification will be published. - - Registration requests sent to the mailing list for review should use - an appropriate subject (e.g., "Request to register algorithm: - example"). - - Within the review period, the Designated Experts will either approve - or deny the registration request, communicating this decision to the - review list and IANA. Denials should include an explanation and, if - applicable, suggestions as to how to make the request successful. - - - - -Jones Standards Track [Page 32] - -RFC 7518 JSON Web Algorithms (JWA) May 2015 - - - Registration requests that are undetermined for a period longer than - 21 days can be brought to the IESG's attention (using the - iesg@ietf.org mailing list) for resolution. - - Criteria that should be applied by the Designated Experts include - determining whether the proposed registration duplicates existing - functionality, whether it is likely to be of general applicability or - useful only for a single application, and whether the registration - description is clear. - - IANA must only accept registry updates from the Designated Experts - and should direct all requests for registration to the review mailing - list. - - It is suggested that multiple Designated Experts be appointed who are - able to represent the perspectives of different applications using - this specification, in order to enable broadly informed review of - registration decisions. In cases where a registration decision could - be perceived as creating a conflict of interest for a particular - Expert, that Expert should defer to the judgment of the other - Experts. - -7.1. JSON Web Signature and Encryption Algorithms Registry - - This specification establishes the IANA "JSON Web Signature and - Encryption Algorithms" registry for values of the JWS and JWE "alg" - (algorithm) and "enc" (encryption algorithm) Header Parameters. The - registry records the algorithm name, the algorithm description, the - algorithm usage locations, the implementation requirements, the - change controller, and a reference to the specification that defines - it. The same algorithm name can be registered multiple times, - provided that the sets of usage locations are disjoint. - - It is suggested that the length of the key be included in the - algorithm name when multiple variations of algorithms are being - registered that use keys of different lengths and the key lengths for - each need to be fixed (for instance, because they will be created by - key derivation functions). This allows readers of the JSON text to - more easily make security decisions. - - The Designated Experts should perform reasonable due diligence that - algorithms being registered either are currently considered - cryptographically credible or are being registered as Deprecated or - Prohibited. - - - - - - - -Jones Standards Track [Page 33] - -RFC 7518 JSON Web Algorithms (JWA) May 2015 - - - The implementation requirements of an algorithm may be changed over - time as the cryptographic landscape evolves, for instance, to change - the status of an algorithm to Deprecated or to change the status of - an algorithm from Optional to Recommended+ or Required. Changes of - implementation requirements are only permitted on a Specification - Required basis after review by the Designated Experts, with the new - specification defining the revised implementation requirements level. - -7.1.1. Registration Template - - Algorithm Name: - The name requested (e.g., "HS256"). This name is a case-sensitive - ASCII string. Names may not match other registered names in a - case-insensitive manner unless the Designated Experts state that - there is a compelling reason to allow an exception. - - Algorithm Description: - Brief description of the algorithm (e.g., "HMAC using SHA-256"). - - Algorithm Usage Location(s): - The algorithm usage locations. This must be one or more of the - values "alg" or "enc" if the algorithm is to be used with JWS or - JWE. The value "JWK" is used if the algorithm identifier will be - used as a JWK "alg" member value, but will not be used with JWS or - JWE; this could be the case, for instance, for non-authenticated - encryption algorithms. Other values may be used with the approval - of a Designated Expert. - - JOSE Implementation Requirements: - The algorithm implementation requirements for JWS and JWE, which - must be one the words Required, Recommended, Optional, Deprecated, - or Prohibited. Optionally, the word can be followed by a "+" or - "-". The use of "+" indicates that the requirement strength is - likely to be increased in a future version of the specification. - The use of "-" indicates that the requirement strength is likely - to be decreased in a future version of the specification. Any - identifiers registered for non-authenticated encryption algorithms - or other algorithms that are otherwise unsuitable for direct use - as JWS or JWE algorithms must be registered as "Prohibited". - - Change Controller: - For Standards Track RFCs, list the "IESG". For others, give the - name of the responsible party. Other details (e.g., postal - address, email address, home page URI) may also be included. - - - - - - - -Jones Standards Track [Page 34] - -RFC 7518 JSON Web Algorithms (JWA) May 2015 - - - Specification Document(s): - Reference to the document or documents that specify the parameter, - preferably including URIs that can be used to retrieve copies of - the documents. An indication of the relevant sections may also be - included but is not required. - - Algorithm Analysis Documents(s): - References to a publication or publications in well-known - cryptographic conferences, by national standards bodies, or by - other authoritative sources analyzing the cryptographic soundness - of the algorithm to be registered. The Designated Experts may - require convincing evidence of the cryptographic soundness of a - new algorithm to be provided with the registration request unless - the algorithm is being registered as Deprecated or Prohibited. - Having gone through working group and IETF review, the initial - registrations made by this document are exempt from the need to - provide this information. - -7.1.2. Initial Registry Contents - - o Algorithm Name: "HS256" - o Algorithm Description: HMAC using SHA-256 - o Algorithm Usage Location(s): "alg" - o JOSE Implementation Requirements: Required - o Change Controller: IESG - o Specification Document(s): Section 3.2 of RFC 7518 - o Algorithm Analysis Documents(s): n/a - - o Algorithm Name: "HS384" - o Algorithm Description: HMAC using SHA-384 - o Algorithm Usage Location(s): "alg" - o JOSE Implementation Requirements: Optional - o Change Controller: IESG - o Specification Document(s): Section 3.2 of RFC 7518 - o Algorithm Analysis Documents(s): n/a - - o Algorithm Name: "HS512" - o Algorithm Description: HMAC using SHA-512 - o Algorithm Usage Location(s): "alg" - o JOSE Implementation Requirements: Optional - o Change Controller: IESG - o Specification Document(s): Section 3.2 of RFC 7518 - o Algorithm Analysis Documents(s): n/a - - - - - - - - -Jones Standards Track [Page 35] - -RFC 7518 JSON Web Algorithms (JWA) May 2015 - - - o Algorithm Name: "RS256" - o Algorithm Description: RSASSA-PKCS1-v1_5 using SHA-256 - o Algorithm Usage Location(s): "alg" - o JOSE Implementation Requirements: Recommended - o Change Controller: IESG - o Specification Document(s): Section 3.3 of RFC 7518 - o Algorithm Analysis Documents(s): n/a - - o Algorithm Name: "RS384" - o Algorithm Description: RSASSA-PKCS1-v1_5 using SHA-384 - o Algorithm Usage Location(s): "alg" - o JOSE Implementation Requirements: Optional - o Change Controller: IESG - o Specification Document(s): Section 3.3 of RFC 7518 - o Algorithm Analysis Documents(s): n/a - - o Algorithm Name: "RS512" - o Algorithm Description: RSASSA-PKCS1-v1_5 using SHA-512 - o Algorithm Usage Location(s): "alg" - o JOSE Implementation Requirements: Optional - o Change Controller: IESG - o Specification Document(s): Section 3.3 of RFC 7518 - o Algorithm Analysis Documents(s): n/a - - o Algorithm Name: "ES256" - o Algorithm Description: ECDSA using P-256 and SHA-256 - o Algorithm Usage Location(s): "alg" - o JOSE Implementation Requirements: Recommended+ - o Change Controller: IESG - o Specification Document(s): Section 3.4 of RFC 7518 - o Algorithm Analysis Documents(s): n/a - - o Algorithm Name: "ES384" - o Algorithm Description: ECDSA using P-384 and SHA-384 - o Algorithm Usage Location(s): "alg" - o JOSE Implementation Requirements: Optional - o Change Controller: IESG - o Specification Document(s): Section 3.4 of RFC 7518 - o Algorithm Analysis Documents(s): n/a - - o Algorithm Name: "ES512" - o Algorithm Description: ECDSA using P-521 and SHA-512 - o Algorithm Usage Location(s): "alg" - o JOSE Implementation Requirements: Optional - o Change Controller: IESG - o Specification Document(s): Section 3.4 of RFC 7518 - o Algorithm Analysis Documents(s): n/a - - - - -Jones Standards Track [Page 36] - -RFC 7518 JSON Web Algorithms (JWA) May 2015 - - - o Algorithm Name: "PS256" - o Algorithm Description: RSASSA-PSS using SHA-256 and MGF1 with - SHA-256 - o Algorithm Usage Location(s): "alg" - o JOSE Implementation Requirements: Optional - o Change Controller: IESG - o Specification Document(s): Section 3.5 of RFC 7518 - o Algorithm Analysis Documents(s): n/a - - o Algorithm Name: "PS384" - o Algorithm Description: RSASSA-PSS using SHA-384 and MGF1 with - SHA-384 - o Algorithm Usage Location(s): "alg" - o JOSE Implementation Requirements: Optional - o Change Controller: IESG - o Specification Document(s): Section 3.5 of RFC 7518 - o Algorithm Analysis Documents(s): n/a - - o Algorithm Name: "PS512" - o Algorithm Description: RSASSA-PSS using SHA-512 and MGF1 with - SHA-512 - o Algorithm Usage Location(s): "alg" - o JOSE Implementation Requirements: Optional - o Change Controller: IESG - o Specification Document(s): Section 3.5 of RFC 7518 - o Algorithm Analysis Documents(s): n/a - - o Algorithm Name: "none" - o Algorithm Description: No digital signature or MAC performed - o Algorithm Usage Location(s): "alg" - o JOSE Implementation Requirements: Optional - o Change Controller: IESG - o Specification Document(s): Section 3.6 of RFC 7518 - o Algorithm Analysis Documents(s): n/a - - o Algorithm Name: "RSA1_5" - o Algorithm Description: RSAES-PKCS1-v1_5 - o Algorithm Usage Location(s): "alg" - o JOSE Implementation Requirements: Recommended- - o Change Controller: IESG - o Specification Document(s): Section 4.2 of RFC 7518 - o Algorithm Analysis Documents(s): n/a - - - - - - - - - -Jones Standards Track [Page 37] - -RFC 7518 JSON Web Algorithms (JWA) May 2015 - - - o Algorithm Name: "RSA-OAEP" - o Algorithm Description: RSAES OAEP using default parameters - o Algorithm Usage Location(s): "alg" - o JOSE Implementation Requirements: Recommended+ - o Change Controller: IESG - o Specification Document(s): Section 4.3 of RFC 7518 - o Algorithm Analysis Documents(s): n/a - - o Algorithm Name: "RSA-OAEP-256" - o Algorithm Description: RSAES OAEP using SHA-256 and MGF1 with - SHA-256 - o Algorithm Usage Location(s): "alg" - o JOSE Implementation Requirements: Optional - o Change Controller: IESG - o Specification Document(s): Section 4.3 of RFC 7518 - o Algorithm Analysis Documents(s): n/a - - o Algorithm Name: "A128KW" - o Algorithm Description: AES Key Wrap using 128-bit key - o Algorithm Usage Location(s): "alg" - o JOSE Implementation Requirements: Recommended - o Change Controller: IESG - o Specification Document(s): Section 4.4 of RFC 7518 - o Algorithm Analysis Documents(s): n/a - - o Algorithm Name: "A192KW" - o Algorithm Description: AES Key Wrap using 192-bit key - o Algorithm Usage Location(s): "alg" - o JOSE Implementation Requirements: Optional - o Change Controller: IESG - o Specification Document(s): Section 4.4 of RFC 7518 - o Algorithm Analysis Documents(s): n/a - - o Algorithm Name: "A256KW" - o Algorithm Description: AES Key Wrap using 256-bit key - o Algorithm Usage Location(s): "alg" - o JOSE Implementation Requirements: Recommended - o Change Controller: IESG - o Specification Document(s): Section 4.4 of RFC 7518 - o Algorithm Analysis Documents(s): n/a - - o Algorithm Name: "dir" - o Algorithm Description: Direct use of a shared symmetric key - o Algorithm Usage Location(s): "alg" - o JOSE Implementation Requirements: Recommended - o Change Controller: IESG - o Specification Document(s): Section 4.5 of RFC 7518 - o Algorithm Analysis Documents(s): n/a - - - -Jones Standards Track [Page 38] - -RFC 7518 JSON Web Algorithms (JWA) May 2015 - - - o Algorithm Name: "ECDH-ES" - o Algorithm Description: ECDH-ES using Concat KDF - o Algorithm Usage Location(s): "alg" - o JOSE Implementation Requirements: Recommended+ - o Change Controller: IESG - o Specification Document(s): Section 4.6 of RFC 7518 - o Algorithm Analysis Documents(s): n/a - - o Algorithm Name: "ECDH-ES+A128KW" - o Algorithm Description: ECDH-ES using Concat KDF and "A128KW" - wrapping - o Algorithm Usage Location(s): "alg" - o JOSE Implementation Requirements: Recommended - o Change Controller: IESG - o Specification Document(s): Section 4.6 of RFC 7518 - o Algorithm Analysis Documents(s): n/a - - o Algorithm Name: "ECDH-ES+A192KW" - o Algorithm Description: ECDH-ES using Concat KDF and "A192KW" - wrapping - o Algorithm Usage Location(s): "alg" - o JOSE Implementation Requirements: Optional - o Change Controller: IESG - o Specification Document(s): Section 4.6 of RFC 7518 - o Algorithm Analysis Documents(s): n/a - - o Algorithm Name: "ECDH-ES+A256KW" - o Algorithm Description: ECDH-ES using Concat KDF and "A256KW" - wrapping - o Algorithm Usage Location(s): "alg" - o JOSE Implementation Requirements: Recommended - o Change Controller: IESG - o Specification Document(s): Section 4.6 of RFC 7518 - o Algorithm Analysis Documents(s): n/a - - o Algorithm Name: "A128GCMKW" - o Algorithm Description: Key wrapping with AES GCM using 128-bit key - o Algorithm Usage Location(s): "alg" - o JOSE Implementation Requirements: Optional - o Change Controller: IESG - o Specification Document(s): Section 4.7 of RFC 7518 - o Algorithm Analysis Documents(s): n/a - - - - - - - - - -Jones Standards Track [Page 39] - -RFC 7518 JSON Web Algorithms (JWA) May 2015 - - - o Algorithm Name: "A192GCMKW" - o Algorithm Description: Key wrapping with AES GCM using 192-bit key - o Algorithm Usage Location(s): "alg" - o JOSE Implementation Requirements: Optional - o Change Controller: IESG - o Specification Document(s): Section 4.7 of RFC 7518 - o Algorithm Analysis Documents(s): n/a - - o Algorithm Name: "A256GCMKW" - o Algorithm Description: Key wrapping with AES GCM using 256-bit key - o Algorithm Usage Location(s): "alg" - o JOSE Implementation Requirements: Optional - o Change Controller: IESG - o Specification Document(s): Section 4.7 of RFC 7518 - o Algorithm Analysis Documents(s): n/a - - o Algorithm Name: "PBES2-HS256+A128KW" - o Algorithm Description: PBES2 with HMAC SHA-256 and "A128KW" - wrapping - o Algorithm Usage Location(s): "alg" - o JOSE Implementation Requirements: Optional - o Change Controller: IESG - o Specification Document(s): Section 4.8 of RFC 7518 - o Algorithm Analysis Documents(s): n/a - - o Algorithm Name: "PBES2-HS384+A192KW" - o Algorithm Description: PBES2 with HMAC SHA-384 and "A192KW" - wrapping - o Algorithm Usage Location(s): "alg" - o JOSE Implementation Requirements: Optional - o Change Controller: IESG - o Specification Document(s): Section 4.8 of RFC 7518 - o Algorithm Analysis Documents(s): n/a - - o Algorithm Name: "PBES2-HS512+A256KW" - o Algorithm Description: PBES2 with HMAC SHA-512 and "A256KW" - wrapping - o Algorithm Usage Location(s): "alg" - o JOSE Implementation Requirements: Optional - o Change Controller: IESG - o Specification Document(s): Section 4.8 of RFC 7518 - o Algorithm Analysis Documents(s): n/a - - - - - - - - - -Jones Standards Track [Page 40] - -RFC 7518 JSON Web Algorithms (JWA) May 2015 - - - o Algorithm Name: "A128CBC-HS256" - o Algorithm Description: AES_128_CBC_HMAC_SHA_256 authenticated - encryption algorithm - o Algorithm Usage Location(s): "enc" - o JOSE Implementation Requirements: Required - o Change Controller: IESG - o Specification Document(s): Section 5.2.3 of RFC 7518 - o Algorithm Analysis Documents(s): n/a - - o Algorithm Name: "A192CBC-HS384" - o Algorithm Description: AES_192_CBC_HMAC_SHA_384 authenticated - encryption algorithm - o Algorithm Usage Location(s): "enc" - o JOSE Implementation Requirements: Optional - o Change Controller: IESG - o Specification Document(s): Section 5.2.4 of RFC 7518 - o Algorithm Analysis Documents(s): n/a - - o Algorithm Name: "A256CBC-HS512" - o Algorithm Description: AES_256_CBC_HMAC_SHA_512 authenticated - encryption algorithm - o Algorithm Usage Location(s): "enc" - o JOSE Implementation Requirements: Required - o Change Controller: IESG - o Specification Document(s): Section 5.2.5 of RFC 7518 - o Algorithm Analysis Documents(s): n/a - - o Algorithm Name: "A128GCM" - o Algorithm Description: AES GCM using 128-bit key - o Algorithm Usage Location(s): "enc" - o JOSE Implementation Requirements: Recommended - o Change Controller: IESG - o Specification Document(s): Section 5.3 of RFC 7518 - o Algorithm Analysis Documents(s): n/a - - o Algorithm Name: "A192GCM" - o Algorithm Description: AES GCM using 192-bit key - o Algorithm Usage Location(s): "enc" - o JOSE Implementation Requirements: Optional - o Change Controller: IESG - o Specification Document(s): Section 5.3 of RFC 7518 - o Algorithm Analysis Documents(s): n/a - - - - - - - - - -Jones Standards Track [Page 41] - -RFC 7518 JSON Web Algorithms (JWA) May 2015 - - - o Algorithm Name: "A256GCM" - o Algorithm Description: AES GCM using 256-bit key - o Algorithm Usage Location(s): "enc" - o JOSE Implementation Requirements: Recommended - o Change Controller: IESG - o Specification Document(s): Section 5.3 of RFC 7518 - o Algorithm Analysis Documents(s): n/a - -7.2. Header Parameter Names Registration - - This section registers the Header Parameter names defined in Sections - 4.6.1, 4.7.1, and 4.8.1 of this specification in the IANA "JSON Web - Signature and Encryption Header Parameters" registry established by - [JWS]. - -7.2.1. Registry Contents - - o Header Parameter Name: "epk" - o Header Parameter Description: Ephemeral Public Key - o Header Parameter Usage Location(s): JWE - o Change Controller: IESG - o Specification Document(s): Section 4.6.1.1 of RFC 7518 - - o Header Parameter Name: "apu" - o Header Parameter Description: Agreement PartyUInfo - o Header Parameter Usage Location(s): JWE - o Change Controller: IESG - o Specification Document(s): Section 4.6.1.2 of RFC 7518 - - o Header Parameter Name: "apv" - o Header Parameter Description: Agreement PartyVInfo - o Header Parameter Usage Location(s): JWE - o Change Controller: IESG - o Specification Document(s): Section 4.6.1.3 of RFC 7518 - - o Header Parameter Name: "iv" - o Header Parameter Description: Initialization Vector - o Header Parameter Usage Location(s): JWE - o Change Controller: IESG - o Specification Document(s): Section 4.7.1.1 of RFC 7518 - - o Header Parameter Name: "tag" - o Header Parameter Description: Authentication Tag - o Header Parameter Usage Location(s): JWE - o Change Controller: IESG - o Specification Document(s): Section 4.7.1.2 of RFC 7518 - - - - - -Jones Standards Track [Page 42] - -RFC 7518 JSON Web Algorithms (JWA) May 2015 - - - o Header Parameter Name: "p2s" - o Header Parameter Description: PBES2 Salt Input - o Header Parameter Usage Location(s): JWE - o Change Controller: IESG - o Specification Document(s): Section 4.8.1.1 of RFC 7518 - - o Header Parameter Name: "p2c" - o Header Parameter Description: PBES2 Count - o Header Parameter Usage Location(s): JWE - o Change Controller: IESG - o Specification Document(s): Section 4.8.1.2 of RFC 7518 - -7.3. JSON Web Encryption Compression Algorithms Registry - - This specification establishes the IANA "JSON Web Encryption - Compression Algorithms" registry for JWE "zip" member values. The - registry records the compression algorithm value and a reference to - the specification that defines it. - -7.3.1. Registration Template - - Compression Algorithm Value: - The name requested (e.g., "DEF"). Because a core goal of this - specification is for the resulting representations to be compact, - it is RECOMMENDED that the name be short -- not to exceed 8 - characters without a compelling reason to do so. This name is - case sensitive. Names may not match other registered names in a - case-insensitive manner unless the Designated Experts state that - there is a compelling reason to allow an exception. - - Compression Algorithm Description: - Brief description of the compression algorithm (e.g., "DEFLATE"). - - Change Controller: - For Standards Track RFCs, list "IESG". For others, give the name - of the responsible party. Other details (e.g., postal address, - email address, home page URI) may also be included. - - Specification Document(s): - Reference to the document or documents that specify the parameter, - preferably including URIs that can be used to retrieve copies of - the documents. An indication of the relevant sections may also be - included but is not required. - - - - - - - - -Jones Standards Track [Page 43] - -RFC 7518 JSON Web Algorithms (JWA) May 2015 - - -7.3.2. Initial Registry Contents - - o Compression Algorithm Value: "DEF" - o Compression Algorithm Description: DEFLATE - o Change Controller: IESG - o Specification Document(s): JSON Web Encryption (JWE) [JWE] - -7.4. JSON Web Key Types Registry - - This specification establishes the IANA "JSON Web Key Types" registry - for values of the JWK "kty" (key type) parameter. The registry - records the "kty" value, implementation requirements, and a reference - to the specification that defines it. - - The implementation requirements of a key type may be changed over - time as the cryptographic landscape evolves, for instance, to change - the status of a key type to Deprecated or to change the status of a - key type from Optional to Recommended+ or Required. Changes of - implementation requirements are only permitted on a Specification - Required basis after review by the Designated Experts, with the new - specification defining the revised implementation requirements level. - -7.4.1. Registration Template - - "kty" Parameter Value: - The name requested (e.g., "EC"). Because a core goal of this - specification is for the resulting representations to be compact, - it is RECOMMENDED that the name be short -- not to exceed 8 - characters without a compelling reason to do so. This name is - case sensitive. Names may not match other registered names in a - case-insensitive manner unless the Designated Experts state that - there is a compelling reason to allow an exception. - - Key Type Description: - Brief description of the Key Type (e.g., "Elliptic Curve"). - - Change Controller: - For Standards Track RFCs, list "IESG". For others, give the name - of the responsible party. Other details (e.g., postal address, - email address, home page URI) may also be included. - - - - - - - - - - - -Jones Standards Track [Page 44] - -RFC 7518 JSON Web Algorithms (JWA) May 2015 - - - JOSE Implementation Requirements: - The key type implementation requirements for JWS and JWE, which - must be one the words Required, Recommended, Optional, Deprecated, - or Prohibited. Optionally, the word can be followed by a "+" or - "-". The use of "+" indicates that the requirement strength is - likely to be increased in a future version of the specification. - The use of "-" indicates that the requirement strength is likely - to be decreased in a future version of the specification. - - Specification Document(s): - Reference to the document or documents that specify the parameter, - preferably including URIs that can be used to retrieve copies of - the documents. An indication of the relevant sections may also be - included but is not required. - -7.4.2. Initial Registry Contents - - This section registers the values defined in Section 6.1. - - o "kty" Parameter Value: "EC" - o Key Type Description: Elliptic Curve - o JOSE Implementation Requirements: Recommended+ - o Change Controller: IESG - o Specification Document(s): Section 6.2 of RFC 7518 - - o "kty" Parameter Value: "RSA" - o Key Type Description: RSA - o JOSE Implementation Requirements: Required - o Change Controller: IESG - o Specification Document(s): Section 6.3 of RFC 7518 - - o "kty" Parameter Value: "oct" - o Key Type Description: Octet Sequence - o JOSE Implementation Requirements: Required - o Change Controller: IESG - o Specification Document(s): Section 6.4 of RFC 7518 - -7.5. JSON Web Key Parameters Registration - - This section registers the parameter names defined in Sections 6.2, - 6.3, and 6.4 of this specification in the IANA "JSON Web Key - Parameters" registry established by [JWK]. - - - - - - - - - -Jones Standards Track [Page 45] - -RFC 7518 JSON Web Algorithms (JWA) May 2015 - - -7.5.1. Registry Contents - - o Parameter Name: "crv" - o Parameter Description: Curve - o Used with "kty" Value(s): "EC" - o Parameter Information Class: Public - o Change Controller: IESG - o Specification Document(s): Section 6.2.1.1 of RFC 7518 - - o Parameter Name: "x" - o Parameter Description: X Coordinate - o Used with "kty" Value(s): "EC" - o Parameter Information Class: Public - o Change Controller: IESG - o Specification Document(s): Section 6.2.1.2 of RFC 7518 - - o Parameter Name: "y" - o Parameter Description: Y Coordinate - o Used with "kty" Value(s): "EC" - o Parameter Information Class: Public - o Change Controller: IESG - o Specification Document(s): Section 6.2.1.3 of RFC 7518 - - o Parameter Name: "d" - o Parameter Description: ECC Private Key - o Used with "kty" Value(s): "EC" - o Parameter Information Class: Private - o Change Controller: IESG - o Specification Document(s): Section 6.2.2.1 of RFC 7518 - - o Parameter Name: "n" - o Parameter Description: Modulus - o Used with "kty" Value(s): "RSA" - o Parameter Information Class: Public - o Change Controller: IESG - o Specification Document(s): Section 6.3.1.1 of RFC 7518 - - o Parameter Name: "e" - o Parameter Description: Exponent - o Used with "kty" Value(s): "RSA" - o Parameter Information Class: Public - o Change Controller: IESG - o Specification Document(s): Section 6.3.1.2 of RFC 7518 - - - - - - - - -Jones Standards Track [Page 46] - -RFC 7518 JSON Web Algorithms (JWA) May 2015 - - - o Parameter Name: "d" - o Parameter Description: Private Exponent - o Used with "kty" Value(s): "RSA" - o Parameter Information Class: Private - o Change Controller: IESG - o Specification Document(s): Section 6.3.2.1 of RFC 7518 - - o Parameter Name: "p" - o Parameter Description: First Prime Factor - o Used with "kty" Value(s): "RSA" - o Parameter Information Class: Private - o Change Controller: IESG - o Specification Document(s): Section 6.3.2.2 of RFC 7518 - - o Parameter Name: "q" - o Parameter Description: Second Prime Factor - o Used with "kty" Value(s): "RSA" - o Parameter Information Class: Private - o Change Controller: IESG - o Specification Document(s): Section 6.3.2.3 of RFC 7518 - - o Parameter Name: "dp" - o Parameter Description: First Factor CRT Exponent - o Used with "kty" Value(s): "RSA" - o Parameter Information Class: Private - o Change Controller: IESG - o Specification Document(s): Section 6.3.2.4 of RFC 7518 - - o Parameter Name: "dq" - o Parameter Description: Second Factor CRT Exponent - o Used with "kty" Value(s): "RSA" - o Parameter Information Class: Private - o Change Controller: IESG - o Specification Document(s): Section 6.3.2.5 of RFC 7518 - - o Parameter Name: "qi" - o Parameter Description: First CRT Coefficient - o Used with "kty" Value(s): "RSA" - o Parameter Information Class: Private - o Change Controller: IESG - o Specification Document(s): Section 6.3.2.6 of RFC 7518 - - - - - - - - - - -Jones Standards Track [Page 47] - -RFC 7518 JSON Web Algorithms (JWA) May 2015 - - - o Parameter Name: "oth" - o Parameter Description: Other Primes Info - o Used with "kty" Value(s): "RSA" - o Parameter Information Class: Private - o Change Controller: IESG - o Specification Document(s): Section 6.3.2.7 of RFC 7518 - - o Parameter Name: "k" - o Parameter Description: Key Value - o Used with "kty" Value(s): "oct" - o Parameter Information Class: Private - o Change Controller: IESG - o Specification Document(s): Section 6.4.1 of RFC 7518 - -7.6. JSON Web Key Elliptic Curve Registry - - This section establishes the IANA "JSON Web Key Elliptic Curve" - registry for JWK "crv" member values. The registry records the curve - name, implementation requirements, and a reference to the - specification that defines it. This specification registers the - parameter names defined in Section 6.2.1.1. - - The implementation requirements of a curve may be changed over time - as the cryptographic landscape evolves, for instance, to change the - status of a curve to Deprecated or to change the status of a curve - from Optional to Recommended+ or Required. Changes of implementation - requirements are only permitted on a Specification Required basis - after review by the Designated Experts, with the new specification - defining the revised implementation requirements level. - -7.6.1. Registration Template - - Curve Name: - The name requested (e.g., "P-256"). Because a core goal of this - specification is for the resulting representations to be compact, - it is RECOMMENDED that the name be short -- not to exceed 8 - characters without a compelling reason to do so. This name is - case sensitive. Names may not match other registered names in a - case-insensitive manner unless the Designated Experts state that - there is a compelling reason to allow an exception. - - Curve Description: - Brief description of the curve (e.g., "P-256 Curve"). - - JOSE Implementation Requirements: - The curve implementation requirements for JWS and JWE, which must - be one the words Required, Recommended, Optional, Deprecated, or - Prohibited. Optionally, the word can be followed by a "+" or "-". - - - -Jones Standards Track [Page 48] - -RFC 7518 JSON Web Algorithms (JWA) May 2015 - - - The use of "+" indicates that the requirement strength is likely - to be increased in a future version of the specification. The use - of "-" indicates that the requirement strength is likely to be - decreased in a future version of the specification. - - Change Controller: - For Standards Track RFCs, list "IESG". For others, give the name - of the responsible party. Other details (e.g., postal address, - email address, home page URI) may also be included. - - Specification Document(s): - Reference to the document or documents that specify the parameter, - preferably including URIs that can be used to retrieve copies of - the documents. An indication of the relevant sections may also be - included but is not required. - -7.6.2. Initial Registry Contents - - o Curve Name: "P-256" - o Curve Description: P-256 Curve - o JOSE Implementation Requirements: Recommended+ - o Change Controller: IESG - o Specification Document(s): Section 6.2.1.1 of RFC 7518 - - o Curve Name: "P-384" - o Curve Description: P-384 Curve - o JOSE Implementation Requirements: Optional - o Change Controller: IESG - o Specification Document(s): Section 6.2.1.1 of RFC 7518 - - o Curve Name: "P-521" - o Curve Description: P-521 Curve - o JOSE Implementation Requirements: Optional - o Change Controller: IESG - o Specification Document(s): Section 6.2.1.1 of RFC 7518 - -8. 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 and employing countermeasures to various attacks. - - The security considerations in [AES], [DSS], [JWE], [JWK], [JWS], - [NIST.800-38D], [NIST.800-56A], [NIST.800-107], [RFC2104], [RFC3394], - [RFC3447], [RFC5116], [RFC6090], and [SHS] apply to this - specification. - - - - -Jones Standards Track [Page 49] - -RFC 7518 JSON Web Algorithms (JWA) May 2015 - - -8.1. Cryptographic Agility - - Implementers should be aware that cryptographic algorithms become - weaker with time. As new cryptanalysis techniques are developed and - computing performance improves, the work factor to break a particular - cryptographic algorithm will be reduced. Therefore, implementers and - deployments must be prepared for the set of algorithms that are - supported and used to change over time. Thus, cryptographic - algorithm implementations should be modular, allowing new algorithms - to be readily inserted. - -8.2. Key Lifetimes - - Many algorithms have associated security considerations related to - key lifetimes and/or the number of times that a key may be used. - Those security considerations continue to apply when using those - algorithms with JOSE data structures. See NIST SP 800-57 - [NIST.800-57] for specific guidance on key lifetimes. - -8.3. RSAES-PKCS1-v1_5 Security Considerations - - While Section 8 of RFC 3447 [RFC3447] explicitly calls for people not - to adopt RSASSA-PKCS1-v1_5 for new applications and instead requests - that people transition to RSASSA-PSS, this specification does include - RSASSA-PKCS1-v1_5, for interoperability reasons, because it is - commonly implemented. - - Keys used with RSAES-PKCS1-v1_5 must follow the constraints in - Section 7.2 of RFC 3447. Also, keys with a low public key exponent - value, as described in Section 3 of "Twenty Years of Attacks on the - RSA Cryptosystem" [Boneh99], must not be used. - -8.4. AES GCM Security Considerations - - Keys used with AES GCM must follow the constraints in Section 8.3 of - [NIST.800-38D], which states: "The total number of invocations of the - authenticated encryption function shall not exceed 2^32, including - all IV lengths and all instances of the authenticated encryption - function with the given key". In accordance with this rule, AES GCM - MUST NOT be used with the same key value more than 2^32 times. - - An IV value MUST NOT ever be used multiple times with the same AES - GCM key. One way to prevent this is to store a counter with the key - and increment it with every use. The counter can also be used to - prevent exceeding the 2^32 limit above. - - This security consideration does not apply to the composite AES-CBC - HMAC SHA-2 or AES Key Wrap algorithms. - - - -Jones Standards Track [Page 50] - -RFC 7518 JSON Web Algorithms (JWA) May 2015 - - -8.5. Unsecured JWS Security Considerations - - Unsecured JWSs (JWSs that use the "alg" value "none") provide no - integrity protection. Thus, they must only be used in contexts in - which the payload is secured by means other than a digital signature - or MAC value, or they need not be secured. - - An example means of preventing accepting Unsecured JWSs by default is - for the "verify" method of a hypothetical JWS software library to - have a Boolean "acceptUnsecured" parameter that indicates "none" is - an acceptable "alg" value. As another example, the "verify" method - might take a list of algorithms that are acceptable to the - application as a parameter and would reject Unsecured JWS values if - "none" is not in that list. - - The following example illustrates the reasons for not accepting - Unsecured JWSs at a global level. Suppose an application accepts - JWSs over two channels, (1) HTTP and (2) HTTPS with client - authentication. It requires a JWS Signature on objects received over - HTTP, but accepts Unsecured JWSs over HTTPS. If the application were - to globally indicate that "none" is acceptable, then an attacker - could provide it with an Unsecured JWS over HTTP and still have that - object successfully validate. Instead, the application needs to - indicate acceptance of "none" for each object received over HTTPS - (e.g., by setting "acceptUnsecured" to "true" for the first - hypothetical JWS software library above), but not for each object - received over HTTP. - -8.6. Denial-of-Service Attacks - - Receiving agents that validate signatures and sending agents that - encrypt messages need to be cautious of cryptographic processing - usage when validating signatures and encrypting messages using keys - larger than those mandated in this specification. An attacker could - supply content using keys that would result in excessive - cryptographic processing, for example, keys larger than those - mandated in this specification. Implementations should set and - enforce upper limits on the key sizes they accept. Section 5.6.1 - (Comparable Algorithm Strengths) of NIST SP 800-57 [NIST.800-57] - contains statements on largest approved key sizes that may be - applicable. - -8.7. Reusing Key Material when Encrypting Keys - - It is NOT RECOMMENDED to reuse the same entire set of key material - (Key Encryption Key, Content Encryption Key, Initialization Vector, - etc.) to encrypt multiple JWK or JWK Set objects, or to encrypt the - same JWK or JWK Set object multiple times. One suggestion for - - - -Jones Standards Track [Page 51] - -RFC 7518 JSON Web Algorithms (JWA) May 2015 - - - preventing reuse is to always generate at least one new piece of key - material for each encryption operation (e.g., a new Content - Encryption Key, a new IV, and/or a new PBES2 Salt), based on the - considerations noted in this document as well as from RFC 4086 - [RFC4086]. - -8.8. Password Considerations - - Passwords are vulnerable to a number of attacks. To help mitigate - some of these limitations, this document applies principles from RFC - 2898 [RFC2898] to derive cryptographic keys from user-supplied - passwords. - - However, the strength of the password still has a significant impact. - A high-entropy password has greater resistance to dictionary attacks. - [NIST.800-63-2] contains guidelines for estimating password entropy, - which can help applications and users generate stronger passwords. - - An ideal password is one that is as large as (or larger than) the - derived key length. However, passwords larger than a certain - algorithm-specific size are first hashed, which reduces an attacker's - effective search space to the length of the hash algorithm. It is - RECOMMENDED that a password used for "PBES2-HS256+A128KW" be no - shorter than 16 octets and no longer than 128 octets and a password - used for "PBES2-HS512+A256KW" be no shorter than 32 octets and no - longer than 128 octets long. - - Still, care needs to be taken in where and how password-based - encryption is used. These algorithms can still be susceptible to - dictionary-based attacks if the iteration count is too small; this is - of particular concern if these algorithms are used to protect data - that an attacker can have indefinite number of attempts to circumvent - the protection, such as protected data stored on a file system. - -8.9. Key Entropy and Random Values - - See Section 10.1 of [JWS] for security considerations on key entropy - and random values. - -8.10. Differences between Digital Signatures and MACs - - See Section 10.5 of [JWS] for security considerations on differences - between digital signatures and MACs. - - - - - - - - -Jones Standards Track [Page 52] - -RFC 7518 JSON Web Algorithms (JWA) May 2015 - - -8.11. Using Matching Algorithm Strengths - - See Section 11.3 of [JWE] for security considerations on using - matching algorithm strengths. - -8.12. Adaptive Chosen-Ciphertext Attacks - - See Section 11.4 of [JWE] for security considerations on adaptive - chosen-ciphertext attacks. - -8.13. Timing Attacks - - See Section 10.9 of [JWS] and Section 11.5 of [JWE] for security - considerations on timing attacks. - -8.14. RSA Private Key Representations and Blinding - - See Section 9.3 of [JWK] for security considerations on RSA private - key representations and blinding. - -9. Internationalization Considerations - - Passwords obtained from users are likely to require preparation and - normalization to account for differences of octet sequences generated - by different input devices, locales, etc. It is RECOMMENDED that - applications perform the steps outlined in [PRECIS] to prepare a - password supplied directly by a user before performing key derivation - and encryption. - -10. References - -10.1. Normative References - - [AES] National Institute of Standards and Technology (NIST), - "Advanced Encryption Standard (AES)", FIPS PUB 197, - November 2001, . - - [Boneh99] "Twenty Years of Attacks on the RSA Cryptosystem", Notices - of the American Mathematical Society (AMS), Vol. 46, - No. 2, pp. 203-213, 1999, . - - - - - - - - - -Jones Standards Track [Page 53] - -RFC 7518 JSON Web Algorithms (JWA) May 2015 - - - [DSS] National Institute of Standards and Technology (NIST), - "Digital Signature Standard (DSS)", FIPS PUB 186-4, July - 2013, . - - [JWE] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", - RFC 7516, DOI 10.17487/RFC7516, May 2015, - . - - [JWK] Jones, M., "JSON Web Key (JWK)", RFC 7517, - DOI 10.17487/RFC7517, May 2015, - . - - [JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web - Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May - 2015, . - - [NIST.800-38A] - National Institute of Standards and Technology (NIST), - "Recommendation for Block Cipher Modes of Operation", NIST - Special Publication 800-38A, December 2001, - . - - [NIST.800-38D] - National Institute of Standards and Technology (NIST), - "Recommendation for Block Cipher Modes of Operation: - Galois/Counter Mode (GCM) and GMAC", NIST Special - Publication 800-38D, December 2001, - . - - [NIST.800-56A] - National Institute of Standards and Technology (NIST), - "Recommendation for Pair-Wise Key Establishment Schemes - Using Discrete Logarithm Cryptography", NIST Special - Publication 800-56A, Revision 2, May 2013, - . - - [NIST.800-57] - National Institute of Standards and Technology (NIST), - "Recommendation for Key Management - Part 1: General - (Revision 3)", NIST Special Publication 800-57, Part 1, - Revision 3, July 2012, . - - - - - -Jones Standards Track [Page 54] - -RFC 7518 JSON Web Algorithms (JWA) May 2015 - - - [RFC20] Cerf, V., "ASCII format for Network Interchange", STD 80, - RFC 20, DOI 10.17487/RFC0020, October 1969, - . - - [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: - Keyed-Hashing for Message Authentication", RFC 2104, - DOI 10.17487/RFC2104, February 1997, - . - - [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate - Requirement Levels", BCP 14, RFC 2119, - DOI 10.17487/RFC2119, March 1997, - . - - [RFC2898] Kaliski, B., "PKCS #5: Password-Based Cryptography - Specification Version 2.0", RFC 2898, - DOI 10.17487/RFC2898, September 2000, - . - - [RFC3394] Schaad, J. and R. Housley, "Advanced Encryption Standard - (AES) Key Wrap Algorithm", RFC 3394, DOI 10.17487/RFC3394, - September 2002, . - - [RFC3447] Jonsson, J. and B. Kaliski, "Public-Key Cryptography - Standards (PKCS) #1: RSA Cryptography Specifications - Version 2.1", RFC 3447, DOI 10.17487/RFC3447, February - 2003, . - - [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO - 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November - 2003, . - - [RFC4868] Kelly, S. and S. Frankel, "Using HMAC-SHA-256, - HMAC-SHA-384, and HMAC-SHA-512 with IPsec", RFC 4868, - DOI 10.17487/RFC4868, May 2007, - . - - [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", - FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007, - . - - [RFC5652] Housley, R., "Cryptographic Message Syntax (CMS)", STD 70, - RFC 5652, DOI 10.17487/RFC5652, September 2009, - . - - - - - - - -Jones Standards Track [Page 55] - -RFC 7518 JSON Web Algorithms (JWA) May 2015 - - - [RFC6090] McGrew, D., Igoe, K., and M. Salter, "Fundamental Elliptic - Curve Cryptography Algorithms", RFC 6090, - DOI 10.17487/RFC6090, February 2011, - . - - [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data - Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March - 2014, . - - [SEC1] Standards for Efficient Cryptography Group, "SEC 1: - Elliptic Curve Cryptography", Version 2.0, May 2009, - . - - [SHS] National Institute of Standards and Technology (NIST), - "Secure Hash Standard (SHS)", FIPS PUB 180-4, March 2012, - . - - [UNICODE] The Unicode Consortium, "The Unicode Standard", - . - -10.2. Informative References - - [AEAD-CBC-SHA] - McGrew, D., Foley, J., and K. Paterson, "Authenticated - Encryption with AES-CBC and HMAC-SHA", Work in Progress, - draft-mcgrew-aead-aes-cbc-hmac-sha2-05, July 2014. - - [CanvasApp] - Facebook, "Canvas Applications", 2010, - . - - [JCA] Oracle, "Java Cryptography Architecture (JCA) Reference - Guide", 2014, . - - [JSE] Bradley, J. and N. Sakimura (editor), "JSON Simple - Encryption", September 2010, - . - - [JSMS] Rescorla, E. and J. Hildebrand, "JavaScript Message - Security Format", Work in Progress, - draft-rescorla-jsms-00, March 2011. - - [JSS] Bradley, J. and N. Sakimura, Ed., "JSON Simple Sign 1.0", - Draft 01, September 2010, . - - - - -Jones Standards Track [Page 56] - -RFC 7518 JSON Web Algorithms (JWA) May 2015 - - - [JWE-JWK] Miller, M., "Using JavaScript Object Notation (JSON) Web - Encryption (JWE) for Protecting JSON Web Key (JWK) - Objects", Work in Progress, - draft-miller-jose-jwe-protected-jwk-02, June 2013. - - [MagicSignatures] - Panzer, J., Ed., Laurie, B., and D. Balfanz, "Magic - Signatures", January 2011, - . - - [NIST.800-107] - National Institute of Standards and Technology (NIST), - "Recommendation for Applications Using Approved Hash - Algorithms", NIST Special Publication 800-107, Revision 1, - August 2012, . - - [NIST.800-63-2] - National Institute of Standards and Technology (NIST), - "Electronic Authentication Guideline", NIST Special - Publication 800-63-2, August 2013, - . - - [PRECIS] Saint-Andre, P. and A. Melnikov, "Preparation, - Enforcement, and Comparison of Internationalized Strings - Representing Usernames and Passwords", Work in Progress, - draft-ietf-precis-saslprepbis-16, April 2015. - - [RFC2631] Rescorla, E., "Diffie-Hellman Key Agreement Method", - RFC 2631, DOI 10.17487/RFC2631, June 1999, - . - - [RFC3275] Eastlake 3rd, D., Reagle, J., and D. Solo, "(Extensible - Markup Language) XML-Signature Syntax and Processing", - RFC 3275, DOI 10.17487/RFC3275, March 2002, - . - - [RFC4086] Eastlake 3rd, D., Schiller, J., and S. Crocker, - "Randomness Requirements for Security", BCP 106, RFC 4086, - DOI 10.17487/RFC4086, June 2005, - . - - [RFC5116] McGrew, D., "An Interface and Algorithms for Authenticated - Encryption", RFC 5116, DOI 10.17487/RFC5116, January 2008, - . - - - - -Jones Standards Track [Page 57] - -RFC 7518 JSON Web Algorithms (JWA) May 2015 - - - [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an - IANA Considerations Section in RFCs", BCP 26, RFC 5226, - DOI 10.17487/RFC5226, May 2008, - . - - [W3C.NOTE-xmldsig-core2-20130411] - Eastlake, D., Reagle, J., Solo, D., Hirsch, F., Roessler, - T., Yiu, K., Datta, P., and S. Cantor, "XML Signature - Syntax and Processing Version 2.0", World Wide Web - Consortium Note NOTE-xmldsig-core2-20130411, April 2013, - . - - [W3C.REC-xmlenc-core-20021210] - Eastlake, D. and J. Reagle, "XML Encryption Syntax and - Processing", World Wide Web Consortium Recommendation REC- - xmlenc-core-20021210, December 2002, - . - - [W3C.REC-xmlenc-core1-20130411] - Eastlake, D., Reagle, J., Hirsch, F., and T. Roessler, - "XML Encryption Syntax and Processing Version 1.1", World - Wide Web Consortium Recommendation REC-xmlenc- - core1-20130411, April 2013, - . - - - - - - - - - - - - - - - - - - - - - - - - - - - -Jones Standards Track [Page 58] - -RFC 7518 JSON Web Algorithms (JWA) May 2015 - - -Appendix A. Algorithm Identifier Cross-Reference - - This appendix contains tables cross-referencing the cryptographic - algorithm identifier values defined in this specification with the - equivalent identifiers used by other standards and software packages. - See XML DSIG [RFC3275], XML DSIG 2.0 - [W3C.NOTE-xmldsig-core2-20130411], XML Encryption - [W3C.REC-xmlenc-core-20021210], XML Encryption 1.1 - [W3C.REC-xmlenc-core1-20130411], and Java Cryptography Architecture - [JCA] for more information about the names defined by those - documents. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Jones Standards Track [Page 59] - -RFC 7518 JSON Web Algorithms (JWA) May 2015 - - -A.1. Digital Signature/MAC Algorithm Identifier Cross-Reference - - This section contains a table cross-referencing the JWS digital - signature and MAC "alg" (algorithm) values defined in this - specification with the equivalent identifiers used by other standards - and software packages. - - +-------------------------------------------------------------------+ - | JWS | XML DSIG | - | | JCA | OID | - +-------------------------------------------------------------------+ - | HS256 | http://www.w3.org/2001/04/xmldsig-more#hmac-sha256 | - | | HmacSHA256 | 1.2.840.113549.2.9 | - +-------------------------------------------------------------------+ - | HS384 | http://www.w3.org/2001/04/xmldsig-more#hmac-sha384 | - | | HmacSHA384 | 1.2.840.113549.2.10 | - +-------------------------------------------------------------------+ - | HS512 | http://www.w3.org/2001/04/xmldsig-more#hmac-sha512 | - | | HmacSHA512 | 1.2.840.113549.2.11 | - +-------------------------------------------------------------------+ - | RS256 | http://www.w3.org/2001/04/xmldsig-more#rsa-sha256 | - | | SHA256withRSA | 1.2.840.113549.1.1.11 | - +-------------------------------------------------------------------+ - | RS384 | http://www.w3.org/2001/04/xmldsig-more#rsa-sha384 | - | | SHA384withRSA | 1.2.840.113549.1.1.12 | - +-------------------------------------------------------------------+ - | RS512 | http://www.w3.org/2001/04/xmldsig-more#rsa-sha512 | - | | SHA512withRSA | 1.2.840.113549.1.1.13 | - +-------------------------------------------------------------------+ - | ES256 | http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha256 | - | | SHA256withECDSA | 1.2.840.10045.4.3.2 | - +-------------------------------------------------------------------+ - | ES384 | http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha384 | - | | SHA384withECDSA | 1.2.840.10045.4.3.3 | - +-------------------------------------------------------------------+ - | ES512 | http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha512 | - | | SHA512withECDSA | 1.2.840.10045.4.3.4 | - +-------------------------------------------------------------------+ - | PS256 | http://www.w3.org/2007/05/xmldsig-more#sha256-rsa-MGF1 | - | | SHA256withRSAandMGF1 | 1.2.840.113549.1.1.10 | - +-------------------------------------------------------------------+ - | PS384 | http://www.w3.org/2007/05/xmldsig-more#sha384-rsa-MGF1 | - | | SHA384withRSAandMGF1 | 1.2.840.113549.1.1.10 | - +-------------------------------------------------------------------+ - | PS512 | http://www.w3.org/2007/05/xmldsig-more#sha512-rsa-MGF1 | - | | SHA512withRSAandMGF1 | 1.2.840.113549.1.1.10 | - +-------------------------------------------------------------------+ - - - - -Jones Standards Track [Page 60] - -RFC 7518 JSON Web Algorithms (JWA) May 2015 - - -A.2. Key Management Algorithm Identifier Cross-Reference - - This section contains a table cross-referencing the JWE "alg" - (algorithm) values defined in this specification with the equivalent - identifiers used by other standards and software packages. - - +-------------------------------------------------------------------+ - | JWE | XML ENC | - | | JCA | OID | - +-------------------------------------------------------------------+ - | RSA1_5 | http://www.w3.org/2001/04/xmlenc#rsa-1_5 | - | | RSA/ECB/PKCS1Padding | 1.2.840.113549.1.1.1 | - +-------------------------------------------------------------------+ - | RSA-OAEP | http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p | - | | RSA/ECB/OAEPWithSHA-1AndMGF1Padding | 1.2.840.113549.1.1.7 | - +-------------------------------------------------------------------+ - | RSA-OAEP-256 | http://www.w3.org/2009/xmlenc11#rsa-oaep | - | | & http://www.w3.org/2009/xmlenc11#mgf1sha256 | - | | RSA/ECB/OAEPWithSHA-256AndMGF1Padding | | - | | & MGF1ParameterSpec.SHA256 | 1.2.840.113549.1.1.7 | - +-------------------------------------------------------------------+ - | ECDH-ES | http://www.w3.org/2009/xmlenc11#ECDH-ES | - | | ECDH | 1.3.132.1.12 | - +-------------------------------------------------------------------+ - | A128KW | http://www.w3.org/2001/04/xmlenc#kw-aes128 | - | | AESWrap | 2.16.840.1.101.3.4.1.5 | - +-------------------------------------------------------------------+ - | A192KW | http://www.w3.org/2001/04/xmlenc#kw-aes192 | - | | AESWrap | 2.16.840.1.101.3.4.1.25 | - +-------------------------------------------------------------------+ - | A256KW | http://www.w3.org/2001/04/xmlenc#kw-aes256 | - | | AESWrap | 2.16.840.1.101.3.4.1.45 | - +-------------------------------------------------------------------+ - - - - - - - - - - - - - - - - - - -Jones Standards Track [Page 61] - -RFC 7518 JSON Web Algorithms (JWA) May 2015 - - -A.3. Content Encryption Algorithm Identifier Cross-Reference - - This section contains a table cross-referencing the JWE "enc" - (encryption algorithm) values defined in this specification with the - equivalent identifiers used by other standards and software packages. - - For the composite algorithms "A128CBC-HS256", "A192CBC-HS384", and - "A256CBC-HS512", the corresponding AES-CBC algorithm identifiers are - listed. - - +-------------------------------------------------------------------+ - | JWE | XML ENC | - | | JCA | OID | - +-------------------------------------------------------------------+ - | A128CBC-HS256 | http://www.w3.org/2001/04/xmlenc#aes128-cbc | - | | AES/CBC/PKCS5Padding | 2.16.840.1.101.3.4.1.2 | - +-------------------------------------------------------------------+ - | A192CBC-HS384 | http://www.w3.org/2001/04/xmlenc#aes192-cbc | - | | AES/CBC/PKCS5Padding | 2.16.840.1.101.3.4.1.22 | - +-------------------------------------------------------------------+ - | A256CBC-HS512 | http://www.w3.org/2001/04/xmlenc#aes256-cbc | - | | AES/CBC/PKCS5Padding | 2.16.840.1.101.3.4.1.42 | - +-------------------------------------------------------------------+ - | A128GCM | http://www.w3.org/2009/xmlenc11#aes128-gcm | - | | AES/GCM/NoPadding | 2.16.840.1.101.3.4.1.6 | - +-------------------------------------------------------------------+ - | A192GCM | http://www.w3.org/2009/xmlenc11#aes192-gcm | - | | AES/GCM/NoPadding | 2.16.840.1.101.3.4.1.26 | - +-------------------------------------------------------------------+ - | A256GCM | http://www.w3.org/2009/xmlenc11#aes256-gcm | - | | AES/GCM/NoPadding | 2.16.840.1.101.3.4.1.46 | - +-------------------------------------------------------------------+ - -Appendix B. Test Cases for AES_CBC_HMAC_SHA2 Algorithms - - The following test cases can be used to validate implementations of - the AES_CBC_HMAC_SHA2 algorithms defined in Section 5.2. They are - also intended to correspond to test cases that may appear in a future - version of [AEAD-CBC-SHA], demonstrating that the cryptographic - computations performed are the same. - - The variable names are those defined in Section 5.2. All values are - hexadecimal. - - - - - - - - -Jones Standards Track [Page 62] - -RFC 7518 JSON Web Algorithms (JWA) May 2015 - - -B.1. Test Cases for AES_128_CBC_HMAC_SHA_256 - - AES_128_CBC_HMAC_SHA_256 - - K = 00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f - 10 11 12 13 14 15 16 17 18 19 1a 1b 1c 1d 1e 1f - - MAC_KEY = 00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f - - ENC_KEY = 10 11 12 13 14 15 16 17 18 19 1a 1b 1c 1d 1e 1f - - P = 41 20 63 69 70 68 65 72 20 73 79 73 74 65 6d 20 - 6d 75 73 74 20 6e 6f 74 20 62 65 20 72 65 71 75 - 69 72 65 64 20 74 6f 20 62 65 20 73 65 63 72 65 - 74 2c 20 61 6e 64 20 69 74 20 6d 75 73 74 20 62 - 65 20 61 62 6c 65 20 74 6f 20 66 61 6c 6c 20 69 - 6e 74 6f 20 74 68 65 20 68 61 6e 64 73 20 6f 66 - 20 74 68 65 20 65 6e 65 6d 79 20 77 69 74 68 6f - 75 74 20 69 6e 63 6f 6e 76 65 6e 69 65 6e 63 65 - - IV = 1a f3 8c 2d c2 b9 6f fd d8 66 94 09 23 41 bc 04 - - A = 54 68 65 20 73 65 63 6f 6e 64 20 70 72 69 6e 63 - 69 70 6c 65 20 6f 66 20 41 75 67 75 73 74 65 20 - 4b 65 72 63 6b 68 6f 66 66 73 - - AL = 00 00 00 00 00 00 01 50 - - E = c8 0e df a3 2d df 39 d5 ef 00 c0 b4 68 83 42 79 - a2 e4 6a 1b 80 49 f7 92 f7 6b fe 54 b9 03 a9 c9 - a9 4a c9 b4 7a d2 65 5c 5f 10 f9 ae f7 14 27 e2 - fc 6f 9b 3f 39 9a 22 14 89 f1 63 62 c7 03 23 36 - 09 d4 5a c6 98 64 e3 32 1c f8 29 35 ac 40 96 c8 - 6e 13 33 14 c5 40 19 e8 ca 79 80 df a4 b9 cf 1b - 38 4c 48 6f 3a 54 c5 10 78 15 8e e5 d7 9d e5 9f - bd 34 d8 48 b3 d6 95 50 a6 76 46 34 44 27 ad e5 - 4b 88 51 ff b5 98 f7 f8 00 74 b9 47 3c 82 e2 db - - M = 65 2c 3f a3 6b 0a 7c 5b 32 19 fa b3 a3 0b c1 c4 - e6 e5 45 82 47 65 15 f0 ad 9f 75 a2 b7 1c 73 ef - - T = 65 2c 3f a3 6b 0a 7c 5b 32 19 fa b3 a3 0b c1 c4 - - - - - - - - - -Jones Standards Track [Page 63] - -RFC 7518 JSON Web Algorithms (JWA) May 2015 - - -B.2. Test Cases for AES_192_CBC_HMAC_SHA_384 - - K = 00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f - 10 11 12 13 14 15 16 17 18 19 1a 1b 1c 1d 1e 1f - 20 21 22 23 24 25 26 27 28 29 2a 2b 2c 2d 2e 2f - - MAC_KEY = 00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f - 10 11 12 13 14 15 16 17 - - ENC_KEY = 18 19 1a 1b 1c 1d 1e 1f 20 21 22 23 24 25 26 27 - 28 29 2a 2b 2c 2d 2e 2f - - P = 41 20 63 69 70 68 65 72 20 73 79 73 74 65 6d 20 - 6d 75 73 74 20 6e 6f 74 20 62 65 20 72 65 71 75 - 69 72 65 64 20 74 6f 20 62 65 20 73 65 63 72 65 - 74 2c 20 61 6e 64 20 69 74 20 6d 75 73 74 20 62 - 65 20 61 62 6c 65 20 74 6f 20 66 61 6c 6c 20 69 - 6e 74 6f 20 74 68 65 20 68 61 6e 64 73 20 6f 66 - 20 74 68 65 20 65 6e 65 6d 79 20 77 69 74 68 6f - 75 74 20 69 6e 63 6f 6e 76 65 6e 69 65 6e 63 65 - - IV = 1a f3 8c 2d c2 b9 6f fd d8 66 94 09 23 41 bc 04 - - A = 54 68 65 20 73 65 63 6f 6e 64 20 70 72 69 6e 63 - 69 70 6c 65 20 6f 66 20 41 75 67 75 73 74 65 20 - 4b 65 72 63 6b 68 6f 66 66 73 - - AL = 00 00 00 00 00 00 01 50 - - E = ea 65 da 6b 59 e6 1e db 41 9b e6 2d 19 71 2a e5 - d3 03 ee b5 00 52 d0 df d6 69 7f 77 22 4c 8e db - 00 0d 27 9b dc 14 c1 07 26 54 bd 30 94 42 30 c6 - 57 be d4 ca 0c 9f 4a 84 66 f2 2b 22 6d 17 46 21 - 4b f8 cf c2 40 0a dd 9f 51 26 e4 79 66 3f c9 0b - 3b ed 78 7a 2f 0f fc bf 39 04 be 2a 64 1d 5c 21 - 05 bf e5 91 ba e2 3b 1d 74 49 e5 32 ee f6 0a 9a - c8 bb 6c 6b 01 d3 5d 49 78 7b cd 57 ef 48 49 27 - f2 80 ad c9 1a c0 c4 e7 9c 7b 11 ef c6 00 54 e3 - - M = 84 90 ac 0e 58 94 9b fe 51 87 5d 73 3f 93 ac 20 - 75 16 80 39 cc c7 33 d7 45 94 f8 86 b3 fa af d4 - 86 f2 5c 71 31 e3 28 1e 36 c7 a2 d1 30 af de 57 - - T = 84 90 ac 0e 58 94 9b fe 51 87 5d 73 3f 93 ac 20 - 75 16 80 39 cc c7 33 d7 - - - - - - -Jones Standards Track [Page 64] - -RFC 7518 JSON Web Algorithms (JWA) May 2015 - - -B.3. Test Cases for AES_256_CBC_HMAC_SHA_512 - - K = 00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f - 10 11 12 13 14 15 16 17 18 19 1a 1b 1c 1d 1e 1f - 20 21 22 23 24 25 26 27 28 29 2a 2b 2c 2d 2e 2f - 30 31 32 33 34 35 36 37 38 39 3a 3b 3c 3d 3e 3f - - MAC_KEY = 00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f - 10 11 12 13 14 15 16 17 18 19 1a 1b 1c 1d 1e 1f - - ENC_KEY = 20 21 22 23 24 25 26 27 28 29 2a 2b 2c 2d 2e 2f - 30 31 32 33 34 35 36 37 38 39 3a 3b 3c 3d 3e 3f - - P = 41 20 63 69 70 68 65 72 20 73 79 73 74 65 6d 20 - 6d 75 73 74 20 6e 6f 74 20 62 65 20 72 65 71 75 - 69 72 65 64 20 74 6f 20 62 65 20 73 65 63 72 65 - 74 2c 20 61 6e 64 20 69 74 20 6d 75 73 74 20 62 - 65 20 61 62 6c 65 20 74 6f 20 66 61 6c 6c 20 69 - 6e 74 6f 20 74 68 65 20 68 61 6e 64 73 20 6f 66 - 20 74 68 65 20 65 6e 65 6d 79 20 77 69 74 68 6f - 75 74 20 69 6e 63 6f 6e 76 65 6e 69 65 6e 63 65 - - IV = 1a f3 8c 2d c2 b9 6f fd d8 66 94 09 23 41 bc 04 - - A = 54 68 65 20 73 65 63 6f 6e 64 20 70 72 69 6e 63 - 69 70 6c 65 20 6f 66 20 41 75 67 75 73 74 65 20 - 4b 65 72 63 6b 68 6f 66 66 73 - - AL = 00 00 00 00 00 00 01 50 - - E = 4a ff aa ad b7 8c 31 c5 da 4b 1b 59 0d 10 ff bd - 3d d8 d5 d3 02 42 35 26 91 2d a0 37 ec bc c7 bd - 82 2c 30 1d d6 7c 37 3b cc b5 84 ad 3e 92 79 c2 - e6 d1 2a 13 74 b7 7f 07 75 53 df 82 94 10 44 6b - 36 eb d9 70 66 29 6a e6 42 7e a7 5c 2e 08 46 a1 - 1a 09 cc f5 37 0d c8 0b fe cb ad 28 c7 3f 09 b3 - a3 b7 5e 66 2a 25 94 41 0a e4 96 b2 e2 e6 60 9e - 31 e6 e0 2c c8 37 f0 53 d2 1f 37 ff 4f 51 95 0b - be 26 38 d0 9d d7 a4 93 09 30 80 6d 07 03 b1 f6 - - M = 4d d3 b4 c0 88 a7 f4 5c 21 68 39 64 5b 20 12 bf - 2e 62 69 a8 c5 6a 81 6d bc 1b 26 77 61 95 5b c5 - fd 30 a5 65 c6 16 ff b2 f3 64 ba ec e6 8f c4 07 - 53 bc fc 02 5d de 36 93 75 4a a1 f5 c3 37 3b 9c - - T = 4d d3 b4 c0 88 a7 f4 5c 21 68 39 64 5b 20 12 bf - 2e 62 69 a8 c5 6a 81 6d bc 1b 26 77 61 95 5b c5 - - - - -Jones Standards Track [Page 65] - -RFC 7518 JSON Web Algorithms (JWA) May 2015 - - -Appendix C. Example ECDH-ES Key Agreement Computation - - This example uses ECDH-ES Key Agreement and the Concat KDF to derive - the CEK in the manner described in Section 4.6. In this example, the - ECDH-ES Direct Key Agreement mode ("alg" value "ECDH-ES") is used to - produce an agreed-upon key for AES GCM with a 128-bit key ("enc" - value "A128GCM"). - - In this example, a producer Alice is encrypting content to a consumer - Bob. The producer (Alice) generates an ephemeral key for the key - agreement computation. Alice's ephemeral key (in JWK format) used - for the key agreement computation in this example (including the - private part) is: - - {"kty":"EC", - "crv":"P-256", - "x":"gI0GAILBdu7T53akrFmMyGcsF3n5dO7MmwNBHKW5SV0", - "y":"SLW_xSffzlPWrHEVI30DHM_4egVwt3NQqeUD7nMFpps", - "d":"0_NxaRPUMQoAJt50Gz8YiTr8gRTwyEaCumd-MToTmIo" - } - - The consumer's (Bob's) key (in JWK format) used for the key agreement - computation in this example (including the private part) is: - - {"kty":"EC", - "crv":"P-256", - "x":"weNJy2HscCSM6AEDTDg04biOvhFhyyWvOHQfeF_PxMQ", - "y":"e8lnCO-AlStT-NJVX-crhB7QRYhiix03illJOVAOyck", - "d":"VEmDZpDXXK8p8N0Cndsxs924q6nS1RXFASRl6BfUqdw" - } - - Header Parameter values used in this example are as follows. The - "apu" (agreement PartyUInfo) Header Parameter value is the base64url - encoding of the UTF-8 string "Alice" and the "apv" (agreement - PartyVInfo) Header Parameter value is the base64url encoding of the - UTF-8 string "Bob". The "epk" (ephemeral public key) Header - Parameter is used to communicate the producer's (Alice's) ephemeral - public key value to the consumer (Bob). - - - - - - - - - - - - - -Jones Standards Track [Page 66] - -RFC 7518 JSON Web Algorithms (JWA) May 2015 - - - {"alg":"ECDH-ES", - "enc":"A128GCM", - "apu":"QWxpY2U", - "apv":"Qm9i", - "epk": - {"kty":"EC", - "crv":"P-256", - "x":"gI0GAILBdu7T53akrFmMyGcsF3n5dO7MmwNBHKW5SV0", - "y":"SLW_xSffzlPWrHEVI30DHM_4egVwt3NQqeUD7nMFpps" - } - } - - The resulting Concat KDF [NIST.800-56A] parameter values are: - - Z - This is set to the ECDH-ES key agreement output. (This value is - often not directly exposed by libraries, due to NIST security - requirements, and only serves as an input to a KDF.) In this - example, Z is following the octet sequence (using JSON array - notation): - [158, 86, 217, 29, 129, 113, 53, 211, 114, 131, 66, 131, 191, 132, - 38, 156, 251, 49, 110, 163, 218, 128, 106, 72, 246, 218, 167, 121, - 140, 254, 144, 196]. - - keydatalen - This value is 128 - the number of bits in the desired output key - (because "A128GCM" uses a 128-bit key). - - AlgorithmID - This is set to the octets representing the 32-bit big-endian value - 7 - [0, 0, 0, 7] - the number of octets in the AlgorithmID content - "A128GCM", followed, by the octets representing the ASCII string - "A128GCM" - [65, 49, 50, 56, 71, 67, 77]. - - PartyUInfo - This is set to the octets representing the 32-bit big-endian value - 5 - [0, 0, 0, 5] - the number of octets in the PartyUInfo content - "Alice", followed, by the octets representing the UTF-8 string - "Alice" - [65, 108, 105, 99, 101]. - - PartyVInfo - This is set to the octets representing the 32-bit big-endian value - 3 - [0, 0, 0, 3] - the number of octets in the PartyUInfo content - "Bob", followed, by the octets representing the UTF-8 string "Bob" - - [66, 111, 98]. - - - - - - -Jones Standards Track [Page 67] - -RFC 7518 JSON Web Algorithms (JWA) May 2015 - - - SuppPubInfo - This is set to the octets representing the 32-bit big-endian value - 128 - [0, 0, 0, 128] - the keydatalen value. - - SuppPrivInfo - This is set to the empty octet sequence. - - Concatenating the parameters AlgorithmID through SuppPubInfo results - in an OtherInfo value of: - [0, 0, 0, 7, 65, 49, 50, 56, 71, 67, 77, 0, 0, 0, 5, 65, 108, 105, - 99, 101, 0, 0, 0, 3, 66, 111, 98, 0, 0, 0, 128] - - Concatenating the round number 1 ([0, 0, 0, 1]), Z, and the OtherInfo - value results in the Concat KDF round 1 hash input of: - [0, 0, 0, 1, - 158, 86, 217, 29, 129, 113, 53, 211, 114, 131, 66, 131, 191, 132, 38, - 156, 251, 49, 110, 163, 218, 128, 106, 72, 246, 218, 167, 121, 140, - 254, 144, 196, - 0, 0, 0, 7, 65, 49, 50, 56, 71, 67, 77, 0, 0, 0, 5, 65, 108, 105, 99, - 101, 0, 0, 0, 3, 66, 111, 98, 0, 0, 0, 128] - - The resulting derived key, which is the first 128 bits of the round 1 - hash output is: - [86, 170, 141, 234, 248, 35, 109, 32, 92, 34, 40, 205, 113, 167, 16, - 26] - - The base64url-encoded representation of this derived key is: - - VqqN6vgjbSBcIijNcacQGg - - - - - - - - - - - - - - - - - - - - - - -Jones Standards Track [Page 68] - -RFC 7518 JSON Web Algorithms (JWA) May 2015 - - -Acknowledgements - - Solutions for signing and encrypting JSON content were previously - explored by "Magic Signatures" [MagicSignatures], "JSON Simple Sign - 1.0" [JSS], "Canvas Applications" [CanvasApp], "JSON Simple - Encryption" [JSE], and "JavaScript Message Security Format" [JSMS], - all of which influenced this document. - - The "Authenticated Encryption with AES-CBC and HMAC-SHA" - [AEAD-CBC-SHA] specification, upon which the AES_CBC_HMAC_SHA2 - algorithms are based, was written by David A. McGrew and Kenny - Paterson. The test cases for AES_CBC_HMAC_SHA2 are based upon those - for [AEAD-CBC-SHA] by John Foley. - - Matt Miller wrote "Using JavaScript Object Notation (JSON) Web - Encryption (JWE) for Protecting JSON Web Key (JWK) Objects" - [JWE-JWK], upon which the password-based encryption content of this - document is based. - - This specification is the work of the JOSE working group, which - includes dozens of active and dedicated participants. In particular, - the following individuals contributed ideas, feedback, and wording - that influenced this specification: - - Dirk Balfanz, Richard Barnes, Carsten Bormann, John Bradley, Brian - Campbell, Alissa Cooper, Breno de Medeiros, Vladimir Dzhuvinov, Roni - Even, Stephen Farrell, Yaron Y. Goland, Dick Hardt, Joe Hildebrand, - Jeff Hodges, Edmund Jay, Charlie Kaufman, Barry Leiba, James Manger, - Matt Miller, Kathleen Moriarty, Tony Nadalin, Axel Nennker, John - Panzer, Emmanuel Raviart, Eric Rescorla, Pete Resnick, Nat Sakimura, - Jim Schaad, Hannes Tschofenig, and Sean 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. - -Author's Address - - Michael B. Jones - Microsoft - - EMail: mbj@microsoft.com - URI: http://self-issued.info/ - - - - - - - - -Jones Standards Track [Page 69] - diff --git a/rfc/rfc7638.txt b/rfc/rfc7638.txt deleted file mode 100644 index 7997207..0000000 --- a/rfc/rfc7638.txt +++ /dev/null @@ -1,731 +0,0 @@ - - - - - - -Internet Engineering Task Force (IETF) M. Jones -Request for Comments: 7638 Microsoft -Category: Standards Track N. Sakimura -ISSN: 2070-1721 Nomura Research Institute - September 2015 - - - JSON Web Key (JWK) Thumbprint - -Abstract - - This specification defines a method for computing a hash value over a - JSON Web Key (JWK). It defines which fields in a JWK are used in the - hash computation, the method of creating a canonical form for those - fields, and how to convert the resulting Unicode string into a byte - sequence to be hashed. The resulting hash value can be used for - identifying or selecting the key represented by the JWK that is the - subject of the thumbprint. - -Status of This Memo - - This is an Internet Standards Track document. - - This document is a product of the Internet Engineering Task Force - (IETF). It represents the consensus of the IETF community. It has - received public review and has been approved for publication by the - Internet Engineering Steering Group (IESG). Further information on - Internet Standards is available in Section 2 of RFC 5741. - - Information about the current status of this document, any errata, - and how to provide feedback on it may be obtained at - http://www.rfc-editor.org/info/rfc7638. - -Copyright Notice - - Copyright (c) 2015 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. - - - - -Jones & Sakimura Standards Track [Page 1] - -RFC 7638 JSON Web Key (JWK) Thumbprint September 2015 - - -Table of Contents - - 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 - 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 2 - 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 - 3. JSON Web Key (JWK) Thumbprint . . . . . . . . . . . . . . . . 3 - 3.1. Example JWK Thumbprint Computation . . . . . . . . . . . 4 - 3.2. JWK Members Used in the Thumbprint Computation . . . . . 6 - 3.2.1. JWK Thumbprint of a Private Key . . . . . . . . . . . 6 - 3.2.2. Why Not Include Optional Members? . . . . . . . . . . 7 - 3.3. Order and Representation of Members in Hash Input . . . . 7 - 3.4. Selection of Hash Function . . . . . . . . . . . . . . . 8 - 3.5. JWK Thumbprints of Keys Not in JWK Format . . . . . . . . 8 - 4. Practical JSON and Unicode Considerations . . . . . . . . . . 8 - 5. Relationship to Digests of X.509 Values . . . . . . . . . . . 9 - 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 - 7. Security Considerations . . . . . . . . . . . . . . . . . . . 10 - 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 11 - 8.1. Normative References . . . . . . . . . . . . . . . . . . 11 - 8.2. Informative References . . . . . . . . . . . . . . . . . 12 - Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 13 - Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 13 - -1. Introduction - - This specification defines a method for computing a hash value - (a.k.a. digest) over a JSON Web Key (JWK) [JWK]. It defines which - fields in a JWK are used in the hash computation, the method of - creating a canonical form for those fields, and how to convert the - resulting Unicode string into a byte sequence to be hashed. The - resulting hash value can be used for identifying or selecting the key - represented by the JWK that is the subject of the thumbprint, for - instance, by using the base64url-encoded JWK Thumbprint value as a - "kid" (key ID) value. - -1.1. Notational Conventions - - The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", - "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and - "OPTIONAL" in this document are to be interpreted as described in - "Key words for use in RFCs to Indicate Requirement Levels" [RFC2119]. - The interpretation should only be applied when the terms appear in - all capital letters. - - - - - - - - -Jones & Sakimura Standards Track [Page 2] - -RFC 7638 JSON Web Key (JWK) Thumbprint September 2015 - - -2. Terminology - - This specification uses the same terminology as the "JSON Web Key - (JWK)" [JWK], "JSON Web Signature (JWS)" [JWS], and "JSON Web - Algorithms (JWA)" [JWA] specifications. - - This term is defined by this specification: - - JWK Thumbprint - The digest value for a JWK. - -3. JSON Web Key (JWK) Thumbprint - - The thumbprint of a JSON Web Key (JWK) is computed as follows: - - 1. Construct a JSON object [RFC7159] containing only the required - members of a JWK representing the key and with no whitespace or - line breaks before or after any syntactic elements and with the - required members ordered lexicographically by the Unicode - [UNICODE] code points of the member names. (This JSON object is - itself a legal JWK representation of the key.) - - 2. Hash the octets of the UTF-8 representation of this JSON object - with a cryptographic hash function H. For example, SHA-256 [SHS] - might be used as H. See Section 3.4 for a discussion on the - choice of hash function. - - The resulting value is the JWK Thumbprint with H of the JWK. The - details of this computation are further described in subsequent - sections. - - - - - - - - - - - - - - - - - - - - - -Jones & Sakimura Standards Track [Page 3] - -RFC 7638 JSON Web Key (JWK) Thumbprint September 2015 - - -3.1. Example JWK Thumbprint Computation - - This section demonstrates the JWK Thumbprint computation for the JWK - below (with the long line broken for display purposes only): - - { - "kty": "RSA", - "n": "0vx7agoebGcQSuuPiLJXZptN9nndrQmbXEps2aiAFbWhM78LhWx4cbbfAAt - VT86zwu1RK7aPFFxuhDR1L6tSoc_BJECPebWKRXjBZCiFV4n3oknjhMstn6 - 4tZ_2W-5JsGY4Hc5n9yBXArwl93lqt7_RN5w6Cf0h4QyQ5v-65YGjQR0_FD - W2QvzqY368QQMicAtaSqzs8KJZgnYb9c7d0zgdAZHzu6qMQvRL5hajrn1n9 - 1CbOpbISD08qNLyrdkt-bFTWhAI4vMQFh6WeZu0fM4lFd2NcRwr3XPksINH - aQ-G_xBniIqbw0Ls1jF44-csFCur-kEgU8awapJzKnqDKgw", - "e": "AQAB", - "alg": "RS256", - "kid": "2011-04-29" - } - - As defined in "JSON Web Key (JWK)" [JWK] and "JSON Web Algorithms - (JWA)" [JWA], the required members for an RSA public key are: - - o "kty" - o "n" - o "e" - - Therefore, these are the members used in the thumbprint computation. - - Their lexicographic order, per Section 3.3, is: - - o "e" - o "kty" - o "n" - - Therefore, the JSON object constructed as an intermediate step in the - computation is as follows (with the line broken for display purposes - only): - - {"e":"AQAB","kty":"RSA","n":"0vx7agoebGcQSuuPiLJXZptN9nndrQmbXEps2 - aiAFbWhM78LhWx4cbbfAAtVT86zwu1RK7aPFFxuhDR1L6tSoc_BJECPebWKRXjBZCi - FV4n3oknjhMstn64tZ_2W-5JsGY4Hc5n9yBXArwl93lqt7_RN5w6Cf0h4QyQ5v-65Y - GjQR0_FDW2QvzqY368QQMicAtaSqzs8KJZgnYb9c7d0zgdAZHzu6qMQvRL5hajrn1n - 91CbOpbISD08qNLyrdkt-bFTWhAI4vMQFh6WeZu0fM4lFd2NcRwr3XPksINHaQ-G_x - BniIqbw0Ls1jF44-csFCur-kEgU8awapJzKnqDKgw"} - - - - - - - - -Jones & Sakimura Standards Track [Page 4] - -RFC 7638 JSON Web Key (JWK) Thumbprint September 2015 - - - The octets of the UTF-8 representation of this JSON object are: - - [123, 34, 101, 34, 58, 34, 65, 81, 65, 66, 34, 44, 34, 107, 116, 121, - 34, 58, 34, 82, 83, 65, 34, 44, 34, 110, 34, 58, 34, 48, 118, 120, - 55, 97, 103, 111, 101, 98, 71, 99, 81, 83, 117, 117, 80, 105, 76, 74, - 88, 90, 112, 116, 78, 57, 110, 110, 100, 114, 81, 109, 98, 88, 69, - 112, 115, 50, 97, 105, 65, 70, 98, 87, 104, 77, 55, 56, 76, 104, 87, - 120, 52, 99, 98, 98, 102, 65, 65, 116, 86, 84, 56, 54, 122, 119, 117, - 49, 82, 75, 55, 97, 80, 70, 70, 120, 117, 104, 68, 82, 49, 76, 54, - 116, 83, 111, 99, 95, 66, 74, 69, 67, 80, 101, 98, 87, 75, 82, 88, - 106, 66, 90, 67, 105, 70, 86, 52, 110, 51, 111, 107, 110, 106, 104, - 77, 115, 116, 110, 54, 52, 116, 90, 95, 50, 87, 45, 53, 74, 115, 71, - 89, 52, 72, 99, 53, 110, 57, 121, 66, 88, 65, 114, 119, 108, 57, 51, - 108, 113, 116, 55, 95, 82, 78, 53, 119, 54, 67, 102, 48, 104, 52, 81, - 121, 81, 53, 118, 45, 54, 53, 89, 71, 106, 81, 82, 48, 95, 70, 68, - 87, 50, 81, 118, 122, 113, 89, 51, 54, 56, 81, 81, 77, 105, 99, 65, - 116, 97, 83, 113, 122, 115, 56, 75, 74, 90, 103, 110, 89, 98, 57, 99, - 55, 100, 48, 122, 103, 100, 65, 90, 72, 122, 117, 54, 113, 77, 81, - 118, 82, 76, 53, 104, 97, 106, 114, 110, 49, 110, 57, 49, 67, 98, 79, - 112, 98, 73, 83, 68, 48, 56, 113, 78, 76, 121, 114, 100, 107, 116, - 45, 98, 70, 84, 87, 104, 65, 73, 52, 118, 77, 81, 70, 104, 54, 87, - 101, 90, 117, 48, 102, 77, 52, 108, 70, 100, 50, 78, 99, 82, 119, - 114, 51, 88, 80, 107, 115, 73, 78, 72, 97, 81, 45, 71, 95, 120, 66, - 110, 105, 73, 113, 98, 119, 48, 76, 115, 49, 106, 70, 52, 52, 45, 99, - 115, 70, 67, 117, 114, 45, 107, 69, 103, 85, 56, 97, 119, 97, 112, - 74, 122, 75, 110, 113, 68, 75, 103, 119, 34, 125] - - Using SHA-256 [SHS] as the hash function H, the JWK SHA-256 - Thumbprint value is the SHA-256 hash of these octets, specifically: - - [55, 54, 203, 177, 120, 124, 184, 48, 156, 119, 238, 140, 55, 5, 197, - 225, 111, 251, 158, 133, 151, 21, 144, 31, 30, 76, 89, 177, 17, 130, - 245, 123] - - The base64url encoding [JWS] of this JWK SHA-256 Thumbprint value - (which might, for instance, be used as a "kid" (key ID) value) is: - - NzbLsXh8uDCcd-6MNwXF4W_7noWXFZAfHkxZsRGC9Xs - - - - - - - - - - - - - -Jones & Sakimura Standards Track [Page 5] - -RFC 7638 JSON Web Key (JWK) Thumbprint September 2015 - - -3.2. JWK Members Used in the Thumbprint Computation - - Only the required members of a key's representation are used when - computing its JWK Thumbprint value. As defined in "JSON Web Key - (JWK)" [JWK] and "JSON Web Algorithms (JWA)" [JWA], the required - members for an elliptic curve public key for the curves specified in - Section 6.2.1.1 of RFC 7518 [JWA], in lexicographic order, are: - - o "crv" - o "kty" - o "x" - o "y" - - The required members for an RSA public key, in lexicographic order, - are: - - o "e" - o "kty" - o "n" - - The required members for a symmetric key, in lexicographic order, - are: - - o "k" - o "kty" - - As other "kty" (key type) values are defined, the specifications - defining them should be similarly consulted to determine which - members, in addition to "kty", are required. - -3.2.1. JWK Thumbprint of a Private Key - - The JWK Thumbprint of a JWK representing a private key is computed as - the JWK Thumbprint of a JWK representing the corresponding public - key. This has the intentional benefit that the same JWK Thumbprint - value can be computed both by parties using either the public or - private key. The JWK Thumbprint can then be used to refer to both - keys of the key pair. Application context can be used to determine - if the public or private key is the one being referred to by the JWK - Thumbprint. - - This specification defines the method of computing JWK Thumbprints of - JWKs representing private keys for interoperability reasons -- so - that different implementations computing JWK Thumbprints of private - keys will produce the same result. - - - - - - -Jones & Sakimura Standards Track [Page 6] - -RFC 7638 JSON Web Key (JWK) Thumbprint September 2015 - - -3.2.2. Why Not Include Optional Members? - - Optional members of JWKs are intentionally not included in the JWK - Thumbprint computation so that their absence or presence in the JWK - does not alter the resulting value. The JWK Thumbprint value is a - digest of the members required to represent the key as a JWK -- not - of additional data that may also accompany the key. - - Optional members are not included so that the JWK Thumbprint refers - to a key -- not a key with an associated set of key attributes. - Different application contexts might or might not include different - subsets of optional attributes about the key in the JWK. If these - were included in the calculation of the JWK thumbprint, the values - would be different for those JWKs, even though the keys are the same. - The benefit of including only the JWK required members is that the - JWK Thumbprint of any JWK representing the key remains the same, - regardless of any other attributes that are present. - - Different kinds of thumbprints could be defined by other - specifications that might include some or all additional JWK members, - if use cases arise where such different kinds of thumbprints would be - useful. See Section 9.1 of RFC 7517 [JWK] for notes on some ways to - cryptographically bind attributes to a key. - -3.3. Order and Representation of Members in Hash Input - - The required members in the input to the hash function are ordered - lexicographically by the Unicode code points of the member names. - - Characters in member names and member values MUST be represented - without being escaped. This means that thumbprints of JWKs that - require such characters are not defined by this specification. (This - is not expected to limit the applicability of this specification, in - practice, as the members of JWK representations are not expected to - use any of these characters.) The characters specified as requiring - escaping by Section 7 of [RFC7159] are quotation mark, reverse - solidus (a.k.a. backslash), and the control characters U+0000 through - U+001F. - - If the JWK key type uses members whose values are themselves JSON - objects, then the members of those objects MUST likewise be - lexicographically ordered. (As of the time of this writing, none are - defined that do.) - - If the JWK key type uses members whose values are JSON numbers, and - if those numbers are integers, then they MUST be represented as a - JSON number as defined in Section 6 of [RFC7159] without including a - fraction part or exponent part. For instance, the value "1.024e3" - - - -Jones & Sakimura Standards Track [Page 7] - -RFC 7638 JSON Web Key (JWK) Thumbprint September 2015 - - - MUST be represented as "1024". This means that thumbprints of JWKs - using numbers that are not integers are not defined by this - specification. Also, as noted in "The I-JSON Message Format" - [RFC7493], implementations cannot expect an integer whose absolute - value is greater than 9007199254740991 (i.e., that is outside the - range [-(2**53)+1, (2**53)-1]) to be treated as an exact value. (As - of the time of this writing, none are defined that use JSON numbers.) - - See Section 4 for a discussion of further practical considerations - pertaining to the representation of the hash input. - -3.4. Selection of Hash Function - - A specific hash function must be chosen by an application to compute - the hash value of the hash input. For example, SHA-256 [SHS] might - be used as the hash function by the application. While SHA-256 is a - good default choice at the time of this writing, the hash function of - choice can be expected to change over time as the cryptographic - landscape evolves. - - Note that in many cases, only the party that creates a key will need - to know the hash function used. A typical usage is for the producer - of the key to use the base64url-encoded JWK Thumbprint value as a - "kid" (key ID) value. In this case, the consumer of the "kid" treats - it as an opaque value that it uses to select the key. - - However, in some cases, multiple parties will be reproducing the JWK - Thumbprint calculation and comparing the results. In these cases, - the parties will need to know which hash function was used and use - the same one. - -3.5. JWK Thumbprints of Keys Not in JWK Format - - Note that a key need not be in JWK format to create a JWK Thumbprint - of it. The only prerequisites are that the JWK representation of the - key be defined and the party creating the JWK Thumbprint be in - possession of the necessary key material. These are sufficient to - create the hash input from the JWK representation of the key, as - described in Section 3.3. - -4. Practical JSON and Unicode Considerations - - Implementations will almost certainly use functionality provided by - the platform's JSON support when parsing the JWK and emitting the - JSON object used as the hash input. As a practical consideration, - future JWK member names and values should be avoided for which - different platforms or libraries might emit different - representations. As of the time of this writing, all defined JWK - - - -Jones & Sakimura Standards Track [Page 8] - -RFC 7638 JSON Web Key (JWK) Thumbprint September 2015 - - - member names and values use only printable ASCII characters, which - should not exhibit this problem. Note however, that JSON.stringify() - cannot be counted on to lexicographically sort the members of JSON - objects, so while it could be used to emit some kinds of member - values, different code is likely to be needed to perform the sorting. - - In particular, while the operation of lexicographically ordering - member names by their Unicode code points is well defined, different - platform sort functions may produce different results for non-ASCII - characters, in ways that may not be obvious to developers. If - writers of future specifications defining new JWK key type values - choose to restrict themselves to printable ASCII member names and - values (which are for machine and not human consumption anyway), some - future interoperability problems might be avoided. - - However, if new JWK members are defined that use non-ASCII member - names or values, their definitions should specify the exact Unicode - code point sequences used to represent them. This is particularly - important in cases in which Unicode normalization could result in the - transformation of one set of code points into another under any - circumstances. - - Use of escaped characters in JWKs for which JWK Thumbprints will be - computed should be avoided. Use of escaped characters in the hash - input JWKs derived from these original JWKs is prohibited. - - There is a natural representation to use for numeric values that are - integers. However, this specification does not attempt to define a - standard representation for numbers that are not integers or that - contain an exponent component. This is not expected to be a problem - in practice, as the required members of JWK representations are - expected to use only numbers that are integers. - - Use of number representations containing fraction or exponent parts - in JWKs for which JWK Thumbprints will be computed should be avoided. - - All of these practical considerations are really an instance of Jon - Postel's principle: "Be liberal in what you accept, and conservative - in what you send." - -5. Relationship to Digests of X.509 Values - - JWK Thumbprint values are computed on the JWK members required to - represent a key, rather than all members of a JWK that the key is - represented in. Thus, they are more analogous to applications that - use digests of X.509 Subject Public Key Info (SPKI) values, which are - defined in Section 4.1.2.7 of [RFC5280], than to applications that - use digests of complete certificate values, as the "x5t" (X.509 - - - -Jones & Sakimura Standards Track [Page 9] - -RFC 7638 JSON Web Key (JWK) Thumbprint September 2015 - - - certificate SHA-1 thumbprint) [JWS] value defined for X.509 - certificate objects does. While logically equivalent to a digest of - the SPKI representation of the key, a JWK Thumbprint is computed over - a JSON representation of that key, rather than over an ASN.1 - representation of it. - -6. IANA Considerations - - This specification adds to the instructions for the Designated - Experts of the following IANA registries, all of which are in the - "JSON Object Signing and Encryption (JOSE)" registry [IANA.JOSE]: - - o JSON Web Key Types - o JSON Web Key Elliptic Curve - o JSON Web Key Parameters - - IANA has added a link to this specification in the Reference sections - of these registries. - - For these registries, because of the practical JSON and Unicode - considerations described in Section 4, the Designated Experts must - either: - - (a) require that JWK member names and values being registered use - only printable ASCII characters excluding double quote ('"') and - backslash ('\') (the Unicode characters with code points U+0021, - U+0023 through U+005B, and U+005D through U+007E), or - - (b) if new JWK members or values are defined that use other code - points, require that their definitions specify the exact Unicode code - point sequences used to represent them. Furthermore, proposed - registrations that use Unicode code points that can only be - represented in JSON strings as escaped characters must not be - accepted. - -7. Security Considerations - - The JSON Security Considerations and Unicode Comparison Security - Considerations described in Sections 10.12 and 10.13 of "JSON Web - Signature (JWS)" [JWS] also apply to this specification. - - Also, as described in Section 4, some implementations may produce - incorrect results if esoteric or escaped characters are used in the - member names. The security implications of this appear to be limited - for JWK Thumbprints of public keys, because while it may result in - implementations failing to identify the intended key, it should not - leak information. The information in a public key is already public - in nature, by definition. - - - -Jones & Sakimura Standards Track [Page 10] - -RFC 7638 JSON Web Key (JWK) Thumbprint September 2015 - - - A hash of a symmetric key has the potential to leak information about - the key value. Thus, the JWK Thumbprint of a symmetric key should - typically be concealed from parties not in possession of the - symmetric key, unless in the application context, the cryptographic - hash used, such as SHA-256, is known to provide sufficient protection - against disclosure of the key value. - - A JWK Thumbprint will only uniquely identify a particular key if a - single unambiguous JWK representation for that key is defined and - used when computing the JWK Thumbprint. (Such representations are - defined for all the key types defined in "JSON Web Algorithms (JWA)" - [JWA].) For example, if an RSA key were to use "e":"AAEAAQ" - (representing [0, 1, 0, 1]) rather than the specified correct - representation of "e":"AQAB" (representing [1, 0, 1]), then a - different thumbprint value would be produced for what could be - effectively the same key, at least for implementations that are lax - in validating the JWK values that they accept. Thus, JWK Thumbprint - values can only be relied upon to be unique for a given key if the - implementation also validates that the correct representation of the - key is used. - - Even more insidious is that an attacker may supply a key that is a - transformation of a legal key in order to have it appear to be a - different key. For instance, if a legitimate RSA key uses a modulus - value N and an attacker supplies a key with modulus 3*N, the modified - key would still work about 1/3 of the time, but would appear to be a - different key. Thus, while thumbprint values are valuable for - identifying legitimate keys, comparing thumbprint values is not a - reliable means of excluding (blacklisting) the use of particular keys - (or transformations thereof). - -8. References - -8.1. Normative References - - [IANA.JOSE] IANA, "JSON Object Signing and Encryption (JOSE)", - . - - [JWA] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518, - DOI 10.17487/RFC7518, May 2015, - . - - [JWK] Jones, M., "JSON Web Key (JWK)", RFC 7517, - DOI 10.17487/RFC7517, May 2015, - . - - - - - - -Jones & Sakimura Standards Track [Page 11] - -RFC 7638 JSON Web Key (JWK) Thumbprint September 2015 - - - [JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web - Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May - 2015, . - - [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate - Requirement Levels", BCP 14, RFC 2119, - DOI 10.17487/RFC2119, March 1997, - . - - [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) - Data Interchange Format", RFC 7159, DOI 10.17487/RFC7159, - March 2014, . - - [SHS] National Institute of Standards and Technology, "Secure - Hash Standard (SHS)", FIPS PUB 180-4, March 2012, - . - - [UNICODE] The Unicode Consortium, "The Unicode Standard", - . - -8.2. Informative References - - [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., - Housley, R., and W. Polk, "Internet X.509 Public Key - Infrastructure Certificate and Certificate Revocation - List (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May - 2008, . - - [RFC7493] Bray, T., Ed., "The I-JSON Message Format", RFC 7493, - DOI 10.17487/RFC7493, March 2015, - . - - - - - - - - - - - - - - - - - - - -Jones & Sakimura Standards Track [Page 12] - -RFC 7638 JSON Web Key (JWK) Thumbprint September 2015 - - -Acknowledgements - - James Manger and John Bradley participated in discussions that led to - the creation of this specification. Thanks also to Joel Halpern, - Barry Leiba, Adam Montville, Kathleen Moriarty, and Jim Schaad for - their reviews of this specification. - -Authors' Addresses - - Michael B. Jones - Microsoft - - Email: mbj@microsoft.com - URI: http://self-issued.info/ - - - Nat Sakimura - Nomura Research Institute - - Email: n-sakimura@nri.co.jp - URI: http://nat.sakimura.org/ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Jones & Sakimura Standards Track [Page 13] -