Tech-invite3GPPspaceIETFspace
959493929190898887868584838281807978777675747372717069686766656463626160595857565554535251504948474645444342414039383736353433323130292827262524232221201918171615141312111009080706050403020100
in Index   Prev   Next

RFC 7515

JSON Web Signature (JWS)

Pages: 59
Proposed Standard
Errata
Part 1 of 3 – Pages 1 to 15
None   None   Next

Top   ToC   RFC7515 - Page 1
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.
Top   ToC   RFC7515 - Page 2
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
Top   ToC   RFC7515 - Page 3
   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
Top   ToC   RFC7515 - Page 4
       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.
Top   ToC   RFC7515 - Page 5
   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.
Top   ToC   RFC7515 - Page 6
   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.
Top   ToC   RFC7515 - Page 7
   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.
Top   ToC   RFC7515 - Page 8

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.)
Top   ToC   RFC7515 - Page 9
     {"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
Top   ToC   RFC7515 - Page 10
   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
Top   ToC   RFC7515 - Page 11
   (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
Top   ToC   RFC7515 - Page 12
   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.
Top   ToC   RFC7515 - Page 13
   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"".
Top   ToC   RFC7515 - Page 14

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
Top   ToC   RFC7515 - Page 15
   (Section 4.2).  Unlike Public Header Parameter names, Private Header
   Parameter names are subject to collision and should be used with
   caution.



(page 15 continued on part 2)

Next Section