[GitHub] [mina-sshd] tomaswolf commented on a diff in pull request #217: [SSHD-966] Flush pending packets asynchronously at end of KEX

[GitBox <gi...@apache.org>]

tomaswolf commented on code in PR #217:
URL: https://github.com/apache/mina-sshd/pull/217#discussion_r856517459


##########
docs/kex.md:
##########
@@ -0,0 +1,131 @@
+## SSH Key Exchange
+
+**Key Exchange** (or **KEX** for short) is a sub-protocol in the SSH protocol
+enabling the two parties in a connection to exchange information and compute a
+shared secret that will then be used for encrypting all following messages.
+
+A key exchange runs initially, after the network connection is established,
+but before authentication. Later on, KEX may be repeated; when exactly,
+depends on various settings:
+
+* it is re-run when a certain amount of bytes have been sent since the last KEX.
+* it may be re-run when a certain number of SSH packets have been sent since the last KEX.
+* it may be re-run when a certain time has elapsed since the last KEX.
+
+The purpose of re-running KEX is to establish a new shared secret from time to
+time, changing the encryption for all subsequent messages, until the next KEX.
+This mitigates possible attacks against the encryption when a lot of data is sent
+using the same encryption with the same shared secret.
+
+KEX is specified in [RFC 4253, section 7](https://tools.ietf.org/html/rfc4253#section-7).
+
+### Basic KEX message exchange
+
+A key exchange starts with both parties sending a SSH_MSG_KEX_INIT message,
+passing along information about available cryptographic algorithms. Both
+parties can decide from this information what kind of key exchange to perform.
+They then run the cryptographic key exchange protocol, which may incur several
+message exchanges. Once that protocol ends, both sides know the shared secret.
+At that point they both send a SSH_MSG_NEW_KEYS message to tell the other side
+they're ready, and use the new encryption for any subsequent outgoing message.
+The SSH_MSG_NEW_KEYS message itself is still sent with the old encryption. On
+receiving a SSH_MSG_NEW_KEYS message, each side starts using the new encryption
+to decrypt any subsequent incoming messages. Note that the SSH_MSG_NEW_KEYS
+message does not contain the new encryption key or the shared secret; it is
+just a marker message telling the other side that from now on, the new encryption
+will be used.
+
+Apache MINA sshd maintains internally in [`AbstractSession`](../sshd-core/src/main/java/org/apache/sshd/common/session/helpers/AbstractSession.java)
+a *KEX state* (in Java [`KexState`](../sshd-common/src/main/java/org/apache/sshd/common/kex/KexState.java)).
+This models the key exchange on one side of the connection as a state machine
+going through the states `DONE`, `INIT`, `RUN`, `KEYS`, `DONE`.
+
+![KEX state machine](./kex_states.png)
+
+These states mark important points in the key exchange sub-protocol:
+
+* `DONE` means no key exchange is ongoing, this side has received the peer's SSH_MSG_NEW_KEYS message, and both sides have a shared secret that they use for encryption.
+* `INIT` means this side of the connection has requested a new KEX; it has sent it's SSH_MSG_KEX_INIT message.
+* `RUN` means this side has received the peer's SSH_MSG_KEX_INIT message, and key exchange is running now to determine a new shared secret.
+* `KEYS` means the key exchange has been done; both sides know the shared secret, and this side has sent its SSH_MS_NEW_KEYS message.
+* When the peer's SSH_MSG_NEW_KEYS message is received, the state changes back to `DONE`.
+
+In Apache MINA sshd, there are methods in `AbstractSession` for each of the KEX
+messages:
+
+* `requestNewKeyExchange`: switches from `DONE` to `INIT` and calls `sendKexInit` to send the SSH_MSG_KEX_INIT message.
+* `handleKexInit`: receives the peer's SSH_MSG_KEX_INIT message; switches to `RUN`.
+* `sendNewKeys`: switches from `RUN` to `KEYS` and sends this side's SSH_MS_NEW_KEYS message.
+* `handleNewKeys`: receives the peer's SSH_MSG_KEX_INIT message; switches from `KEYS` to `DONE`.
+
+![KEX interactions](./kex_interaction_1.png)

Review Comment:
   I can also use SVG. Won't make it much easier to change the diagrams, though. Inkscape has some problems with the SVG exported by the tool I used.
   
   Binary files in git are totally fine. What is problematic are large files.
   
   But I agree, let's use SVG for diagrams, and I'll also put the original source somewhere.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: dev-unsubscribe@mina.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@mina.apache.org
For additional commands, e-mail: dev-help@mina.apache.org