tech-invite   World Map     

IETF     RFCs     Groups     SIP     ABNFs    |    3GPP     Specs     Glossaries     Architecture     IMS     UICC    |    search     info

RFC 7518

 
 
 

JSON Web Algorithms (JWA)

Part 2 of 4, p. 11 to 32
Prev RFC Part       Next RFC Part

 


prevText      Top      Up      ToC       Page 11 
4.  Cryptographic Algorithms for Key Management

   JWE uses cryptographic algorithms to encrypt or determine the Content
   Encryption Key (CEK).

Top      Up      ToC       Page 12 
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"           |        |                |

Top      Up      ToC       Page 13 
   | 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].

Top      Up      ToC       Page 14 
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.

Top      Up      ToC       Page 15 
   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.

Top      Up      ToC       Page 16 
   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.

Top      Up      ToC       Page 17 
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.

Top      Up      ToC       Page 18 
   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]).

Top      Up      ToC       Page 19 
   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.

Top      Up      ToC       Page 20 
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.

Top      Up      ToC       Page 21 
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.

Top      Up      ToC       Page 22 
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.

Top      Up      ToC       Page 23 
   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.

Top      Up      ToC       Page 24 
       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.

Top      Up      ToC       Page 25 
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.

Top      Up      ToC       Page 26 
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            |
   +---------------+---------------------------------------------------+

Top      Up      ToC       Page 27 
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.

Top      Up      ToC       Page 28 
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"

Top      Up      ToC       Page 29 
   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).

Top      Up      ToC       Page 30 
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.

Top      Up      ToC       Page 31 
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.

Top      Up      ToC       Page 32 
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.



(page 32 continued on part 3)

Next RFC Part