New channel requests...

["Joseph Galbraith" <galb-list%vandyke.com@localhost>]

This isn't part of what we agreed on in the meeting,
so I've done it as a separate email-- but, it makes
sense to me to change the channel requests in a parallel
fashion to the global requests.

Also, we [Van Dyke] have wanted better failure messages for
subsystem requests, so I've introduced "start-subsystem"
to replace "subsystem" with better failure results
provided.

Again, please comment.  Do people think this is a bad
idea, or can we go ahead, since it is fully backward
compatible?

Joseph Galbraith
galb-list%vandyke.com@localhost

------------ Section 3.4

    3.4 Channel-Specific Requests

       Many channel types have extensions that are specific to that
       particular channel type.  An example is requesting a pty (pseudo
       terminal) for an interactive session.

       All channel-specific requests use the following format.

        byte      SSH_MSG_CHANNEL_REQUEST
        uint32    recipient channel
        string    request type (restricted to US-ASCII)
        boolean   want reply
        ... type-specific data

       If want reply is FALSE, no response will be sent to the request.
       Otherwise, the recipient responds with either
       SSH_MSG_CHANNEL_SUCCESS or SSH_MSG_CHANNEL_FAILURE, or request-
       specific continuation messages.  If the request is not recognized
       or is not supported for the channel, SSH_MSG_CHANNEL_FAILURE is
       returned.

       This message does not consume window space and can be sent even if
       no window space is available.  Request types are local to each
       channel type.

        byte      SSH_MSG_CHANNEL_SUCCESS
        uint32    recipient_channel
        ...request specific data


        byte      SSH_MSG_CHANNEL_FAILURE
        uint32    recipient_channel
        ...request specific data

       These messages do not consume window space and can be sent even if
       no window space is available.

       Unless otherwise specified, a request uses the general form
       of these messages, with no request specific failure or success
       data.

       If the recipient doesn't recognize the request, it
       will send a SSH_MSG_CHANNEL_FAILURE without any
       request specific data.  This is called the generic
       form.

       Requests that do send information during failure MUST
       use the following format:

        byte      SSH_MSG_CHANNEL_FAILURE
        uint32    recipient_channel
        uint32    reason
        string    descriptive-text [UTF8]
        string    language
        ... further request-specific data follows

       New requests SHOULD use this extended failure message
       in order to provide end users and server administrators
       with information about a failure.

    3.4.1 Multiple requests and ordering

       The client is allowed to send further messages without waiting for
       the response to the request.  The recipient must respond to messages
       in the order received so that responses can be matched to requests.

    3.4.2 Compatibility with older software

       As with global requests, older software can send old requests
       without fear of receiving an extended response.  New software,
       sending new requests to older software will receive the generic
       form of SSH_MSG_CHANNEL_FAILURE.  If the task can be accomplished
       in another way, the new software can proceed to attempt that;
       otherwise, it knows the receiver does not support the operation
       being attempted.

------------ Section 3.4, part about subsystems

        byte      SSH_MSG_CHANNEL_REQUEST
        uint32    recipient channel
        string    "start-subsystem"
        boolean   want reply
        string    subsystem name

      This last form executes a predefined subsystem.  It is expected
      that these will include a general file transfer mechanism, and
      possibly other features.  Implementations may also allow
      configuring more such mechanisms.  As the user's shell is usually
      used to execute the subsystem, it is advisable for the subsystem
      protocol to have a "magic cookie" at the beginning of the protocol
      transaction to distinguish from arbitrary output from shell
      initialization scripts etc.  This spurious output from the shell
      may be filtered out either at the server or at the client.

      The server SHOULD not halt the execution of the protocol stack
      when starting a shell or a program.  All input and output from
      these SHOULD be redirected to the channel or to the encrypted
      tunnel.

      It is RECOMMENDED to request and check the reply for these
      messages.  The client SHOULD ignore these messages.

      The server response uses the generic form of
      SSH_MSG_CHANNEL_SUCCESS in the success case.  In the
      failure case, the extended form of SSH_MSG_CHANNEL_FAILURE
      is used as defined in Section 3.4.  There is no additional
      request specific data beyond the reason, description and language
      fields.  The reason codes used are as follows:

        SSH_SUBSYSTEM_GENERIC    0
            Generic error to be used for errors not covered
            by other reason codes.

        SSH_SUBSYSTEM_UNKNOWN    1
            The subsystem name is not defined on the server.

        SSH_SUBSYSTEM_NOT_FOUND  2
            The subsystem name is defined, but could not be
            started because the associated component didn't exist.

        SSH_SUBSYSTEM_ADMINISTRATIVELY_PROHIBITED    3
            The subsystem will not be started because it the user
            requesting it is not permitted to do so.

    3.4.1 Compatibility

       This request used to be "subsystem".  The "subsystem" request
       is still supported, but implementations should move away from
       using it.  The "subsystem" request is identical to the
       "start-subsystem" request, except that it uses the general
       form of the response messages, making it impossible to determine
       why the subsystem did not start, in the event of a failure.

       Old software receiving a "start-subsystem" request will fail
       it with the general response form.  Newer software can then
       fall back on the old "subsystem" request.

       Old software making "subsystem" requests will receive
       compatible general response forms, regardless of whether a
       new or old implementation is the receiver.