From 92b61a38ee9b765f5049f03cd1143e13f3878905 Mon Sep 17 00:00:00 2001 From: "djm@openbsd.org" Date: Wed, 26 Sep 2018 07:30:05 +0000 Subject: [PATCH] upstream: Document mux proxy mode; added by Markus in openssh-7.4 Also add a little bit of information about the overall packet format OpenBSD-Commit-ID: bdb6f6ea8580ef96792e270cae7857786ad84a95 --- PROTOCOL.mux | 144 ++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 107 insertions(+), 37 deletions(-) diff --git a/PROTOCOL.mux b/PROTOCOL.mux index f042961f117..77a0780a523 100644 --- a/PROTOCOL.mux +++ b/PROTOCOL.mux @@ -1,15 +1,52 @@ This document describes the multiplexing protocol used by ssh(1)'s ControlMaster connection-sharing. -Most messages from the client to the server contain a "request id" field. -This field is returned in replies as "client request id" to facilitate -matching of responses to requests. +Multiplexing starts with a ssh(1) configured to act as a multiplexing +master. This will cause ssh(1) to listen on a Unix domain socket for +requests from clients. Clients communicate over this socket using a +simple packetised protocol, where each message is proceeded with +a length and message type in SSH uint32 wire format: + + uint32 packet length + uint32 packet type + ... packet body + +Most messages from the client to the server contain a "request id" +field. This field is returned in replies as "client request id" to +facilitate matching of responses to requests. + +Many muliplexing (mux) client requests yield immediate responses from +the mux process; requesting a forwarding, performing an alive check or +requesting the master terminate itself fall in to this category. + +The most common use of multiplexing however is to maintain multiple +concurrent sessions. These are supported via two separate modes: + +"Passenger" clients start by requesting a new session with a +MUX_C_NEW_SESSION message and passing stdio file descriptors over the +Unix domain control socket. The passenger client then waits until it is +signaled or the mux server closes the session. This mode is so named as +the client waits around while the mux server does all the driving. + +Stdio forwarding (requested using MUX_C_NEW_STDIO_FWD) is another +example of passenger mode; the client passes the stdio file descriptors +and passively waits for something to happen. + +"Proxy" clients, requested using MUX_C_PROXY, work quite differently. In +this mode, the mux client/server connection socket will stop speaking +the multiplexing protocol and start proxying SSH connection protocol +messages between the client and server. The client therefore must +speak a significant subset of the SSH protocol, but in return is able +to access basically the full suite of connection protocol features. +Moreover, as no file descriptor passing is required, the connection +supporting a proxy client may iteself be forwarded or relayed to another +host if necessary. 1. Connection setup When a multiplexing connection is made to a ssh(1) operating as a -ControlMaster from a ssh(1) in multiplex slave mode, the first -action of each is to exchange hello messages: +ControlMaster from a client ssh(1), the first action of each is send +a hello messages to its peer: uint32 MUX_MSG_HELLO uint32 protocol version @@ -17,16 +54,16 @@ action of each is to exchange hello messages: string extension value [optional] ... -The current version of the mux protocol is 4. A slave should refuse +The current version of the mux protocol is 4. A client should refuse to connect to a master that speaks an unsupported protocol version. -Following the version identifier are zero or more extensions -represented as a name/value pair. No extensions are currently -defined. -2. Opening sessions +Following the version identifier are zero or more extensions represented +as a name/value pair. No extensions are currently defined. -To open a new multiplexed session, a client may send the following -request: +2. Opening a passenger mode session + +To open a new multiplexed session in passenger mode, a client sends the +following request: uint32 MUX_C_NEW_SESSION uint32 request id @@ -80,7 +117,25 @@ return its local tty to "cooked" mode. uint32 MUX_S_TTY_ALLOC_FAIL uint32 session id -3. Health checks +3. Requesting passenger-mode stdio forwarding + +A client may request the master to establish a stdio forwarding: + + uint32 MUX_C_NEW_STDIO_FWD + uint32 request id + string reserved + string connect host + string connect port + +The client then sends its standard input and output file descriptors +(in that order) using Unix domain socket control messages. + +The contents of "reserved" are currently ignored. + +A server may reply with a MUX_S_SESSION_OPENED, a MUX_S_PERMISSION_DENIED +or a MUX_S_FAILURE. + +4. Health checks The client may request a health check/PID report from a server: @@ -93,7 +148,7 @@ The server replies with: uint32 client request id uint32 server pid -4. Remotely terminating a master +5. Remotely terminating a master A client may request that a master terminate immediately: @@ -102,7 +157,7 @@ A client may request that a master terminate immediately: The server will reply with one of MUX_S_OK or MUX_S_PERMISSION_DENIED. -5. Requesting establishment of port forwards +6. Requesting establishment of port forwards A client may request the master to establish a port forward: @@ -131,7 +186,7 @@ For dynamically allocated listen port the server replies with uint32 client request id uint32 allocated remote listen port -6. Requesting closure of port forwards +7. Requesting closure of port forwards Note: currently unimplemented (server will always reply with MUX_S_FAILURE). @@ -148,36 +203,45 @@ A client may request the master to close a port forward: A server may reply with a MUX_S_OK, a MUX_S_PERMISSION_DENIED or a MUX_S_FAILURE. -7. Requesting stdio forwarding +8. Requesting shutdown of mux listener -A client may request the master to establish a stdio forwarding: +A client may request the master to stop accepting new multiplexing requests +and remove its listener socket. - uint32 MUX_C_NEW_STDIO_FWD + uint32 MUX_C_STOP_LISTENING uint32 request id - string reserved - string connect host - string connect port -The client then sends its standard input and output file descriptors -(in that order) using Unix domain socket control messages. +A server may reply with a MUX_S_OK, a MUX_S_PERMISSION_DENIED or a +MUX_S_FAILURE. -The contents of "reserved" are currently ignored. +9. Requesting proxy mode -A server may reply with a MUX_S_SESSION_OPENED, a MUX_S_PERMISSION_DENIED -or a MUX_S_FAILURE. +A client may request that the the control connection be placed in proxy +mode: -8. Requesting shutdown of mux listener + uint32 MUX_C_PROXY + uint32 request id -A client may request the master to stop accepting new multiplexing requests -and remove its listener socket. +When a mux master receives this message, it will reply with a +confirmation: - uint32 MUX_C_STOP_LISTENING + uint32 MUX_S_PROXY uint32 request id -A server may reply with a MUX_S_OK, a MUX_S_PERMISSION_DENIED or a -MUX_S_FAILURE. +And go into proxy mode. All subsequent data over the connection will +be formatted as unencrypted, unpadded, SSH transport messages: + + uint32 packet length + byte 0 (padding length) + byte packet type + byte[packet length - 2] ... -9. Status messages +The mux master will accept most connection messages and global requests, +and will translate channel identifiers to ensure that the proxy client has +globally unique channel numbers (i.e. a proxy client need not worry about +collisions with other clients). + +10. Status messages The MUX_S_OK message is empty: @@ -194,7 +258,7 @@ The MUX_S_PERMISSION_DENIED and MUX_S_FAILURE include a reason: uint32 client request id string reason -10. Protocol numbers +11. Protocol numbers #define MUX_MSG_HELLO 0x00000001 #define MUX_C_NEW_SESSION 0x10000002 @@ -224,5 +288,11 @@ XXX watch in/out traffic (pre/post crypto) XXX inject packet (what about replies) XXX server->client error/warning notifications XXX send signals via mux - -$OpenBSD: PROTOCOL.mux,v 1.10 2015/07/17 03:04:27 djm Exp $ +XXX ^Z support in passengers +XXX extensions for multi-agent +XXX extensions for multi-X11 +XXX session inspection via master +XXX signals via mux request +XXX list active connections via mux + +$OpenBSD: PROTOCOL.mux,v 1.11 2018/09/26 07:30:05 djm Exp $