idnits 2.17.1 draft-ietf-cose-webauthn-algorithms-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (July 8, 2019) is 1754 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Unused Reference: 'RFC7049' is defined on line 324, but no explicit reference was found in the text -- Possible downref: Non-RFC (?) normative reference: ref. 'DSS' ** Downref: Normative reference to an Informational RFC: RFC 6194 ** Obsolete normative reference: RFC 7049 (Obsoleted by RFC 8949) ** Downref: Normative reference to an Informational RFC: RFC 8017 ** Obsolete normative reference: RFC 8152 (Obsoleted by RFC 9052, RFC 9053) -- Possible downref: Non-RFC (?) normative reference: ref. 'SEC1' -- Possible downref: Non-RFC (?) normative reference: ref. 'SEC2' Summary: 4 errors (**), 0 flaws (~~), 2 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 COSE Working Group M. Jones 3 Internet-Draft Microsoft 4 Intended status: Standards Track July 8, 2019 5 Expires: January 9, 2020 7 COSE and JOSE Registrations for WebAuthn Algorithms 8 draft-ietf-cose-webauthn-algorithms-01 10 Abstract 12 The W3C Web Authentication (WebAuthn) specification and the FIDO2 13 Client to Authenticator Protocol (CTAP) specification use COSE 14 algorithm identifiers. This specification registers algorithms in 15 the IANA "COSE Algorithms" registry that are used by WebAuthn and 16 CTAP implementations that are not already registered. Also, they are 17 registered in the IANA "JSON Web Signature and Encryption Algorithms" 18 registry, when not already registered there. 20 Status of This Memo 22 This Internet-Draft is submitted in full conformance with the 23 provisions of BCP 78 and BCP 79. 25 Internet-Drafts are working documents of the Internet Engineering 26 Task Force (IETF). Note that other groups may also distribute 27 working documents as Internet-Drafts. The list of current Internet- 28 Drafts is at https://datatracker.ietf.org/drafts/current/. 30 Internet-Drafts are draft documents valid for a maximum of six months 31 and may be updated, replaced, or obsoleted by other documents at any 32 time. It is inappropriate to use Internet-Drafts as reference 33 material or to cite them other than as "work in progress." 35 This Internet-Draft will expire on January 9, 2020. 37 Copyright Notice 39 Copyright (c) 2019 IETF Trust and the persons identified as the 40 document authors. All rights reserved. 42 This document is subject to BCP 78 and the IETF Trust's Legal 43 Provisions Relating to IETF Documents 44 (https://trustee.ietf.org/license-info) in effect on the date of 45 publication of this document. Please review these documents 46 carefully, as they describe your rights and restrictions with respect 47 to this document. Code Components extracted from this document must 48 include Simplified BSD License text as described in Section 4.e of 49 the Trust Legal Provisions and are provided without warranty as 50 described in the Simplified BSD License. 52 Table of Contents 54 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 55 1.1. Requirements Notation and Conventions . . . . . . . . . . 2 56 2. RSASSA-PKCS1-v1_5 Signature Algorithm . . . . . . . . . . . . 3 57 3. Using secp256k1 with JOSE and COSE . . . . . . . . . . . . . 3 58 3.1. JOSE and COSE secp256k1 Curve Key Representations . . . . 3 59 3.2. ECDSA Signature with secp256k1 Curve . . . . . . . . . . 4 60 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 5 61 4.1. COSE Algorithms Registrations . . . . . . . . . . . . . . 5 62 4.2. COSE Elliptic Curves Registrations . . . . . . . . . . . 6 63 4.3. JOSE Algorithms Registrations . . . . . . . . . . . . . . 6 64 4.4. JSON Web Key Elliptic Curves Registrations . . . . . . . 6 65 5. Security Considerations . . . . . . . . . . . . . . . . . . . 6 66 5.1. RSA Key Size Security Considerations . . . . . . . . . . 6 67 5.2. RSASSA-PKCS1-v1_5 with SHA-2 Security Considerations . . 7 68 5.3. RSASSA-PKCS1-v1_5 with SHA-1 Security Considerations . . 7 69 5.4. secp256k1 Security Considerations . . . . . . . . . . . . 7 70 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 7 71 6.1. Normative References . . . . . . . . . . . . . . . . . . 7 72 6.2. Informative References . . . . . . . . . . . . . . . . . 8 73 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 9 74 Document History . . . . . . . . . . . . . . . . . . . . . . . . 9 75 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 10 77 1. Introduction 79 This specification defines how to use several algorithms with COSE 80 [RFC8152] that are used by implementations of the W3C Web 81 Authentication (WebAuthn) [WebAuthn] and FIDO2 Client to 82 Authenticator Protocol (CTAP) [CTAP] specifications. These 83 algorithms are registered in the IANA "COSE Algorithms" registry 84 [IANA.COSE.Algorithms] and also in the IANA "JSON Web Signature and 85 Encryption Algorithms" registry [IANA.JOSE.Algorithms], when not 86 already registered there. 88 1.1. Requirements Notation and Conventions 90 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 91 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 92 "OPTIONAL" in this document are to be interpreted as described in BCP 93 14 [RFC2119] [RFC8174] when, and only when, they appear in all 94 capitals, as shown here. 96 2. RSASSA-PKCS1-v1_5 Signature Algorithm 98 The RSASSA-PKCS1-v1_5 signature algorithm is defined in [RFC8017]. 99 The RSASSA-PKCS1-v1_5 signature algorithm is parameterized with a 100 hash function (h). 102 A key of size 2048 bits or larger MUST be used with these algorithms. 103 Implementations need to check that the key type is 'RSA' when 104 creating or verifying a signature. 106 The RSASSA-PKCS1-v1_5 algorithms specified in this document are in 107 the following table. 109 +-------+-----------------------------+---------+-------------------+ 110 | Name | Value | Hash | Description | 111 +-------+-----------------------------+---------+-------------------+ 112 | RS256 | TBD (temporary assignment | SHA-256 | RSASSA-PKCS1-v1_5 | 113 | | -257 already in place) | | using SHA-256 | 114 | RS384 | TBD (temporary assignment | SHA-384 | RSASSA-PKCS1-v1_5 | 115 | | -258 already in place) | | using SHA-384 | 116 | RS512 | TBD (temporary assignment | SHA-512 | RSASSA-PKCS1-v1_5 | 117 | | -259 already in place) | | using SHA-512 | 118 | RS1 | TBD (temporary assignment | SHA-1 | RSASSA-PKCS1-v1_5 | 119 | | -65535 already in place) | | using SHA-1 | 120 +-------+-----------------------------+---------+-------------------+ 122 Table 1: RSASSA-PKCS1-v1_5 Algorithm Values 124 3. Using secp256k1 with JOSE and COSE 126 This section defines algorithm encodings and representations enabling 127 the Standards for Efficient Cryptography Group (SECG) elliptic curve 128 secp256k1 [SEC2] to be used for JSON Object Signing and Encryption 129 (JOSE) [RFC7515] and CBOR Object Signing and Encryption (COSE) 130 [RFC8152] messages. 132 3.1. JOSE and COSE secp256k1 Curve Key Representations 134 The Standards for Efficient Cryptography Group (SECG) elliptic curve 135 secp256k1 [SEC2] is represented in a JSON Web Key (JWK) [RFC7517] 136 using these values: 138 o "kty": "EC" 139 o "crv": "secp256k1" 141 plus "x" and "y" values to represent the curve point for the key. 142 Other optional values such as "alg" MAY also be present. 144 It is represented in a COSE_Key [RFC8152] using these values: 146 o "kty" (1): "EC2" (2) 147 o "crv" (-1): "secp256k1" (TBD - requested assignment 8) 149 plus "x" (-2) and "y" (-3) values to represent the curve point for 150 the key. Other optional values such as "alg" (3) MAY also be 151 present. 153 3.2. ECDSA Signature with secp256k1 Curve 155 The ECDSA signature algorithm is defined in [DSS]. This 156 specification defines the use of ECDSA with the secp256k1 curve and 157 the SHA-256 [DSS] cryptographic hash function. Implementations need 158 to check that the key type is "EC" for JOSE or "EC2" (2) for COSE 159 when creating or verifying a signature. 161 The ECDSA secp256k1 SHA-256 digital signature is generated as 162 follows: 164 1. Generate a digital signature of the JWS Signing Input or the COSE 165 payload using ECDSA secp256k1 SHA-256 with the desired private 166 key. The output will be the pair (R, S), where R and S are 167 256-bit unsigned integers. 169 2. Turn R and S into octet sequences in big-endian order, with each 170 array being be 32 octets long. The octet sequence 171 representations MUST NOT be shortened to omit any leading zero 172 octets contained in the values. 174 3. Concatenate the two octet sequences in the order R and then S. 175 (Note that many ECDSA implementations will directly produce this 176 concatenation as their output.) 178 4. The resulting 64-octet sequence is the JWS Signature or COSE 179 signature value. 181 The ECDSA secp256k1 SHA-256 algorithm specified in this document uses 182 these identifiers: 184 +------------+------------------------+-----------------------------+ 185 | JOSE Alg | COSE Alg Value | Description | 186 | Name | | | 187 +------------+------------------------+-----------------------------+ 188 | ES256K | TBD (requested | ECDSA using secp256k1 curve | 189 | | assignment -43) | and SHA-256 | 190 +------------+------------------------+-----------------------------+ 192 Table 2: ECDSA Algorithm Values 194 4. IANA Considerations 196 4.1. COSE Algorithms Registrations 198 This section registers the following values in the IANA "COSE 199 Algorithms" registry [IANA.COSE.Algorithms]. 201 o Name: RS256 202 o Value: TBD (temporary assignment -257 already in place) 203 o Description: RSASSA-PKCS1-v1_5 using SHA-256 204 o Reference: Section 2 of this document 205 o Recommended: No 207 o Name: RS384 208 o Value: TBD (temporary assignment -258 already in place) 209 o Description: RSASSA-PKCS1-v1_5 using SHA-384 210 o Reference: Section 2 of this document 211 o Recommended: No 213 o Name: RS512 214 o Value: TBD (temporary assignment -259 already in place) 215 o Description: RSASSA-PKCS1-v1_5 using SHA-512 216 o Reference: Section 2 of this document 217 o Recommended: No 219 o Name: RS1 220 o Value: TBD (temporary assignment -65535 already in place) 221 o Description: RSASSA-PKCS1-v1_5 using SHA-1 222 o Reference: Section 2 of this document 223 o Recommended: Deprecated 225 o Name: ES256K 226 o Value: TBD (requested assignment -43) 227 o Description: ECDSA using secp256k1 curve and SHA-256 228 o Reference: Section 3.2 of this document 229 o Recommended: Yes 231 4.2. COSE Elliptic Curves Registrations 233 This section registers the following value in the IANA "COSE Elliptic 234 Curves" registry [IANA.COSE.Curves]. 236 o Name: secp256k1 237 o Value: TBD (requested assignment 8) 238 o Key Type: EC2 239 o Description: SECG secp256k1 curve 240 o Change Controller: IESG 241 o Reference: Section 3.1 of [[ this specification ]] 242 o Recommended: Yes 244 4.3. JOSE Algorithms Registrations 246 This section registers the following value in the IANA "JSON Web 247 Signature and Encryption Algorithms" registry [IANA.JOSE.Algorithms]. 249 o Algorithm Name: ES256K 250 o Algorithm Description: ECDSA using secp256k1 curve and SHA-256 251 o Algorithm Usage Locations: alg 252 o JOSE Implementation Requirements: Optional 253 o Change Controller: IESG 254 o Reference: Section 3.2 of [[ this specification ]] 255 o Algorithm Analysis Document(s): [SEC2] 257 4.4. JSON Web Key Elliptic Curves Registrations 259 This section registers the following value in the IANA "JSON Web Key 260 Elliptic Curve" registry [IANA.JOSE.Curves]. 262 o Curve Name: secp256k1 263 o Curve Description: SECG secp256k1 curve 264 o JOSE Implementation Requirements: Optional 265 o Change Controller: IESG 266 o Specification Document(s): Section 3.1 of [[ this specification ]] 268 5. Security Considerations 270 5.1. RSA Key Size Security Considerations 272 The security considerations on key sizes for RSA algorithms from 273 Section 6.1 of [RFC8230] also apply to the RSA algorithms in this 274 specification. 276 5.2. RSASSA-PKCS1-v1_5 with SHA-2 Security Considerations 278 The security considerations on the use of RSASSA-PKCS1-v1_5 with 279 SHA-2 hash functions from Section 8.3 of [RFC7518] also apply to 280 their use in this specification. For that reason, these algorithms 281 are registered as being "Not Recommended". 283 5.3. RSASSA-PKCS1-v1_5 with SHA-1 Security Considerations 285 The security considerations on the use of the SHA-1 hash function 286 from [RFC6194] apply in this specification. For that reason, the 287 "RS1" algorithm is registered as "Deprecated". It MUST NOT be used 288 by COSE implementations. 290 A COSE algorithm identifier for this algorithm is nonetheless being 291 registered because deployed TPMs continue to use it, and therefore 292 WebAuthn implementations need a COSE algorithm identifier for "RS1" 293 when TPM attestations using this algorithm are being represented. 295 5.4. secp256k1 Security Considerations 297 Care should be taken that a secp256k1 key is not mistaken for a P-256 298 key, given that their representations are the same except for the 299 "crv" value. 301 The procedures and security considerations described in the [SEC1], 302 [SEC2], and [DSS] specifications apply to implementations of this 303 specification. 305 6. References 307 6.1. Normative References 309 [DSS] National Institute of Standards and Technology (NIST), 310 "Digital Signature Standard (DSS)", FIPS PUB 186-4, July 311 2013, . 314 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 315 Requirement Levels", BCP 14, RFC 2119, 316 DOI 10.17487/RFC2119, March 1997, 317 . 319 [RFC6194] Polk, T., Chen, L., Turner, S., and P. Hoffman, "Security 320 Considerations for the SHA-0 and SHA-1 Message-Digest 321 Algorithms", RFC 6194, DOI 10.17487/RFC6194, March 2011, 322 . 324 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 325 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 326 October 2013, . 328 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 329 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 330 2015, . 332 [RFC7517] Jones, M., "JSON Web Key (JWK)", RFC 7517, 333 DOI 10.17487/RFC7517, May 2015, 334 . 336 [RFC7518] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518, 337 DOI 10.17487/RFC7518, May 2015, 338 . 340 [RFC8017] Moriarty, K., Ed., Kaliski, B., Jonsson, J., and A. Rusch, 341 "PKCS #1: RSA Cryptography Specifications Version 2.2", 342 RFC 8017, DOI 10.17487/RFC8017, November 2016, 343 . 345 [RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)", 346 RFC 8152, DOI 10.17487/RFC8152, July 2017, 347 . 349 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 350 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 351 May 2017, . 353 [RFC8230] Jones, M., "Using RSA Algorithms with CBOR Object Signing 354 and Encryption (COSE) Messages", RFC 8230, 355 DOI 10.17487/RFC8230, September 2017, 356 . 358 [SEC1] Standards for Efficient Cryptography Group, "SEC 1: 359 Elliptic Curve Cryptography", Version 2.0, May 2009, 360 . 362 [SEC2] Standards for Efficient Cryptography Group, "SEC 2: 363 Recommended Elliptic Curve Domain Parameters", 364 Version 2.0, January 2010, 365 . 367 6.2. Informative References 369 [CTAP] Brand, C., Czeskis, A., Ehrensvaerd, J., Jones, M., Kumar, 370 A., Lindemann, R., Powers, A., and J. Verrept, "Client to 371 Authenticator Protocol (CTAP)", FIDO Alliance Proposed 372 Standard, January 2019, . 376 [IANA.COSE.Algorithms] 377 IANA, "COSE Algorithms", 378 . 381 [IANA.COSE.Curves] 382 IANA, "COSE Elliptic Curves", 383 . 386 [IANA.JOSE.Algorithms] 387 IANA, "JSON Web Signature and Encryption Algorithms", 388 . 391 [IANA.JOSE.Curves] 392 IANA, "JSON Web Key Elliptic Curve", 393 . 396 [WebAuthn] 397 Balfanz, D., Czeskis, A., Hodges, J., Jones, J., Jones, 398 M., Kumar, A., Liao, A., Lindemann, R., and E. Lundberg, 399 "Web Authentication: An API for accessing Public Key 400 Credentials - Level 1", World Wide Web Consortium 401 (W3C) Recommendation, March 2019, 402 . 404 Acknowledgements 406 Thanks to Stephen Farrell, John Fontana, Jeff Hodges, John Mattsson, 407 Tony Nadalin, Matt Palmer, Jim Schaad, Goeran Selander, Wendy 408 Seltzer, Sean Turner, and Samuel Weiler for their roles in 409 registering these algorithm identifiers. 411 Document History 413 [[ to be removed by the RFC Editor before publication as an RFC ]] 415 -01 416 o Changed the JOSE curve identifier from "P-256K" to "secp256k1". 418 o Specified that secp256k1 signing is done using the SHA-256 hash 419 function. 421 -00 423 o Created the initial working group draft from draft-jones-cose- 424 additional-algorithms-00, changing only the title, date, and 425 history entry. 427 Author's Address 429 Michael B. Jones 430 Microsoft 432 Email: mbj@microsoft.com 433 URI: http://self-issued.info/