draft-ietf-jose-json-web-algorithms-31.txt   draft-ietf-jose-json-web-algorithms-32.txt 
JOSE Working Group M. Jones JOSE Working Group M. Jones
Internet-Draft Microsoft Internet-Draft Microsoft
Intended status: Standards Track July 4, 2014 Intended status: Standards Track September 23, 2014
Expires: January 5, 2015 Expires: March 27, 2015
JSON Web Algorithms (JWA) JSON Web Algorithms (JWA)
draft-ietf-jose-json-web-algorithms-31 draft-ietf-jose-json-web-algorithms-32
Abstract Abstract
The JSON Web Algorithms (JWA) specification registers cryptographic The JSON Web Algorithms (JWA) specification registers cryptographic
algorithms and identifiers to be used with the JSON Web Signature algorithms and identifiers to be used with the JSON Web Signature
(JWS), JSON Web Encryption (JWE), and JSON Web Key (JWK) (JWS), JSON Web Encryption (JWE), and JSON Web Key (JWK)
specifications. It defines several IANA registries for these specifications. It defines several IANA registries for these
identifiers. identifiers.
Status of this Memo Status of this Memo
skipping to change at page 1, line 34 skipping to change at page 1, line 34
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on January 5, 2015. This Internet-Draft will expire on March 27, 2015.
Copyright Notice Copyright Notice
Copyright (c) 2014 IETF Trust and the persons identified as the Copyright (c) 2014 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 3, line 17 skipping to change at page 3, line 17
6.2.1.2. "x" (X Coordinate) Parameter . . . . . . . . . . . 29 6.2.1.2. "x" (X Coordinate) Parameter . . . . . . . . . . . 29
6.2.1.3. "y" (Y Coordinate) Parameter . . . . . . . . . . . 29 6.2.1.3. "y" (Y Coordinate) Parameter . . . . . . . . . . . 29
6.2.2. Parameters for Elliptic Curve Private Keys . . . . . . 29 6.2.2. Parameters for Elliptic Curve Private Keys . . . . . . 29
6.2.2.1. "d" (ECC Private Key) Parameter . . . . . . . . . 29 6.2.2.1. "d" (ECC Private Key) Parameter . . . . . . . . . 29
6.3. Parameters for RSA Keys . . . . . . . . . . . . . . . . . 29 6.3. Parameters for RSA Keys . . . . . . . . . . . . . . . . . 29
6.3.1. Parameters for RSA Public Keys . . . . . . . . . . . . 30 6.3.1. Parameters for RSA Public Keys . . . . . . . . . . . . 30
6.3.1.1. "n" (Modulus) Parameter . . . . . . . . . . . . . 30 6.3.1.1. "n" (Modulus) Parameter . . . . . . . . . . . . . 30
6.3.1.2. "e" (Exponent) Parameter . . . . . . . . . . . . . 30 6.3.1.2. "e" (Exponent) Parameter . . . . . . . . . . . . . 30
6.3.2. Parameters for RSA Private Keys . . . . . . . . . . . 30 6.3.2. Parameters for RSA Private Keys . . . . . . . . . . . 30
6.3.2.1. "d" (Private Exponent) Parameter . . . . . . . . . 30 6.3.2.1. "d" (Private Exponent) Parameter . . . . . . . . . 30
6.3.2.2. "p" (First Prime Factor) Parameter . . . . . . . . 30 6.3.2.2. "p" (First Prime Factor) Parameter . . . . . . . . 31
6.3.2.3. "q" (Second Prime Factor) Parameter . . . . . . . 31 6.3.2.3. "q" (Second Prime Factor) Parameter . . . . . . . 31
6.3.2.4. "dp" (First Factor CRT Exponent) Parameter . . . . 31 6.3.2.4. "dp" (First Factor CRT Exponent) Parameter . . . . 31
6.3.2.5. "dq" (Second Factor CRT Exponent) Parameter . . . 31 6.3.2.5. "dq" (Second Factor CRT Exponent) Parameter . . . 31
6.3.2.6. "qi" (First CRT Coefficient) Parameter . . . . . . 31 6.3.2.6. "qi" (First CRT Coefficient) Parameter . . . . . . 31
6.3.2.7. "oth" (Other Primes Info) Parameter . . . . . . . 31 6.3.2.7. "oth" (Other Primes Info) Parameter . . . . . . . 32
6.4. Parameters for Symmetric Keys . . . . . . . . . . . . . . 32 6.4. Parameters for Symmetric Keys . . . . . . . . . . . . . . 32
6.4.1. "k" (Key Value) Parameter . . . . . . . . . . . . . . 32 6.4.1. "k" (Key Value) Parameter . . . . . . . . . . . . . . 33
7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 32 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 33
7.1. JSON Web Signature and Encryption Algorithms Registry . . 33 7.1. JSON Web Signature and Encryption Algorithms Registry . . 34
7.1.1. Registration Template . . . . . . . . . . . . . . . . 34 7.1.1. Registration Template . . . . . . . . . . . . . . . . 34
7.1.2. Initial Registry Contents . . . . . . . . . . . . . . 35 7.1.2. Initial Registry Contents . . . . . . . . . . . . . . 35
7.2. Header Parameter Names Registration . . . . . . . . . . . 41 7.2. Header Parameter Names Registration . . . . . . . . . . . 41
7.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 41 7.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 41
7.3. JSON Web Encryption Compression Algorithms Registry . . . 42 7.3. JSON Web Encryption Compression Algorithms Registry . . . 42
7.3.1. Registration Template . . . . . . . . . . . . . . . . 42 7.3.1. Registration Template . . . . . . . . . . . . . . . . 42
7.3.2. Initial Registry Contents . . . . . . . . . . . . . . 42 7.3.2. Initial Registry Contents . . . . . . . . . . . . . . 43
7.4. JSON Web Key Types Registry . . . . . . . . . . . . . . . 43 7.4. JSON Web Key Types Registry . . . . . . . . . . . . . . . 43
7.4.1. Registration Template . . . . . . . . . . . . . . . . 43 7.4.1. Registration Template . . . . . . . . . . . . . . . . 43
7.4.2. Initial Registry Contents . . . . . . . . . . . . . . 44 7.4.2. Initial Registry Contents . . . . . . . . . . . . . . 44
7.5. JSON Web Key Parameters Registration . . . . . . . . . . . 44 7.5. JSON Web Key Parameters Registration . . . . . . . . . . . 44
7.5.1. Registry Contents . . . . . . . . . . . . . . . . . . 44 7.5.1. Registry Contents . . . . . . . . . . . . . . . . . . 44
7.6. JSON Web Key Elliptic Curve Registry . . . . . . . . . . . 46 7.6. JSON Web Key Elliptic Curve Registry . . . . . . . . . . . 47
7.6.1. Registration Template . . . . . . . . . . . . . . . . 47 7.6.1. Registration Template . . . . . . . . . . . . . . . . 47
7.6.2. Initial Registry Contents . . . . . . . . . . . . . . 47 7.6.2. Initial Registry Contents . . . . . . . . . . . . . . 48
8. Security Considerations . . . . . . . . . . . . . . . . . . . 48 8. Security Considerations . . . . . . . . . . . . . . . . . . . 48
8.1. Algorithms and Key Sizes will be Deprecated . . . . . . . 48 8.1. Cryptographic Agility . . . . . . . . . . . . . . . . . . 48
8.2. Key Lifetimes . . . . . . . . . . . . . . . . . . . . . . 48 8.2. Key Lifetimes . . . . . . . . . . . . . . . . . . . . . . 49
8.3. RSAES-PKCS1-v1_5 Security Considerations . . . . . . . . . 49 8.3. RSAES-PKCS1-v1_5 Security Considerations . . . . . . . . . 49
8.4. AES GCM Security Considerations . . . . . . . . . . . . . 49 8.4. AES GCM Security Considerations . . . . . . . . . . . . . 49
8.5. Plaintext JWS Security Considerations . . . . . . . . . . 49 8.5. Unsecured JWS Security Considerations . . . . . . . . . . 49
8.6. Denial of Service Attacks . . . . . . . . . . . . . . . . 50 8.6. Denial of Service Attacks . . . . . . . . . . . . . . . . 50
8.7. Reusing Key Material when Encrypting Keys . . . . . . . . 50 8.7. Reusing Key Material when Encrypting Keys . . . . . . . . 50
8.8. Password Considerations . . . . . . . . . . . . . . . . . 50 8.8. Password Considerations . . . . . . . . . . . . . . . . . 51
8.9. Key Entropy . . . . . . . . . . . . . . . . . . . . . . . 51 8.9. Key Entropy and Random Values . . . . . . . . . . . . . . 51
8.10. Differences between Digital Signatures and MACs . . . . . 51 8.10. Differences between Digital Signatures and MACs . . . . . 51
8.11. Using Matching Algorithm Strengths . . . . . . . . . . . . 51 8.11. Using Matching Algorithm Strengths . . . . . . . . . . . . 51
8.12. Adaptive Chosen-Ciphertext Attacks . . . . . . . . . . . . 51 8.12. Adaptive Chosen-Ciphertext Attacks . . . . . . . . . . . . 52
8.13. Timing Attacks . . . . . . . . . . . . . . . . . . . . . . 51 8.13. Timing Attacks . . . . . . . . . . . . . . . . . . . . . . 52
8.14. RSA Private Key Representations and Blinding . . . . . . . 51 8.14. RSA Private Key Representations and Blinding . . . . . . . 52
9. Internationalization Considerations . . . . . . . . . . . . . 52 9. Internationalization Considerations . . . . . . . . . . . . . 52
10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 52 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 52
10.1. Normative References . . . . . . . . . . . . . . . . . . . 52 10.1. Normative References . . . . . . . . . . . . . . . . . . . 52
10.2. Informative References . . . . . . . . . . . . . . . . . . 54 10.2. Informative References . . . . . . . . . . . . . . . . . . 54
Appendix A. Algorithm Identifier Cross-Reference . . . . . . . . 55 Appendix A. Algorithm Identifier Cross-Reference . . . . . . . . 56
A.1. Digital Signature/MAC Algorithm Identifier A.1. Digital Signature/MAC Algorithm Identifier
Cross-Reference . . . . . . . . . . . . . . . . . . . . . 56 Cross-Reference . . . . . . . . . . . . . . . . . . . . . 56
A.2. Key Management Algorithm Identifier Cross-Reference . . . 56 A.2. Key Management Algorithm Identifier Cross-Reference . . . 57
A.3. Content Encryption Algorithm Identifier Cross-Reference . 57 A.3. Content Encryption Algorithm Identifier Cross-Reference . 57
Appendix B. Test Cases for AES_CBC_HMAC_SHA2 Algorithms . . . . . 58 Appendix B. Test Cases for AES_CBC_HMAC_SHA2 Algorithms . . . . . 58
B.1. Test Cases for AES_128_CBC_HMAC_SHA_256 . . . . . . . . . 59 B.1. Test Cases for AES_128_CBC_HMAC_SHA_256 . . . . . . . . . 59
B.2. Test Cases for AES_192_CBC_HMAC_SHA_384 . . . . . . . . . 60 B.2. Test Cases for AES_192_CBC_HMAC_SHA_384 . . . . . . . . . 60
B.3. Test Cases for AES_256_CBC_HMAC_SHA_512 . . . . . . . . . 61 B.3. Test Cases for AES_256_CBC_HMAC_SHA_512 . . . . . . . . . 61
Appendix C. Example ECDH-ES Key Agreement Computation . . . . . . 62 Appendix C. Example ECDH-ES Key Agreement Computation . . . . . . 62
Appendix D. Acknowledgements . . . . . . . . . . . . . . . . . . 64 Appendix D. Acknowledgements . . . . . . . . . . . . . . . . . . 64
Appendix E. Document History . . . . . . . . . . . . . . . . . . 65 Appendix E. Document History . . . . . . . . . . . . . . . . . . 65
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 74 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 75
1. Introduction 1. Introduction
The JSON Web Algorithms (JWA) specification registers cryptographic The JSON Web Algorithms (JWA) specification registers cryptographic
algorithms and identifiers to be used with the JSON Web Signature algorithms and identifiers to be used with the JSON Web Signature
(JWS) [JWS], JSON Web Encryption (JWE) [JWE], and JSON Web Key (JWK) (JWS) [JWS], JSON Web Encryption (JWE) [JWE], and JSON Web Key (JWK)
[JWK] specifications. It defines several IANA registries for these [JWK] specifications. It defines several IANA registries for these
identifiers. All these specifications utilize JavaScript Object identifiers. All these specifications utilize JavaScript Object
Notation (JSON) [RFC7159] based data structures. This specification Notation (JSON) [RFC7159] based data structures. This specification
also describes the semantics and operations that are specific to also describes the semantics and operations that are specific to
skipping to change at page 6, line 4 skipping to change at page 6, line 4
representation of STRING. representation of STRING.
The concatenation of two values A and B is denoted as A || B. The concatenation of two values A and B is denoted as A || B.
2. Terminology 2. Terminology
These terms defined by the JSON Web Signature (JWS) [JWS] These terms defined by the JSON Web Signature (JWS) [JWS]
specification are incorporated into this specification: "JSON Web specification are incorporated into this specification: "JSON Web
Signature (JWS)", "Base64url Encoding", "Header Parameter", "JOSE Signature (JWS)", "Base64url Encoding", "Header Parameter", "JOSE
Header", "JWS Payload", "JWS Protected Header", "JWS Signature", "JWS Header", "JWS Payload", "JWS Protected Header", "JWS Signature", "JWS
Signing Input", and "Plaintext JWS". Signing Input", and "Unsecured JWS".
These terms defined by the JSON Web Encryption (JWE) [JWE] These terms defined by the JSON Web Encryption (JWE) [JWE]
specification are incorporated into this specification: "JSON Web specification are incorporated into this specification: "JSON Web
Encryption (JWE)", "Additional Authenticated Data (AAD)", Encryption (JWE)", "Additional Authenticated Data (AAD)",
"Authentication Tag", "Ciphertext", "Content Encryption Key (CEK)", "Authentication Tag", "Ciphertext", "Content Encryption Key (CEK)",
"Direct Encryption", "Direct Key Agreement", "JWE Authentication "Direct Encryption", "Direct Key Agreement", "JWE Authentication
Tag", "JWE Ciphertext", "JWE Encrypted Key", "JWE Initialization Tag", "JWE Ciphertext", "JWE Encrypted Key", "JWE Initialization
Vector", "JWE Protected Header", "Key Agreement with Key Wrapping", Vector", "JWE Protected Header", "Key Agreement with Key Wrapping",
"Key Encryption", "Key Management Mode", "Key Wrapping", and "Key Encryption", "Key Management Mode", "Key Wrapping", and
"Plaintext". "Plaintext".
skipping to change at page 9, line 18 skipping to change at page 9, line 18
procedure for RSASSA-PKCS1-V1_5 SHA-256 -- just using the procedure for RSASSA-PKCS1-V1_5 SHA-256 -- just using the
corresponding hash algorithms instead of SHA-256. corresponding hash algorithms instead of SHA-256.
An example using this algorithm is shown in Appendix A.2 of [JWS]. An example using this algorithm is shown in Appendix A.2 of [JWS].
3.4. Digital Signature with ECDSA 3.4. Digital Signature with ECDSA
The Elliptic Curve Digital Signature Algorithm (ECDSA) [DSS] provides The Elliptic Curve Digital Signature Algorithm (ECDSA) [DSS] provides
for the use of Elliptic Curve cryptography, which is able to provide for the use of Elliptic Curve cryptography, which is able to provide
equivalent security to RSA cryptography but using shorter key sizes equivalent security to RSA cryptography but using shorter key sizes
and with greater processing speed. This means that ECDSA digital and with greater processing speed for many operations. This means
signatures will be substantially smaller in terms of length than that ECDSA digital signatures will be substantially smaller in terms
equivalently strong RSA digital signatures. of length than equivalently strong RSA digital signatures.
This specification defines the use of ECDSA with the P-256 curve and 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 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 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 SHA-512 hash function. The P-256, P-384, and P-521 curves are
defined in [DSS]. defined in [DSS].
The ECDSA P-256 SHA-256 digital signature is generated as follows: The ECDSA P-256 SHA-256 digital signature is generated as follows:
1. Generate a digital signature of the JWS Signing Input using ECDSA 1. Generate a digital signature of the JWS Signing Input using ECDSA
skipping to change at page 11, line 37 skipping to change at page 11, line 37
using MGF1 as the mask generation function with SHA-256. using MGF1 as the mask generation function with SHA-256.
Signing and validation with the RSASSA-PSS SHA-384 and RSASSA-PSS Signing and validation with the RSASSA-PSS SHA-384 and RSASSA-PSS
SHA-512 algorithms is performed identically to the procedure for SHA-512 algorithms is performed identically to the procedure for
RSASSA-PSS SHA-256 -- just using the alternative hash algorithm in RSASSA-PSS SHA-256 -- just using the alternative hash algorithm in
both roles. both roles.
3.6. Using the Algorithm "none" 3.6. Using the Algorithm "none"
JWSs MAY also be created that do not provide integrity protection. JWSs MAY also be created that do not provide integrity protection.
Such a JWS is called a "Plaintext JWS". A Plaintext JWS MUST use the Such a JWS is called an Unsecured JWS. An Unsecured JWS MUST use the
"alg" value "none", and is formatted identically to other JWSs, but "alg" value "none", and is formatted identically to other JWSs, but
MUST use the empty octet sequence as its JWS Signature value. MUST use the empty octet sequence as its JWS Signature value.
Receivers MUST verify that the JWS Signature value is the empty octet Receivers MUST verify that the JWS Signature value is the empty octet
sequence. See Section 8.5 for security considerations associated sequence. See Section 8.5 for security considerations associated
with using this algorithm. with using this algorithm.
4. Cryptographic Algorithms for Key Management 4. Cryptographic Algorithms for Key Management
JWE uses cryptographic algorithms to encrypt or determine the Content JWE uses cryptographic algorithms to encrypt or determine the Content
Encryption Key (CEK). Encryption Key (CEK).
skipping to change at page 19, line 50 skipping to change at page 19, line 50
4.7.1.2. "tag" (Authentication Tag) Header Parameter 4.7.1.2. "tag" (Authentication Tag) Header Parameter
The "tag" (authentication tag) Header Parameter value is the The "tag" (authentication tag) Header Parameter value is the
base64url encoded representation of the Authentication Tag value base64url encoded representation of the Authentication Tag value
resulting from the key encryption operation. This Header Parameter resulting from the key encryption operation. This Header Parameter
MUST be present and MUST be understood and processed by MUST be present and MUST be understood and processed by
implementations when these algorithms are used. implementations when these algorithms are used.
4.8. Key Encryption with PBES2 4.8. Key Encryption with PBES2
This section defines the specifies of performing password-based This section defines the specifics of performing password-based
encryption of a JWE CEK, by first deriving a key encryption key from encryption of a JWE CEK, by first deriving a key encryption key from
a user-supplied password using PBES2 schemes as specified in Section a user-supplied password using PBES2 schemes as specified in Section
6.2 of [RFC2898], then by encrypting the JWE CEK using the derived 6.2 of [RFC2898], then by encrypting the JWE CEK using the derived
key. key.
These algorithms use HMAC SHA-2 algorithms as the Pseudo-Random These algorithms use HMAC SHA-2 algorithms as the Pseudo-Random
Function (PRF) for the PBKDF2 key derivation and AES Key Wrap Function (PRF) for the PBKDF2 key derivation and AES Key Wrap
[RFC3394] for the encryption scheme. The PBES2 password input is an [RFC3394] for the encryption scheme. The PBES2 password input is an
octet sequence; if the password to be used is represented as a text 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 rather than an octet sequence, the UTF-8 encoding of the text
skipping to change at page 23, line 16 skipping to change at page 23, line 16
#7 padding using the cipher with the key X. #7 padding using the cipher with the key X.
MAC(Y, M) denotes the application of the Message Authentication MAC(Y, M) denotes the application of the Message Authentication
Code (MAC) to the message M, using the key Y. Code (MAC) to the message M, using the key Y.
5.2.2. Generic AES_CBC_HMAC_SHA2 Algorithm 5.2.2. Generic AES_CBC_HMAC_SHA2 Algorithm
This section defines AES_CBC_HMAC_SHA2 in a manner that is 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. independent of the AES CBC key size or hash function to be used.
Section 5.2.2.1 and Section 5.2.2.2 define the generic encryption and Section 5.2.2.1 and Section 5.2.2.2 define the generic encryption and
decryption algorithms. Section 5.2.3 and Section 5.2.5 define decryption algorithms. Sections 5.2.3 through 5.2.5 define instances
instances of AES_CBC_HMAC_SHA2 that specify those details. of AES_CBC_HMAC_SHA2 that specify those details.
5.2.2.1. AES_CBC_HMAC_SHA2 Encryption 5.2.2.1. AES_CBC_HMAC_SHA2 Encryption
The authenticated encryption algorithm takes as input four octet The authenticated encryption algorithm takes as input four octet
strings: a secret key K, a plaintext P, additional authenticated data strings: a secret key K, a plaintext P, additional authenticated data
A, and an initialization vector IV. The authenticated ciphertext A, and an initialization vector IV. The authenticated ciphertext
value E and the authentication tag value T are provided as outputs. value E and the authentication tag value T are provided as outputs.
The data in the plaintext are encrypted and authenticated, and the The data in the plaintext are encrypted and authenticated, and the
additional authenticated data are authenticated, but not encrypted. additional authenticated data are authenticated, but not encrypted.
skipping to change at page 23, line 43 skipping to change at page 23, line 43
string. string.
MAC_KEY consists of the initial MAC_KEY_LEN octets of K, in MAC_KEY consists of the initial MAC_KEY_LEN octets of K, in
order. order.
ENC_KEY consists of the final ENC_KEY_LEN octets of K, in ENC_KEY consists of the final ENC_KEY_LEN octets of K, in
order. order.
Here we denote the number of octets in the MAC_KEY as Here we denote the number of octets in the MAC_KEY as
MAC_KEY_LEN, and the number of octets in ENC_KEY as ENC_KEY_LEN; MAC_KEY_LEN, and the number of octets in ENC_KEY as ENC_KEY_LEN;
the values of these parameters are specified by the AEAD the values of these parameters are specified by the Authenticated
algorithms (in Section 5.2.3 and Section 5.2.5). The number of Encryption algorithms in Sections 5.2.3 through 5.2.5. The
octets in the input key K is the sum of MAC_KEY_LEN and number of octets in the input key K MUST be the sum of
ENC_KEY_LEN. When generating the secondary keys from K, MAC_KEY MAC_KEY_LEN and ENC_KEY_LEN. When generating the secondary keys
and ENC_KEY MUST NOT overlap. Note that the MAC key comes before from K, MAC_KEY and ENC_KEY MUST NOT overlap. Note that the MAC
the encryption key in the input key K; this is in the opposite key comes before the encryption key in the input key K; this is
order of the algorithm names in the identifier in the opposite order of the algorithm names in the identifier
"AES_CBC_HMAC_SHA2". "AES_CBC_HMAC_SHA2".
2. The Initialization Vector (IV) used is a 128 bit value generated 2. The Initialization Vector (IV) used is a 128 bit value generated
randomly or pseudorandomly for use in the cipher. randomly or pseudorandomly for use in the cipher.
3. The plaintext is CBC encrypted using PKCS #7 padding using 3. The plaintext is CBC encrypted using PKCS #7 padding using
ENC_KEY as the key, and the IV. We denote the ciphertext output ENC_KEY as the key, and the IV. We denote the ciphertext output
from this step as E. from this step as E.
4. The octet string AL is equal to the number of bits in A expressed 4. The octet string AL is equal to the number of bits in the
as a 64-bit unsigned integer in network byte order. additional authenticated data A expressed as a 64-bit unsigned
big endian integer.
5. A message authentication tag T is computed by applying HMAC 5. A message authentication tag T is computed by applying HMAC
[RFC2104] to the following data, in order: [RFC2104] to the following data, in order:
the additional authenticated data A, the additional authenticated data A,
the initialization vector IV, the initialization vector IV,
the ciphertext E computed in the previous step, and the ciphertext E computed in the previous step, and
skipping to change at page 24, line 37 skipping to change at page 24, line 38
of the MAC computed in this step as M. The first T_LEN bits of M of the MAC computed in this step as M. The first T_LEN bits of M
are used as T. are used as T.
6. The Ciphertext E and the Authentication Tag T are returned as the 6. The Ciphertext E and the Authentication Tag T are returned as the
outputs of the authenticated encryption. outputs of the authenticated encryption.
The encryption process can be illustrated as follows. Here K, P, A, The encryption process can be illustrated as follows. Here K, P, A,
IV, and E denote the key, plaintext, additional authenticated data, IV, and E denote the key, plaintext, additional authenticated data,
initialization vector, and ciphertext, respectively. initialization vector, and ciphertext, respectively.
MAC_KEY = initial MAC_KEY_LEN bytes of K, MAC_KEY = initial MAC_KEY_LEN octets of K,
ENC_KEY = final ENC_KEY_LEN bytes of K, ENC_KEY = final ENC_KEY_LEN octets of K,
E = CBC-PKCS5-ENC(ENC_KEY, P), E = CBC-PKCS5-ENC(ENC_KEY, P),
M = MAC(MAC_KEY, A || IV || E || AL), M = MAC(MAC_KEY, A || IV || E || AL),
T = initial T_LEN bytes of M. T = initial T_LEN octets of M.
5.2.2.2. AES_CBC_HMAC_SHA2 Decryption 5.2.2.2. AES_CBC_HMAC_SHA2 Decryption
The authenticated decryption operation has four inputs: K, A, E, and The authenticated decryption operation has five inputs: K, A, IV, E,
T as defined above. It has only a single output, either a plaintext and T as defined above. It has only a single output, either a
value P or a special symbol FAIL that indicates that the inputs are plaintext value P or a special symbol FAIL that indicates that the
not authentic. The authenticated decryption algorithm is as follows, inputs are not authentic. The authenticated decryption algorithm is
or uses an equivalent set of steps: as follows, or uses an equivalent set of steps:
1. The secondary keys MAC_KEY and ENC_KEY are generated from the 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. 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 2. The integrity and authenticity of A and E are checked by
computing an HMAC with the inputs as in Step 5 of computing an HMAC with the inputs as in Step 5 of
Section 5.2.2.1. The value T, from the previous step, is 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 compared to the first MAC_KEY length bits of the HMAC output. If
those values are identical, then A and E are considered valid, those values are identical, then A and E are considered valid,
and processing is continued. Otherwise, all of the data used in and processing is continued. Otherwise, all of the data used in
the MAC validation are discarded, and the AEAD decryption the MAC validation are discarded, and the Authenticated
operation returns an indication that it failed, and the operation Encryption decryption operation returns an indication that it
halts. (But see Section 11.2 of [JWE] for security failed, and the operation halts. (But see Section 11.5 of [JWE]
considerations on thwarting timing attacks.) for security considerations on thwarting timing attacks.)
3. The value E is decrypted and the PKCS #7 padding is removed. The 3. The value E is decrypted and the PKCS #7 padding is removed. The
value IV is used as the initialization vector. The value ENC_KEY value IV is used as the initialization vector. The value ENC_KEY
is used as the decryption key. is used as the decryption key.
4. The plaintext value is returned. 4. The plaintext value is returned.
5.2.3. AES_128_CBC_HMAC_SHA_256 5.2.3. AES_128_CBC_HMAC_SHA_256
This algorithm is a concrete instantiation of the generic This algorithm is a concrete instantiation of the generic
skipping to change at page 29, line 8 skipping to change at page 29, line 8
6.2.1.1. "crv" (Curve) Parameter 6.2.1.1. "crv" (Curve) Parameter
The "crv" (curve) member identifies the cryptographic curve used with The "crv" (curve) member identifies the cryptographic curve used with
the key. Curve values from [DSS] used by this specification are: the key. Curve values from [DSS] used by this specification are:
o "P-256" o "P-256"
o "P-384" o "P-384"
o "P-521" o "P-521"
These values are registered in the IANA JSON Web Key Elliptic Curve These values are registered in the IANA JSON Web Key Elliptic Curve
registry defined in Section 7.6. Additional "crv" values MAY be registry defined in Section 7.6. Additional "crv" values can be
registered by other specifications. Additional "crv" values MAY be
used, provided they are understood by implementations using that used, provided they are understood by implementations using that
Elliptic Curve key. The "crv" value is a case-sensitive string. Elliptic Curve key. The "crv" value is a case-sensitive string.
6.2.1.2. "x" (X Coordinate) Parameter 6.2.1.2. "x" (X Coordinate) Parameter
The "x" (x coordinate) member contains the x coordinate for the The "x" (x coordinate) member contains the x coordinate for the
elliptic curve point. It is represented as the base64url encoding of elliptic curve point. It is represented as the base64url encoding of
the octet string representation of the coordinate, as defined in the octet string representation of the coordinate, as defined in
Section 2.3.5 of SEC1 [SEC1]. The length of this octet string MUST 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" be the full size of a coordinate for the curve specified in the "crv"
skipping to change at page 30, line 17 skipping to change at page 30, line 17
The following members MUST be present for RSA public keys. The following members MUST be present for RSA public keys.
6.3.1.1. "n" (Modulus) Parameter 6.3.1.1. "n" (Modulus) Parameter
The "n" (modulus) member contains the modulus value for the RSA The "n" (modulus) member contains the modulus value for the RSA
public key. It is represented as the base64url encoding of the public key. It is represented as the base64url encoding of the
value's unsigned big endian representation as an octet sequence. The value's unsigned big endian representation as an octet sequence. The
octet sequence MUST utilize the minimum number of octets to represent octet sequence MUST utilize the minimum number of octets to represent
the value. the 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 6.3.1.2. "e" (Exponent) Parameter
The "e" (exponent) member contains the exponent value for the RSA The "e" (exponent) member contains the exponent value for the RSA
public key. It is represented as the base64url encoding of the public key. It is represented as the base64url encoding of the
value's unsigned big endian representation as an octet sequence. The value's unsigned big endian representation as an octet sequence. The
octet sequence MUST utilize the minimum number of octets to represent octet sequence MUST utilize the minimum number of octets to represent
the value. For instance, when representing the value 65537, the the value. For instance, when representing the value 65537, the
octet sequence to be base64url encoded MUST consist of the three octet sequence to be base64url encoded MUST consist of the three
octets [1, 0, 1]. octets [1, 0, 1].
skipping to change at page 48, line 24 skipping to change at page 48, line 41
o Curve Description: P-521 curve o Curve Description: P-521 curve
o JOSE Implementation Requirements: Optional o JOSE Implementation Requirements: Optional
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): Section 6.2.1.1 of [[ this document ]] o Specification Document(s): Section 6.2.1.1 of [[ this document ]]
8. Security Considerations 8. Security Considerations
All of the security issues that are pertinent to any cryptographic All of the security issues that are pertinent to any cryptographic
application must be addressed by JWS/JWE/JWK agents. Among these application must be addressed by JWS/JWE/JWK agents. Among these
issues are protecting the user's asymmetric private and symmetric issues are protecting the user's asymmetric private and symmetric
secret keys, preventing various attacks, and helping avoid mistakes secret keys and employing countermeasures to various attacks.
such as inadvertently encrypting a message to the wrong recipient.
The entire list of security considerations is beyond the scope of
this document, but some significant considerations are listed here.
The security considerations in [AES], [DSS], [JWE], [JWK], [JWS], The security considerations in [AES], [DSS], [JWE], [JWK], [JWS],
[NIST.800-38A], [NIST.800-38D], [NIST.800-56A], [RFC2104], [RFC3394], [NIST.800-38A], [NIST.800-38D], [NIST.800-56A], [RFC2104], [RFC3394],
[RFC3447], [RFC5116], [RFC6090], and [SHS] apply to this [RFC3447], [RFC5116], [RFC6090], and [SHS] apply to this
specification. specification.
8.1. Algorithms and Key Sizes will be Deprecated 8.1. Cryptographic Agility
Eventually the algorithms and/or key sizes currently described in Implementers should be aware that cryptographic algorithms become
this specification will no longer be considered sufficiently secure weaker with time. As new cryptanalysis techniques are developed and
and will be deprecated. Therefore, implementers and deployments must computing performance improves, the work factor to break a particular
be prepared for this eventuality. cryptographic algorithm will be reduced. Therefore, implementers and
deployments must be prepared for the set of algorithms that are
supported and used to change over time. Thus, cryptographic
algorithm implementations should be modular, allowing new algorithms
to be readily inserted.
8.2. Key Lifetimes 8.2. Key Lifetimes
Many algorithms have associated security considerations related to Many algorithms have associated security considerations related to
key lifetimes and/or the number of times that a key may be used. key lifetimes and/or the number of times that a key may be used.
Those security considerations continue to apply when using those Those security considerations continue to apply when using those
algorithms with JOSE data structures. See NIST SP 800-57 algorithms with JOSE data structures. See NIST SP 800-57
[NIST.800-57] for specific guidance on key lifetimes. [NIST.800-57] for specific guidance on key lifetimes.
8.3. RSAES-PKCS1-v1_5 Security Considerations 8.3. RSAES-PKCS1-v1_5 Security Considerations
skipping to change at page 49, line 34 skipping to change at page 49, line 48
MUST NOT be used with the same key value more than 2^32 times. MUST NOT be used with the same key value more than 2^32 times.
An Initialization Vector value MUST never be used multiple times with An Initialization Vector value MUST never be used multiple times with
the same AES GCM key. One way to prevent this is to store a counter the same AES GCM key. One way to prevent this is to store a counter
with the key and increment it with every use. The counter can also with the key and increment it with every use. The counter can also
be used to prevent exceeding the 2^32 limit above. be used to prevent exceeding the 2^32 limit above.
This security consideration does not apply to the composite AES-CBC This security consideration does not apply to the composite AES-CBC
HMAC SHA-2 or AES Key Wrap algorithms. HMAC SHA-2 or AES Key Wrap algorithms.
8.5. Plaintext JWS Security Considerations 8.5. Unsecured JWS Security Considerations
Plaintext JWSs (JWSs that use the "alg" value "none") provide no Unsecured JWSs (JWSs that use the "alg" value "none") provide no
integrity protection. Thus, they must only be used in contexts where integrity protection. Thus, they must only be used in contexts in
the payload is secured by means other than a digital signature or MAC which the payload is secured by means other than a digital signature
value, or need not be secured. or MAC value, or need not be secured.
Implementations that support Plaintext JWS objects MUST NOT accept Implementations that support Unsecured JWS objects MUST NOT accept
such objects as valid unless the application specifies that it is such objects as valid unless the application specifies that it is
acceptable for a specific object to not be integrity-protected. acceptable for a specific object to not be integrity-protected.
Implementations MUST NOT accept Plaintext JWS objects by default. Implementations MUST NOT accept Unsecured JWS objects by default.
For example, the "verify" method of a hypothetical JWS software For example, the "verify" method of a hypothetical JWS software
library might have a Boolean "acceptUnsigned" parameter that library might have a Boolean "acceptUnsigned" parameter that
indicates "none" is an acceptable "alg" value. As another example, indicates "none" is an acceptable "alg" value. As another example,
the "verify" method might take a list of algorithms that are the "verify" method might take a list of algorithms that are
acceptable to the application as a parameter and would reject acceptable to the application as a parameter and would reject
Plaintext JWS values if "none" is not in that list. Unsecured JWS values if "none" is not in that list.
In order to mitigate downgrade attacks, applications MUST NOT signal In order to mitigate downgrade attacks, applications MUST NOT signal
acceptance of Plaintext JWS objects at a global level, and SHOULD acceptance of Unsecured JWS objects at a global level, and SHOULD
signal acceptance on a per-object basis. For example, suppose an signal acceptance on a per-object basis. For example, suppose an
application accepts JWS objects over two channels, (1) HTTP and (2) application accepts JWS objects over two channels, (1) HTTP and (2)
HTTPS with client authentication. It requires a JWS signature on HTTPS with client authentication. It requires a JWS signature on
objects received over HTTP, but accepts Plaintext JWS objects over objects received over HTTP, but accepts Unsecured JWS objects over
HTTPS. If the application were to globally indicate that "none" is HTTPS. If the application were to globally indicate that "none" is
acceptable, then an attacker could provide it with an unsigned object acceptable, then an attacker could provide it with an unsigned object
over HTTP and still have that object successfully validate. Instead, over HTTP and still have that object successfully validate. Instead,
the application needs to indicate acceptance of "none" for each the application needs to indicate acceptance of "none" for each
object received over HTTPS (e.g., by setting "acceptUnsigned" to object received over HTTPS (e.g., by setting "acceptUnsigned" to
"true" for the first hypothetical JWS software library above), but "true" for the first hypothetical JWS software library above), but
not for each object received over HTTP. not for each object received over HTTP.
8.6. Denial of Service Attacks 8.6. Denial of Service Attacks
skipping to change at page 50, line 36 skipping to change at page 50, line 51
element. Agents that use such keys without first validating the element. Agents that use such keys without first validating the
certificate to a trust anchor are advised to have some sort of certificate to a trust anchor are advised to have some sort of
cryptographic resource management system to prevent such attacks. cryptographic resource management system to prevent such attacks.
8.7. Reusing Key Material when Encrypting Keys 8.7. Reusing Key Material when Encrypting Keys
It is NOT RECOMMENDED to reuse the same key material (Key Encryption It is NOT RECOMMENDED to reuse the same key material (Key Encryption
Key, Content Encryption Key, Initialization Vector, etc.) to encrypt Key, Content Encryption Key, Initialization Vector, etc.) to encrypt
multiple JWK or JWK Set objects, or to encrypt the same JWK or JWK multiple JWK or JWK Set objects, or to encrypt the same JWK or JWK
Set object multiple times. One suggestion for preventing re-use is Set object multiple times. One suggestion for preventing re-use is
to always generate a new set key material for each encryption to always generate a new set of key material for each encryption
operation, based on the considerations noted in this document as well operation, based on the considerations noted in this document as well
as from RFC 4086 [RFC4086]. as from RFC 4086 [RFC4086].
8.8. Password Considerations 8.8. Password Considerations
Passwords are vulnerable to a number of attacks. To help mitigate Passwords are vulnerable to a number of attacks. To help mitigate
some of these limitations, this document applies principles from RFC some of these limitations, this document applies principles from RFC
2898 [RFC2898] to derive cryptographic keys from user-supplied 2898 [RFC2898] to derive cryptographic keys from user-supplied
passwords. passwords.
skipping to change at page 51, line 21 skipping to change at page 51, line 35
used for "PBES2-HS512+A256KW" be no shorter than 32 octets and no used for "PBES2-HS512+A256KW" be no shorter than 32 octets and no
longer than 128 octets long. longer than 128 octets long.
Still, care needs to be taken in where and how password-based Still, care needs to be taken in where and how password-based
encryption is used. These algorithms can still be susceptible to encryption is used. These algorithms can still be susceptible to
dictionary-based attacks if the iteration count is too small; this is dictionary-based attacks if the iteration count is too small; this is
of particular concern if these algorithms are used to protect data of particular concern if these algorithms are used to protect data
that an attacker can have indefinite number of attempts to circumvent that an attacker can have indefinite number of attempts to circumvent
the protection, such as protected data stored on a file system. the protection, such as protected data stored on a file system.
8.9. Key Entropy 8.9. Key Entropy and Random Values
See Section 10.1 of [JWS] for security considerations on key entropy. See Section 10.1 of [JWS] for security considerations on key entropy
and random values.
8.10. Differences between Digital Signatures and MACs 8.10. Differences between Digital Signatures and MACs
See Section 10.4 of [JWS] for security considerations on differences See Section 10.5 of [JWS] for security considerations on differences
between digital signatures and MACs. between digital signatures and MACs.
8.11. Using Matching Algorithm Strengths 8.11. Using Matching Algorithm Strengths
See Section 11.1 of [JWE] for security considerations on using See Section 11.3 of [JWE] for security considerations on using
matching algorithm strengths. matching algorithm strengths.
8.12. Adaptive Chosen-Ciphertext Attacks 8.12. Adaptive Chosen-Ciphertext Attacks
See Section 11.2 of [JWE] for security considerations on adaptive See Section 11.4 of [JWE] for security considerations on adaptive
chosen-ciphertext attacks. chosen-ciphertext attacks.
8.13. Timing Attacks 8.13. Timing Attacks
See Section 10.3 of [JWS] and Section 11.3 of [JWE] for security See Section 10.9 of [JWS] and Section 11.5 of [JWE] for security
considerations on timing attacks. considerations on timing attacks.
8.14. RSA Private Key Representations and Blinding 8.14. RSA Private Key Representations and Blinding
See Section 9.3 of [JWK] for security considerations on RSA private See Section 9.3 of [JWK] for security considerations on RSA private
key representations and blinding. key representations and blinding.
9. Internationalization Considerations 9. Internationalization Considerations
Passwords obtained from users are likely to require preparation and Passwords obtained from users are likely to require preparation and
skipping to change at page 52, line 27 skipping to change at page 52, line 42
[AES] National Institute of Standards and Technology (NIST), [AES] National Institute of Standards and Technology (NIST),
"Advanced Encryption Standard (AES)", FIPS PUB 197, "Advanced Encryption Standard (AES)", FIPS PUB 197,
November 2001. November 2001.
[DSS] National Institute of Standards and Technology, "Digital [DSS] National Institute of Standards and Technology, "Digital
Signature Standard (DSS)", FIPS PUB 186-4, July 2013. Signature Standard (DSS)", FIPS PUB 186-4, July 2013.
[JWE] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", [JWE] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)",
draft-ietf-jose-json-web-encryption (work in progress), draft-ietf-jose-json-web-encryption (work in progress),
July 2014. September 2014.
[JWK] Jones, M., "JSON Web Key (JWK)", [JWK] Jones, M., "JSON Web Key (JWK)",
draft-ietf-jose-json-web-key (work in progress), draft-ietf-jose-json-web-key (work in progress),
July 2014. September 2014.
[JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web [JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web
Signature (JWS)", draft-ietf-jose-json-web-signature (work Signature (JWS)", draft-ietf-jose-json-web-signature (work
in progress), July 2014. in progress), September 2014.
[NIST.800-38A] [NIST.800-38A]
National Institute of Standards and Technology (NIST), National Institute of Standards and Technology (NIST),
"Recommendation for Block Cipher Modes of Operation", "Recommendation for Block Cipher Modes of Operation",
NIST PUB 800-38A, December 2001. NIST PUB 800-38A, December 2001.
[NIST.800-38D] [NIST.800-38D]
National Institute of Standards and Technology (NIST), National Institute of Standards and Technology (NIST),
"Recommendation for Block Cipher Modes of Operation: "Recommendation for Block Cipher Modes of Operation:
Galois/Counter Mode (GCM) and GMAC", NIST PUB 800-38D, Galois/Counter Mode (GCM) and GMAC", NIST PUB 800-38D,
skipping to change at page 53, line 45 skipping to change at page 54, line 12
[RFC6090] McGrew, D., Igoe, K., and M. Salter, "Fundamental Elliptic [RFC6090] McGrew, D., Igoe, K., and M. Salter, "Fundamental Elliptic
Curve Cryptography Algorithms", RFC 6090, February 2011. Curve Cryptography Algorithms", RFC 6090, February 2011.
[RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data
Interchange Format", RFC 7159, March 2014. Interchange Format", RFC 7159, March 2014.
[SEC1] Standards for Efficient Cryptography Group, "SEC 1: [SEC1] Standards for Efficient Cryptography Group, "SEC 1:
Elliptic Curve Cryptography", May 2009. Elliptic Curve Cryptography", May 2009.
[SHS] National Institute of Standards and Technology, "Secure [SHS] National Institute of Standards and Technology, "Secure
Hash Standard (SHS)", FIPS PUB 180-3, October 2008. Hash Standard (SHS)", FIPS PUB 180-4, March 2012.
[USASCII] American National Standards Institute, "Coded Character [USASCII] American National Standards Institute, "Coded Character
Set -- 7-bit American Standard Code for Information Set -- 7-bit American Standard Code for Information
Interchange", ANSI X3.4, 1986. Interchange", ANSI X3.4, 1986.
10.2. Informative References 10.2. Informative References
[CanvasApp] [CanvasApp]
Facebook, "Canvas Applications", 2010. Facebook, "Canvas Applications", 2010.
skipping to change at page 65, line 28 skipping to change at page 65, line 28
and Sean Turner. and Sean Turner.
Jim Schaad and Karen O'Donoghue chaired the JOSE working group and Jim Schaad and Karen O'Donoghue chaired the JOSE working group and
Sean Turner, Stephen Farrell, and Kathleen Moriarty served as Sean Turner, Stephen Farrell, and Kathleen Moriarty served as
Security area directors during the creation of this specification. Security area directors during the creation of this specification.
Appendix E. Document History Appendix E. Document History
[[ to be removed by the RFC Editor before publication as an RFC ]] [[ to be removed by the RFC Editor before publication as an RFC ]]
-32
o Added a note to implementers about libraries that prefix an extra
zero-valued octet to RSA modulus representations returned.
o Addressed secdir review comments by Charlie Kaufman, Scott Kelly,
and Stephen Kent.
o Addressed Gen-ART review comments by Roni Even.
o Replaced the term Plaintext JWS with Unsecured JWS.
-31 -31
o Referenced NIST SP 800-57 for guidance on key lifetimes. o Referenced NIST SP 800-57 for guidance on key lifetimes.
o Updated the reference to draft-mcgrew-aead-aes-cbc-hmac-sha2. o Updated the reference to draft-mcgrew-aead-aes-cbc-hmac-sha2.
-30 -30
o Cleaned up the reference syntax in a few places. o Cleaned up the reference syntax in a few places.
 End of changes. 52 change blocks. 
83 lines changed or deleted 106 lines changed or added

This html diff was produced by rfcdiff 1.41. The latest version is available from http://tools.ietf.org/tools/rfcdiff/