<?xml version="1.0" encoding="ISO-8859-1"?> version='1.0' encoding='utf-8'?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
<!ENTITY rfc2119 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml">
<!ENTITY rfc4250 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4250.xml">
<!ENTITY rfc4251 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4251.xml">
<!ENTITY rfc4253 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4253.xml">
<!ENTITY rfc5656 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5656.xml">
<!ENTITY rfc6234 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6234.xml">
<!ENTITY rfc7748 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.7748.xml">
<!ENTITY rfc8174 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.8174.xml">
]>

<?rfc compact="yes"?>
<?rfc toc="yes"?>
<?rfc symrefs="yes"?>

<?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>
<?rfc strict="yes" ?>
<?rfc tocdepth="4"?>
<?rfc sortrefs="yes" ?>
<?rfc subcompact="no" ?> "rfc2629-xhtml.ent">

<rfc number="8731" consensus="true" xmlns:xi="http://www.w3.org/2001/XInclude" category="std"
     ipr="trust200902"
     docName="draft-ietf-curdle-ssh-curves-12"> docName="draft-ietf-curdle-ssh-curves-12" obsoletes=""
     updates="" submissionType="IETF" xml:lang="en" tocInclude="true"
     symRefs="true" tocDepth="4" sortRefs="true" version="3">

  <!-- xml2rfc v2v3 conversion 2.35.0 -->
  <front>
    <title abbrev="Curve25519/448 for SSH">
      Secure Shell (SSH) Key Exchange Method using Using Curve25519 and
      Curve448
    </title>
    <seriesInfo name="RFC" value="8731" />
    <author initials="A." surname="Adamantiadis" fullname="Aris Adamantiadis">
      <organization>libssh</organization>
      <address>
        <email>aris@badcode.be</email>
      </address>
    </author>
    <author initials="S." surname="Josefsson" fullname="Simon Josefsson">
      <organization>SJD AB</organization>
      <address>
        <email>simon@josefsson.org</email>
      </address>
    </author>
    <author initials="M. D." initials="M." surname="Baushke" fullname="Mark D. Baushke">
      <organization>Juniper Networks, Inc.</organization>
      <address>
        <email>mdb@juniper.net</email>
      </address>
    </author>
    <date year="2019"/> month="February" year="2020"/>
    <workgroup>Internet Engineering Task Force</workgroup>

<keyword>Elliptic</keyword>
<keyword>Curve</keyword>
<keyword>Diffie</keyword>
<keyword>Hellman</keyword>
<keyword>ECDH</keyword>

    <abstract>
      <t>
        This document describes the specification for using Curve25519
        and Curve448 key exchange methods in the Secure Shell (SSH)
        protocol.
      </t>
    </abstract>
  </front>
  <middle>
    <section title="Introduction"> numbered="true" toc="default">
      <name>Introduction</name>
      <t>
        Secure Shell (SSH) <xref target="RFC4251"/> target="RFC4251" format="default"/> is a secure remote
        login protocol. The key exchange protocol described in <xref
        target="RFC4253"/>
	target="RFC4253" format="default"/> supports an extensible set of
	methods.
        <xref target="RFC5656"/> target="RFC5656" format="default"/> defines how elliptic curves are
        integrated into this extensible SSH framework, and this
        document reuses the Elliptic Curve Diffie-Hellman (ECDH) key
        exchange protocol messages defined in section 7.1 "ECDH Section
        <xref target="RFC5656" sectionFormat="bare" section="7.1">ECDH Message Numbers"
	Numbers</xref> of <xref target="RFC5656"/>. Other parts of
        <xref target="RFC5656"/>, target="RFC5656" format="default"/>, such as Elliptic Curve
        Menezes-Qu-Vanstone (ECMQV) key agreement, agreement and Elliptic Curve
        Digital Signature Algorithm (ECDSA) (ECDSA), are not considered in this
        document.
      </t>
      <t>
        This document describes how to implement key exchange based on
        Curve25519 and Curve448 <xref target="RFC7748"/> target="RFC7748" format="default"/> in SSH. For
        Curve25519 with SHA-256 <xref target="RFC6234"/> and <xref
        target="SHS"/>, target="RFC6234" format="default"/><xref
	target="SHS" format="default"/>, the algorithm described is equivalent
	to the
        privately defined algorithm "curve25519-sha256@libssh.org",
        which at the time of publication was implemented and widely
        deployed in libssh <xref target="libssh"/> target="libssh" format="default"/> and
	OpenSSH <xref
        target="OpenSSH"/>. target="OpenSSH" format="default"/>. The Curve448 key
	exchange method is
        similar but uses SHA-512 <xref target="RFC6234"/> and <xref
        target="SHS"/>. target="RFC6234"
	format="default"/><xref target="SHS" format="default"/>.
      </t>
    </section>
    <section title="Requirements Language"> numbered="true" toc="default">
      <name>Requirements Language</name>
        <t>
    The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
        NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT
        RECOMMENDED", "MAY", "<bcp14>MUST</bcp14>", "<bcp14>MUST NOT</bcp14>",
    "<bcp14>REQUIRED</bcp14>", "<bcp14>SHALL</bcp14>", "<bcp14>SHALL
    NOT</bcp14>", "<bcp14>SHOULD</bcp14>", "<bcp14>SHOULD NOT</bcp14>",
    "<bcp14>RECOMMENDED</bcp14>", "<bcp14>NOT RECOMMENDED</bcp14>",
    "<bcp14>MAY</bcp14>", and "OPTIONAL" "<bcp14>OPTIONAL</bcp14>" in this document are to be interpreted as
    described in BCP&nbsp;14 <xref target="RFC2119"/> <xref target="RFC8174"/>
    when, and only when, they appear in all capitals, as shown here.
        </t>

    </section>
    <section title="Key numbered="true" toc="default">
      <name>Key Exchange Methods"> Methods</name>
      <t>
        The key exchange procedure is similar to the ECDH method
        described in chapter 4 of <xref target="RFC5656" />, sectionFormat="of" section="4"/>, though
        with a different wire encoding used for public values and the
        final shared secret. Public ephemeral keys are encoded for
        transmission as standard SSH strings.
      </t>
      <t>
        The protocol flow, the SSH_MSG_KEX_ECDH_INIT and
        SSH_MSG_KEX_ECDH_REPLY messages, and the structure of the
        exchange hash are identical to chapter 4 of <xref target="RFC5656" />.
	sectionFormat="of" section="4"/>.
      </t>
      <t>
        The method names registered by this document are
        "curve25519-sha256" and "curve448-sha512".
      </t>
      <t>
        The methods are based on Curve25519 and Curve448 scalar
        multiplication, as described in <xref target="RFC7748"/>. target="RFC7748" format="default"/>.
        Private and public keys are generated as described therein.
        Public keys are defined as strings of 32 bytes for Curve25519
        and 56 bytes for Curve448.
      </t>
      <t>
        Key-agreement
        The key-agreement schemes "curve25519-sha256" and
        "curve448-sha512" perform the Diffie-Hellman protocol using
        the functions X25519 and X448, respectively. Implementations
        SHOULD
        <bcp14>SHOULD</bcp14> compute these functions using the algorithms described
        in [RFC7748]. <xref target="RFC7748" format="default"/>. When they do so,
	implementations MUST <bcp14>MUST</bcp14> check
        whether the computed Diffie-Hellman shared secret is the
        all-zero value and abort if so, as described in Section 6 of
        [RFC7748]. <xref target="RFC7748"
	sectionFormat="of" section="6"/>.
	Alternative implementations of these functions
        SHOULD
        <bcp14>SHOULD</bcp14> abort when either the client or the server input
   forces the shared secret to one of a small set of values, as
   described in Section 7 Sections <xref target="RFC7748" section="6"
	sectionFormat="bare"/> and <xref target="RFC7748" section="7"
	sectionFormat="bare"/> of
        [RFC7748]. <xref target="RFC7748"/>. Clients and servers MUST <bcp14>MUST</bcp14> also abort if
        the length of the received public keys are not the expected
        lengths. An abort for these purposes is defined as a
        disconnect (SSH_MSG_DISCONNECT) of the session and SHOULD <bcp14>SHOULD</bcp14> use
        the SSH_DISCONNECT_KEY_EXCHANGE_FAILED reason for the message
        <xref target="IANA-REASON"/>. target="IANA-REASON" format="default"/>.
        No further validation is required beyond what is described in
        <xref target="RFC7748"/>. target="RFC7748" format="default"/>. The derived shared secret is 32
        bytes when "curve25519-sha256" is used and 56 bytes when
        "curve448-sha512" is used. The encodings of all values are
        defined in <xref target="RFC7748"/>. target="RFC7748" format="default"/>. The hash used is SHA-256
        for "curve25519-sha256" and SHA-512 for "curve448-sha512".
      </t>
      <section title="Shared numbered="true" toc="default">
        <name>Shared Secret Encoding"> Encoding</name>
        <t>
          The following step differs from <xref target="RFC5656"/>, target="RFC5656" format="default"/>,
          which uses a different conversion. This is not intended to
          modify that text generally, but only to be applicable to the
          scope of the mechanism described in this document.
        </t>
        <t>
          The shared secret, K, is defined in <xref target="RFC4253"/> target="RFC4253" format="default"/>
          and <xref target="RFC5656"/> target="RFC5656" format="default"/> as an integer encoded
          as a multiple precision integer (mpint). Curve25519/448
          outputs a binary string X, which is the 32 32- or 56 byte 56-byte point
          obtained by scalar multiplication of the other side's public
          key and the local private key scalar. The 32 or 56 bytes of
          X are converted into K by interpreting the octets as an
          unsigned fixed-length integer encoded in network byte order.
        </t>

        <t>
          The integer mpint K is then encoded as an mpint using the process
          described in section 5 of <xref target="RFC4251"/> target="RFC4251" sectionFormat="of" section="5"/>, and the
          resulting bytes are fed as described in <xref
          target="RFC4253"/> target="RFC4253" format="default"/> to the key exchange method's hash
          function to generate encryption keys.
        </t>
        <t>
          When performing the X25519 or X448 operations, the integer
          values there will be encoded into byte strings by doing a
          fixed-length unsigned little-endian conversion, per <xref
          target="RFC7748"/>.
	  target="RFC7748" format="default"/>. It is only later when these
	  byte strings
          are then passed to the ECDH function in SSH that the bytes
          are re-interpreted reinterpreted as a fixed-length unsigned big-endian
          integer value K, and then later that K value is encoded as a
          variable-length signed "mpint" before being fed to the hash
          algorithm used for key generation. The mpint K is then fed
          along with other data to the key exchange method's hash
          function to generate encryption keys.
        </t>
      </section>
    </section>

    <section title="Acknowledgements">

      <t>
        The "curve25519-sha256" key exchange method is identical to
        the "curve25519-sha256@libssh.org" key exchange method created
        by Aris Adamantiadis and implemented in libssh and OpenSSH.
      </t>

      <t>
        Thanks to the following people for review and comments: Denis
        Bider, Damien Miller, Niels Möller, Matt Johnston, Eric
        Rescorla, Ron Frederick, Stefan Bühler.
      </t>

    </section>

    <section title="Security Considerations"> numbered="true" toc="default">
      <name>Security Considerations</name>
      <t>
        The security considerations of <xref target="RFC4251"/>, target="RFC4251" format="default"/>, <xref
        target="RFC5656"/>, target="RFC5656" format="default"/>, and <xref target="RFC7748"/> target="RFC7748" format="default"/> are
        inherited.
      </t>
      <t>
        Curve25519 with SHA-256 provides strong (~128 bits) security
        and security,
        is efficient on a wide range of architectures, and has
        properties
        characteristics that allows allow for better implementation properties
        compared to traditional elliptic curves. Curve448 with SHA-512
        provides stronger (~224 bits) security with similar
        implementation properties, but properties; however, it has not received the same
        cryptographic review as Curve25519, and Curve25519.  It is also slower (larger key
        material and larger secure hash algorithm), but it is provided
        as a hedge to combat unforeseen analytical advances against
        Curve25519 and SHA-256 due to the larger number of security
        bits.
      </t>
      <t>
        The way the derived mpint binary secret string is encoded into a
        mpint
        before it is hashed (i.e., adding or removing zero-bytes zero bytes
        for encoding) raises the potential for a side-channel attack attack,
        which could determine the length of what is hashed. This
        would leak the most significant bit of the derived secret, secret
        and/or allow detection of when the most significant bytes are
        zero. For backwards compatibility reasons backwards-compatibility reasons, it was decided not
        to address this potential problem.
      </t>
      <t>
        This document provides "curve25519-sha256" as the preferred
        choice,
        choice but suggests that the "curve448-sha512" is be implemented
        to provide more than 128 bits of security strength should that
        become a requirement.
      </t>
    </section>
    <section anchor="iana-considerations" title="IANA Considerations"> numbered="true" toc="default">
      <name>IANA Considerations</name>
      <t>
        IANA is requested to add has added "curve25519-sha256" and
        "curve448-sha512" to the "Key Exchange Method Names" registry
        for SSH <xref target="IANA-KEX"/> target="IANA-KEX" format="default"/> that was created in
	<xref
        target="RFC4250">RFC 4250 section 4.10</xref>. target="RFC4250" sectionFormat="of" section="4.10"/>.
      </t>
    </section>
  </middle>
  <back>

    <references title="Normative References">

      &rfc2119;
      &rfc4250;
      &rfc4251;
      &rfc4253;
      &rfc5656;
      &rfc8174;
    <references>
      <name>References</name>
      <references>
        <name>Normative References</name>
        <xi:include href="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.2119.xml"/>
        <xi:include href="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.4250.xml"/>
        <xi:include href="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.4251.xml"/>
        <xi:include href="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.4253.xml"/>
        <xi:include href="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.5656.xml"/>
        <xi:include href="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.8174.xml"/>

        <reference anchor="SHS"
          target="http://dx.doi.org/10.6028/NIST.FIPS.180-4"> target="https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.180-4.pdf">
          <front>
            <title>Secure Hash Standard (SHS)</title>
            <author>
            <organization>Information Technology Laboratory
              <organization>
            National Institute of Standards and Technology</organization>
            </author>
            <date month="August" year="2015"/>
          </front>
          <seriesInfo name="FIPS PUB" value="180-4"/>
          <seriesInfo name="DOI" value="10.6028/NIST.FIPS.180-4"/>
        </reference>
      </references>

    <references title="Informative References">

      <references>

        <name>Informative References</name>
        <reference anchor="IANA-KEX"
         target="http://www.iana.org/assignments/ssh-parameters/ssh-parameters.xhtml#ssh-parameters-16"> target="https://www.iana.org/assignments/ssh-parameters/">
          <front>
            <title>Secure Shell (SSH) Protocol Parameters:
         Key Exchange Method Names</title>
            <author>
           <organization>Internet Assigned Numbers Authority (IANA)
              <organization>IANA
              </organization>
            </author>
         <date month="August" year="2019"/>
            <date/>
          </front>
        </reference>

        <reference anchor="IANA-REASON"
         target="http://www.iana.org/assignments/ssh-parameters/ssh-parameters.xhtml#ssh-parameters-3"> target="https://www.iana.org/assignments/ssh-parameters/">
          <front>
            <title>Secure Shell (SSH) Protocol Parameters:
         Disconnection Messages Reason Codes and Descriptions</title>
            <author>
           <organization>Internet Assigned Numbers Authority (IANA)
              <organization>IANA
              </organization>
            </author>
         <date month="August" year="2019"/>
            <date/>
          </front>
        </reference>

      &rfc6234;
      &rfc7748;

        <xi:include href="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.6234.xml"/>
        <xi:include href="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.7748.xml"/>

        <reference anchor="libssh" target="https://www.libssh.org/">
          <front>
            <title>The SSH Library</title>
            <author>
              <organization>libssh</organization>
            </author>
            <date month="September" year="2019"/> month="" year=""/>
          </front>
        </reference>

        <reference anchor="OpenSSH" target="https://www.openssh.com/">
          <front>
            <title>The OpenSSH Project</title>
            <author>
              <organization>OpenSSH group of OpenBSD</organization>
            </author>
            <date month="September" year="2019"/> month="" year=""/>
          </front>
        </reference>
      </references>

   <!-- Change Log

v01 2017-03-17 MDB   Updated draft-josefsson-ssh-curves-04 as
                     draft-ietf-curdle-ssh-curves-01. Fixed
                     initials="" for Curve25519. Expanded LNCS.
                     Trimmed trailing whitespace.

v02 2017-04-11 MDB   Moved
    </references>

    <section numbered="false" toc="default">
      <name>Acknowledgements</name>
      <t>
        The "curve25519-sha256" key exchange method is identical to Standards Track, updated Abstract,
        the "curve25519-sha256@libssh.org" key exchange method created
        by <contact fullname="Aris Adamantiadis"/> and
                     updated Introduction per Daniel Migault.
                     Add initils for Mike Hamburg citation.
                     Add an IANA-KEX reference.

v03 2017-04-12 MDB   Fix NIT RFC4634 -> RFC6234

v04 2017-04-12 MDB   Use Curve25519 implemented in libssh and Curve448 from RFC7748 rather
                     than reference informative papers on the curves
                     per Sean Turner <sean@sn3rd.com> comments.

v05 2017-05-11 MDB   Fix grammar per Eric Rescorla <ekr@rtfm.com>.
                     Add clarifications OpenSSH.
      </t>
      <t>
        Thanks to shared secret encoding per
                     Ron Frederick. Add Ron to Acknowledgements.
                     Add pseudo-code from Stefan Bühler and
                     acknowlegement.

v06 2017-05-16 MDB   Additional updates suggested by Ron Frederick.

v07 2018-01-02 MDB   Add requirements language section.

v08 2018-06-27 MDB   Minor cleanup for expired draft.

v09 2019-08-01 MDB   Clean up the following people for expired draft. Address ekr comments.

v10 2019-08-12 MDB   Fix comment from Ron Frederick review and Benjamin Kaduk.
    2019-08-25 MDB   Fix nit from Tobias Gondrom.
    2019-08-26 MDB   Fix GenArt comments from Christer Holmberg.
    2019-09-03 MDB   Fix Éric Vyncke comments.
                     Remove "Copying conditions" section.

v11 2019-09-03 MDB   Adopt revised sentence from Ron Fredericks in section 3.
    2019-09-04 MDB   Fix per Roman Danyliw comments.

   --> comments: <contact fullname="Denis
        Bider"/>, <contact fullname="Damien Miller"/>, <contact fullname="Niels Moeller"/>, <contact fullname="Matt Johnston"/>, <contact fullname="Eric
        Rescorla"/>, <contact fullname="Ron Frederick"/>, and <contact fullname="Stefan Buehler"/>.
      </t>
    </section>
  </back>
</rfc>