From 4bfd864f10b68b71482b35c818559068ef8d5797 Mon Sep 17 00:00:00 2001 From: Thomas Voss Date: Wed, 27 Nov 2024 20:54:24 +0100 Subject: doc: Add RFC documents --- doc/rfc/rfc8812.txt | 533 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 533 insertions(+) create mode 100644 doc/rfc/rfc8812.txt (limited to 'doc/rfc/rfc8812.txt') diff --git a/doc/rfc/rfc8812.txt b/doc/rfc/rfc8812.txt new file mode 100644 index 0000000..748ee35 --- /dev/null +++ b/doc/rfc/rfc8812.txt @@ -0,0 +1,533 @@ + + + + +Internet Engineering Task Force (IETF) M. Jones +Request for Comments: 8812 Microsoft +Category: Standards Track August 2020 +ISSN: 2070-1721 + + + CBOR Object Signing and Encryption (COSE) and JSON Object Signing and + Encryption (JOSE) Registrations for Web Authentication (WebAuthn) + Algorithms + +Abstract + + The W3C Web Authentication (WebAuthn) specification and the FIDO + Alliance FIDO2 Client to Authenticator Protocol (CTAP) specification + use CBOR Object Signing and Encryption (COSE) algorithm identifiers. + This specification registers the following algorithms (which are used + by WebAuthn and CTAP implementations) in the IANA "COSE Algorithms" + registry: RSASSA-PKCS1-v1_5 using SHA-256, SHA-384, SHA-512, and SHA- + 1; and Elliptic Curve Digital Signature Algorithm (ECDSA) using the + secp256k1 curve and SHA-256. It registers the secp256k1 elliptic + curve in the IANA "COSE Elliptic Curves" registry. Also, for use + with JSON Object Signing and Encryption (JOSE), it registers the + algorithm ECDSA using the secp256k1 curve and SHA-256 in the IANA + "JSON Web Signature and Encryption Algorithms" registry and the + secp256k1 elliptic curve in the IANA "JSON Web Key Elliptic Curve" + registry. + +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 + https://www.rfc-editor.org/info/rfc8812. + +Copyright Notice + + Copyright (c) 2020 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 + (https://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. + +Table of Contents + + 1. Introduction + 1.1. Requirements Notation and Conventions + 2. RSASSA-PKCS1-v1_5 Signature Algorithm + 3. Using secp256k1 with JOSE and COSE + 3.1. JOSE and COSE secp256k1 Curve Key Representations + 3.2. ECDSA Signature with secp256k1 Curve + 3.3. Other Uses of the secp256k1 Elliptic Curve + 4. IANA Considerations + 4.1. COSE Algorithms Registrations + 4.2. COSE Elliptic Curves Registrations + 4.3. JOSE Algorithms Registrations + 4.4. JSON Web Key Elliptic Curves Registrations + 5. Security Considerations + 5.1. RSA Key Size Security Considerations + 5.2. RSASSA-PKCS1-v1_5 with SHA-2 Security Considerations + 5.3. RSASSA-PKCS1-v1_5 with SHA-1 Security Considerations + 5.4. secp256k1 Security Considerations + 6. References + 6.1. Normative References + 6.2. Informative References + Acknowledgements + Author's Address + +1. Introduction + + This specification defines how to use several algorithms with CBOR + Object Signing and Encryption (COSE) [RFC8152] that are used by + implementations of the W3C Web Authentication (WebAuthn) [WebAuthn] + and FIDO Alliance FIDO2 Client to Authenticator Protocol (CTAP) + [CTAP] specifications. This specification registers these algorithms + in the IANA "COSE Algorithms" registry [IANA.COSE.Algorithms] and + registers an elliptic curve in the IANA "COSE Elliptic Curves" + registry [IANA.COSE.Curves]. This specification also registers a + corresponding algorithm for use with JSON Object Signing and + Encryption (JOSE) [RFC7515] in the IANA "JSON Web Signature and + Encryption Algorithms" registry [IANA.JOSE.Algorithms] and registers + an elliptic curve in the IANA "JSON Web Key Elliptic Curve" registry + [IANA.JOSE.Curves]. + +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-PKCS1-v1_5 Signature Algorithm + + The RSASSA-PKCS1-v1_5 signature algorithm is defined in [RFC8017]. + The RSASSA-PKCS1-v1_5 signature algorithm is parameterized with a + hash function (h). + + A key of size 2048 bits or larger MUST be used with these algorithms. + Implementations need to check that the key type is 'RSA' when + creating or verifying a signature. + + The RSASSA-PKCS1-v1_5 algorithms specified in this document are in + the following table. + + +=======+========+=========+===================+=============+ + | Name | Value | Hash | Description | Recommended | + +=======+========+=========+===================+=============+ + | RS256 | -257 | SHA-256 | RSASSA-PKCS1-v1_5 | No | + | | | | using SHA-256 | | + +-------+--------+---------+-------------------+-------------+ + | RS384 | -258 | SHA-384 | RSASSA-PKCS1-v1_5 | No | + | | | | using SHA-384 | | + +-------+--------+---------+-------------------+-------------+ + | RS512 | -259 | SHA-512 | RSASSA-PKCS1-v1_5 | No | + | | | | using SHA-512 | | + +-------+--------+---------+-------------------+-------------+ + | RS1 | -65535 | SHA-1 | RSASSA-PKCS1-v1_5 | Deprecated | + | | | | using SHA-1 | | + +-------+--------+---------+-------------------+-------------+ + + Table 1: RSASSA-PKCS1-v1_5 Algorithm Values + + Security considerations for use of the first three algorithms are in + Section 5.2. Security considerations for use of the last algorithm + are in Section 5.3. + + Note that these algorithms are already present in the IANA "JSON Web + Signature and Encryption Algorithms" registry [IANA.JOSE.Algorithms], + and so these registrations are only for the IANA "COSE Algorithms" + registry [IANA.COSE.Algorithms]. + +3. Using secp256k1 with JOSE and COSE + + This section defines algorithm encodings and representations enabling + the Standards for Efficient Cryptography Group (SECG) elliptic curve + secp256k1 [SEC2] to be used for JOSE [RFC7515] and COSE [RFC8152] + messages. + +3.1. JOSE and COSE secp256k1 Curve Key Representations + + The SECG elliptic curve secp256k1 [SEC2] is represented in a JSON Web + Key (JWK) [RFC7517] using these values: + + * "kty": "EC" + * "crv": "secp256k1" + + plus the values needed to represent the curve point, as defined in + Section 6.2.1 of [RFC7518]. As a compressed point encoding + representation is not defined for JWK elliptic curve points, the + uncompressed point encoding defined there MUST be used. The "x" and + "y" values represented MUST both be exactly 256 bits, with any + leading zeros preserved. Other optional values such as "alg" MAY + also be present. + + It is represented in a COSE_Key [RFC8152] using these values: + + * "kty" (1): "EC2" (2) + * "crv" (-1): "secp256k1" (8) + + plus the values needed to represent the curve point, as defined in + Section 13.1.1 of [RFC8152]. Either the uncompressed or compressed + point encoding representations defined there can be used. The "x" + value represented MUST be exactly 256 bits, with any leading zeros + preserved. If the uncompressed representation is used, the "y" value + represented MUST likewise be exactly 256 bits, with any leading zeros + preserved; if the compressed representation is used, the "y" value is + a boolean value, as specified in Section 13.1.1 of [RFC8152]. Other + optional values such as "alg" (3) MAY also be present. + +3.2. ECDSA Signature with secp256k1 Curve + + The ECDSA signature algorithm is defined in [DSS]. This + specification defines the "ES256K" algorithm identifier, which is + used to specify the use of ECDSA with the secp256k1 curve and the + SHA-256 [DSS] cryptographic hash function. Implementations need to + check that the key type is "EC" for JOSE or "EC2" (2) for COSE and + that the curve of the key is secp256k1 when creating or verifying a + signature. + + The ECDSA secp256k1 SHA-256 digital signature is generated as + follows: + + 1. Generate a digital signature of the JWS Signing Input or the COSE + Sig_structure using ECDSA secp256k1 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 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 or COSE + signature value. + + Implementations SHOULD use a deterministic algorithm to generate the + ECDSA nonce, k, such as the algorithm defined in [RFC6979]. However, + in situations where devices are vulnerable to physical attacks, + deterministic ECDSA has been shown to be susceptible to fault + injection attacks [KUDELSKI17] [EURO-SP18]. Where this is a + possibility, implementations SHOULD implement appropriate + countermeasures. Where there are specific certification requirements + (such as FIPS approval), implementors should check whether + deterministic ECDSA is an approved nonce generation method. + + The ECDSA secp256k1 SHA-256 algorithm specified in this document uses + these identifiers: + + +========+=======+=======================+=============+ + | Name | Value | Description | Recommended | + +========+=======+=======================+=============+ + | ES256K | -47 | ECDSA using secp256k1 | No | + | | | curve and SHA-256 | | + +--------+-------+-----------------------+-------------+ + + Table 2: ECDSA Algorithm Values + + When using a JWK or COSE_Key for this algorithm, the following checks + are made: + + * The "kty" field MUST be present, and it MUST be "EC" for JOSE or + "EC2" for COSE. + + * The "crv" field MUST be present, and it MUST represent the + "secp256k1" elliptic curve. + + * If the "alg" field is present, it MUST represent the "ES256K" + algorithm. + + * If the "key_ops" field is present, it MUST include "sign" when + creating an ECDSA signature. + + * If the "key_ops" field is present, it MUST include "verify" when + verifying an ECDSA signature. + + * If the JWK "use" field is present, its value MUST be "sig". + +3.3. Other Uses of the secp256k1 Elliptic Curve + + This specification defines how to use the secp256k1 curve for ECDSA + signatures for both JOSE and COSE implementations. While in theory + the curve could also be used for ECDH-ES key agreement, it is beyond + the scope of this specification to state whether this is or is not + advisable. Thus, whether or not to recommend its use with ECDH-ES is + left for experts to decide in future specifications. + + When used for ECDSA, the secp256k1 curve MUST be used only with the + "ES256K" algorithm identifier and not any others, including not with + the COSE "ES256" identifier. Note that the "ES256K" algorithm + identifier needed to be introduced for JOSE to sign with the + secp256k1 curve because the JOSE "ES256" algorithm is defined to be + used only with the P-256 curve. The COSE treatment of how to sign + with secp256k1 is intentionally parallel to that for JOSE, where the + secp256k1 curve MUST be used with the "ES256K" algorithm identifier. + +4. IANA Considerations + +4.1. COSE Algorithms Registrations + + IANA has registered the following values in the "COSE Algorithms" + registry [IANA.COSE.Algorithms]. + + Name: RS256 + Value: -257 + Description: RSASSA-PKCS1-v1_5 using SHA-256 + Change Controller: IESG + Reference: Section 2 of RFC 8812 + Recommended: No + + Name: RS384 + Value: -258 + Description: RSASSA-PKCS1-v1_5 using SHA-384 + Change Controller: IESG + Reference: Section 2 of RFC 8812 + Recommended: No + + Name: RS512 + Value: -259 + Description: RSASSA-PKCS1-v1_5 using SHA-512 + Change Controller: IESG + Reference: Section 2 of RFC 8812 + Recommended: No + + Name: RS1 + Value: -65535 + Description: RSASSA-PKCS1-v1_5 using SHA-1 + Change Controller: IESG + Reference: Section 2 of RFC 8812 + Recommended: Deprecated + + Name: ES256K + Value: -47 + Description: ECDSA using secp256k1 curve and SHA-256 + Change Controller: IESG + Reference: Section 3.2 of RFC 8812 + Recommended: No + +4.2. COSE Elliptic Curves Registrations + + IANA has registered the following value in the "COSE Elliptic Curves" + registry [IANA.COSE.Curves]. + + Name: secp256k1 + Value: 8 + Key Type: EC2 + Description: SECG secp256k1 curve + Change Controller: IESG + Reference: Section 3.1 of RFC 8812 + Recommended: No + +4.3. JOSE Algorithms Registrations + + IANA has registered the following value in the "JSON Web Signature + and Encryption Algorithms" registry [IANA.JOSE.Algorithms]. + + Algorithm Name: ES256K + Algorithm Description: ECDSA using secp256k1 curve and SHA-256 + Algorithm Usage Location(s): alg + JOSE Implementation Requirements: Optional + Change Controller: IESG + Reference: Section 3.2 of RFC 8812 + Algorithm Analysis Document(s): [SEC2] + +4.4. JSON Web Key Elliptic Curves Registrations + + IANA has registered the following value in the "JSON Web Key Elliptic + Curve" registry [IANA.JOSE.Curves]. + + Curve Name: secp256k1 + Curve Description: SECG secp256k1 curve + JOSE Implementation Requirements: Optional + Change Controller: IESG + Specification Document(s): Section 3.1 of RFC 8812 + +5. Security Considerations + +5.1. RSA Key Size Security Considerations + + The security considerations on key sizes for RSA algorithms from + Section 6.1 of [RFC8230] also apply to the RSA algorithms in this + specification. + +5.2. RSASSA-PKCS1-v1_5 with SHA-2 Security Considerations + + The security considerations on the use of RSASSA-PKCS1-v1_5 with + SHA-2 hash functions (SHA-256, SHA-384, and SHA-512) from Section 8.3 + of [RFC7518] also apply to their use in this specification. For that + reason, these algorithms are registered as being "Not Recommended". + Likewise, the exponent restrictions described in Section 8.3 of + [RFC7518] also apply. + +5.3. RSASSA-PKCS1-v1_5 with SHA-1 Security Considerations + + The security considerations on the use of the SHA-1 hash function + from [RFC6194] apply in this specification. For that reason, the + "RS1" algorithm is registered as "Deprecated". Likewise, the + exponent restrictions described in Section 8.3 of [RFC7518] also + apply. + + A COSE algorithm identifier for this algorithm is nonetheless being + registered because deployed Trusted Platform Modules (TPMs) continue + to use it; therefore, WebAuthn implementations need a COSE algorithm + identifier for "RS1" when TPM attestations using this algorithm are + being represented. New COSE applications and protocols MUST NOT use + this algorithm. + +5.4. secp256k1 Security Considerations + + Care should be taken that a secp256k1 key is not mistaken for a P-256 + [RFC7518] key, given that their representations are the same except + for the "crv" value. As described in Section 8.1.1 of [RFC8152], we + currently do not have any way to deal with this attack except to + restrict the set of curves that can be used. + + The procedures and security considerations described in the [SEC1], + [SEC2], and [DSS] specifications apply to implementations of this + specification. + + Timing side-channel attacks are possible if the implementation of + scalar multiplication over the curve does not execute in constant + time. + + There are theoretical weaknesses with this curve that could result in + future attacks. While these potential weaknesses are not unique to + this curve, they are the reason that this curve is registered as + "Recommended: No". + +6. References + +6.1. Normative References + + [DSS] National Institute of Standards and Technology (NIST), + "Digital Signature Standard (DSS)", FIPS PUB 186-4, + DOI 10.6028/NIST.FIPS.186-4, July 2013, + . + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, + DOI 10.17487/RFC2119, March 1997, + . + + [RFC6194] Polk, T., Chen, L., Turner, S., and P. Hoffman, "Security + Considerations for the SHA-0 and SHA-1 Message-Digest + Algorithms", RFC 6194, DOI 10.17487/RFC6194, March 2011, + . + + [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web + Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May + 2015, . + + [RFC7517] Jones, M., "JSON Web Key (JWK)", RFC 7517, + DOI 10.17487/RFC7517, May 2015, + . + + [RFC7518] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518, + DOI 10.17487/RFC7518, May 2015, + . + + [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, + . + + [RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)", + RFC 8152, DOI 10.17487/RFC8152, July 2017, + . + + [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC + 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, + May 2017, . + + [RFC8230] Jones, M., "Using RSA Algorithms with CBOR Object Signing + and Encryption (COSE) Messages", RFC 8230, + DOI 10.17487/RFC8230, September 2017, + . + + [SEC1] Standards for Efficient Cryptography Group, "SEC 1: + Elliptic Curve Cryptography", Version 2.0, May 2009, + . + + [SEC2] Standards for Efficient Cryptography Group, "SEC 2: + Recommended Elliptic Curve Domain Parameters", + Version 2.0, January 2010, + . + +6.2. Informative References + + [CTAP] Brand, C., Czeskis, A., Ehrensvärd, J., Jones, M., Kumar, + A., Lindemann, R., Powers, A., and J. Verrept, "Client to + Authenticator Protocol (CTAP)", FIDO Alliance Proposed + Standard, January 2019, . + + [EURO-SP18] + Poddebniak, D., Somorovsky, J., Schinzel, S., Lochter, M., + and P. Rösler, "Attacking Deterministic Signature Schemes + using Fault Attacks", 2018 IEEE European Symposium on + Security and Privacy (EuroS&P), + DOI 10.1109/EuroSP.2018.00031, April 2018, + . + + [IANA.COSE.Algorithms] + IANA, "COSE Algorithms", + . + + [IANA.COSE.Curves] + IANA, "COSE Elliptic Curves", + . + + [IANA.JOSE.Algorithms] + IANA, "JSON Web Signature and Encryption Algorithms", + . + + [IANA.JOSE.Curves] + IANA, "JSON Web Key Elliptic Curve", + . + + [KUDELSKI17] + Romailler, Y., "How to Defeat Ed25519 and EdDSA Using + Faults", Kudelski Security Research, October 2017, + . + + [RFC6979] Pornin, T., "Deterministic Usage of the Digital Signature + Algorithm (DSA) and Elliptic Curve Digital Signature + Algorithm (ECDSA)", RFC 6979, DOI 10.17487/RFC6979, August + 2013, . + + [WebAuthn] Balfanz, D., Czeskis, A., Hodges, J., Jones, J.C., Jones, + M., Kumar, A., Liao, A., Lindemann, R., and E. Lundberg, + "Web Authentication: An API for accessing Public Key + Credentials - Level 1", W3C Recommendation, March 2019, + . + +Acknowledgements + + Thanks to Roman Danyliw, Linda Dunbar, Stephen Farrell, John Fontana, + Jeff Hodges, Kevin Jacobs, J.C. Jones, Benjamin Kaduk, Murray + Kucherawy, Neil Madden, John Mattsson, Matthew Miller, Tony Nadalin, + Matt Palmer, Eric Rescorla, Rich Salz, Jim Schaad, Goeran Selander, + Wendy Seltzer, Sean Turner, and Samuel Weiler for their roles in + registering these algorithm identifiers. + +Author's Address + + Michael B. Jones + Microsoft + + Email: mbj@microsoft.com + URI: https://self-issued.info/ -- cgit v1.2.3