3. Cryptographic Algorithms for Digital Signatures and MACs
JWS uses cryptographic algorithms to digitally sign or create a MAC of the contents of the JWS Protected Header and the JWS Payload.
3.1 "alg" (Algorithm) Header Parameter Values for JWS
The table below defines the "alg" (algorithm) Header Parameter values for JWS defined by this specification:
| "alg" Param Value | Digital Signature or MAC Algorithm | Implementation Requirements |
|---|---|---|
| HS256 | HMAC using SHA-256 | Required |
| HS384 | HMAC using SHA-384 | Optional |
| HS512 | HMAC using SHA-512 | Optional |
| RS256 | RSASSA-PKCS1-v1_5 using SHA-256 | Recommended |
| RS384 | RSASSA-PKCS1-v1_5 using SHA-384 | Optional |
| RS512 | RSASSA-PKCS1-v1_5 using SHA-512 | Optional |
| ES256 | ECDSA using P-256 and SHA-256 | Recommended+ |
| ES384 | ECDSA using P-384 and SHA-384 | Optional |
| ES512 | ECDSA using P-521 and SHA-512 | Optional |
| PS256 | RSASSA-PSS using SHA-256 and MGF1 with SHA-256 | Optional |
| PS384 | RSASSA-PSS using SHA-384 and MGF1 with SHA-384 | Optional |
| PS512 | RSASSA-PSS using SHA-512 and MGF1 with SHA-512 | Optional |
| none | No digital signature or MAC performed | Optional |
Note: The "+" in the Implementation Requirements column indicates that the requirement strength may be increased in future versions of the specification.
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 algorithm is defined in RFC 2104 [RFC2104].
Key Requirements: A key of the same size as the hash output (for instance, 256 bits for "HS256") or larger MUST be used with this algorithm.
HMAC Algorithm Values:
| "alg" Param Value | MAC Algorithm |
|---|---|
| HS256 | HMAC using SHA-256 |
| HS384 | HMAC using SHA-384 |
| HS512 | HMAC using SHA-512 |
Validation Requirements: The comparison of HMAC values MUST be performed in constant time to prevent timing attacks.
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] with the SHA-2 hash functions.
Key Requirements: A key of size 2048 bits or larger MUST be used with this algorithm.
Algorithm Values:
| "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 |
3.4 Digital Signature with ECDSA
The Elliptic Curve Digital Signature Algorithm (ECDSA) [DSS] uses elliptic curve cryptography, providing equivalent security to RSA with shorter key lengths and faster processing.
Supported Curves and Hash Functions:
- P-256 curve with SHA-256
- P-384 curve with SHA-384
- P-521 curve with SHA-512
ECDSA P-256 SHA-256 Signature Generation Steps:
- Generate a digital signature of the JWS Signing Input using ECDSA P-256 SHA-256 with the private key, producing an (R, S) pair, each a 256-bit unsigned integer
- Convert R and S to octet sequences in big-endian order, each 32 octets long
- Concatenate the two octet sequences in the order R then S
- The resulting 64-octet sequence is the JWS Signature value
Algorithm Values:
| "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 |
Signature Lengths:
- ES256: 64 octets (R and S are each 32 octets)
- ES384: 96 octets (R and S are each 48 octets)
- ES512: 132 octets (R and S are each 66 octets)
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.
Key Parameters:
- The RSASSA-PSS hash function and MGF1 hash function use the same hash function
- The salt value size equals the hash function output size
- Key size requirement: 2048 bits or larger
Algorithm Values:
| "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 |
3.6 Using the Algorithm "none"
The JWS specification [JWS] defines the "alg" value "none" for use in creating Unsecured JWS objects that provide no integrity protection.
Security Warning: Implementations MUST understand the security implications of using this algorithm. The "alg" value "none" SHOULD only be used when integrity protection is not needed.