From 6ebd472c391a73574abe02771712d407c48e130d Mon Sep 17 00:00:00 2001 From: "djm@openbsd.org" Date: Tue, 5 Aug 2025 04:00:15 +0000 Subject: [PATCH] upstream: a bunch of the protocol extensions we support now have RFCs and I-Ds that are more complete and detailed than what we have in the PROTOCOL.* files. Refer to these when possible instead of documenting them here. OpenBSD-Commit-ID: 4fa5b0fcf5d5f24093d33d9e82c7ca4850d50d70 --- PROTOCOL | 115 +++++++------------------------------- PROTOCOL.chacha20poly1305 | 107 ----------------------------------- 2 files changed, 21 insertions(+), 201 deletions(-) delete mode 100644 PROTOCOL.chacha20poly1305 diff --git a/PROTOCOL b/PROTOCOL index f99173c52..af2a813f9 100644 --- a/PROTOCOL +++ b/PROTOCOL @@ -33,10 +33,7 @@ The method is documented in: https://www.openssh.com/txt/draft-miller-secsh-compression-delayed-00.txt -1.3. transport: New public key algorithms "ssh-rsa-cert-v01@openssh.com", - "ecdsa-sha2-nistp256-cert-v01@openssh.com", - "ecdsa-sha2-nistp384-cert-v01@openssh.com" and - "ecdsa-sha2-nistp521-cert-v01@openssh.com" +1.3. transport: Certificate key algorithms OpenSSH introduces new public key algorithms to support certificate authentication for users and host keys. These methods are documented @@ -81,29 +78,20 @@ contains: 1.6 transport: AES-GCM OpenSSH supports the AES-GCM algorithm as specified in RFC 5647. -Because of problems with the specification of the key exchange -the behaviour of OpenSSH differs from the RFC as follows: +Because of problems with design of algorithm negotiation in this +RFC, OpenSSH (and other SSH implementation) use different rules as +described in: -AES-GCM is only negotiated as the cipher algorithms -"aes128-gcm@openssh.com" or "aes256-gcm@openssh.com" and never as -an MAC algorithm. Additionally, if AES-GCM is selected as the cipher -the exchanged MAC algorithms are ignored and there doesn't have to be -a matching MAC. +https://datatracker.ietf.org/doc/draft-miller-sshm-aes-gcm/ 1.7 transport: chacha20-poly1305@openssh.com authenticated encryption OpenSSH supports authenticated encryption using ChaCha20 and Poly1305 -as described in PROTOCOL.chacha20poly1305. +as described in: -1.8 transport: curve25519-sha256@libssh.org key exchange algorithm +https://datatracker.ietf.org/doc/draft-ietf-sshm-chacha20-poly1305/ -OpenSSH supports the use of ECDH in Curve25519 for key exchange as -described at: -http://git.libssh.org/users/aris/libssh.git/plain/doc/curve25519-sha256@libssh.org.txt?h=curve25519 - -This is identical to curve25519-sha256 as later published in RFC8731. - -1.9 transport: ping facility +1.8 transport: ping facility OpenSSH implements a transport level ping message SSH2_MSG_PING and a corresponding SSH2_MSG_PONG reply. @@ -136,34 +124,16 @@ than as a named global or channel request to allow pings with very short packet lengths, which would not be possible with other approaches. -1.10 transport: strict key exchange extension - -OpenSSH supports a number of transport-layer hardening measures under -a "strict KEX" feature. This feature is signalled similarly to the -RFC8308 ext-info feature: by including a additional algorithm in the -initial SSH2_MSG_KEXINIT kex_algorithms field. The client may append -"kex-strict-c-v00@openssh.com" to its kex_algorithms and the server -may append "kex-strict-s-v00@openssh.com". These pseudo-algorithms -are only valid in the initial SSH2_MSG_KEXINIT and MUST be ignored -if they are present in subsequent SSH2_MSG_KEXINIT packets. - -When an endpoint that supports this extension observes this algorithm -name in a peer's KEXINIT packet, it MUST make the following changes to -the protocol: - -a) During initial KEX, terminate the connection if out-of-sequence - packet or any message that is not strictly required by KEX is - received. This includes terminating the connection if the first - packet received is not SSH2_MSG_KEXINIT. Unexpected packets for - the purpose of strict KEX include messages that are otherwise - valid at any time during the connection such as SSH2_MSG_DEBUG, - SSH2_MSG_IGNORE or SSH2_MSG_UNIMPLEMENTED. -b) After sending or receiving a SSH2_MSG_NEWKEYS message, reset the - packet sequence number to zero. This behaviour persists for the - duration of the connection (i.e. not just the first - SSH2_MSG_NEWKEYS). - -1.11 transport: SSH2_MSG_EXT_INFO during user authentication +1.9 transport: strict key exchange extension + +OpenSSH supports a number of transport-layer hardening measures +designed to thwart the so-called "Terrapin" attack against the +early SSH protocol. These are collectively referred to as +"strict KEX" and documented in an Internet-Draft: + +https://datatracker.ietf.org/doc/draft-miller-sshm-strict-kex/ + +1.10 transport: SSH2_MSG_EXT_INFO during user authentication This protocol extension allows the SSH2_MSG_EXT_INFO to be sent during user authentication. RFC8308 does allow a second @@ -368,52 +338,9 @@ and "hostkeys-prove-00@openssh.com" OpenSSH supports a protocol extension allowing a server to inform a client of all its protocol v.2 host keys after user-authentication -has completed. - - byte SSH_MSG_GLOBAL_REQUEST - string "hostkeys-00@openssh.com" - char 0 /* want-reply */ - string[] hostkeys - -Upon receiving this message, a client should check which of the -supplied host keys are present in known_hosts. - -Note that the server may send key types that the client does not -support. The client should disregard such keys if they are received. - -If the client identifies any keys that are not present for the host, -it should send a "hostkeys-prove@openssh.com" message to request the -server prove ownership of the private half of the key. - - byte SSH_MSG_GLOBAL_REQUEST - string "hostkeys-prove-00@openssh.com" - char 1 /* want-reply */ - string[] hostkeys - -When a server receives this message, it should generate a signature -using each requested key over the following: - - string "hostkeys-prove-00@openssh.com" - string session identifier - string hostkey - -These signatures should be included in the reply, in the order matching -the hostkeys in the request: - - byte SSH_MSG_REQUEST_SUCCESS - string[] signatures - -When the client receives this reply (and not a failure), it should -validate the signatures and may update its known_hosts file, adding keys -that it has not seen before and deleting keys for the server host that -are no longer offered. +has completed. This is documented in an Internet-Draft -These extensions let a client learn key types that it had not previously -encountered, thereby allowing it to potentially upgrade from weaker -key algorithms to better ones. It also supports graceful key rotation: -a server may offer multiple keys of the same type for a period (to -give clients an opportunity to learn them using this extension) before -removing the deprecated key from those offered. +https://datatracker.ietf.org/doc/draft-miller-sshm-hostkey-update/ 2.6. connection: SIGINFO support for "signal" channel request @@ -791,4 +718,4 @@ master instance and later clients. OpenSSH extends the usual agent protocol. These changes are documented in the PROTOCOL.agent file. -$OpenBSD: PROTOCOL,v 1.57 2025/05/06 05:40:56 djm Exp $ +$OpenBSD: PROTOCOL,v 1.58 2025/08/05 04:00:15 djm Exp $ diff --git a/PROTOCOL.chacha20poly1305 b/PROTOCOL.chacha20poly1305 deleted file mode 100644 index 0bfff28d7..000000000 --- a/PROTOCOL.chacha20poly1305 +++ /dev/null @@ -1,107 +0,0 @@ -This document describes the chacha20-poly1305@openssh.com authenticated -encryption cipher supported by OpenSSH. - -Background ----------- - -ChaCha20 is a stream cipher designed by Daniel Bernstein and described -in [1]. It operates by permuting 128 fixed bits, 128 or 256 bits of key, -a 64 bit nonce and a 64 bit counter into 64 bytes of output. This output -is used as a keystream, with any unused bytes simply discarded. - -Poly1305[2], also by Daniel Bernstein, is a one-time Carter-Wegman MAC -that computes a 128 bit integrity tag given a message and a single-use -256 bit secret key. - -The chacha20-poly1305@openssh.com combines these two primitives into an -authenticated encryption mode. The construction used is based on that -proposed for TLS by Adam Langley in [3], but differs in the layout of -data passed to the MAC and in the addition of encryption of the packet -lengths. - -Negotiation ------------ - -The chacha20-poly1305@openssh.com offers both encryption and -authentication. As such, no separate MAC is required. If the -chacha20-poly1305@openssh.com cipher is selected in key exchange, -the offered MAC algorithms are ignored and no MAC is required to be -negotiated. - -Detailed Construction ---------------------- - -The chacha20-poly1305@openssh.com cipher requires 512 bits of key -material as output from the SSH key exchange. This forms two 256 bit -keys (K_1 and K_2), used by two separate instances of chacha20. -The first 256 bits constitute K_2 and the second 256 bits become -K_1. - -The instance keyed by K_1 is a stream cipher that is used only -to encrypt the 4 byte packet length field. The second instance, -keyed by K_2, is used in conjunction with poly1305 to build an AEAD -(Authenticated Encryption with Associated Data) that is used to encrypt -and authenticate the entire packet. - -Two separate cipher instances are used here so as to keep the packet -lengths confidential but not create an oracle for the packet payload -cipher by decrypting and using the packet length prior to checking -the MAC. By using an independently-keyed cipher instance to encrypt the -length, an active attacker seeking to exploit the packet input handling -as a decryption oracle can learn nothing about the payload contents or -its MAC (assuming key derivation, ChaCha20 and Poly1305 are secure). - -The AEAD is constructed as follows: for each packet, generate a Poly1305 -key by taking the first 256 bits of ChaCha20 stream output generated -using K_2, an IV consisting of the packet sequence number encoded as an -uint64 under the SSH wire encoding rules and a ChaCha20 block counter of -zero. The K_2 ChaCha20 block counter is then set to the little-endian -encoding of 1 (i.e. {1, 0, 0, 0, 0, 0, 0, 0}) and this instance is used -for encryption of the packet payload. - -Packet Handling ---------------- - -When receiving a packet, the length must be decrypted first. When 4 -bytes of ciphertext length have been received, they may be decrypted -using the K_1 key, a nonce consisting of the packet sequence number -encoded as a uint64 under the usual SSH wire encoding and a zero block -counter to obtain the plaintext length. - -Once the entire packet has been received, the MAC MUST be checked -before decryption. A per-packet Poly1305 key is generated as described -above and the MAC tag calculated using Poly1305 with this key over the -ciphertext of the packet length and the payload together. The calculated -MAC is then compared in constant time with the one appended to the -packet and the packet decrypted using ChaCha20 as described above (with -K_2, the packet sequence number as nonce and a starting block counter of -1). - -To send a packet, first encode the 4 byte length and encrypt it using -K_1. Encrypt the packet payload (using K_2) and append it to the -encrypted length. Finally, calculate a MAC tag and append it. - -Rekeying --------- - -ChaCha20 must never reuse a {key, nonce} for encryption nor may it be -used to encrypt more than 2^70 bytes under the same {key, nonce}. The -SSH Transport protocol (RFC4253) recommends a far more conservative -rekeying every 1GB of data sent or received. If this recommendation -is followed, then chacha20-poly1305@openssh.com requires no special -handling in this area. - -References ----------- - -[1] "ChaCha, a variant of Salsa20", Daniel Bernstein - http://cr.yp.to/chacha/chacha-20080128.pdf - -[2] "The Poly1305-AES message-authentication code", Daniel Bernstein - http://cr.yp.to/mac/poly1305-20050329.pdf - -[3] "ChaCha20 and Poly1305 based Cipher Suites for TLS", Adam Langley - http://tools.ietf.org/html/draft-agl-tls-chacha20poly1305-03 - -$OpenBSD: PROTOCOL.chacha20poly1305,v 1.5 2020/02/21 00:04:43 dtucker Exp $ - -- 2.47.2