remctl: Remote Authenticated Command Service

2.1. Session Sequence

A remctl connection is always initiated by a client opening a TCP connection to a server. The protocol then proceeds as follows:¶

1. Client sends message with an empty payload and flags TOKEN_NOOP, TOKEN_CONTEXT_NEXT, and TOKEN_PROTOCOL (0x51). If the client doesn't include TOKEN_PROTOCOL, it is speaking the version 1 protocol, and the server MUST either drop the connection or fall back to the version 1 protocol. This initial message is useless in a pure version 2 or 3 protocol world and is done only for backward compatibility with the version 1 protocol.¶
2. Client calls gss_init_sec_context and sends the results as the message body with flags TOKEN_CONTEXT and TOKEN_PROTOCOL (0x42). The client MUST pass GSS_C_MUTUAL_FLAG, GSS_C_CONF_FLAG, and GSS_C_INTEG_FLAG as requested flags to gss_init_sec_context and SHOULD pass GSS_C_REPLAY_FLAG and GSS_C_SEQUENCE_FLAG.¶
3. Server replies with the results of gss_accept_sec_context and flags TOKEN_CONTEXT and TOKEN_PROTOCOL (0x42). If the server doesn't include TOKEN_PROTOCOL in the flags, it is speaking the version 1 protocol, and the client MUST either drop the connection or fall back to the version 1 protocol.¶
4. Client passes data to gss_init_sec_context and replies with the results and TOKEN_CONTEXT and TOKEN_PROTOCOL (0x42). The client must pass GSS_C_MUTUAL_FLAG, GSS_C_CONF_FLAG, and GSS_C_INTEG_FLAG as requested flags and SHOULD pass GSS_C_REPLAY_FLAG and GSS_C_SEQUENCE_FLAG.¶
5. Server and client repeat, passing in the payload from the last packet from the other side, for as long as GSS-API indicates that continuation is required. If either side drops TOKEN_PROTOCOL from the flags, it is an considered an error and the connect MUST be dropped. (This could be a down-negotiation attack.) After the establishment of the security context, both client and server MUST confirm that GSS_C_MUTUAL_FLAG, GSS_C_CONF_FLAG, and GSS_C_INTEG_FLAG are set in the resulting security context and MUST immediately close the connection if this is not the case.¶
6. After the security context has been established, the client and server exchange commands and responses as described below. All commands are sent with flags TOKEN_DATA and TOKEN_PROTOCOL (0x44) and the data payload of all packets is protected with gss_wrap. The conf_req_flag parameter of gss_wrap MUST be set to non-zero, requesting both confidentiality and integrity services.¶

2.2. Message Format

All client and server messages will use the following format inside the data payload. This is the format of the message before passing it to gss_wrap for confidentiality and integrity protection.¶

    1 octet     protocol version
    1 octet     message type
    <command-specific data>

The protocol version sent for all messages should be 2 with the exception of MESSAGE_NOOP, which should have a protocol version of 3. The version 1 protocol does not use this message format, and therefore a protocol version of 1 is invalid. See below for protocol version negotiation.¶

The message type is one of the following constants:¶

    1   MESSAGE_COMMAND
    2   MESSAGE_QUIT
    3   MESSAGE_OUTPUT
    4   MESSAGE_STATUS
    5   MESSAGE_ERROR
    6   MESSAGE_VERSION
    7   MESSAGE_NOOP

The first two message types are client messages and MUST NOT be sent by the server. The remaining message types except for MESSAGE_NOOP are server messages and MUST NOT by sent by the client.¶

All of these message types were introduced in protocol version 2 except for MESSAGE_NOOP, which is a protocol version 3 message.¶

2.3. Protocol Version Negotiation

If the server ever receives a message from a client that claims a protocol version higher than the server supports, the server MUST otherwise ignore the contents of the message and SHOULD respond with a message type of MESSAGE_VERSION and the following message payload:¶

    1 octet     highest supported version

The client MUST then either send only messages supported at that protocol version or lower or send MESSAGE_QUIT and close the connection.¶

Currently, there are only two meaningful values for the highest supported version: 3, which indicates everything in this specification is supported, or 2, which indicates that everything except MESSAGE_NOOP is supported.¶

2.4. MESSAGE_COMMAND

Most client messages will be of type MESSAGE_COMMAND, which has the following format:¶

    1 octet     keep-alive flag
    1 octet     continue status
    4 octets    number of arguments
    4 octets    argument length
    <length>    argument
    ...

If the keep-alive flag is 0, the server SHOULD close the connection after processing the command. If it is 1, the server SHOULD leave the connection open (up to a timeout period) and wait for more commands. This is similar to HTTP keep-alive.¶

If the continue status is 0, it indicates that this is the complete command. If the continue status is 1, it indicates that there is more data coming. The server should accept the data sent, buffer it, and wait for additional messages before running the command or otherwise responding. If the the continue status is 2, it indicates that this message is logically a part of the previous message (which MUST have had a continue status of 1 or 2) and still has more data coming. If the continue status is 3, it says that this message is logically part of the previous message, like 2, but it also says that this is the end of the command.¶

A continuation of a message starts with the keep-alive flag and continue status and then the next chunk of data. To reconstruct a continued message, remove the first two octets from each chunk and concatenate the pieces together. The result is the portion of a MESSAGE_COMMAND starting with the number of arguments.¶

The current implementation permits messages to be broken into multiple MESSAGE_COMMANDs even in the middle of the number of arguments or an argument length. In other words, the first three octets of the number of arguments could be in the first MESSAGE_COMMAND (with continue status 1) and the last octet would then be in the next MESSAGE_COMMAND (with continue status 2 or 3). However, the client SHOULD NOT take advantage of this support and SHOULD NOT split an argument count or argument length across multiple messages, since this support may be dropped in a subsequent protocol revision.¶

For as long as the continue status is 1 or 2, the next message from the client MUST be either another MESSAGE_COMMAND with a continue status of 2 or 3 or a MESSAGE_QUIT. In other words, other message types MUST NOT be intermixed with continued commands, but MESSAGE_QUIT may be sent by the client in the middle of a continued command to abort that command. If the server receives MESSAGE_QUIT from the client before receiving a MESSAGE_COMMAND with a status of 3 (indicating the end of the command), the command MUST be discarded and not executed.¶

If a client sends an invalid sequence of MESSAGE_COMMAND messages that violate the continuation rules described above, the server SHOULD reply with a MESSAGE_ERROR message, generally with one of the ERROR_BAD_TOKEN, ERROR_UNKNOWN_MESSAGE, ERROR_BAD_COMMAND, or ERROR_UNEXPECTED_MESSAGE error codes. It MUST discard the partial command without acting on it. The client cannot correct an error in a continued MESSAGE_COMMAND stream by resending the previous part. It MUST start again at the beginning with a MESSAGE_COMMAND with a continue status of 0 or 1.¶

Number of arguments is a four-octet number in network byte order that gives the total number of command arguments. For each argument, there is then a length and argument data pair, where the length is a four-octet number in network byte order indicating the number of octets of data in the following argument. Argument length may be 0. Commands with no arguments are permitted by the protocol.¶

Servers may impose limits on the number of arguments and the size of argument data to limit resource usage. If the client message exceeds one of those limits, the server MUST respond with MESSAGE_ERROR with an error code of ERROR_TOOMANY_ARGS or ERROR_TOOMUCH_DATA as appropriate.¶

2.5. MESSAGE_OUTPUT and MESSAGE_STATUS

The server response to MESSAGE_COMMAND is zero or more MESSAGE_OUTPUT messages followed by either a MESSAGE_STATUS or a MESSAGE_ERROR response. Each MESSAGE_OUTPUT message has the following format:¶

    1 octet     output stream
    4 octets    output length
    <length>    output

The output stream is either 1 for standard output or 2 for standard error. Output length is a four-octet number in network byte order that specifies the length of the following output data.¶

The MESSAGE_STATUS message has the following format:¶

    1 octet     exit status

MESSAGE_STATUS indicates the command has finished and returns the final exit stauts of the command. Exit status is 0 for success and non-zero for failure, where the meaning of non-zero exit statuses is left to the application to define. (This is identical to a Unix command exit status.)¶

Unless the MESSAGE_COMMAND message from the client had the keep-alive flag set to 1, the server MUST close the network connection immediately after sending the MESSAGE_STATUS response message.¶

2.6. MESSAGE_ERROR

At any point before sending MESSAGE_STATUS, the server may respond with MESSAGE_ERROR if some error occurred. This can be the first response after a MESSAGE_COMMAND, or it may be sent after one or more MESSAGE_OUTPUT messages. The format of MESSAGE_ERROR is as follows:¶

    4 octets    error code
    4 octets    message length
    <length>    error message

The error code is a four-octet number in network byte order indicating the type of error. The error code may be one of the following values:¶

    1  ERROR_INTERNAL           Internal server failure
    2  ERROR_BAD_TOKEN          Invalid format in token
    3  ERROR_UNKNOWN_MESSAGE    Unknown message type
    4  ERROR_BAD_COMMAND        Invalid command format in token
    5  ERROR_UNKNOWN_COMMAND    Unknown command
    6  ERROR_ACCESS             Access denied
    7  ERROR_TOOMANY_ARGS       Argument count exceeds server limit
    8  ERROR_TOOMUCH_DATA       Argument size exceeds server limit
    9  ERROR_UNEXPECTED_MESSAGE Message type not valid now

Additional error codes may be added without changing the version of the remctl protocol, so clients MUST accept error codes other than the ones above.¶

The message length is a four-octet number in network byte order that specifies the length in octets of the following error message. The error message is a free-form informational message intended for human consumption and MUST NOT be interpreted by an automated process. Software should instead use the error code.¶

Unless the MESSAGE_COMMAND message from the client had the keep-alive flag set to 1, the server MUST close the network connection immediately after sending the MESSAGE_ERROR response message. Otherwise, the server SHOULD still honor that flag, although the server MAY terminate the connection after an unreasonable number of errors.¶

2.7. MESSAGE_QUIT

MESSAGE_QUIT is a way of terminating the connection cleanly if the client asked for keep-alive and then decided not to use it. There is no message body. Upon receiving this message, the server MUST immediately close the connection.¶

2.8. MESSAGE_NOOP

MESSAGE_NOOP provides a way for a client to keep the connection open to a remctl server, including through firewall session timeouts and similar network constraints that require periodic activity, without sending new commands. There is no body. When the client sends a MESSAGE_NOOP message, the server replies with a MESSAGE_NOOP message.¶

Note that MESSAGE_NOOP was introduced in protocol version 3 and therefore should be marked accordingly. Clients should be prepared for older servers to reply with MESSAGE_VERSION instead of MESSAGE_NOOP.¶