source: web/old/remctl-2.14/docs/protocol.html @ f6f3e91

web
Last change on this file since f6f3e91 was f6f3e91, checked in by Jessica B. Hamrick <jhamrick@…>, 15 years ago

Preserve directory hierarchy (not sure what happened to it)
  • Property mode set to 100644
File size: 29.7 KB
Line 
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
2<html lang="en"><head><title>remctl Protocol: remctl: Remote Authenticated Command Service</title>
3<meta http-equiv="Expires" content="Fri, 22 May 2009 23:07:44 +0000">
4<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
5<meta name="description" content="remctl: Remote Authenticated Command Service">
6<meta name="generator" content="xml2rfc v1.33 (http://xml.resource.org/)">
7<style type='text/css'><!--
8        body {
9                font-family: verdana, charcoal, helvetica, arial, sans-serif;
10                font-size: small; color: #000; background-color: #FFF;
11                margin: 2em;
12        }
13        h1, h2, h3, h4, h5, h6 {
14                font-family: helvetica, monaco, "MS Sans Serif", arial, sans-serif;
15                font-weight: bold; font-style: normal;
16        }
17        h1 { color: #900; background-color: transparent; text-align: right; }
18        h3 { color: #333; background-color: transparent; }
19
20        td.RFCbug {
21                font-size: x-small; text-decoration: none;
22                width: 30px; height: 30px; padding-top: 2px;
23                text-align: justify; vertical-align: middle;
24                background-color: #000;
25        }
26        td.RFCbug span.RFC {
27                font-family: monaco, charcoal, geneva, "MS Sans Serif", helvetica, verdana, sans-serif;
28                font-weight: bold; color: #666;
29        }
30        td.RFCbug span.hotText {
31                font-family: charcoal, monaco, geneva, "MS Sans Serif", helvetica, verdana, sans-serif;
32                font-weight: normal; text-align: center; color: #FFF;
33        }
34
35        table.TOCbug { width: 30px; height: 15px; }
36        td.TOCbug {
37                text-align: center; width: 30px; height: 15px;
38                color: #FFF; background-color: #900;
39        }
40        td.TOCbug a {
41                font-family: monaco, charcoal, geneva, "MS Sans Serif", helvetica, sans-serif;
42                font-weight: bold; font-size: x-small; text-decoration: none;
43                color: #FFF; background-color: transparent;
44        }
45
46        td.header {
47                font-family: arial, helvetica, sans-serif; font-size: x-small;
48                vertical-align: top; width: 33%;
49                color: #FFF; background-color: #666;
50        }
51        td.author { font-weight: bold; font-size: x-small; margin-left: 4em; }
52        td.author-text { font-size: x-small; }
53
54        /* info code from SantaKlauss at http://www.madaboutstyle.com/tooltip2.html */
55        a.info {
56                /* This is the key. */
57                position: relative;
58                z-index: 24;
59                text-decoration: none;
60        }
61        a.info:hover {
62                z-index: 25;
63                color: #FFF; background-color: #900;
64        }
65        a.info span { display: none; }
66        a.info:hover span.info {
67                /* The span will display just on :hover state. */
68                display: block;
69                position: absolute;
70                font-size: smaller;
71                top: 2em; left: -5em; width: 15em;
72                padding: 2px; border: 1px solid #333;
73                color: #900; background-color: #EEE;
74                text-align: left;
75        }
76
77        a { font-weight: bold; }
78        a:link    { color: #900; background-color: transparent; }
79        a:visited { color: #633; background-color: transparent; }
80        a:active  { color: #633; background-color: transparent; }
81
82        p { margin-left: 2em; margin-right: 2em; }
83        p.copyright { font-size: x-small; }
84        p.toc { font-size: small; font-weight: bold; margin-left: 3em; }
85        table.toc { margin: 0 0 0 3em; padding: 0; border: 0; vertical-align: text-top; }
86        td.toc { font-size: small; font-weight: bold; vertical-align: text-top; }
87
88        ol.text { margin-left: 2em; margin-right: 2em; }
89        ul.text { margin-left: 2em; margin-right: 2em; }
90        li      { margin-left: 3em; }
91
92        /* RFC-2629 <spanx>s and <artwork>s. */
93        em     { font-style: italic; }
94        strong { font-weight: bold; }
95        dfn    { font-weight: bold; font-style: normal; }
96        cite   { font-weight: normal; font-style: normal; }
97        tt     { color: #036; }
98        tt, pre, pre dfn, pre em, pre cite, pre span {
99                font-family: "Courier New", Courier, monospace; font-size: small;
100        }
101        pre {
102                text-align: left; padding: 4px;
103                color: #000; background-color: #CCC;
104        }
105        pre dfn  { color: #900; }
106        pre em   { color: #66F; background-color: #FFC; font-weight: normal; }
107        pre .key { color: #33C; font-weight: bold; }
108        pre .id  { color: #900; }
109        pre .str { color: #000; background-color: #CFF; }
110        pre .val { color: #066; }
111        pre .rep { color: #909; }
112        pre .oth { color: #000; background-color: #FCF; }
113        pre .err { background-color: #FCC; }
114
115        /* RFC-2629 <texttable>s. */
116        table.all, table.full, table.headers, table.none {
117                font-size: small; text-align: center; border-width: 2px;
118                vertical-align: top; border-collapse: collapse;
119        }
120        table.all, table.full { border-style: solid; border-color: black; }
121        table.headers, table.none { border-style: none; }
122        th {
123                font-weight: bold; border-color: black;
124                border-width: 2px 2px 3px 2px;
125        }
126        table.all th, table.full th { border-style: solid; }
127        table.headers th { border-style: none none solid none; }
128        table.none th { border-style: none; }
129        table.all td {
130                border-style: solid; border-color: #333;
131                border-width: 1px 2px;
132        }
133        table.full td, table.headers td, table.none td { border-style: none; }
134
135        hr { height: 1px; }
136        hr.insert {
137                width: 80%; border-style: none; border-width: 0;
138                color: #CCC; background-color: #CCC;
139        }
140--></style>
141</head>
142<body>
143<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
144<table summary="layout" width="66%" border="0" cellpadding="0" cellspacing="0"><tr><td><table summary="layout" width="100%" border="0" cellpadding="2" cellspacing="1">
145<tr><td class="header">remctl Protocol</td><td class="header">R. Allbery</td></tr>
146<tr><td class="header">&nbsp;</td><td class="header">Stanford University</td></tr>
147<tr><td class="header">&nbsp;</td><td class="header">September 2007</td></tr>
148</table></td></tr></table>
149<h1><br />remctl: Remote Authenticated Command Service</h1>
150
151<h3>Abstract</h3>
152
153<p>This document specifies the remctl wire protocol, used to send
154      commands and arguments to a remote system and receive the results of
155      executing that command.  The protocol uses GSS-API and Kerberos v5
156      for authentication, confidentiality, and integrity protection.  Both
157      the current (version 2) protocol and the older version 1 protocol
158      are described.  The version 1 protocol should only be implemented
159      for backward compatibility.
160</p><a name="toc"></a><br /><hr />
161<h3>Table of Contents</h3>
162<p class="toc">
163<a href="#format">1.</a>&nbsp;
164Basic Packet Format<br />
165<a href="#proto2">2.</a>&nbsp;
166Network Protocol (version 2)<br />
167&nbsp;&nbsp;&nbsp;&nbsp;<a href="#packet">2.1.</a>&nbsp;
168Session Sequence<br />
169&nbsp;&nbsp;&nbsp;&nbsp;<a href="#messages">2.2.</a>&nbsp;
170Message Format<br />
171&nbsp;&nbsp;&nbsp;&nbsp;<a href="#negotiation">2.3.</a>&nbsp;
172Protocol Version Negotiation<br />
173&nbsp;&nbsp;&nbsp;&nbsp;<a href="#command">2.4.</a>&nbsp;
174MESSAGE_COMMAND<br />
175&nbsp;&nbsp;&nbsp;&nbsp;<a href="#output">2.5.</a>&nbsp;
176MESSAGE_OUTPUT and MESSAGE_STATUS<br />
177&nbsp;&nbsp;&nbsp;&nbsp;<a href="#error">2.6.</a>&nbsp;
178MESSAGE_ERROR<br />
179&nbsp;&nbsp;&nbsp;&nbsp;<a href="#quit">2.7.</a>&nbsp;
180MESSAGE_QUIT<br />
181<a href="#proto1">3.</a>&nbsp;
182Network Protocol (version 1)<br />
183<a href="#security">4.</a>&nbsp;
184Security Considerations<br />
185<a href="#credits">Appendix&nbsp;A.</a>&nbsp;
186Acknowledgements<br />
187<a href="#rfc.authors">&#167;</a>&nbsp;
188Author's Address<br />
189</p>
190<br clear="all" />
191
192<a name="format"></a><br /><hr />
193<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
194<a name="rfc.section.1"></a><h3>1.&nbsp;
195Basic Packet Format</h3>
196
197<p>The remctl network protocol consists of data packets sent from a
198      client to a server or a server to a client over a TCP connection.
199      The remctl protocol may be used over any port, but the
200      IANA-registered port and the RECOMMENDED default for the protocol is
201      4373.  Each data packet has the following format:
202</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>
203    1 octet     flags
204    4 octets    length
205    &lt;length&gt;    data payload
206</pre></div>
207<p>The total size of each token, including the five octet prefix,
208      MUST NOT be larger than 1,048,576 octets (1MB).
209</p>
210<p>The flag octet contains one or more of the following
211        values, combined with binary xor:
212</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>
213    0x01        TOKEN_NOOP
214    0x02        TOKEN_CONTEXT
215    0x04        TOKEN_DATA
216    0x08        TOKEN_MIC
217    0x10        TOKEN_CONTEXT_NEXT
218    0x20        TOKEN_SEND_MIC
219    0x40        TOKEN_PROTOCOL
220</pre></div>
221<p>Only TOKEN_CONTEXT, TOKEN_CONTEXT_NEXT, TOKEN_DATA, and
222        TOKEN_PROTOCOL are used for version 2 packets.  The other flags
223        are used only with the legacy version 1 protocol.
224</p>
225<p>The length field is a four-octet length in network byte order,
226      specifying the number of octets in the following data payload.
227</p>
228<p>The data payload is empty, the results of gss_accept_sec_context,
229      the results of gss_init_sec_context, or a data payload protected
230      with gss_wrap.  The length of the data passed to gss_wrap MUST NOT
231      be larger than 65,536 octets (64KB), even if the underlying Kerberos
232      implementation supports longer input buffers.
233</p>
234<a name="proto2"></a><br /><hr />
235<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
236<a name="rfc.section.2"></a><h3>2.&nbsp;
237Network Protocol (version 2)</h3>
238
239<a name="packet"></a><br /><hr />
240<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
241<a name="rfc.section.2.1"></a><h3>2.1.&nbsp;
242Session Sequence</h3>
243
244<p>A remctl connection is always initiated by a client opening a
245        TCP connection to a server.  The protocol then proceeds as
246        follows:
247          </p>
248<ol class="text">
249<li>Client sends message with an empty payload and flags
250            TOKEN_NOOP, TOKEN_CONTEXT_NEXT, and TOKEN_PROTOCOL (0x51).  If
251            the client doesn't include TOKEN_PROTOCOL, it is speaking the
252            version 1 protocol, and the server MUST either drop the
253            connection or fall back to the version 1 protocol.  This
254            initial message is useless in a pure version 2 protocol world
255            and is done only for backward compatibility with the version 1
256            protocol.
257</li>
258<li>Client calls gss_init_sec_context and replies with the
259            results and TOKEN_CONTEXT and TOKEN_PROTOCOL (0x42).  The
260            client MUST pass GSS_C_MUTUAL_FLAG, GSS_C_CONF_FLAG, and
261            GSS_C_INTEG_FLAG as requested flags and SHOULD pass
262            GSS_C_REPLAY_FLAG and GSS_C_SEQUENCE_FLAG.
263</li>
264<li>Server replies with the results of gss_accept_sec_context
265            and flags TOKEN_CONTEXT and TOKEN_PROTOCOL (0x42).  If the
266            server doesn't include TOKEN_PROTOCOL in the flags, it is
267            speaking the version 1 protocol, and the client MUST either
268            drop the connection or fall back to the version 1
269            protocol.
270</li>
271<li>Client passes data to gss_init_sec_context and replies with
272            the results and TOKEN_CONTEXT and TOKEN_PROTOCOL (0x42).  The
273            client must pass GSS_C_MUTUAL_FLAG, GSS_C_CONF_FLAG, and
274            GSS_C_INTEG_FLAG as requested flags and SHOULD pass
275            GSS_C_REPLAY_FLAG and GSS_C_SEQUENCE_FLAG.
276</li>
277<li>Server and client repeat, passing in the payload from the
278            last packet from the other side, for as long as GSS-API
279            indicates that continuation is required.  If either side drops
280            TOKEN_PROTOCOL from the flags, it is an considered an error
281            and the connect MUST be dropped.  (This could be a
282            down-negotiation attack.)  After the establishment of the
283            security context, both client and server MUST confirm that
284            GSS_C_MUTUAL_FLAG, GSS_C_CONF_FLAG, and GSS_C_INTEG_FLAG are
285            set in the resulting security context and MUST immediately
286            close the connection if this is not the case.
287</li>
288<li>After the security context has been established, the client
289            and server exchange commands and responses as described below.
290            All commands are sent with flags TOKEN_DATA and TOKEN_PROTOCOL
291            (0x44) and the data payload of all packets is protected with
292            gss_wrap.  The conf_req_flag parameter of gss_wrap MUST be set
293            to non-zero, requesting both confidentiality and integrity
294            services.
295</li>
296</ol><p>
297       
298</p>
299<a name="messages"></a><br /><hr />
300<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
301<a name="rfc.section.2.2"></a><h3>2.2.&nbsp;
302Message Format</h3>
303
304<p>All client and server messages will use the following format
305        inside the data payload.  This is the format of the message before
306        passing it to gss_wrap for confidentiality and integrity
307        protection.
308</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>
309    1 octet     protocol version
310    1 octet     message type
311    &lt;command-specific data&gt;
312</pre></div>
313<p>The protocol version for the version 2 protocol is 2.  (Note
314        that the version 1 protocol does not use this message format, and
315        therefore a protocol version of 1 is invalid.)  See below for
316        protocol version negotiation.
317</p>
318<p>The message type is one of the following
319          constants:
320</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>
321    1   MESSAGE_COMMAND
322    2   MESSAGE_QUIT
323    3   MESSAGE_OUTPUT
324    4   MESSAGE_STATUS
325    5   MESSAGE_ERROR
326    6   MESSAGE_VERSION
327</pre></div>
328<p>The first two message types are client messages and MUST NOT be
329        sent by the server.  The remaining message types are server messages
330        and MUST NOT by sent by the client.
331</p>
332<a name="negotiation"></a><br /><hr />
333<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
334<a name="rfc.section.2.3"></a><h3>2.3.&nbsp;
335Protocol Version Negotiation</h3>
336
337<p>If the server ever receives a message from a client that claims a
338        protocol version higher than the server supports, the server MUST
339        otherwise ignore the contents of the message and SHOULD respond with
340        a message type of MESSAGE_VERSION and the following message
341        payload:
342</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>
343    1 octet     highest supported version
344</pre></div>
345<p>The client MUST then either send only messages supported at
346        that protocol version or lower or send MESSAGE_QUIT and close the
347        connection.
348</p>
349<a name="command"></a><br /><hr />
350<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
351<a name="rfc.section.2.4"></a><h3>2.4.&nbsp;
352MESSAGE_COMMAND</h3>
353
354<p>Most client messages will be of type MESSAGE_COMMAND, which has
355        the following format:
356</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>
357    1 octet     keep-alive flag
358    1 octet     continue status
359    4 octets    number of arguments
360    4 octets    argument length
361    &lt;length&gt;    argument
362    ...
363</pre></div>
364<p>If the keep-alive flag is 0, the server SHOULD close the
365        connection after processing the command.  If it is 1, the server
366        SHOULD leave the connection open (up to a timeout period) and wait
367        for more commands.  This is similar to HTTP keep-alive.
368</p>
369<p>If the continue status is 1, it indicates that there is more
370        data coming.  The server should accept the data sent, buffer or
371        process it, and wait for more data before responding.  If the the
372        continue status is 2, it indicates that this message is logically
373        a part of the previous message (which MUST have had a continue
374        status of 1 or 2) and still has more data coming.  If the continue
375        status is 3, it says that this message is logically part of the
376        previous message, like 2, but it also says that this is the end of
377        the command.
378</p>
379<p>A continuation of a message starts with the keep-alive flag and
380        continue status and then the next chunk of data.  To reconstruct a
381        continued message, remove the first two octets from each chunk and
382        concatenate the pieces together.  The result is the portion of a
383        MESSAGE_COMMAND starting with the number of arguments.  Messages
384        may be broken into multiple MESSAGE_COMMANDs even in the middle of
385        the number of arguments or an argument length.  In other words,
386        the first three octets of the number of arguments could be in the
387        first MESSAGE_COMMAND (with continue status 1) and the last octet
388        would then be in the next MESSAGE_COMMAND (with continue status 2
389        or 3).
390</p>
391<p>Number of arguments is a four-octet number in network byte
392        order that gives the total number of command arguments.  For each
393        argument, there is then a length and argument data pair, where the
394        length is a four-octet number in network byte order indicating the
395        number of octets of data in the following argument.  Argument
396        length may be 0.  Commands with no arguments are permitted by the
397        protocol.
398</p>
399<p>Servers may impose limits on the number of arguments and the
400        size of argument data to limit resource usage.  If the client
401        message exceeds one of those limits, the server MUST respond with
402        MESSAGE_ERROR with an error code of ERROR_TOOMANY_ARGS or
403        ERROR_TOOMUCH_DATA as appropriate.
404</p>
405<a name="output"></a><br /><hr />
406<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
407<a name="rfc.section.2.5"></a><h3>2.5.&nbsp;
408MESSAGE_OUTPUT and MESSAGE_STATUS</h3>
409
410<p>The server response to MESSAGE_COMMAND is zero or more
411        MESSAGE_OUTPUT messages followed by either a MESSAGE_STATUS or a
412        MESSAGE_ERROR response.  Each MESSAGE_OUTPUT message has the
413        following format:
414</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>
415    1 octet     output stream
416    4 octets    output length
417    &lt;length&gt;    output
418</pre></div>
419<p>The output stream is either 1 for standard output or 2 for
420        standard error.  Output length is a four-octet number in network
421        byte order that specifies the length of the following output
422        data.
423</p>
424<p>The MESSAGE_STATUS message has the following format:
425</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>
426    1 octet     exit status
427</pre></div>
428<p>MESSAGE_STATUS indicates the command has finished and returns
429        the final exit stauts of the command.  Exit status is 0 for
430        success and non-zero for failure, where the meaning of non-zero
431        exit statuses is left to the application to define.  (This is
432        identical to a Unix command exit status.)
433</p>
434<p>Unless the MESSAGE_COMMAND message from the client had the
435        keep-alive flag set to 1, the server MUST close the network
436        connection immediately after sending the MESSAGE_STATUS response
437        message.
438</p>
439<a name="error"></a><br /><hr />
440<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
441<a name="rfc.section.2.6"></a><h3>2.6.&nbsp;
442MESSAGE_ERROR</h3>
443
444<p>At any point before sending MESSAGE_STATUS, the server may
445        respond with MESSAGE_ERROR if some error occurred.  This can be
446        the first response after a MESSAGE_COMMAND, or it may be sent
447        after one or more MESSAGE_OUTPUT messages.  The format of
448        MESSAGE_ERROR is as follows:
449</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>
450    4 octets    error code
451    4 octets    message length
452    &lt;length&gt;    error message
453</pre></div>
454<p>The error code is a four-octet number in network byte order
455        indicating the type of error.  The error code may be one of the
456        following values:
457</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>
458    1  ERROR_INTERNAL           Internal server failure
459    2  ERROR_BAD_TOKEN          Invalid format in token
460    3  ERROR_UNKNOWN_MESSAGE    Unknown message type
461    4  ERROR_BAD_COMMAND        Invalid command format in token
462    5  ERROR_UNKNOWN_COMMAND    Unknown command
463    6  ERROR_ACCESS             Access denied
464    7  ERROR_TOOMANY_ARGS       Argument count exceeds server limit
465    8  ERROR_TOOMUCH_DATA       Argument size exceeds server limit
466</pre></div>
467<p>Additional error codes may be added without changing the
468        version of the remctl protocol, so clients MUST accept error codes
469        other than the ones above.
470</p>
471<p>The message length is a four-octet number in network byte order
472        that specifies the length in octets of the following error
473        message.  The error message is a free-form informational message
474        intended for human consumption and MUST NOT be interpreted by an
475        automated process.  Software should instead use the error
476        code.
477</p>
478<p>Unless the MESSAGE_COMMAND message from the client had the
479        keep-alive flag set to 1, the server MUST close the network
480        connection immediately after sending the MESSAGE_ERROR response
481        message.  Otherwise, the server SHOULD still honor that flag,
482        although the server MAY terminate the connection after an
483        unreasonable number of errors.
484</p>
485<a name="quit"></a><br /><hr />
486<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
487<a name="rfc.section.2.7"></a><h3>2.7.&nbsp;
488MESSAGE_QUIT</h3>
489
490<p>MESSAGE_QUIT is a way of terminating the connection cleanly if
491        the client asked for keep-alive and then decided not to use it.
492        There is no message body.  Upon receiving this message, the server
493        MUST immediately close the connection.
494</p>
495<a name="proto1"></a><br /><hr />
496<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
497<a name="rfc.section.3"></a><h3>3.&nbsp;
498Network Protocol (version 1)</h3>
499
500<p>The old network protocol supported only 64KB of data payload,
501      only a single command and response, and had some additional
502      unnecessary protocol components.  It SHOULD NOT be used by clients,
503      but MAY be supported by servers for backward compatibility.  It is
504      recognized by the server and client by the lack of TOKEN_PROTOCOL in
505      the flags of the initial security context negotiation.
506</p>
507<p>The old protocol always uses the following steps:
508        </p>
509<ol class="text">
510<li>Client opens TCP connection to server.
511</li>
512<li>Client sends message with flags TOKEN_NOOP and
513          TOKEN_CONTEXT_NEXT and an empty payload.
514</li>
515<li>Client calls gss_init_sec_context and sends message with the
516          results and flags TOKEN_CONTEXT.  The client MUST pass
517          GSS_C_MUTUAL_FLAG, GSS_C_CONF_FLAG, and GSS_C_INTEG_FLAG as
518          requested flags and SHOULD pass GSS_C_REPLAY_FLAG and
519          GSS_C_SEQUENCE_FLAG, although the version one protocol does not
520          check the results of this negotiation.
521</li>
522<li>Server replies with the results of gss_accept_sec_context and
523          flags TOKEN_CONTEXT.
524</li>
525<li>Client calls gss_init_sec_context again with the data from
526          the server and replies with the results and flags TOKEN_CONTEXT,
527          using the same requested flags as described above.
528</li>
529<li>Server and client repeat, passing in the payload from the
530          last packet from the other side, for as long as GSS-API
531          indicates that continuation is required.  Each of these packets
532          have only TOKEN_CONTEXT set in the flags.
533</li>
534<li>Client sends command with flags TOKEN_DATA and TOKEN_SEND_MIC
535          and the following payload format:  four-octet number of
536          arguments, and then for each argument, a four-octet length and
537          then the argument value.  All numbers are in network type order.
538          The payload MUST be protected with gss_wrap and the
539          conf_req_flag parameter of gss_wrap MUST be set to non-zero,
540          requesting both confidentiality and integrity services.
541</li>
542<li>Server accepts and decrypts data, generates a MIC with
543          gss_get_mic, and sends the MIC back to the client with flags
544          TOKEN_MIC.  This is the only packet that isn't encrypted with
545          gss_wrap.  Client receives and then SHOULD verify this MIC.
546</li>
547<li>Server runs the command, collects the output, and sends the
548          output back with flags TOKEN_DATA and the following payload
549          format:  four-octet exit status, four-octet data length, data.
550          All numbers are in network byte order.  The exit status is 0 if
551          there were no errors and non-zero otherwise, where the meaning
552          of non-zero values are defined by the application.  The payload
553          MUST be protected with gss_wrap with a conf_req_flag set to
554          non-zero.
555</li>
556<li>Server and client close connection.
557</li>
558</ol><p>
559     
560</p>
561<a name="security"></a><br /><hr />
562<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
563<a name="rfc.section.4"></a><h3>4.&nbsp;
564Security Considerations</h3>
565
566<p>It would be preferrable to insist on replay and sequence
567      protection (GSS_C_REPLAY_FLAG and GSS_C_SEQUENCE_FLAG) for all
568      contexts, but some older Kerberos GSS-API implementations don't
569      support this and hence it is not mandatory in the protocol.  Clients
570      SHOULD always request replay and sequence protection, however, and
571      servers MAY require such protection be negotiated.
572</p>
573<p>The old protocol doesn't provide integrity protection for the
574      flags, but since it always follows the same fixed sequence of
575      operations, this should pose no security concerns in practice.  The
576      new protocol only uses the flag field outside of the encrypted
577      section of the packet for initial negotiation and closes the
578      connection if the flags aren't what was expected (avoiding a
579      down-negotiation attack).
580</p>
581<p>In the old protocol, the server calculated and sent a MIC back to
582      the client, which then verified that the command as received by the
583      server was correct.  Not only does GSS-API already provide integrity
584      protection, but this verification also happens after the server has
585      already started running the command.  It has been dropped in the new
586      protocol.
587</p>
588<p>The old protocol doesn't require the client and server check the
589      results of the GSS-API flag negotiation, although all old protocol
590      clients passed GSS_C_MUTUAL_FLAG.  However, the old protocol
591      requires gss_wrap be used for all payload with conf_req_flag set to
592      non-zero, so any context that didn't negotiate confidentiality and
593      integrity services would fail later.
594</p>
595<a name="credits"></a><br /><hr />
596<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
597<a name="rfc.section.A"></a><h3>Appendix A.&nbsp;
598Acknowledgements</h3>
599
600<p>The original remctl protocol design was done by Anton Ushakov,
601      with input from Russ Allbery and Roland Schemers.  Thank you to
602      David Hoffman and Mike Newton for their review of the version 2
603      remctl protocol.
604</p>
605<a name="rfc.authors"></a><br /><hr />
606<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
607<h3>Author's Address</h3>
608<table width="99%" border="0" cellpadding="0" cellspacing="0">
609<tr><td class="author-text">&nbsp;</td>
610<td class="author-text">Russ Allbery</td></tr>
611<tr><td class="author-text">&nbsp;</td>
612<td class="author-text">Stanford University</td></tr>
613<tr><td class="author-text">&nbsp;</td>
614<td class="author-text">255 Panama Street, MC 4136</td></tr>
615<tr><td class="author-text">&nbsp;</td>
616<td class="author-text">Stanford, CA  94305-4136</td></tr>
617<tr><td class="author-text">&nbsp;</td>
618<td class="author-text">US</td></tr>
619<tr><td class="author" align="right">Email:&nbsp;</td>
620<td class="author-text"><a href="mailto:rra@stanford.edu">rra@stanford.edu</a></td></tr>
621<tr><td class="author" align="right">URI:&nbsp;</td>
622<td class="author-text"><a href="http://www.eyrie.org/~eagle/">http://www.eyrie.org/~eagle/</a></td></tr>
623</table>
624</body></html>
Note: See TracBrowser for help on using the repository browser.