RFC 8332

Use of RSA Keys with SHA-256 and SHA-512 in the Secure Shell (SSH) Protocol

📅 published March 2018, from ietf

RFC 8332: Use of RSA Keys with SHA-256 and SHA-512 in the Secure Shell (SSH) Protocol ✨

  • Stream: Internet Engineering Task Force (IETF) 🌸
  • Request for Comments: 8332 📜
  • Author: D. Bider, Bitvise Limited 🧚
  • Category: Standards Track 🏆
  • Date: March 2018 📅
  • Updates: 4252, 4253 🔧
  • Obsoletes: none listed
  • ISSN: 2070-1721

Abstract 🦋

Okay so this memo updates RFCs 4252 and 4253 to define new public key algorithms for using RSA keys with SHA-256 and SHA-512, for both server and client authentication in SSH connections. It's giving upgrade energy 💜

Status of This Memo 📣

This is an Internet Standards Track document, so it's officially a big deal 👑

This document is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community. It got public review and was approved for publication by the Internet Engineering Steering Group (IESG). If you want more on Internet Standards, check out Section 2 of RFC 7841 🤓

Info about the current status, any errata, and how to send feedback lives at https://www.rfc-editor.org/info/rfc8332 💌

Copyright (c) 2018 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) as in effect on the date this document was published. Please read these carefully, because they spell out your rights and restrictions for this document. Code Components pulled out of this document need to include Simplified BSD License text, as described in Section 4.e of the Trust Legal Provisions, and they come without warranty, as described in the Simplified BSD License.

This document may contain material from IETF Documents or IETF Contributions that were published or made publicly available before November 10, 2008. The person(s) controlling the copyright in some of this material may not have granted the IETF Trust the right to allow modifications of that material outside the IETF Standards Process. Without an adequate license from the person(s) controlling the copyright in those materials, this document may not be modified outside the IETF Standards Process, and derivative works of it may not be created outside the IETF Standards Process, except to format it for publication as an RFC or to translate it into languages other than English 🌍

Table of Contents 📑

   1.  Overview and Rationale  . . . . . . . . . . . . . . . . . . .   3
     1.1.  Requirements Terminology  . . . . . . . . . . . . . . . .   3
     1.2.  Wire Encoding Terminology . . . . . . . . . . . . . . . .   3
   2.  Public Key Format vs. Public Key Algorithm  . . . . . . . . .   3
   3.  New RSA Public Key Algorithms . . . . . . . . . . . . . . . .   4
     3.1.  Use for Server Authentication . . . . . . . . . . . . . .   5
     3.2.  Use for Client Authentication . . . . . . . . . . . . . .   5
     3.3.  Discovery of Public Key Algorithms Supported by Servers .   6
   4.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .   6
   5.  Security Considerations . . . . . . . . . . . . . . . . . . .   7
     5.1.  Key Size and Signature Hash . . . . . . . . . . . . . . .   7
     5.2.  Transition  . . . . . . . . . . . . . . . . . . . . . . .   7
     5.3.  PKCS #1 v1.5 Padding and Signature Verification . . . . .   7
   6.  References  . . . . . . . . . . . . . . . . . . . . . . . . .   8
     6.1.  Normative References  . . . . . . . . . . . . . . . . . .   8
     6.2.  Informative References  . . . . . . . . . . . . . . . . .   8
   Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . .   9
   Author's Address  . . . . . . . . . . . . . . . . . . . . . . . .   9

1. Overview and Rationale 🌸

Okay bestie, SSH (Secure Shell) is basically the go-to protocol for secure communication on the Internet 🔐. In [RFC4253], SSH originally defined the public key algorithms "ssh-rsa" for server and client authentication using RSA with SHA-1, and "ssh-dss" using 1024-bit DSA and SHA-1. Honestly? These are now considered deficient 💀. For US government use, NIST has disallowed 1024-bit RSA and DSA, and the use of SHA-1 for signing [NIST.800-131A]. Not it 🙅‍♀️

So this memo updates RFCs 4252 and 4253 to define new public key algorithms. The goal is letting existing and new RSA keys interoperate with SHA-256 and SHA-512, and that is a whole glow-up ✨

1.1. Requirements Terminology 📝

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. Capitals only, bestie, that's the rule 🧐

1.2. Wire Encoding Terminology 🧩

The wire encoding types in this document ("boolean", "byte", "string", "mpint") have the meanings described in [RFC4251].

2. Public Key Format vs. Public Key Algorithm 🎀

Quick terminology moment, because this is where people get mixed up 🙈 In [RFC4252], the concept "public key algorithm" links one algorithm name to:

A. procedures used to generate and validate a private/public keypair; B. a format used to encode a public key; and C. procedures used to calculate, encode, and verify a signature.

This document uses the term "public key format" to identify only A and B in isolation. The term "public key algorithm" still covers all three aspects, A, B, and C. Main character energy for "public key algorithm" 👑

3. New RSA Public Key Algorithms 🦋

This memo copies the style and conventions of [RFC4253] for saying how a public key algorithm gets indicated in SSH 💅

The following new public key algorithms are defined:

     rsa-sha2-256        RECOMMENDED    sign    Raw RSA key
     rsa-sha2-512        OPTIONAL       sign    Raw RSA key

These algorithms work for the SSH transport layer [RFC4253] when doing server authentication, and for the authentication layer [RFC4252] when doing client authentication. Both spots, slay 🔥

Since RSA keys don't depend on the choice of hash function, the new public key algorithms reuse the "ssh-rsa" public key format defined in [RFC4253]:

   string    "ssh-rsa"
   mpint     e
   mpint     n

Every part of the "ssh-rsa" format is kept, including the encoded string "ssh-rsa". This means existing RSA keys can be used with the new public key algorithms, with no re-encoding needed and no effect on already trusted key fingerprints 🫶

Signing and verifying with these algorithms follows the RSASSA-PKCS1-v1_5 scheme in [RFC8017], using SHA-2 [SHS] as the hash.

For the algorithm "rsa-sha2-256", the hash is SHA-256. For the algorithm "rsa-sha2-512", the hash is SHA-512.

The resulting signature gets encoded like this:

   string   "rsa-sha2-256" / "rsa-sha2-512"
   string    rsa_signature_blob

The value of rsa_signature_blob is encoded as a string holding an octet string S (the output of RSASSA-PKCS1-v1_5). That string has the same length, in octets, as the RSA modulus. Some signers send a shorter encoding of S when S has leading zeros, leaving them out. A verifier MAY accept shorter encodings of S with one or more leading zeros omitted 🤏

3.1. Use for Server Authentication 🖥️

To show support and preference for one or both of these algorithms when server authentication happens, the SSH client or server puts one or both algorithm names, "rsa-sha2-256" and/or "rsa-sha2-512", into the name-list field server_host_key_algorithms in the SSH_MSG_KEXINIT packet [RFC4253]. If one of the two host key algorithms gets negotiated, the server sends an "ssh-rsa" public key as part of the negotiated key exchange method (for example, in SSH_MSG_KEXDH_REPLY). It then encodes a signature using the matching signature algorithm name, either "rsa-sha2-256" or "rsa-sha2-512" 💫

3.2. Use for Client Authentication 🔑

To use this algorithm for client authentication, the SSH client sends an SSH_MSG_USERAUTH_REQUEST message [RFC4252]. That message encodes the "publickey" method and the string field "public key algorithm name" with the value "rsa-sha2-256" or "rsa-sha2-512". The "public key blob" field encodes the RSA public key using the "ssh-rsa" public key format.

For example, as defined in [RFC4252] and [RFC4253], an SSH "publickey" authentication request using an "rsa-sha2-512" signature would be encoded like this:

     byte      SSH_MSG_USERAUTH_REQUEST
     string    user name
     string    service name
     string    "publickey"
     boolean   TRUE
     string    "rsa-sha2-512"
     string    public key blob:
         string    "ssh-rsa"
         mpint     e
         mpint     n
     string    signature:
         string    "rsa-sha2-512"
         string    rsa_signature_blob

If the client includes the signature field, the client MUST encode the same algorithm name in the signature as it used in SSH_MSG_USERAUTH_REQUEST, either "rsa-sha2-256" or "rsa-sha2-512". If a server gets a mismatching request, it MAY apply arbitrary authentication penalties, including but not limited to authentication failure or disconnect. That's a hard no, bestie 🚫

OpenSSH 7.2 (but not 7.2p2) incorrectly encodes the algorithm in the signature as "ssh-rsa" when the algorithm in SSH_MSG_USERAUTH_REQUEST is "rsa-sha2-256" or "rsa-sha2-512". In this case, the signature really does use SHA-256 or SHA-512, so the math checks out 🥹 A server MAY, but is not required to, accept this variant or another variant that corresponds to a good-faith implementation and is considered safe to accept. It's a choice, not a rule 🤷‍♀️

3.3. Discovery of Public Key Algorithms Supported by Servers 🔍

Implementation experience has shown that some servers apply authentication penalties to clients that try public key algorithms the SSH server doesn't support. Ouch 😭

Servers that accept rsa-sha2-* signatures for client authentication SHOULD implement the extension negotiation mechanism defined in [RFC8308], especially the "server-sig-algs" extension. Pro tip, and it's a SHOULD, so it's a strong recommendation 💅

When authenticating with an RSA key against a server that doesn't implement the "server-sig-algs" extension, clients MAY default to an "ssh-rsa" signature to avoid authentication penalties. Once the new rsa-sha2-* algorithms are adopted widely enough to justify disabling "ssh-rsa", clients MAY default to one of the new algorithms instead. Glow-up complete 🌟

5.2. Transition ✨

okay so this whole document is built on one big vibe: RSA is still hanging around in a lot of places, and switching to better algorithms should feel smooth, not like someone yanking the rug out 🧶🫶. the move is for SSH implementations to add the new RSA public key algorithms next to SSH_MSG_EXT_INFO and the "server-sig-algs" extension, so new deployments can coexist with older versions that only speak "ssh-rsa" 💖. the sweet spot is this: implementations SHOULD start disabling "ssh-rsa" in their default configurations as soon as the implementers feel the new RSA signature algorithms have been widely adopted 💅✨

5.3. PKCS #1 v1.5 Padding and Signature Verification 🎀

so why does this document stick with RSASSA-PKCS1-v1_5 padding? ngl it's three reasons:

  1. RSASSA-PSS is not universally available to all implementations 🙈
  2. PKCS #1 v1.5 is widely supported in existing SSH implementations 🍓
  3. PKCS #1 v1.5 is not known to be insecure for use in this scheme 🔥

implementers, this part is SERIOUS 😭. a signature with RSASSA-PKCS1-v1_5 padding MUST NOT be verified by applying the RSA key to the signature and then parsing the output to pull out the hash. that's basically handing an attacker a map to flaws in the parsing and ways to vary the encoding 💀. verifiers MUST instead apply RSASSA-PKCS1-v1_5 padding to the expected hash, then compare the encoded bytes with the output of the RSA operation 👑

6. References 📚

6.1. Normative References

6.2. Informative References

Acknowledgments 🫶

Huge thanks to Jon Bright, Niels Moeller, Stephen Farrell, Mark D. Baushke, Jeffrey Hutzelman, Hanno Boeck, Peter Gutmann, Damien Miller, Mat Berchtold, Roumen Petrov, Daniel Migault, Eric Rescorla, Russ Housley, Alissa Cooper, Adam Roach, and Ben Campbell for reviews, comments, and suggestions 🌸💜

Author's Address 🦋

Denis Bider Bitvise Limited 4105 Lombardy Court Colleyville, Texas 76034 United States of America

Email: ietf-ssh3@denisbider.com URI: https://www.bitvise.com/

📦 where this page comes from