RFC 7518

JSON Web Algorithms (JWA)

Internet Engineering Task Force (IETF) M. Jones
Request for Comments: 7518 Microsoft
Category: Standards Track May 2015
ISSN: 2070-1721
JSON Web Algorithms (JWA)
Abstract
This specification registers cryptographic algorithms and identifiers
to be used with the JSON Web Signature (JWS), JSON Web Encryption
(JWE), and JSON Web Key (JWK) specifications. It defines several
IANA registries for these identifiers.
Status of This Memo
This is an Internet Standards Track document.
This document is a product of the Internet Engineering Task Force
(IETF). It represents the consensus of the IETF community. It has
received public review and has been approved for publication by the
Internet Engineering Steering Group (IESG). Further information on
Internet Standards is available in Section 2 of RFC 5741.
Information about the current status of this document, any errata,
and how to provide feedback on it may be obtained at
http://www.rfc-editor.org/info/rfc7518.
Copyright Notice
Copyright (c) 2015 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.

The interpretation should only be applied when the terms appear in
all capital letters.
BASE64URL(OCTETS) denotes the base64url encoding of OCTETS, per
Section 2 of [JWS].
UTF8(STRING) denotes the octets of the UTF-8 [RFC3629] representation
of STRING, where STRING is a sequence of zero or more Unicode
[UNICODE] characters.
ASCII(STRING) denotes the octets of the ASCII [RFC20] representation
of STRING, where STRING is a sequence of zero or more ASCII
characters.
The concatenation of two values A and B is denoted as A || B.
2. Terminology
The terms "JSON Web Signature (JWS)", "Base64url Encoding", "Header
Parameter", "JOSE Header", "JWS Payload", "JWS Protected Header",
"JWS Signature", "JWS Signing Input", and "Unsecured JWS" are defined
by the JWS specification [JWS].
The terms "JSON Web Encryption (JWE)", "Additional Authenticated Data
(AAD)", "Authentication Tag", "Content Encryption Key (CEK)", "Direct
Encryption", "Direct Key Agreement", "JWE Authentication Tag", "JWE
Ciphertext", "JWE Encrypted Key", "JWE Initialization Vector", "JWE
Protected Header", "Key Agreement with Key Wrapping", "Key
Encryption", "Key Management Mode", and "Key Wrapping" are defined by
the JWE specification [JWE].
The terms "JSON Web Key (JWK)" and "JWK Set" are defined by the JWK
specification [JWK].
The terms "Ciphertext", "Digital Signature", "Initialization Vector",
"Message Authentication Code (MAC)", and "Plaintext" are defined by
the "Internet Security Glossary, Version 2" [RFC4949].
This term is defined by this specification:
Base64urlUInt
The representation of a positive or zero integer value as the
base64url encoding of the value's unsigned big-endian
representation as an octet sequence. The octet sequence MUST
utilize the minimum number of octets needed to represent the
value. Zero is represented as BASE64URL(single zero-valued
octet), which is "AA".

3.2. HMAC with SHA-2 Functions
Hash-based Message Authentication Codes (HMACs) enable one to use a
secret plus a cryptographic hash function to generate a MAC. This
can be used to demonstrate that whoever generated the MAC was in
possession of the MAC key. The algorithm for implementing and
validating HMACs is provided in RFC 2104 [RFC2104].
A key of the same size as the hash output (for instance, 256 bits for
"HS256") or larger MUST be used with this algorithm. (This
requirement is based on Section 5.3.4 (Security Effect of the HMAC
Key) of NIST SP 800-117 [NIST.800-107], which states that the
effective security strength is the minimum of the security strength
of the key and two times the size of the internal hash value.)
The HMAC SHA-256 MAC is generated per RFC 2104, using SHA-256 as the
hash algorithm "H", using the JWS Signing Input as the "text" value,
and using the shared key. The HMAC output value is the JWS
Signature.
The following "alg" (algorithm) Header Parameter values are used to
indicate that the JWS Signature is an HMAC value computed using the
corresponding algorithm:
+-------------------+--------------------+
| "alg" Param Value | MAC Algorithm |
+-------------------+--------------------+
| HS256 | HMAC using SHA-256 |
| HS384 | HMAC using SHA-384 |
| HS512 | HMAC using SHA-512 |
+-------------------+--------------------+
The HMAC SHA-256 MAC for a JWS is validated by computing an HMAC
value per RFC 2104, using SHA-256 as the hash algorithm "H", using
the received JWS Signing Input as the "text" value, and using the
shared key. This computed HMAC value is then compared to the result
of base64url decoding the received encoded JWS Signature value. The
comparison of the computed HMAC value to the JWS Signature value MUST
be done in a constant-time manner to thwart timing attacks.
Alternatively, the computed HMAC value can be base64url encoded and
compared to the received encoded JWS Signature value (also in a
constant-time manner), as this comparison produces the same result as
comparing the unencoded values. In either case, if the values match,
the HMAC has been validated.

Securing content and validation with the HMAC SHA-384 and HMAC
SHA-512 algorithms is performed identically to the procedure for HMAC
SHA-256 -- just using the corresponding hash algorithms with
correspondingly larger minimum key sizes and result values: 384 bits
each for HMAC SHA-384 and 512 bits each for HMAC SHA-512.
An example using this algorithm is shown in Appendix A.1 of [JWS].
3.3. Digital Signature with RSASSA-PKCS1-v1_5
This section defines the use of the RSASSA-PKCS1-v1_5 digital
signature algorithm as defined in Section 8.2 of RFC 3447 [RFC3447]
(commonly known as PKCS #1), using SHA-2 [SHS] hash functions.
A key of size 2048 bits or larger MUST be used with these algorithms.
The RSASSA-PKCS1-v1_5 SHA-256 digital signature is generated as
follows: generate a digital signature of the JWS Signing Input using
RSASSA-PKCS1-v1_5-SIGN and the SHA-256 hash function with the desired
private key. This is the JWS Signature value.
The following "alg" (algorithm) Header Parameter values are used to
indicate that the JWS Signature is a digital signature value computed
using the corresponding algorithm:
+-------------------+---------------------------------+
| "alg" Param Value | Digital Signature Algorithm |
+-------------------+---------------------------------+
| RS256 | RSASSA-PKCS1-v1_5 using SHA-256 |
| RS384 | RSASSA-PKCS1-v1_5 using SHA-384 |
| RS512 | RSASSA-PKCS1-v1_5 using SHA-512 |
+-------------------+---------------------------------+
The RSASSA-PKCS1-v1_5 SHA-256 digital signature for a JWS is
validated as follows: submit the JWS Signing Input, the JWS
Signature, and the public key corresponding to the private key used
by the signer to the RSASSA-PKCS1-v1_5-VERIFY algorithm using SHA-256
as the hash function.
Signing and validation with the RSASSA-PKCS1-v1_5 SHA-384 and RSASSA-
PKCS1-v1_5 SHA-512 algorithms is performed identically to the
procedure for RSASSA-PKCS1-v1_5 SHA-256 -- just using the
corresponding hash algorithms instead of SHA-256.
An example using this algorithm is shown in Appendix A.2 of [JWS].

3.4. Digital Signature with ECDSA
The Elliptic Curve Digital Signature Algorithm (ECDSA) [DSS] provides
for the use of Elliptic Curve Cryptography, which is able to provide
equivalent security to RSA cryptography but using shorter key sizes
and with greater processing speed for many operations. This means
that ECDSA digital signatures will be substantially smaller in terms
of length than equivalently strong RSA digital signatures.
This specification defines the use of ECDSA with the P-256 curve and
the SHA-256 cryptographic hash function, ECDSA with the P-384 curve
and the SHA-384 hash function, and ECDSA with the P-521 curve and the
SHA-512 hash function. The P-256, P-384, and P-521 curves are
defined in [DSS].
The ECDSA P-256 SHA-256 digital signature is generated as follows:
1. Generate a digital signature of the JWS Signing Input using ECDSA
P-256 SHA-256 with the desired private key. The output will be
the pair (R, S), where R and S are 256-bit unsigned integers.
2. Turn R and S into octet sequences in big-endian order, with each
array being be 32 octets long. The octet sequence
representations MUST NOT be shortened to omit any leading zero
octets contained in the values.
3. Concatenate the two octet sequences in the order R and then S.
(Note that many ECDSA implementations will directly produce this
concatenation as their output.)
4. The resulting 64-octet sequence is the JWS Signature value.
The following "alg" (algorithm) Header Parameter values are used to
indicate that the JWS Signature is a digital signature value computed
using the corresponding algorithm:
+-------------------+-------------------------------+
| "alg" Param Value | Digital Signature Algorithm |
+-------------------+-------------------------------+
| ES256 | ECDSA using P-256 and SHA-256 |
| ES384 | ECDSA using P-384 and SHA-384 |
| ES512 | ECDSA using P-521 and SHA-512 |
+-------------------+-------------------------------+

The ECDSA P-256 SHA-256 digital signature for a JWS is validated as
follows:
1. The JWS Signature value MUST be a 64-octet sequence. If it is
not a 64-octet sequence, the validation has failed.
2. Split the 64-octet sequence into two 32-octet sequences. The
first octet sequence represents R and the second S. The values R
and S are represented as octet sequences using the Integer-to-
OctetString Conversion defined in Section 2.3.7 of SEC1 [SEC1]
(in big-endian octet order).
3. Submit the JWS Signing Input, R, S, and the public key (x, y) to
the ECDSA P-256 SHA-256 validator.
Signing and validation with the ECDSA P-384 SHA-384 and ECDSA P-521
SHA-512 algorithms is performed identically to the procedure for
ECDSA P-256 SHA-256 -- just using the corresponding hash algorithms
with correspondingly larger result values. For ECDSA P-384 SHA-384,
R and S will be 384 bits each, resulting in a 96-octet sequence. For
ECDSA P-521 SHA-512, R and S will be 521 bits each, resulting in a
132-octet sequence. (Note that the Integer-to-OctetString Conversion
defined in Section 2.3.7 of SEC1 [SEC1] used to represent R and S as
octet sequences adds zero-valued high-order padding bits when needed
to round the size up to a multiple of 8 bits; thus, each 521-bit
integer is represented using 528 bits in 66 octets.)
Examples using these algorithms are shown in Appendices A.3 and A.4
of [JWS].
3.5. Digital Signature with RSASSA-PSS
This section defines the use of the RSASSA-PSS digital signature
algorithm as defined in Section 8.1 of RFC 3447 [RFC3447] with the
MGF1 mask generation function and SHA-2 hash functions, always using
the same hash function for both the RSASSA-PSS hash function and the
MGF1 hash function. The size of the salt value is the same size as
the hash function output. All other algorithm parameters use the
defaults specified in Appendix A.2.3 of RFC 3447.
A key of size 2048 bits or larger MUST be used with this algorithm.
The RSASSA-PSS SHA-256 digital signature is generated as follows:
generate a digital signature of the JWS Signing Input using RSASSA-
PSS-SIGN, the SHA-256 hash function, and the MGF1 mask generation
function with SHA-256 with the desired private key. This is the JWS
Signature value.

The following "alg" (algorithm) Header Parameter values are used to
indicate that the JWS Signature is a digital signature value computed
using the corresponding algorithm:
+-------------------+-----------------------------------------------+
| "alg" Param Value | Digital Signature Algorithm |
+-------------------+-----------------------------------------------+
| PS256 | RSASSA-PSS using SHA-256 and MGF1 with |
| | SHA-256 |
| PS384 | RSASSA-PSS using SHA-384 and MGF1 with |
| | SHA-384 |
| PS512 | RSASSA-PSS using SHA-512 and MGF1 with |
| | SHA-512 |
+-------------------+-----------------------------------------------+
The RSASSA-PSS SHA-256 digital signature for a JWS is validated as
follows: submit the JWS Signing Input, the JWS Signature, and the
public key corresponding to the private key used by the signer to the
RSASSA-PSS-VERIFY algorithm using SHA-256 as the hash function and
using MGF1 as the mask generation function with SHA-256.
Signing and validation with the RSASSA-PSS SHA-384 and RSASSA-PSS
SHA-512 algorithms is performed identically to the procedure for
RSASSA-PSS SHA-256 -- just using the alternative hash algorithm in
both roles.
3.6. Using the Algorithm "none"
JWSs MAY also be created that do not provide integrity protection.
Such a JWS is called an Unsecured JWS. An Unsecured JWS uses the
"alg" value "none" and is formatted identically to other JWSs, but
MUST use the empty octet sequence as its JWS Signature value.
Recipients MUST verify that the JWS Signature value is the empty
octet sequence.
Implementations that support Unsecured JWSs MUST NOT accept such
objects as valid unless the application specifies that it is
acceptable for a specific object to not be integrity protected.
Implementations MUST NOT accept Unsecured JWSs by default. In order
to mitigate downgrade attacks, applications MUST NOT signal
acceptance of Unsecured JWSs at a global level, and SHOULD signal
acceptance on a per-object basis. See Section 8.5 for security
considerations associated with using this algorithm.