RFC 7518
JSON Web Algorithms (JWA)
4. Cryptographic Algorithms for Key Management
JWE uses cryptographic algorithms to encrypt or determine the Content Encryption Key (CEK).
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" | | |
| 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].
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.
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.
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.
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.
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]).
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.
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.
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.
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.
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.
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.
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.
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 | +---------------+---------------------------------------------------+
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.
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"
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).
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.
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.
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)
