Because there is no way to determine message boundaries when using Protocol Buffers, the wire size of each message is sent immediately preceding the message itself as a 32-bit unsigned integer in network byte order. This is referred to as ``length-prefix framing'' and is how Google suggests handling the lack of message delimiters.
The protocol is made up of two basic messages, ClientMessage and ServerMessage described below. The server must accept messages up to two megabytes in size. The server may return an error if the client tries to send a message larger than two megabytes.
message ClientMessage {
oneof type {
AcceptMessage accept_msg = 1;
RejectMessage reject_msg = 2;
ExitMessage exit_msg = 3;
RestartMessage restart_msg = 4;
AlertMessage alert_msg = 5;
IoBuffer ttyin_buf = 6;
IoBuffer ttyout_buf = 7;
IoBuffer stdin_buf = 8;
IoBuffer stdout_buf = 9;
IoBuffer stderr_buf = 10;
ChangeWindowSize winsize_event = 11;
CommandSuspend suspend_event = 12;
ClientHello hello_msg = 13;
}
}
The different ClientMessage sub-messages the client may sent to the server are described below.
message TimeSpec {
int64 tv_sec = 1;
int32 tv_nsec = 2;
}
A TimeSpec is the equivalent of a POSIX struct timespec containing seconds and nanoseconds members. The tv_sec member is a 64-bit integer to support dates after the year 2038.
message InfoMessage {
message StringList {
repeated string strings = 1;
}
message NumberList {
repeated int64 numbers = 1;
}
string key = 1;
oneof value {
int64 numval = 2;
string strval = 3;
StringList strlistval = 4;
NumberList numlistval = 5;
}
}
An InfoMessage is used to represent information about the invoking user as well as the execution environment the command runs in the form of key-value pairs. The key is always a string but the value may be a 64-bit integer, a string, an array of strings or an array of 64-bit integers. The event log data is composed of InfoMessage entries. See the Sx EVENT LOG VARIABLES section for more information.
message ClientHello {
string client_id = 1;
}
A ClientHello message consists of client information that may be sent to the server when the client first connects.
message AcceptMessage {
TimeSpec submit_time = 1;
repeated InfoMessage info_msgs = 2;
bool expect_iobufs = 3;
}
An AcceptMessage is sent by the client when a command is allowed by the security policy. It contains the following members:
If an AcceptMessage is sent, the client must not send a RejectMessage or RestartMessage
message RejectMessage {
TimeSpec submit_time = 1;
string reason = 2;
repeated InfoMessage info_msgs = 3;
}
A RejectMessage is sent by the client when a command is denied by the security policy. It contains the following members:
If a RejectMessage is sent, the client must not send an AcceptMessage or RestartMessage
message ExitMessage {
TimeSpec run_time = 1;
int32 exit_value = 2;
bool dumped_core = 3;
string signal = 4;
string error = 5;
}
An
ExitMessage
is sent by the client after the command has exited or has been
terminated by a signal.
It contains the following members:
When performing I/O logging, the client should wait for a commit_point corresponding to the final IoBuffer before closing the connection unless the final commit_point has already been received.
message RestartMessage {
string log_id = 1;
TimeSpec resume_point = 2;
}
A RestartMessage is sent by the client to resume sending an existing I/O log that was previously interrupted. It contains the following members:
If a RestartMessage is sent, the client must not send an AcceptMessage or RejectMessage
message AlertMessage {
TimeSpec alert_time = 1;
string reason = 2;
}
An AlertMessage is sent by the client to indicate a problem detected by the security policy while the command is running that should be stored in the event log. It contains the following members:
message IoBuffer {
TimeSpec delay = 1;
bytes data = 2;
}
An IoBuffer is used to represent data from terminal input, terminal output, standard input, standard output or standard error. It contains the following members:
message ChangeWindowSize {
TimeSpec delay = 1;
int32 rows = 2;
int32 cols = 3;
}
A ChangeWindowSize message is sent by the client when the terminal running the command changes size. It contains the following members:
message CommandSuspend {
TimeSpec delay = 1;
string signal = 2;
}
A CommandSuspend message is sent by the client when the command is either suspended or resumed. It contains the following members:
message ServerMessage {
oneof type {
ServerHello hello = 1;
TimeSpec commit_point = 2;
string log_id = 3;
string error = 4;
string abort = 5;
}
}
The different ServerMessage sub-messages the server may sent to the client are described below.
message ServerHello {
string server_id = 1;
string redirect = 2;
repeated string servers = 3;
}
The ServerHello message consists of server information sent when the client first connects. It contains the following members:
At any point, the server may send an error or abort message to the client at which point the server will close the connection. If an abort message is received, the client should terminate the running command.
Some variables have a client run or submit prefix. These prefixes are used to eliminate ambiguity for variables that could apply to the client program, the user submitting the command, or the command being run. Variables with a client prefix pertain to the program performing the connection to the log server, for example sudo Variables with a run prefix pertain to the command that the user requested be run. Variables with a submit prefix pertain to the user submitting the request (the user running sudo )
The following InfoMessage entries are required:
The following InfoMessage entries are recognized, but not required:
The server must accept other variables not listed above but may ignore them.
syntax = "proto3";
/*
* Client message to the server. Messages on the wire are
* prefixed with a 32-bit size in network byte order.
*/
message ClientMessage {
oneof type {
AcceptMessage accept_msg = 1;
RejectMessage reject_msg = 2;
ExitMessage exit_msg = 3;
RestartMessage restart_msg = 4;
AlertMessage alert_msg = 5;
IoBuffer ttyin_buf = 6;
IoBuffer ttyout_buf = 7;
IoBuffer stdin_buf = 8;
IoBuffer stdout_buf = 9;
IoBuffer stderr_buf = 10;
ChangeWindowSize winsize_event = 11;
CommandSuspend suspend_event = 12;
}
}
/* Equivalent of POSIX struct timespec */
message TimeSpec {
int64 tv_sec = 1; /* seconds */
int32 tv_nsec = 2; /* nanoseconds */
}
/* I/O buffer with keystroke data */
message IoBuffer {
TimeSpec delay = 1; /* elapsed time since last record */
bytes data = 2; /* keystroke data */
}
/*
* Key/value pairs, like Privilege Manager struct info.
* The value may be a number, a string, or a list of strings.
*/
message InfoMessage {
message StringList {
repeated string strings = 1;
}
message NumberList {
repeated int64 numbers = 1;
}
string key = 1;
oneof value {
int64 numval = 2;
string strval = 3;
StringList strlistval = 4;
NumberList numlistval = 5;
}
}
/*
* Event log data for command accepted by the policy.
*/
message AcceptMessage {
TimeSpec submit_time = 1; /* when command was submitted */
repeated InfoMessage info_msgs = 2; /* key,value event log data */
bool expect_iobufs = 3; /* true if I/O logging enabled */
}
/*
* Event log data for command rejected by the policy.
*/
message RejectMessage {
TimeSpec submit_time = 1; /* when command was submitted */
string reason = 2; /* reason command was rejected */
repeated InfoMessage info_msgs = 3; /* key,value event log data */
}
/* Message sent by client when command exits. */
/* Might revisit runtime and use end_time instead */
message ExitMessage {
TimeSpec run_time = 1; /* total elapsed run time */
int32 exit_value = 2; /* 0-255 */
bool dumped_core = 3; /* true if command dumped core */
string signal = 4; /* signal name if killed by signal */
string error = 5; /* if killed due to other error */
}
/* Alert message, policy module-specific. */
message AlertMessage {
TimeSpec alert_time = 1; /* time alert message occurred */
string reason = 2; /* description of policy violation */
}
/* Used to restart an existing I/O log on the server. */
message RestartMessage {
string log_id = 1; /* ID of log being restarted */
TimeSpec resume_point = 2; /* resume point (elapsed time) */
}
/* Window size change event. */
message ChangeWindowSize {
TimeSpec delay = 1; /* elapsed time since last record */
int32 rows = 2; /* new number of rows */
int32 cols = 3; /* new number of columns */
}
/* Command suspend/resume event. */
message CommandSuspend {
TimeSpec delay = 1; /* elapsed time since last record */
string signal = 2; /* signal that caused suspend/resume */
}
/*
* Server messages to the client. Messages on the wire are
* prefixed with a 32-bit size in network byte order.
*/
message ServerMessage {
oneof type {
ServerHello hello = 1; /* server hello message */
TimeSpec commit_point = 2; /* cumulative time of records stored */
string log_id = 3; /* ID of server-side I/O log */
string error = 4; /* error message from server */
string abort = 5; /* abort message, kill command */
}
}
/* Hello message from server when client connects. */
message ServerHello {
string server_id = 1; /* free-form server description */
string redirect = 2; /* optional redirect if busy */
repeated string servers = 3; /* optional list of known servers */
}
An Todd C. Miller
See the CONTRIBUTORS file in the sudo distribution (https://www.sudo.ws/contributors.html) for an exhaustive list of people who have contributed to sudo