diff options
Diffstat (limited to 'doc/rfc/rfc8230.txt')
| -rw-r--r-- | doc/rfc/rfc8230.txt | 675 |
1 files changed, 675 insertions, 0 deletions
diff --git a/doc/rfc/rfc8230.txt b/doc/rfc/rfc8230.txt new file mode 100644 index 0000000..8e24ed9 --- /dev/null +++ b/doc/rfc/rfc8230.txt @@ -0,0 +1,675 @@ + + + + + + +Internet Engineering Task Force (IETF) M. Jones +Request for Comments: 8230 Microsoft +Category: Standards Track September 2017 +ISSN: 2070-1721 + + + Using RSA Algorithms with + CBOR Object Signing and Encryption (COSE) Messages + +Abstract + + The CBOR Object Signing and Encryption (COSE) specification defines + cryptographic message encodings using Concise Binary Object + Representation (CBOR). This specification defines algorithm + encodings and representations enabling RSA algorithms to be used for + COSE messages. Encodings are specified for the use of RSA + Probabilistic Signature Scheme (RSASSA-PSS) signatures, RSA + Encryption Scheme - Optimal Asymmetric Encryption Padding (RSAES- + OAEP) encryption, and RSA keys. + +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 7841. + + 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/rfc8230. + +Copyright Notice + + Copyright (c) 2017 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. + + + +Jones Standards Track [Page 1] + +RFC 8230 Using RSA Algorithms with COSE Messages September 2017 + + +Table of Contents + + 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 + 1.1. Requirements Notation and Conventions . . . . . . . . . . 3 + 2. RSASSA-PSS Signature Algorithm . . . . . . . . . . . . . . . 3 + 3. RSAES-OAEP Key Encryption Algorithm . . . . . . . . . . . . . 4 + 4. RSA Keys . . . . . . . . . . . . . . . . . . . . . . . . . . 4 + 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6 + 5.1. COSE Algorithms Registrations . . . . . . . . . . . . . . 6 + 5.2. COSE Key Type Registrations . . . . . . . . . . . . . . . 7 + 5.3. COSE Key Type Parameters Registrations . . . . . . . . . 7 + 6. Security Considerations . . . . . . . . . . . . . . . . . . . 9 + 6.1. Key Size Security Considerations . . . . . . . . . . . . 9 + 6.2. RSASSA-PSS Security Considerations . . . . . . . . . . . 10 + 6.3. RSAES-OAEP Security Considerations . . . . . . . . . . . 10 + 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 10 + 7.1. Normative References . . . . . . . . . . . . . . . . . . 10 + 7.2. Informative References . . . . . . . . . . . . . . . . . 11 + Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 12 + Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 12 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Jones Standards Track [Page 2] + +RFC 8230 Using RSA Algorithms with COSE Messages September 2017 + + +1. Introduction + + The CBOR Object Signing and Encryption (COSE) [RFC8152] specification + defines cryptographic message encodings using Concise Binary Object + Representation (CBOR) [RFC7049]. This specification defines + algorithm encodings and representations enabling RSA algorithms to be + used for COSE messages. + +1.1. Requirements Notation and Conventions + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and + "OPTIONAL" in this document are to be interpreted as described in BCP + 14 [RFC2119] [RFC8174] when, and only when, they appear in all + capitals, as shown here. + +2. RSASSA-PSS Signature Algorithm + + The RSASSA-PSS signature algorithm is defined in [RFC8017]. + + The RSASSA-PSS signature algorithm is parameterized with a hash + function (h), a mask generation function (mgf), and a salt length + (sLen). For this specification, the mask generation function is + fixed to be MGF1 as defined in [RFC8017]. It has been recommended + that the same hash function be used for hashing the data as well as + in the mask generation function. This specification follows this + recommendation. The salt length is the same length as the hash + function output. + + Implementations need to check that the key type is 'RSA' when + creating or verifying a signature. + + The RSASSA-PSS algorithms specified in this document are in the + following table. + + +-------+-------+---------+-------------+-----------------------+ + | Name | Value | Hash | Salt Length | Description | + +-------+-------+---------+-------------+-----------------------+ + | PS256 | -37 | SHA-256 | 32 | RSASSA-PSS w/ SHA-256 | + | PS384 | -38 | SHA-384 | 48 | RSASSA-PSS w/ SHA-384 | + | PS512 | -39 | SHA-512 | 64 | RSASSA-PSS w/ SHA-512 | + +-------+-------+---------+-------------+-----------------------+ + + Table 1: RSASSA-PSS Algorithm Values + + + + + + + +Jones Standards Track [Page 3] + +RFC 8230 Using RSA Algorithms with COSE Messages September 2017 + + +3. RSAES-OAEP Key Encryption Algorithm + + RSAES-OAEP is an asymmetric key encryption algorithm. The definition + of RSAEA-OAEP can be found in Section 7.1 of [RFC8017]. The + algorithm is parameterized using a mask generation function (mgf), a + hash function (h), and encoding parameters (P). For the algorithm + identifiers defined in this section: + + o mgf is always set to MGF1 as defined in [RFC8017] and uses the + same hash function as h. + + o P is always set to the empty octet string. + + The following table summarizes the rest of the values. + + +-------------------------------+-------+---------+-----------------+ + | Name | Value | Hash | Description | + +-------------------------------+-------+---------+-----------------+ + | RSAES-OAEP w/ RFC 8017 | -40 | SHA-1 | RSAES-OAEP w/ | + | default parameters | | | SHA-1 | + | RSAES-OAEP w/ SHA-256 | -41 | SHA-256 | RSAES-OAEP w/ | + | | | | SHA-256 | + | RSAES-OAEP w/ SHA-512 | -42 | SHA-512 | RSAES-OAEP w/ | + | | | | SHA-512 | + +-------------------------------+-------+---------+-----------------+ + + Table 2: RSAES-OAEP Algorithm Values + + The key type MUST be 'RSA'. + +4. RSA Keys + + Key types are identified by the 'kty' member of the COSE_Key object. + This specification defines one value for this member in the following + table. + + +------+-------+-------------+ + | Name | Value | Description | + +------+-------+-------------+ + | RSA | 3 | RSA Key | + +------+-------+-------------+ + + Table 3: Key Type Values + + + + + + + + +Jones Standards Track [Page 4] + +RFC 8230 Using RSA Algorithms with COSE Messages September 2017 + + + This document defines a key structure for both the public and private + parts of RSA keys. Together, an RSA public key and an RSA private + key form an RSA key pair. + + The document also provides support for the so-called "multi-prime" + RSA keys, in which the modulus may have more than two prime factors. + The benefit of multi-prime RSA is lower computational cost for the + decryption and signature primitives. For a discussion on how multi- + prime affects the security of RSA cryptosystems, the reader is + referred to [MultiPrimeRSA]. + + This document follows the naming convention of [RFC8017] for the + naming of the fields of an RSA public or private key, and the + corresponding fields have identical semantics. The requirements for + fields for RSA keys are as follows: + + o For all keys, 'kty' MUST be present and MUST have a value of 3. + + o For public keys, the fields 'n' and 'e' MUST be present. All + other fields defined in the following table below MUST be absent. + + o For private keys with two primes, the fields 'other', 'r_i', + 'd_i', and 't_i' MUST be absent; all other fields MUST be present. + + o For private keys with more than two primes, all fields MUST be + present. For the third to nth primes, each of the primes is + represented as a map containing the fields 'r_i', 'd_i', and + 't_i'. The field 'other' is an array of those maps. + + o All numeric key parameters are encoded in an unsigned big-endian + representation as an octet sequence using the CBOR byte string + type (major type 2). The octet sequence MUST utilize the minimum + number of octets needed to represent the value. For instance, the + value 32,768 is represented as the CBOR byte sequence 0b010_00010, + 0x80 0x00 (major type 2, additional information 2 for the length). + + + + + + + + + + + + + + + + +Jones Standards Track [Page 5] + +RFC 8230 Using RSA Algorithms with COSE Messages September 2017 + + + The following table provides a summary of the label values and the + types associated with each of those labels. + + +-------+-------+-------+-------+-----------------------------------+ + | Key | Name | Label | CBOR | Description | + | Type | | | Type | | + +-------+-------+-------+-------+-----------------------------------+ + | 3 | n | -1 | bstr | the RSA modulus n | + | 3 | e | -2 | bstr | the RSA public exponent e | + | 3 | d | -3 | bstr | the RSA private exponent d | + | 3 | p | -4 | bstr | the prime factor p of n | + | 3 | q | -5 | bstr | the prime factor q of n | + | 3 | dP | -6 | bstr | dP is d mod (p - 1) | + | 3 | dQ | -7 | bstr | dQ is d mod (q - 1) | + | 3 | qInv | -8 | bstr | qInv is the CRT coefficient | + | | | | | q^(-1) mod p | + | 3 | other | -9 | array | other prime infos, an array | + | 3 | r_i | -10 | bstr | a prime factor r_i of n, where i | + | | | | | >= 3 | + | 3 | d_i | -11 | bstr | d_i = d mod (r_i - 1) | + | 3 | t_i | -12 | bstr | the CRT coefficient t_i = (r_1 * | + | | | | | r_2 * ... * r_(i-1))^(-1) mod r_i | + +-------+-------+-------+-------+-----------------------------------+ + + Table 4: RSA Key Parameters + +5. IANA Considerations + +5.1. COSE Algorithms Registrations + + IANA has registered the following values in the IANA "COSE + Algorithms" registry [IANA.COSE]. + + o Name: PS256 + o Value: -37 + o Description: RSASSA-PSS w/ SHA-256 + o Reference: Section 2 of this document + o Recommended: Yes + + o Name: PS384 + o Value: -38 + o Description: RSASSA-PSS w/ SHA-384 + o Reference: Section 2 of this document + o Recommended: Yes + + + + + + + +Jones Standards Track [Page 6] + +RFC 8230 Using RSA Algorithms with COSE Messages September 2017 + + + o Name: PS512 + o Value: -39 + o Description: RSASSA-PSS w/ SHA-512 + o Reference: Section 2 of this document + o Recommended: Yes + + o Name: RSAES-OAEP w/ RFC 8017 default parameters + o Value: -40 + o Description: RSAES-OAEP w/ SHA-1 + o Reference: Section 3 of this document + o Recommended: Yes + + o Name: RSAES-OAEP w/ SHA-256 + o Value: -41 + o Description: RSAES-OAEP w/ SHA-256 + o Reference: Section 3 of this document + o Recommended: Yes + + o Name: RSAES-OAEP w/ SHA-512 + o Value: -42 + o Description: RSAES-OAEP w/ SHA-512 + o Reference: Section 3 of this document + o Recommended: Yes + +5.2. COSE Key Type Registrations + + IANA has registered the following value in the IANA "COSE Key Types" + registry [IANA.COSE]. + + o Name: RSA + o Value: 3 + o Description: RSA Key + o Reference: Section 4 of this document + +5.3. COSE Key Type Parameters Registrations + + IANA has registered the following values in the IANA "COSE Key Type + Parameters" registry [IANA.COSE]. + + o Key Type: 3 + o Name: n + o Label: -1 + o CBOR Type: bstr + o Description: the RSA modulus n + o Reference: Section 4 of this document + + + + + + +Jones Standards Track [Page 7] + +RFC 8230 Using RSA Algorithms with COSE Messages September 2017 + + + o Key Type: 3 + o Name: e + o Label: -2 + o CBOR Type: bstr + o Description: the RSA public exponent e + o Reference: Section 4 of this document + + o Key Type: 3 + o Name: d + o Label: -3 + o CBOR Type: bstr + o Description: the RSA private exponent d + o Reference: Section 4 of this document + + o Key Type: 3 + o Name: p + o Label: -4 + o CBOR Type: bstr + o Description: the prime factor p of n + o Reference: Section 4 of this document + + o Key Type: 3 + o Name: q + o Label: -5 + o CBOR Type: bstr + o Description: the prime factor q of n + o Reference: Section 4 of this document + + o Key Type: 3 + o Name: dP + o Label: -6 + o CBOR Type: bstr + o Description: dP is d mod (p - 1) + o Reference: Section 4 of this document + + o Key Type: 3 + o Name: dQ + o Label: -7 + o CBOR Type: bstr + o Description: dQ is d mod (q - 1) + o Reference: Section 4 of this document + + o Key Type: 3 + o Name: qInv + o Label: -8 + o CBOR Type: bstr + o Description: qInv is the CRT coefficient q^(-1) mod p + o Reference: Section 4 of this document + + + +Jones Standards Track [Page 8] + +RFC 8230 Using RSA Algorithms with COSE Messages September 2017 + + + o Key Type: 3 + o Name: other + o Label: -9 + o CBOR Type: array + o Description: other prime infos, an array + o Reference: Section 4 of this document + + o Key Type: 3 + o Name: r_i + o Label: -10 + o CBOR Type: bstr + o Description: a prime factor r_i of n, where i >= 3 + o Reference: Section 4 of this document + + o Key Type: 3 + o Name: d_i + o Label: -11 + o CBOR Type: bstr + o Description: d_i = d mod (r_i - 1) + o Reference: Section 4 of this document + + o Key Type: 3 + o Name: t_i + o Label: -12 + o CBOR Type: bstr + o Description: the CRT coefficient t_i = (r_1 * r_2 * ... * + r_(i-1))^(-1) mod r_i + o Reference: Section 4 of this document + +6. Security Considerations + +6.1. Key Size Security Considerations + + A key size of 2048 bits or larger MUST be used with these algorithms. + This key size corresponds roughly to the same strength as provided by + a 128-bit symmetric encryption algorithm. Implementations SHOULD be + able to encrypt and decrypt with modulus between 2048 and 16K bits in + length. Applications can impose additional restrictions on the + length of the modulus. + + In addition to needing to worry about keys that are too small to + provide the required security, there are issues with keys that are + too large. Denial-of-service attacks have been mounted with overly + large keys or oddly sized keys. This has the potential to consume + resources with these keys. It is highly recommended that checks on + the key length be done before starting a cryptographic operation. + + + + + +Jones Standards Track [Page 9] + +RFC 8230 Using RSA Algorithms with COSE Messages September 2017 + + + There are two reasonable ways to address this attack. First, a key + should not be used for a cryptographic operation until it has been + verified that it is controlled by a party trusted by the recipient. + This approach means that no cryptography will be done until a trust + decision about the key has been made, a process described in + Appendix D, Item 4 of [RFC7515]. Second, applications can impose + maximum- as well as minimum-length requirements on keys. This limits + the resources that would otherwise be consumed by the use of overly + large keys. + +6.2. RSASSA-PSS Security Considerations + + There is a theoretical hash substitution attack that can be mounted + against RSASSA-PSS [HASHID]. However, the requirement that the same + hash function be used consistently for all operations is an effective + mitigation against it. Unlike an Elliptic Curve Digital Signature + Algorithm (ECDSA), hash function outputs are not truncated so that + the full hash value is always signed. The internal padding structure + of RSASSA-PSS means that one needs to have multiple collisions + between the two hash functions to be successful in producing a + forgery based on changing the hash function. This is highly + unlikely. + +6.3. RSAES-OAEP Security Considerations + + A version of RSAES-OAEP using the default parameters specified in + Appendix A.2.1 of [RFC8017] is included because this is the most + widely implemented set of OAEP parameter choices. (Those default + parameters are the SHA-1 hash function and the MGF1 with SHA-1 mask + generation function.) + + Keys used with RSAES-OAEP MUST follow the constraints in Section 7.1 + of [RFC8017]. Also, keys with a low private key exponent value, as + described in Section 3 of "Twenty Years of Attacks on the RSA + Cryptosystem" [Boneh99], MUST NOT be used. + +7. References + +7.1. Normative References + + [Boneh99] Boneh, D., "Twenty Years of Attacks on the RSA + Cryptosystem", Notices of the American Mathematical + Society (AMS), Vol. 46, No. 2, pp. 203-213, 1999, + <http://www.ams.org/notices/199902/boneh.pdf>. + + + + + + + +Jones Standards Track [Page 10] + +RFC 8230 Using RSA Algorithms with COSE Messages September 2017 + + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, + DOI 10.17487/RFC2119, March 1997, + <https://www.rfc-editor.org/info/rfc2119>. + + [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object + Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, + October 2013, <https://www.rfc-editor.org/info/rfc7049>. + + [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web + Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May + 2015, <https://www.rfc-editor.org/info/rfc7515>. + + [RFC8017] Moriarty, K., Ed., Kaliski, B., Jonsson, J., and A. + Rusch, "PKCS #1: RSA Cryptography Specifications Version + 2.2", RFC 8017, DOI 10.17487/RFC8017, November 2016, + <https://www.rfc-editor.org/info/rfc8017>. + + [RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)", + RFC 8152, DOI 10.17487/RFC8152, July 2017, + <https://www.rfc-editor.org/info/rfc8152>. + + [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC + 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, + May 2017, <https://www.rfc-editor.org/info/rfc8174>. + +7.2. Informative References + + [HASHID] Kaliski, B., "On Hash Function Firewalls in Signature + Schemes", Lecture Notes in Computer Science (LNCS), + Volume 2271, pp. 1-16, DOI 10.1007/3-540-45760-7_1, + February 2002, <https://rd.springer.com/chapter/ + 10.1007/3-540-45760-7_1>. + + [IANA.COSE] IANA, "CBOR Object Signing and Encryption (COSE)", + <http://www.iana.org/assignments/cose>. + + [MultiPrimeRSA] + Hinek, M. and D. Cheriton, "On the Security of + Multi-prime RSA", June 2006, + <http://cacr.uwaterloo.ca/techreports/ + 2006/cacr2006-16.pdf>. + + + + + + + + + +Jones Standards Track [Page 11] + +RFC 8230 Using RSA Algorithms with COSE Messages September 2017 + + +Acknowledgements + + This specification incorporates text from "CBOR Encoded Message + Syntax" (September 2015) authored by Jim Schaad and Brian Campbell. + Thanks are due to Ben Campbell, Roni Even, Steve Kent, Kathleen + Moriarty, Eric Rescorla, Adam Roach, Rich Salz, and Jim Schaad for + their reviews of the specification. + +Author's Address + + Michael B. Jones + Microsoft + + Email: mbj@microsoft.com + URI: http://self-issued.info/ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Jones Standards Track [Page 12] + |