RFC 6239

Suite B Cryptographic Suites for Secure Shell (SSH)

📅 published May 2011, from ietf

RFC 6239: Suite B Cryptographic Suites for Secure Shell (SSH) 🎀

Okay bestie, this is RFC 6239 and it's giving "Suite B meets SSH" 💖

Who wrote it: K. Igoe from the National Security Agency 🕵️‍♀️ It came out of the Internet Engineering Task Force (IETF) in May 2011.

Category: Informational 📚 It's not a Standards Track spec. It's published so people can learn from it. The ISSN is 2070-1721 ✨

What it obsoletes or updates: The header doesn't list anything it obsoletes or updates 🙈

Abstract 🌸

Okay so this doc is the architecture blueprint for a Suite B compliant version of the Secure Shell Transport Layer Protocol and the Secure Shell Authentication Protocol 🔐 Suite B SSH is built on ECDH key agreement, ECDSA signatures, AES-GCM, two members of the SHA-2 family (SHA-256 and SHA-384), and X.509 certificates. Main character lineup 👑

Status of This Memo 📝

This document is not an Internet Standards Track specification. It's published for informational purposes 🦋

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). Not every document the IESG approves is a candidate for any level of Internet Standard. See Section 2 of RFC 5741 for that 💅

Information about the current status of this document, any errata, and how to give feedback on it can be found at http://www.rfc-editor.org/info/rfc6239 🔗

Copyright (c) 2011 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 (http://trustee.ietf.org/license-info), as in effect on the date of publication of this document. Please review these documents carefully, because 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 they are provided without warranty as described in the Simplified BSD License 🫶

Table of Contents 🗺️

1. Introduction ....................................................3
2. Suite B and Secure Shell ........................................3
   2.1. Minimum Levels of Security (minLOS) ........................4
   2.2. Digital Signatures and Certificates ........................4
   2.3. Non-Signature Primitives ...................................5
3. Security Mechanism Negotiation and Initialization ...............6
   3.1. Algorithm Negotiation: SSH_MSG_KEXINIT .....................7
4. Key Exchange and Server Authentication ..........................8
   4.1. SSH_MSG_KEXECDH_INIT .......................................9
   4.2. SSH_MSG_KEXECDH_REPLY ......................................9
   4.3. Key and Initialization Vector Derivation ..................10
5. User Authentication ............................................10
   5.1. First SSH_MSG_USERAUTH_REQUEST Message ....................10
   5.2. Second SSH_MSG_USERAUTH_REQUEST Message ...................11
6. Confidentiality and Data Integrity of SSH Binary Packets .......12
   6.1. Galois/Counter Mode .......................................12
   6.2. Data Integrity ............................................12
7. Rekeying .......................................................12
8. Security Considerations ........................................13
9. References .....................................................13
   9.1. Normative References ......................................13
   9.2. Informative References ....................................13

1. Introduction 💖

Okay so this section is the intro, and it's basically the same vibe as the abstract: a Suite B compliant take on the SSH Transport Layer and Authentication Protocols, using ECDH, ECDSA, AES-GCM, SHA-256 and SHA-384, and X.509 certificates ✨

Here's the key words bit 🎀 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document should be read as described in RFC 2119 [RFC2119]. Those are the capital-letter requirement words, so pay attention when you see them 👀

2. Suite B and Secure Shell 🦋

Lowkey the whole point is that several RFCs already explain how each Suite B piece plugs into SSH. Here's the lineup:

  kex algorithms
        ecdh-sha2-nistp256           [SSH-ECC]
        ecdh-sha2-nistp384           [SSH-ECC]

  server host key algorithms
        x509v3-ecdsa-sha2-nistp256   [SSH-X509]
        x509v3-ecdsa-sha2-nistp384   [SSH-X509]

  encryption algorithms (both client_to_server and server_to_client)
        AEAD_AES_128_GCM             [SSH-GCM]
        AEAD_AES_256_GCM             [SSH-GCM]

  MAC algorithms (both client_to_server and server_to_client)
        AEAD_AES_128_GCM             [SSH-GCM]
        AEAD_AES_256_GCM             [SSH-GCM]

Also, in Suite B, public key certificates used to verify signatures MUST be compliant with the Suite B Certificate Profile specified in RFC 5759 [SUITEBCERT]. No exceptions, periodt 💅

The goal here is to pull all of these docs together and give Suite B compliant SSH implementations one clear guide. We're calling that "SecSh-B" for short 🌈 Now, the tea: SecSh-B MUST follow the guidance in this document, but that alone doesn't mean a given SSH implementation is good for protecting classified data 🙈 An implementation of SecSh-B must be validated by the appropriate authority before that kind of use is allowed. Not me being dramatic, it's literally the rule 😭

Quick naming moment ✨ Suite B's two elliptic curves go by two different names, so here they are side by side:

   Curve        NIST name        SECG name     OID [SEC2]
   ---------------------------------------------------------------
   P-256        nistp256         secp256r1     1.2.840.10045.3.1.7
   P-384        nistp384         secp384r1     1.3.132.0.34

You can read about these curves in [NIST] or [SEC2] 📖

For brevity, ECDSA-256 means ECDSA on P-256 using SHA-256, and ECDSA-384 means ECDSA on P-384 using SHA-384 💜

2.1. Minimum Levels of Security (minLOS) 🔥

Suite B gives you two cryptographic security levels: a 128-bit minimum level of security (minLOS_128) and a 192-bit minimum level of security (minLOS_192). Next up, the ECDSA-256/384 signature algorithms and their X.509v3 certificates get treated a bit differently from the non-signature primitives (kex algorithms, encryption algorithms, and Message Authentication Code (MAC) algorithms, which is the SSH term for them).

2.2. Digital Signatures and Certificates 💅

Here's the signature situation. SecSh-B uses ECDSA-256/384 for server authentication, user authentication, and X.509 certificates. [SSH-X509] defines two methods, x509v3-ecdsa-sha2-nistp256 and x509v3-ecdsa-sha2-nistp384, which are meant for server and user authentication. The following conditions must be met:

  1. The server MUST share its public key with the host using an X.509v3 certificate as described in [SSH-X509]. This public key MUST be used to authenticate the server to the host using ECDSA-256 or ECDSA-384 as appropriate (see Section 3). 🔑
  2. User authentication MUST begin with public key authentication using ECDSA-256/384 with X.509v3 certificates (see Section 4). Additional user authentication methods MAY be used, but only after the certificate-based ECDSA authentication has been successfully completed. 🫶
  3. The X.509v3 certificates MUST use only the two Suite B digital signatures, ECDSA-256 and ECDSA-384. ✨
  4. ECDSA-256 MUST NOT be used to sign an ECDSA-384 public key. 🙅‍♀️
  5. ECDSA-384 MAY be used to sign an ECDSA-256 public key. 🌸
  6. At minLOS_192, all SecSh-B implementations MUST be able to verify ECDSA-384 signatures. 💜
  7. At minLOS_128, all SecSh-B implementations MUST be able to verify ECDSA-256 signatures and SHOULD be able to verify ECDSA-384 signatures, unless it is absolutely certain that the implementation will never need to verify certificates originating from an authority that uses an ECDSA-384 signing key. 🧐
  8. At minLOS_128, each SecSh-B server and each SecSh-B user MUST have either an ECDSA-256 signing key with a corresponding X.509v3 certificate, an ECDSA-384 signing key with a corresponding X.509v3 certificate, or both. 🎀
  9. At minLOS_192, each SecSh-B server and each SecSh-B user MUST have an ECDSA-384 signing key with a corresponding X.509v3 certificate. 👑

The signature algorithm used for server authentication is picked by the server_host_key_algorithms name-list in the SSH_MSG_KEXINIT packet (see Section 3.1). The key exchange and server authentication happen in the SSH_MSG_KEXECDH_REPLY packets (see Section 4). User authentication goes through the SSH_MSG_USERAUTH_REQUEST messages (see Section 5). 🧚

2.3. Non-Signature Primitives 🌈

This section covers the limits that the chosen minimum security level puts on picking a key agreement protocol (kex algorithm), an encryption algorithm, and a data integrity algorithm (MAC algorithm). The non-signature algorithms split into two families, shown in Table 1 🍓

   +--------------+----------------------+----------------------+
   |  Algorithm   |  Family 1            |  Family 2            |
   +==============+======================+======================+
   |  kex         |  ecdh-sha2-nistp256  |  ecdh-sha2-nistp384  |
   +--------------+----------------------+----------------------+
   |  encryption  |  AEAD_AES_128_GCM    |  AEAD_AES_256_GCM    |
   +--------------+----------------------+----------------------+
   |  MAC         |  AEAD_AES_128_GCM    |  AEAD_AES_256_GCM    |
   +--------------+-----------------------+---------------------+

     Table 1.  Families of Non-Signature Algorithms in SecSh-B

At the 128-bit minimum level of security:

  • The non-signature algorithms MUST either come exclusively from Family 1 or exclusively from Family 2. 💖
  • The selection of Family 1 versus Family 2 is independent of the choice of server host key algorithm. 🦋

At the 192-bit minimum level of security:

  • The non-signature algorithms MUST all come from Family 2. 👑

Most of the limits in this section can be met by heavily restricting the kex_algorithm, encryption_algorithm, and mac_algorithm name lists offered in the SSH_MSG_KEXINIT packet. See Section 3.1 for details. That's the whole vibe of Part 1, bestie 🌈✨

3. Security Mechanism Negotiation and Initialization ✨

okay so the SSH_MSG_KEXINIT exchange between the server and the client is what decides which key agreement algorithm, MAC algorithm, host key algorithm (server authentication algorithm), and encryption algorithm get used 🔐 (that's all from [SSH-Tran]). this section explains how the Suite B pieces slot into the Secure Shell algorithm negotiation, key agreement, server authentication, and user authentication. bestie it's giving full setup montage 🎬

Setting up a Suite B Secure Shell connection involves these Secure Shell messages (C->S means client to server, and S->C means server to client):

SSH_MSG_KEXINIT           C->S  Contains lists of algorithms
                                acceptable to the client.

SSH_MSG_KEXINIT           S->C  Contains lists of algorithms
                                acceptable to the server.

SSH_MSG_KEXECDH_INIT      C->S  Contains the client's ephemeral
                                elliptic curve Diffie-Hellman key.

SSH_MSG_KEXECDH_REPLY     S->C  Contains a certificate with the
                                server's ECDSA public signature
                                key, the server's ephemeral ECDH
                                contribution, and an ECDSA digital
                                signature of the newly formed
                                exchange hash value.

SSH_MSG_USERAUTH_REQUEST  C->S  Contains the user's name, the
                                name of the service the user is
                                requesting, the name of the
                                authentication method the client
                                wishes to use, and method-specific
                                fields.

when nobody's in the middle of a key exchange, either party may start a key re-exchange by sending an SSH_MSG_KEXINIT packet 🔄. all the packets during the re-exchange are encrypted and authenticated with the current keys, until the re-exchange wraps up and an SSH_MSG_NEWKEYS switches everything over to the new keys. otherwise the re-exchange is basically the same as the initial key exchange, so go check Section 9 of [SSH-Tran] if you want the full tea ☕

3.1. Algorithm Negotiation: SSH_MSG_KEXINIT

ok so every algorithm choice except the user authentication methods comes out of the SSH_MSG_KEXINIT exchange between client and server 🤝 (see [SSH-Tran]). the SSH_MSG_KEXINIT packet looks like this:

byte         SSH_MSG_KEXINIT
byte[16]     cookie (random bytes)
name-list    kex_algorithms
name-list    server_host_key_algorithms
name-list    encryption_algorithms_client_to_server
name-list    encryption_algorithms_server_to_client
name-list    mac_algorithms_client_to_server
name-list    mac_algorithms_server_to_client
name-list    compression_algorithms_client_to_server
name-list    compression_algorithms_server_to_client
name-list    languages_client_to_server
name-list    languages_server_to_client
boolean      first_kex_packet_follows
uint32       0 (reserved for future extension)

the SSH_MSG_KEXINIT name lists can be used to limit which non-signature and host key algorithms you pick, following the vibes from Section 2 💅. Table 2 gives you three allowed name lists for the non-signature algorithms, and you MUST pick one of these options.

Family 1 only (min_LOS 128):
   kex_algorithm name_list         := { ecdh_sha2_nistp256 }
   encryption_algorithm name_list  := { AEAD_AES_128_GCM   }
   mac_algorithm name_list         := { AEAD_AES_128_GCM   }

Family 2 only (min_LOS 128 or 192):
   kex_algorithm name_list         := { ecdh_sha2_nistp384 }
   encryption_algorithm name_list  := { AEAD_AES_256_GCM   }
   mac_algorithm name_list         := { AEAD_AES_256_GCM   }

Family 1 or Family 2 (min_LOS 128):
   kex_algorithm name_list         := { ecdh_sha2_nistp256,
                                        ecdh_sha2_nistp384 }
   encryption_algorithm name_list  := { AEAD_AES_128_GCM,
                                        AEAD_AES_256_GCM   }
   mac_algorithm name_list         := { AEAD_AES_128_GCM,
                                        AEAD_AES_256_GCM   }

    Table 2.  Allowed Non-Signature Algorithm Name Lists

Table 3 gives three allowed name lists for the server host key algorithms, and you MUST use one of these options too 🎀.

ECDSA-256 only (min_LOS 128):
  server_host_key_algorithms name_list :=
                    { x509v3-ecdsa-sha2-nistp256 }

ECDSA-384 only (min_LOS 128 or 192):
  server_host_key_algorithms name_list :=
                    { x509v3-ecdsa-sha2-nistp384 }

ECDSA-256 or ECDSA-384 (min_LOS 128):
  server_host_key_algorithms name_list :=
                    { x509v3-ecdsa-sha2-nistp256,
                      x509v3-ecdsa-sha2-nistp384 }

Table 3.  Allowed Server Host Key Algorithm Name Lists

4. Key Exchange and Server Authentication 🗝️

the vibe here is that SecSh-B uses ECDH to set up a shared secret value between the client and the server 🌈. then the server gets authenticated to the client with an X.509v3 certificate holding the server's public signing ECDSA key, plus an ECDSA signature over the exchange hash value that comes from that brand new shared secret. iconic security moment 👑

4.1. SSH_MSG_KEXECDH_INIT

the key exchange in Secure Shell gets picked from the name lists swapped in the SSH_MSG_KEXINIT packets 🧩. in Suite B, one of the following key agreement methods MUST be used to make the shared secret value (SSV):

ecdh-sha2-nistp256      ephemeral-ephemeral elliptic curve
                        Diffie-Hellman on nistp256 with SHA-256

ecdh-sha2-nistp384      ephemeral-ephemeral elliptic curve
                        Diffie-Hellman on nistp384 with SHA-384

and the SSH_MSG_KEXECDH_INIT message is formatted like this:

byte      SSH_MSG_KEXDH_INIT

string    Q_C    // the client's ephemeral contribution to the
                 // ECDH exchange, encoded as an octet string

the elliptic curve point Q_C gets encoded as an octet string the way Section 2.3.3 of [SEC1] says 🦋.

4.2. SSH_MSG_KEXECDH_REPLY

the SSH_MSG_KEXECDH_REPLY carries the server's piece of the ECDH exchange, the server's public signature key, and a signature over the exchange hash value made from the new shared secret value 💌. like we covered in Section 3.1, the server host key algorithm in SecSh-B MUST be either x509v3-ecdsa-sha2-nistp256 or x509v3-ecdsa-sha2-nistp384. no other options, bestie 🙅‍♀️.

the format of the SSH_MSG_KEXECDH_REPLY is:

byte      SSH_MSG_KEXECDH_REPLY

string    K_S    // a string encoding an X.509v3 certificate
                 // containing the server's ECDSA public host key

string    Q_S    // the server's ephemeral contribution to the
                 // ECDH exchange, encoded as an octet string

string    Sig_S  // an octet string containing the server's
                 // signature of the newly established exchange
                 // hash value

the structure and encoding of that X.509v3 certificate are in Section 2 of [SSH-X509] 📜. the elliptic curve point Q_C gets encoded as an octet string the way Section 2.3.3 of [SEC1] says, and the ECDSA signature Sig_S gets encoded as an octet string the way Section 3.1.2 of [SSH-ECC] describes ✨.

4.3. Key and Initialization Vector Derivation

as [SSH-Tran] lays out, the encryption keys and initialization vectors that Secure Shell needs get derived straight from the SSV 🔑. the hash function comes from the key agreement algorithm: SHA-256 for ecdh-sha2-nistp256, and SHA-384 for ecdh-sha2-nistp384. the client-to-server channel and the server-to-client channel get their own independent keys and initialization vectors 🎀. those keys stay the same until a re-exchange makes a new SSV, so no swapping them out randomly 🙈.

5. User Authentication 🙋‍♀️

okay here's the tea: the Secure Shell Transport Layer Protocol authenticates the server to the host, but it does NOT authenticate the user (or the user's host) to the server 😭. so condition (2) of Section 2.2 says all users of SecSh-B MUST be authenticated with ECDSA-256/384 signatures and X.509v3 certificates. [SSH-X509] gives two methods, x509v3-ecdsa-sha2-nistp256 and x509v3-ecdsa-sha2-nistp384, and one of them MUST be used to get this done. at minLOS 128 either one of those methods may be used, but at minLOS 192, x509v3-ecdsa-sha2-nistp384 MUST be used 💜.

5.1. First SSH_MSG_USERAUTH_REQUEST Message

the user's public key gets sent to the server in an SSH_MSG_USERAUTH_REQUEST message 📨. when an x509v3-ecdsa-sha2-* user authentication method is in use, the structure of the SSH_MSG_USERAUTH_REQUEST message SHOULD be:

byte      SSH_MSG_USERAUTH_REQUEST

string    user_name      // in ISO-10646 UTF-8 encoding

string    service_name   // service name in US-ASCII

string    "publickey"

boolean   FALSE
string    public_key_algorithm_name  // x509v3-ecdsa-sha2-nistp256
                                     // or x509v3-ecdsa-sha2-nistp384

string    public_key_blob // X.509v3 certificate

the structure and encoding of that X.509v3 certificate are in Section 2 of [SSH-X509] 🌸.

5.2. Second SSH_MSG_USERAUTH_REQUEST Message

once the server answers the first request with an SSH_MSG_USERAUTH_PK_OK message, the client sends a second SSH_MSG_USERAUTH_REQUEST message to do the actual authentication 🥁:

byte      SSH_MSG_USERAUTH_REQUEST

string    user_name      // in ISO-10646 UTF-8 encoding

string    service_name   // service name in US-ASCII

string    "publickey"

boolean   TRUE

string    public_key_algorithm_name  // x509v3-ecdsa-sha2-nistp256
                                     // or x509v3-ecdsa-sha2-nistp384

string    Sig_U

the signature field Sig_U is an ECDSA signature over a bunch of values stitched together, including the session identifier, user name, service name, public key algorithm name, and the user's public signing key 🧁. the user's public signing key MUST be the signing key in the X.509v3 certificate that got sent in the first SSH_MSG_USERAUTH_REQUEST message. the ECDSA signature Sig_U gets encoded as an octet string the way Section 3.1.2 of [SSH-ECC] describes.

the server MUST reply with either SSH_MSG_USERAUTH_SUCCESS (if no more authentications are needed) or SSH_MSG_USERAUTH_FAILURE (if the request failed, or more authentications are needed) ✅.

6. Confidentiality and Data Integrity of SSH Binary Packets 🔐

Secure Shell moves data between the client and the server using its own binary packet structure 📦. that structure doesn't depend on whatever packet structure the underlying data channel uses, which is very main character energy 🌈. the contents of each binary packet, plus parts of the header, get encrypted, and every packet gets its own message authentication code. AES GCM does both jobs at once: it encrypts the packet and forms a 16-octet authentication tag for data integrity 💖.

6.1. Galois/Counter Mode ✨

Okay bestie, [SSH-GCM] is the doc that explains how AES Galois/Counter Mode gets used in Secure Shell 🔐. Suite B SSH implementations MUST support AEAD_AES_GCM_128 and SHOULD support AEAD_AES_GCM_256, so you get confidentiality AND data integrity 💖. No other confidentiality or data integrity algorithms are permitted 🙅‍♀️. Rules are rules, periodt.

These algorithms run on two counters 🧮:

  • Invocation Counter: a 64-bit integer that goes up by one after each call to AES-GCM to process an SSH binary packet. Its initial value comes from the SSH initialization vector.
  • Block Counter: a 32-bit integer that gets set to one at the start of each new SSH binary packet, then goes up as each 16-octet block of data is processed.

Getting these counters implemented properly is crucial to the security of the system 😱. If you want the nitty-gritty on their format, initialization, and usage, plus how they tie into the initialization vector and the SSV, go check [SSH-GCM] 📖.

6.2. Data Integrity 🦋

Just a little reminder 🎀: as [SSH-GCM] specifies, Suite B requires that all 16 octets of the authentication tag MUST be used as the SSH data integrity value of the SSH binary packet. All 16 of them, no skipping 💅.

7. Rekeying 🔑

Secure Shell lets either the server or the client ask for the connection to be rekeyed 🔁. Suite B has no limits on how often that happens 🙌, but it does require that the cipher suite being employed MUST NOT be changed when a rekey occurs 🚫. Same suite before and after, no swapping mid-conversation.

8. Security Considerations 💀

Okay, this part is SERIOUS bestie 😭, so please read it twice. When using ecdh_sha2_nistp256, each exponent used in the key exchange must have 256 bits of entropy. Similarly, when using ecdh_sha2_nistp384, each exponent used in the key exchange must have 384 bits of entropy. The security considerations of [SSH-Arch] apply too 🫶.

9. References 📚

9.1. Normative References

  • [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997.
  • [SUITEBCERT] Solinas, J. and L. Zieglar, "Suite B Certificate and Certificate Revocation List (CRL) Profile", RFC 5759, January 2010.
  • [SSH-Arch] Ylonen, T. and C. Lonvick, Ed., "The Secure Shell (SSH) Protocol Architecture", RFC 4251, January 2006.
  • [SSH-Tran] Ylonen, T. and C. Lonvick, Ed., "The Secure Shell (SSH) Transport Layer Protocol", RFC 4253, January 2006.
  • [SSH-ECC] Stebila, D. and J. Green, "Elliptic Curve Algorithm Integration in the Secure Shell Transport Layer", RFC 5656, December 2009.
  • [SSH-GCM] Igoe, K. and J. Solinas, "AES Galois Counter Mode for the Secure Shell Transport Layer Protocol", RFC 5647, August 2009.
  • [SSH-X509] Igoe, K. and D. Stebila, "X.509v3 Certificates for Secure Shell Authentication", RFC 6187, March 2011.

9.2. Informative References

Author's Address 💌

Kevin M. Igoe
NSA/CSS Commercial Solutions Center
National Security Agency

EMail: kmigoe@nsa.gov
📦 where this page comes from