JSON Web Encryption (JWE)
draft-ietf-jose-json-web-encryption-18

quot; member
      that is integrity protected and shared among all recipients, the
      "unprotected" member that is not integrity protected and shared
      among all recipients, and the "header" member that is not
      integrity protected and specific to a particular recipient.  (This
      does not affect the JWE Compact Serialization, in which all Header
      Parameter values are in a single integrity protected JWE Header
      value.)

   o  Shortened the names "authentication_tag" to "tag" and
      "initialization_vector" to "iv" in the JWE JSON Serialization,
      addressing issue #20.

   o  Removed "apv" (agreement PartyVInfo) since it is no longer used.

   o  Removed suggested compact serialization for multiple recipients.

Jones, et al.             Expires May 16, 2014                 [Page 47]
Internet-Draft                     JWE                     November 2013

   o  Changed the MIME type name "application/jwe-js" to
      "application/jwe+json", addressing issue #22.

   o  Tightened the description of the "crit" (critical) header
      parameter.

   -10

   o  Changed the JWE processing rules for multiple recipients so that a
      single AAD value contains the header parameters and encrypted key
      values for all the recipients, enabling AES GCM to be safely used
      for multiple recipients.

   o  Added an appendix suggesting a possible compact serialization for
      JWEs with multiple recipients.

   -09

   o  Added JWE JSON Serialization, as specified by
      draft-jones-jose-jwe-json-serialization-04.

   o  Registered "application/jwe-js" MIME type and "JWE-JS" typ header
      parameter value.

   o  Defined that the default action for header parameters that are not
      understood is to ignore them unless specifically designated as
      "MUST be understood" or included in the new "crit" (critical)
      header parameter list.  This addressed issue #6.

   o  Corrected "x5c" description.  This addressed issue #12.

   o  Changed from using the term "byte" to "octet" when referring to 8
      bit values.

   o  Added Key Management Mode definitions to terminology section and
      used the defined terms to provide clearer key management
      instructions.  This addressed issue #5.

   o  Added text about preventing the recipient from behaving as an
      oracle during decryption, especially when using RSAES-PKCS1-V1_5.

   o  Changed from using the term "Integrity Value" to "Authentication
      Tag".

   o  Changed member name from "integrity_value" to "authentication_tag"
      in the JWE JSON Serialization.

Jones, et al.             Expires May 16, 2014                 [Page 48]
Internet-Draft                     JWE                     November 2013

   o  Removed Initialization Vector from the AAD value since it is
      already integrity protected by all of the authenticated encryption
      algorithms specified in the JWA specification.

   o  Replaced "A128CBC+HS256" and "A256CBC+HS512" with "A128CBC-HS256"
      and "A256CBC-HS512".  The new algorithms perform the same
      cryptographic computations as [I-D.mcgrew-aead-aes-cbc-hmac-sha2],
      but with the Initialization Vector and Authentication Tag values
      remaining separate from the Ciphertext value in the output
      representation.  Also deleted the header parameters "epu"
      (encryption PartyUInfo) and "epv" (encryption PartyVInfo), since
      they are no longer used.

   -08

   o  Replaced uses of the term "AEAD" with "Authenticated Encryption",
      since the term AEAD in the RFC 5116 sense implied the use of a
      particular data representation, rather than just referring to the
      class of algorithms that perform authenticated encryption with
      associated data.

   o  Applied editorial improvements suggested by Jeff Hodges and Hannes
      Tschofenig.  Many of these simplified the terminology used.

   o  Clarified statements of the form "This header parameter is
      OPTIONAL" to "Use of this header parameter is OPTIONAL".

   o  Added a Header Parameter Usage Location(s) field to the IANA JSON
      Web Signature and Encryption Header Parameters registry.

   o  Added seriesInfo information to Internet Draft references.

   -07

   o  Added a data length prefix to PartyUInfo and PartyVInfo values.

   o  Updated values for example AES CBC calculations.

   o  Made several local editorial changes to clean up loose ends left
      over from to the decision to only support block encryption methods
      providing integrity.  One of these changes was to explicitly state
      that the "enc" (encryption method) algorithm must be an
      Authenticated Encryption algorithm with a specified key length.

   -06

   o  Removed the "int" and "kdf" parameters and defined the new
      composite Authenticated Encryption algorithms "A128CBC+HS256" and

Jones, et al.             Expires May 16, 2014                 [Page 49]
Internet-Draft                     JWE                     November 2013

      "A256CBC+HS512" to replace the former uses of AES CBC, which
      required the use of separate integrity and key derivation
      functions.

   o  Included additional values in the Concat KDF calculation -- the
      desired output size and the algorithm value, and optionally
      PartyUInfo and PartyVInfo values.  Added the optional header
      parameters "apu" (agreement PartyUInfo), "apv" (agreement
      PartyVInfo), "epu" (encryption PartyUInfo), and "epv" (encryption
      PartyVInfo).  Updated the KDF examples accordingly.

   o  Promoted Initialization Vector from being a header parameter to
      being a top-level JWE element.  This saves approximately 16 bytes
      in the compact serialization, which is a significant savings for
      some use cases.  Promoting the Initialization Vector out of the
      header also avoids repeating this shared value in the JSON
      serialization.

   o  Changed "x5c" (X.509 Certificate Chain) representation from being
      a single string to being an array of strings, each containing a
      single base64 encoded DER certificate value, representing elements
      of the certificate chain.

   o  Added an AES Key Wrap example.

   o  Reordered the encryption steps so CMK creation is first, when
      required.

   o  Correct statements in examples about which algorithms produce
      reproducible results.

   -05

   o  Support both direct encryption using a shared or agreed upon
      symmetric key, and the use of a shared or agreed upon symmetric
      key to key wrap the CMK.

   o  Added statement that "StringOrURI values are compared as case-
      sensitive strings with no transformations or canonicalizations
      applied".

   o  Updated open issues.

   o  Indented artwork elements to better distinguish them from the body
      text.

   -04

Jones, et al.             Expires May 16, 2014                 [Page 50]
Internet-Draft                     JWE                     November 2013

   o  Refer to the registries as the primary sources of defined values
      and then secondarily reference the sections defining the initial
      contents of the registries.

   o  Normatively reference XML Encryption 1.1
      [W3C.CR-xmlenc-core1-20120313] for its security considerations.

   o  Reference draft-jones-jose-jwe-json-serialization instead of
      draft-jones-json-web-encryption-json-serialization.

   o  Described additional open issues.

   o  Applied editorial suggestions.

   -03

   o  Added the "kdf" (key derivation function) header parameter to
      provide crypto agility for key derivation.  The default KDF
      remains the Concat KDF with the SHA-256 digest function.

   o  Reordered encryption steps so that the Encoded JWE Header is
      always created before it is needed as an input to the
      Authenticated Encryption "additional authenticated data"
      parameter.

   o  Added the "cty" (content type) header parameter for declaring type
      information about the secured content, as opposed to the "typ"
      (type) header parameter, which declares type information about
      this object.

   o  Moved description of how to determine whether a header is for a
      JWS or a JWE from the JWT spec to the JWE spec.

   o  Added complete encryption examples for both Authenticated
      Encryption and non-Authenticated Encryption algorithms.

   o  Added complete key derivation examples.

   o  Added "Collision Resistant Namespace" to the terminology section.

   o  Reference ITU.X690.1994 for DER encoding.

   o  Added Registry Contents sections to populate registry values.

   o  Numerous editorial improvements.

   -02

Jones, et al.             Expires May 16, 2014                 [Page 51]
Internet-Draft                     JWE                     November 2013

   o  When using Authenticated Encryption algorithms (such as AES GCM),
      use the "additional authenticated data" parameter to provide
      integrity for the header, encrypted key, and ciphertext and use
      the resulting "authentication tag" value as the JWE Authentication
      Tag.

   o  Defined KDF output key sizes.

   o  Generalized text to allow key agreement to be employed as an
      alternative to key wrapping or key encryption.

   o  Changed compression algorithm from gzip to DEFLATE.

   o  Clarified that it is an error when a "kid" value is included and
      no matching key is found.

   o  Clarified that JWEs with duplicate Header Parameter Names MUST be
      rejected.

   o  Clarified the relationship between "typ" header parameter values
      and MIME types.

   o  Registered application/jwe MIME type and "JWE" typ header
      parameter value.

   o  Simplified JWK terminology to get replace the "JWK Key Object" and
      "JWK Container Object" terms with simply "JSON Web Key (JWK)" and
      "JSON Web Key Set (JWK Set)" and to eliminate potential confusion
      between single keys and sets of keys.  As part of this change, the
      Header Parameter Name for a public key value was changed from
      "jpk" (JSON Public Key) to "jwk" (JSON Web Key).

   o  Added suggestion on defining additional header parameters such as
      "x5t#S256" in the future for certificate thumbprints using hash
      algorithms other than SHA-1.

   o  Specify RFC 2818 server identity validation, rather than RFC 6125
      (paralleling the same decision in the OAuth specs).

   o  Generalized language to refer to Message Authentication Codes
      (MACs) rather than Hash-based Message Authentication Codes (HMACs)
      unless in a context specific to HMAC algorithms.

   o  Reformatted to give each header parameter its own section heading.

   -01

Jones, et al.             Expires May 16, 2014                 [Page 52]
Internet-Draft                     JWE                     November 2013

   o  Added an integrity check for non-Authenticated Encryption
      algorithms.

   o  Added "jpk" and "x5c" header parameters for including JWK public
      keys and X.509 certificate chains directly in the header.

   o  Clarified that this specification is defining the JWE Compact
      Serialization.  Referenced the new JWE-JS spec, which defines the
      JWE JSON Serialization.

   o  Added text "New header parameters should be introduced sparingly
      since an implementation that does not understand a parameter MUST
      reject the JWE".

   o  Clarified that the order of the encryption and decryption steps is
      not significant in cases where there are no dependencies between
      the inputs and outputs of the steps.

   o  Made other editorial improvements suggested by JOSE working group
      participants.

   -00

   o  Created the initial IETF draft based upon
      draft-jones-json-web-encryption-02 with no normative changes.

   o  Changed terminology to no longer call both digital signatures and
      HMACs "signatures".

Authors' Addresses

   Michael B. Jones
   Microsoft

   Email: mbj@microsoft.com
   URI:   http://self-issued.info/

   Eric Rescorla
   RTFM, Inc.

   Email: ekr@rtfm.com

Jones, et al.             Expires May 16, 2014                 [Page 53]
Internet-Draft                     JWE                     November 2013

   Joe Hildebrand
   Cisco Systems, Inc.

   Email: jhildebr@cisco.com

Jones, et al.             Expires May 16, 2014                 [Page 54]