tech-invite   World Map     

IETF     RFCs     Groups     SIP     ABNFs    |    3GPP     Specs     Gloss.     Arch.     IMS     UICC    |    Misc.    |    search     info

RFC 7515

Proposed STD
Pages: 59
Top     in Index     Prev     Next
in Group Index     Prev in Group     Next in Group     Group: JOSE

JSON Web Signature (JWS)

Part 1 of 3, p. 1 to 15
None       Next RFC Part

 


Top       ToC       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.

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       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       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       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       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       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       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       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       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       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       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       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       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       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 RFC Part