crypto/openssh/PROTOCOL.mux

   1 This document describes the multiplexing protocol used by ssh(1)'s
   2 ControlMaster connection-sharing.
   3
   4 Most messages from the client to the server contain a "request id" field.
   5 This field is returned in replies as "client request id" to facilitate
   6 matching of responses to requests.
   7
   8 1. Connection setup
   9
  10 When a multiplexing connection is made to a ssh(1) operating as a
  11 ControlMaster from a ssh(1) in multiplex slave mode, the first
  12 action of each is to exchange hello messages:
  13
  14         uint32  MUX_MSG_HELLO
  15         uint32  protocol version
  16         string  extension name [optional]
  17         string  extension value [optional]
  18         ...
  19
  20 The current version of the mux protocol is 4. A slave should refuse
  21 to connect to a master that speaks an unsupported protocol version.
  22 Following the version identifier are zero or more extensions
  23 represented as a name/value pair. No extensions are currently
  24 defined.
  25
  26 2. Opening sessions
  27
  28 To open a new multiplexed session, a client may send the following
  29 request:
  30
  31         uint32  MUX_C_NEW_SESSION
  32         uint32  request id
  33         string  reserved
  34         bool    want tty flag
  35         bool    want X11 forwarding flag
  36         bool    want agent flag
  37         bool    subsystem flag
  38         uint32  escape char
  39         string  terminal type
  40         string  command
  41         string  environment string 0 [optional]
  42         ...
  43
  44 To disable the use of an escape character, "escape char" may be set
  45 to 0xffffffff. "terminal type" is generally set to the value of
  46 $TERM. zero or more environment strings may follow the command.
  47
  48 The client then sends its standard input, output and error file
  49 descriptors (in that order) using Unix domain socket control messages.
  50
  51 The contents of "reserved" are currently ignored.
  52
  53 If successful, the server will reply with MUX_S_SESSION_OPENED
  54
  55         uint32  MUX_S_SESSION_OPENED
  56         uint32  client request id
  57         uint32  session id
  58
  59 Otherwise it will reply with an error: MUX_S_PERMISSION_DENIED or
  60 MUX_S_FAILURE.
  61
  62 Once the server has received the fds, it will respond with MUX_S_OK
  63 indicating that the session is up. The client now waits for the
  64 session to end. When it does, the server will send an exit status
  65 message:
  66
  67         uint32  MUX_S_EXIT_MESSAGE
  68         uint32  session id
  69         uint32  exit value
  70
  71 The client should exit with this value to mimic the behaviour of a
  72 non-multiplexed ssh(1) connection. Two additional cases that the
  73 client must cope with are it receiving a signal itself and the
  74 server disconnecting without sending an exit message.
  75
  76 A master may also send a MUX_S_TTY_ALLOC_FAIL before MUX_S_EXIT_MESSAGE
  77 if remote TTY allocation was unsuccessful. The client may use this to
  78 return its local tty to "cooked" mode.
  79
  80         uint32  MUX_S_TTY_ALLOC_FAIL
  81         uint32  session id
  82
  83 3. Health checks
  84
  85 The client may request a health check/PID report from a server:
  86
  87         uint32  MUX_C_ALIVE_CHECK
  88         uint32  request id
  89
  90 The server replies with:
  91
  92         uint32  MUX_S_ALIVE
  93         uint32  client request id
  94         uint32  server pid
  95
  96 4. Remotely terminating a master
  97
  98 A client may request that a master terminate immediately:
  99
 100         uint32  MUX_C_TERMINATE
 101         uint32  request id
 102
 103 The server will reply with one of MUX_S_OK or MUX_S_PERMISSION_DENIED.
 104
 105 5. Requesting establishment of port forwards
 106
 107 A client may request the master to establish a port forward:
 108
 109         uint32  MUX_C_OPEN_FWD
 110         uint32  request id
 111         uint32  forwarding type
 112         string  listen host
 113         uint32  listen port
 114         string  connect host
 115         uint32  connect port
 116
 117 forwarding type may be MUX_FWD_LOCAL, MUX_FWD_REMOTE, MUX_FWD_DYNAMIC.
 118
 119 If listen port is (unsigned int) -2, then the listen host is treated as
 120 a unix socket path name.
 121
 122 If connect port is (unsigned int) -2, then the connect host is treated
 123 as a unix socket path name.
 124
 125 A server may reply with a MUX_S_OK, a MUX_S_REMOTE_PORT, a
 126 MUX_S_PERMISSION_DENIED or a MUX_S_FAILURE.
 127
 128 For dynamically allocated listen port the server replies with
 129
 130         uint32  MUX_S_REMOTE_PORT
 131         uint32  client request id
 132         uint32  allocated remote listen port
 133
 134 6. Requesting closure of port forwards
 135
 136 Note: currently unimplemented (server will always reply with MUX_S_FAILURE).
 137
 138 A client may request the master to close a port forward:
 139
 140         uint32  MUX_C_CLOSE_FWD
 141         uint32  request id
 142         uint32  forwarding type
 143         string  listen host
 144         uint32  listen port
 145         string  connect host
 146         uint32  connect port
 147
 148 A server may reply with a MUX_S_OK, a MUX_S_PERMISSION_DENIED or a
 149 MUX_S_FAILURE.
 150
 151 7. Requesting stdio forwarding
 152
 153 A client may request the master to establish a stdio forwarding:
 154
 155         uint32  MUX_C_NEW_STDIO_FWD
 156         uint32  request id
 157         string  reserved
 158         string  connect host
 159         string  connect port
 160
 161 The client then sends its standard input and output file descriptors
 162 (in that order) using Unix domain socket control messages.
 163
 164 The contents of "reserved" are currently ignored.
 165
 166 A server may reply with a MUX_S_SESSION_OPENED, a MUX_S_PERMISSION_DENIED
 167 or a MUX_S_FAILURE.
 168
 169 8. Requesting shutdown of mux listener
 170
 171 A client may request the master to stop accepting new multiplexing requests
 172 and remove its listener socket.
 173
 174         uint32  MUX_C_STOP_LISTENING
 175         uint32  request id
 176
 177 A server may reply with a MUX_S_OK, a MUX_S_PERMISSION_DENIED or a
 178 MUX_S_FAILURE.
 179
 180 9. Status messages
 181
 182 The MUX_S_OK message is empty:
 183
 184         uint32  MUX_S_OK
 185         uint32  client request id
 186
 187 The MUX_S_PERMISSION_DENIED and MUX_S_FAILURE include a reason:
 188
 189         uint32  MUX_S_PERMISSION_DENIED
 190         uint32  client request id
 191         string  reason
 192
 193         uint32  MUX_S_FAILURE
 194         uint32  client request id
 195         string  reason
 196
 197 10. Protocol numbers
 198
 199 #define MUX_MSG_HELLO           0x00000001
 200 #define MUX_C_NEW_SESSION       0x10000002
 201 #define MUX_C_ALIVE_CHECK       0x10000004
 202 #define MUX_C_TERMINATE         0x10000005
 203 #define MUX_C_OPEN_FWD          0x10000006
 204 #define MUX_C_CLOSE_FWD         0x10000007
 205 #define MUX_C_NEW_STDIO_FWD     0x10000008
 206 #define MUX_C_STOP_LISTENING    0x10000009
 207 #define MUX_S_OK                0x80000001
 208 #define MUX_S_PERMISSION_DENIED 0x80000002
 209 #define MUX_S_FAILURE           0x80000003
 210 #define MUX_S_EXIT_MESSAGE      0x80000004
 211 #define MUX_S_ALIVE             0x80000005
 212 #define MUX_S_SESSION_OPENED    0x80000006
 213 #define MUX_S_REMOTE_PORT       0x80000007
 214 #define MUX_S_TTY_ALLOC_FAIL    0x80000008
 215
 216 #define MUX_FWD_LOCAL   1
 217 #define MUX_FWD_REMOTE  2
 218 #define MUX_FWD_DYNAMIC 3
 219
 220 XXX TODO
 221 XXX extended status (e.g. report open channels / forwards)
 222 XXX lock (maybe)
 223 XXX watch in/out traffic (pre/post crypto)
 224 XXX inject packet (what about replies)
 225 XXX server->client error/warning notifications
 226 XXX send signals via mux
 227
 228 $OpenBSD: PROTOCOL.mux,v 1.10 2015/07/17 03:04:27 djm Exp $