| < draft-ietf-jose-cfrg-curves-03.txt | draft-ietf-jose-cfrg-curves-06.txt > | |||
|---|---|---|---|---|
| Network Working Group I. Liusvaara | Network Working Group I. Liusvaara | |||
| Internet-Draft Independent | Internet-Draft Independent | |||
| Intended status: Standards Track July 1, 2016 | Intended status: Standards Track August 18, 2016 | |||
| Expires: January 2, 2017 | Expires: February 19, 2017 | |||
| CFRG ECDH and signatures in JOSE | CFRG ECDH and signatures in JOSE | |||
| draft-ietf-jose-cfrg-curves-03 | draft-ietf-jose-cfrg-curves-06 | |||
| Abstract | Abstract | |||
| This document defines how to use the Diffie-Hellman algorithms | This document defines how to use the Diffie-Hellman algorithms | |||
| "X25519" and "X448" as well as the signature algorithms "Ed25519" and | "X25519" and "X448" as well as the signature algorithms "Ed25519" and | |||
| "Ed448" from the IRTF CFRG elliptic curves work in JOSE. | "Ed448" from the IRTF CFRG elliptic curves work in JOSE. | |||
| Status of This Memo | Status of This Memo | |||
| This Internet-Draft is submitted in full conformance with the | This Internet-Draft is submitted in full conformance with the | |||
| skipping to change at page 1, line 32 ¶ | skipping to change at page 1, line 32 ¶ | |||
| 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 2, 2017. | This Internet-Draft will expire on February 19, 2017. | |||
| Copyright Notice | Copyright Notice | |||
| Copyright (c) 2016 IETF Trust and the persons identified as the | Copyright (c) 2016 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 | |||
| carefully, as they describe your rights and restrictions with respect | carefully, as they describe your rights and restrictions with respect | |||
| to this document. Code Components extracted from this document must | to this document. Code Components extracted from this document must | |||
| include Simplified BSD License text as described in Section 4.e of | include Simplified BSD License text as described in Section 4.e of | |||
| the Trust Legal Provisions and are provided without warranty as | the Trust Legal Provisions and are provided without warranty as | |||
| described in the Simplified BSD License. | described in the Simplified BSD License. | |||
| Table of Contents | Table of Contents | |||
| 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 | 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 | |||
| 1.1. Requirements Terminology . . . . . . . . . . . . . . . . 3 | 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 | |||
| 2. Key type "OKP" . . . . . . . . . . . . . . . . . . . . . . . 3 | 2. Key type "OKP" . . . . . . . . . . . . . . . . . . . . . . . 3 | |||
| 3. Algorithms . . . . . . . . . . . . . . . . . . . . . . . . . 3 | 3. Algorithms . . . . . . . . . . . . . . . . . . . . . . . . . 3 | |||
| 3.1. Signatures . . . . . . . . . . . . . . . . . . . . . . . 3 | 3.1. Signatures . . . . . . . . . . . . . . . . . . . . . . . 4 | |||
| 3.1.1. Algorithms . . . . . . . . . . . . . . . . . . . . . 3 | 3.1.1. Signing . . . . . . . . . . . . . . . . . . . . . . . 4 | |||
| 3.1.2. Signing . . . . . . . . . . . . . . . . . . . . . . . 4 | 3.1.2. Verification . . . . . . . . . . . . . . . . . . . . 4 | |||
| 3.1.3. Verification . . . . . . . . . . . . . . . . . . . . 4 | ||||
| 3.2. ECDH-ES . . . . . . . . . . . . . . . . . . . . . . . . . 4 | 3.2. ECDH-ES . . . . . . . . . . . . . . . . . . . . . . . . . 4 | |||
| 3.2.1. Performing the ECDH Operation . . . . . . . . . . . . 4 | 3.2.1. Performing the ECDH Operation . . . . . . . . . . . . 5 | |||
| 4. Security considerations . . . . . . . . . . . . . . . . . . . 5 | 4. Security considerations . . . . . . . . . . . . . . . . . . . 5 | |||
| 5. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 5 | 5. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 6 | |||
| 6. IANA considerations . . . . . . . . . . . . . . . . . . . . . 6 | 6. IANA considerations . . . . . . . . . . . . . . . . . . . . . 6 | |||
| 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 7 | 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 7 | |||
| 7.1. Normative References . . . . . . . . . . . . . . . . . . 7 | 7.1. Normative References . . . . . . . . . . . . . . . . . . 7 | |||
| 7.2. Informative References . . . . . . . . . . . . . . . . . 8 | 7.2. Informative References . . . . . . . . . . . . . . . . . 8 | |||
| Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 8 | Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 8 | |||
| A.1. Ed25519 Private Key . . . . . . . . . . . . . . . . . . . 8 | A.1. Ed25519 Private Key . . . . . . . . . . . . . . . . . . . 8 | |||
| A.2. Ed25519 Public Key . . . . . . . . . . . . . . . . . . . 8 | A.2. Ed25519 Public Key . . . . . . . . . . . . . . . . . . . 9 | |||
| A.3. JWK Thumbprint Canonicalization . . . . . . . . . . . . . 8 | A.3. JWK Thumbprint Canonicalization . . . . . . . . . . . . . 9 | |||
| A.4. Ed25519 Signing . . . . . . . . . . . . . . . . . . . . . 9 | A.4. Ed25519 Signing . . . . . . . . . . . . . . . . . . . . . 9 | |||
| A.5. Ed25519 Validation . . . . . . . . . . . . . . . . . . . 10 | A.5. Ed25519 Validation . . . . . . . . . . . . . . . . . . . 10 | |||
| A.6. ECDH-ES with X25519 . . . . . . . . . . . . . . . . . . . 10 | A.6. ECDH-ES with X25519 . . . . . . . . . . . . . . . . . . . 11 | |||
| A.7. ECDH-ES with X448 . . . . . . . . . . . . . . . . . . . . 11 | A.7. ECDH-ES with X448 . . . . . . . . . . . . . . . . . . . . 12 | |||
| Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 13 | Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 13 | |||
| 1. Introduction | 1. Introduction | |||
| Internet Research Task Force (IRTF) Crypto Forum Research Group | Internet Research Task Force (IRTF) Crypto Forum Research Group | |||
| (CFRG) selected new Diffie-Hellman algorithms ("X25519" and "X448"; | (CFRG) selected new Diffie-Hellman algorithms ("X25519" and "X448"; | |||
| [RFC7748]) and signature algorithms ("Ed25519" and "Ed448"; | [RFC7748]) and signature algorithms ("Ed25519" and "Ed448"; | |||
| [I-D.irtf-cfrg-eddsa]) for asymmetric key cryptography. This | [I-D.irtf-cfrg-eddsa]) for asymmetric key cryptography. This | |||
| document defines how those algorithms are to be used in JOSE in | document defines how to use those algorithms in JOSE in interoperable | |||
| interoperable manner. | manner. | |||
| This document defines the conventions to be used in the context of | This document defines the conventions to use in the context of | |||
| [RFC7517] and [RFC7518]. | [RFC7515], [RFC7516], and [RFC7517]. | |||
| While the CFRG also defined two pairs of isogenous elliptic curves | While the CFRG also defined two pairs of isogenous elliptic curves | |||
| that underlie these algorithms, these curves are not directly | that underlie these algorithms, these curves are not directly | |||
| exposed, as the algorithms laid on top are sufficient for the | exposed, as the algorithms laid on top are sufficient for the | |||
| purposes of JOSE and are much easier to use. (Trying to apply ECDSA | purposes of JOSE and are much easier to use. | |||
| to those curves leads to nasty corner-cases and produces odd | ||||
| results.) | ||||
| All inputs to and outputs from the the ECDH and signature functions | ||||
| are defined to be octet strings, with the exception of outputs of | ||||
| verification function, which are booleans. | ||||
| 1.1. Requirements Terminology | All inputs to and outputs from the ECDH and signature functions are | |||
| defined to be octet strings, with the exception of outputs of | ||||
| verification functions, which are booleans. | ||||
| 1.1. Terminology | ||||
| The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", | The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", | |||
| "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this | "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this | |||
| document are to be interpreted as described in [RFC2119]. | document are to be interpreted as described in [RFC2119]. | |||
| "JWS Signing Input" and "JWS Signature" are defined by [RFC7515]. | ||||
| "Key Agreement with Elliptic Curve Diffie-Hellman Ephemeral Static" | ||||
| is defined by [RFC7518], section 4.6. | ||||
| The JOSE key format ("JSON Web Key (JWK)") is defined by [RFC7517] | ||||
| and thumbprints for it ("JSON Web Key (JWK) Thumbprint") in | ||||
| [RFC7638]. | ||||
| 2. Key type "OKP" | 2. Key type "OKP" | |||
| A new key type (kty) value "OKP" (Octet Key Pair) is defined for | A new key type (kty) value "OKP" (Octet Key Pair) is defined for | |||
| public key algorithms that use octet strings as private and public | public key algorithms that use octet strings as private and public | |||
| keys. It has the following parameters: | keys. It has the following parameters: | |||
| o The parameter "kty" MUST be "OKP". | o The parameter "kty" MUST be "OKP". | |||
| o The parameter "crv" MUST be present and contain the subtype of the | o The parameter "crv" MUST be present and contain the subtype of the | |||
| key (from "JSON Web Elliptic Curve" registry). | key (from the "JSON Web Elliptic Curve" registry). | |||
| o The parameter "x" MUST be present and contain the public key | o The parameter "x" MUST be present and contain the public key | |||
| encoded using the base64url [RFC4648] encoding. | encoded using the base64url [RFC4648] encoding. | |||
| o The parameter "d" MUST be present for private keys and contain the | o The parameter "d" MUST be present for private keys and contain the | |||
| private key encoded using the base64url encoding. This parameter | private key encoded using the base64url encoding. This parameter | |||
| MUST NOT be present for public keys. | MUST NOT be present for public keys. | |||
| Note: Do not assume that there is an underlying elliptic curve, | Note: Do not assume that there is an underlying elliptic curve, | |||
| despite the existence of the "crv" and "x" parameters. (For | despite the existence of the "crv" and "x" parameters. (For | |||
| instance, this key type could be extended to represent DH algorithms | instance, this key type could be extended to represent DH algorithms | |||
| based on hyperelliptic surfaces.) | based on hyperelliptic surfaces.) | |||
| When calculating JWK Thumbprints [RFC7638], the three public key | When calculating JWK Thumbprints [RFC7638], the three public key | |||
| fields are included in the hash input lexicographic order: "crv", | fields are included in the hash input in lexicographic order: "crv", | |||
| "kty", and "x". | "kty", and "x". | |||
| 3. Algorithms | 3. Algorithms | |||
| 3.1. Signatures | 3.1. Signatures | |||
| 3.1.1. Algorithms | For purpose of using EdDSA for signing data using "JSON Web Signature | |||
| (JWS)" ([RFC7515]), algorithm "EdDSA" is defined here, to be applied | ||||
| For EdDSA signatures, algorithm "EdDSA" is defined here, to be | as the value of the "alg" parameter. | |||
| applied as value of "alg" parameter. | ||||
| The key type for these keys is "OKP" and key subtype for these keys | The following key subtypes are defined here for use with EdDSA: | |||
| MUST be "Ed25519" for Ed25519 and "Ed448" for Ed448. The keys of | ||||
| these subtypes MUST NOT be used for ECDH-ES. | ||||
| "crv" EdDSA Variant | "crv" EdDSA Variant | |||
| Ed25519 Ed25519 | Ed25519 Ed25519 | |||
| Ed448 Ed448 | Ed448 Ed448 | |||
| 3.1.2. Signing | The key type used with these keys is "OKP" and the algorithm used for | |||
| signing is "EdDSA". These subtypes MUST NOT be used for ECDH-ES. | ||||
| The EdDSA variant used is determined by the subtype of the key | ||||
| (Ed25519 for "Ed25519" and Ed448 for "Ed448"). | ||||
| 3.1.1. Signing | ||||
| Signing for these is preformed by applying the signing algorithm | Signing for these is preformed by applying the signing algorithm | |||
| defined in [I-D.irtf-cfrg-eddsa] to the private key (as private key), | defined in [I-D.irtf-cfrg-eddsa] to the private key (as private key), | |||
| public key (as public key) and the JWS Signing Input (as message). | public key (as public key) and the JWS Signing Input (as message). | |||
| The resulting signature is the JWS Signature value. All inputs and | The resulting signature is the JWS Signature. All inputs and outputs | |||
| outputs are octet strings. | are octet strings. | |||
| 3.1.3. Verification | 3.1.2. Verification | |||
| Verification is performed by applying the verification algorithm | Verification is performed by applying the verification algorithm | |||
| defined in [I-D.irtf-cfrg-eddsa] to the public key (as public key), | defined in [I-D.irtf-cfrg-eddsa] to the public key (as public key), | |||
| the JWS Signing Input (as message) and the JWS Signature value (as | the JWS Signing Input (as message) and the JWS Signature (as | |||
| signature). All inputs are octet strings. If the algorithm accepts, | signature). All inputs are octet strings. If the algorithm accepts, | |||
| the signature is valid; otherwise, the signature is invalid. | the signature is valid; otherwise, the signature is invalid. | |||
| 3.2. ECDH-ES | 3.2. ECDH-ES | |||
| The following key subtypes defined here for purpose of "Key Agreement | The following key subtypes are defined here for purpose of "Key | |||
| with Elliptic Curve Diffie-Hellman Ephemeral Static" (ECDH-ES). | Agreement with Elliptic Curve Diffie-Hellman Ephemeral Static" (ECDH- | |||
| ES): | ||||
| "crv" ECDH Function Applied | "crv" ECDH Function Applied | |||
| X25519 X25519 | X25519 X25519 | |||
| X448 X448 | X448 X448 | |||
| The key type used with these keys is "OKP". These subtypes MUST NOT | The key type used with these keys is "OKP". These subtypes MUST NOT | |||
| be used for signing. | be used for signing. | |||
| [RFC7518] Section 4.6 defines the ECDH-ES algorithms "ECDH- | [RFC7518] Section 4.6 defines the ECDH-ES algorithms "ECDH- | |||
| ES+A128KW", "ECDH-ES+A192KW", "ECDH-ES+A256KW" and "ECDH-ES". | ES+A128KW", "ECDH-ES+A192KW", "ECDH-ES+A256KW" and "ECDH-ES". | |||
| skipping to change at page 6, line 5 ¶ | skipping to change at page 6, line 14 ¶ | |||
| The nominal security strengths of X25519 and X448 are ~126 and ~223 | The nominal security strengths of X25519 and X448 are ~126 and ~223 | |||
| bits. Therefore, using 256-bit symmetric encryption (especially key | bits. Therefore, using 256-bit symmetric encryption (especially key | |||
| wrapping and encryption) with X448 is RECOMMENDED. | wrapping and encryption) with X448 is RECOMMENDED. | |||
| 5. Acknowledgements | 5. Acknowledgements | |||
| Thanks to Michael B. Jones for his comments on an initial pre-draft | Thanks to Michael B. Jones for his comments on an initial pre-draft | |||
| and editorial help. | and editorial help. | |||
| Thanks to Matt Miller for some editorial help. | ||||
| 6. IANA considerations | 6. IANA considerations | |||
| The following is added to the "JSON Web Key Types" registry: | The following is added to the "JSON Web Key Types" registry: | |||
| o "kty" Parameter Value: "OKP" | o "kty" Parameter Value: "OKP" | |||
| o Key Type Description: Octet string key pairs | o Key Type Description: Octet string key pairs | |||
| o JOSE Implementation Requirements: Optional | o JOSE Implementation Requirements: Optional | |||
| o Change Controller: IESG | o Change Controller: IESG | |||
| o Specification Document(s): Section 2 of [RFC-THIS] | o Specification Document(s): Section 2 of [RFC-THIS] | |||
| skipping to change at page 7, line 44 ¶ | skipping to change at page 8, line 5 ¶ | |||
| [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate | [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate | |||
| Requirement Levels", BCP 14, RFC 2119, | Requirement Levels", BCP 14, RFC 2119, | |||
| DOI 10.17487/RFC2119, March 1997, | DOI 10.17487/RFC2119, March 1997, | |||
| <http://www.rfc-editor.org/info/rfc2119>. | <http://www.rfc-editor.org/info/rfc2119>. | |||
| [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data | [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data | |||
| Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, | Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, | |||
| <http://www.rfc-editor.org/info/rfc4648>. | <http://www.rfc-editor.org/info/rfc4648>. | |||
| [RFC7748] Langley, A., Hamburg, M., and S. Turner, "Elliptic Curves | [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web | |||
| for Security", RFC 7748, DOI 10.17487/RFC7748, January | Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May | |||
| 2016, <http://www.rfc-editor.org/info/rfc7748>. | 2015, <http://www.rfc-editor.org/info/rfc7515>. | |||
| [I-D.irtf-cfrg-eddsa] | ||||
| Josefsson, S. and I. Liusvaara, "Edwards-curve Digital | ||||
| Signature Algorithm (EdDSA)", draft-irtf-cfrg-eddsa-05 | ||||
| (work in progress), March 2016. | ||||
| 7.2. Informative References | ||||
| [RFC7517] Jones, M., "JSON Web Key (JWK)", RFC 7517, | [RFC7517] Jones, M., "JSON Web Key (JWK)", RFC 7517, | |||
| DOI 10.17487/RFC7517, May 2015, | DOI 10.17487/RFC7517, May 2015, | |||
| <http://www.rfc-editor.org/info/rfc7517>. | <http://www.rfc-editor.org/info/rfc7517>. | |||
| [RFC7518] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518, | [RFC7518] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518, | |||
| DOI 10.17487/RFC7518, May 2015, | DOI 10.17487/RFC7518, May 2015, | |||
| <http://www.rfc-editor.org/info/rfc7518>. | <http://www.rfc-editor.org/info/rfc7518>. | |||
| [RFC7638] Jones, M. and N. Sakimura, "JSON Web Key (JWK) | [RFC7638] Jones, M. and N. Sakimura, "JSON Web Key (JWK) | |||
| Thumbprint", RFC 7638, DOI 10.17487/RFC7638, September | Thumbprint", RFC 7638, DOI 10.17487/RFC7638, September | |||
| 2015, <http://www.rfc-editor.org/info/rfc7638>. | 2015, <http://www.rfc-editor.org/info/rfc7638>. | |||
| [RFC7748] Langley, A., Hamburg, M., and S. Turner, "Elliptic Curves | ||||
| for Security", RFC 7748, DOI 10.17487/RFC7748, January | ||||
| 2016, <http://www.rfc-editor.org/info/rfc7748>. | ||||
| [I-D.irtf-cfrg-eddsa] | ||||
| Josefsson, S. and I. Liusvaara, "Edwards-curve Digital | ||||
| Signature Algorithm (EdDSA)", draft-irtf-cfrg-eddsa-06 | ||||
| (work in progress), August 2016. | ||||
| 7.2. Informative References | ||||
| [RFC7516] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", | ||||
| RFC 7516, DOI 10.17487/RFC7516, May 2015, | ||||
| <http://www.rfc-editor.org/info/rfc7516>. | ||||
| Appendix A. Examples | Appendix A. Examples | |||
| To the extent possible, the examples use material taken from test | To the extent possible, the examples use material taken from test | |||
| vectors of [RFC7748] and [I-D.irtf-cfrg-eddsa]. | vectors of [RFC7748] and [I-D.irtf-cfrg-eddsa]. | |||
| A.1. Ed25519 Private Key | A.1. Ed25519 Private Key | |||
| {"kty":"OKP","crv":"Ed25519", | {"kty":"OKP","crv":"Ed25519", | |||
| "d":"nWGxne_9WmC6hEr0kuwsxERJxWl7MmkZcDusAxyuf2A" | "d":"nWGxne_9WmC6hEr0kuwsxERJxWl7MmkZcDusAxyuf2A" | |||
| "x":"11qYAYKxCrfVS_7TyWQHOg7hcvPapiMlrwIaaPcHURo"} | "x":"11qYAYKxCrfVS_7TyWQHOg7hcvPapiMlrwIaaPcHURo"} | |||
| End of changes. 27 change blocks. | ||||
| 53 lines changed or deleted | 73 lines changed or added | |||
This html diff was produced by rfcdiff 1.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/ | ||||