File: protocol.html

package info (click to toggle)
remctl 3.18-5
links: PTS, VCS
area: main
in suites: forky, sid
size: 5,612 kB
sloc: ansic: 19,504; sh: 5,386; perl: 1,778; java: 740; makefile: 715; xml: 502; python: 430
file content (1844 lines) | stat: -rw-r--r-- 66,281 bytes
parent folder | download | duplicates (3)
<!DOCTYPE html>
<html lang="en" class="Internet-Draft">
<head>
<meta charset="utf-8">
<meta content="Common,Latin" name="scripts">
<meta content="initial-scale=1.0" name="viewport">
<title>remctl: Remote Authenticated Command Service</title>
<meta content="Russ Allbery" name="author">
<meta content="
       This document specifies the remctl wire protocol, used to send
      commands and arguments to a remote system and receive the results of
      executing that command.  The protocol uses GSS-API and Kerberos v5
      for authentication, confidentiality, and integrity protection.  Both
      the current (version 3) protocol and the older version 1 protocol
      are described.  The version 1 protocol should only be implemented
      for backward compatibility. 
    " name="description">
<meta content="xml2rfc 3.12.4" name="generator">
<meta content="draft-allbery-remctl-00" name="ietf.draft">
<!-- Generator version information:
  xml2rfc 3.12.4
    Python 3.10.4
-->
<link href="protocol.xml" rel="alternate" type="application/rfc+xml">
<link href="#copyright" rel="license">
<style type="text/css">/*

  NOTE: Changes at the bottom of this file overrides some earlier settings.

  Once the style has stabilized and has been adopted as an official RFC style,
  this can be consolidated so that style settings occur only in one place, but
  for now the contents of this file consists first of the initial CSS work as
  provided to the RFC Formatter (xml2rfc) work, followed by itemized and
  commented changes found necssary during the development of the v3
  formatters.

*/

/* fonts */
@import url('https://fonts.googleapis.com/css?family=Noto+Sans'); /* Sans-serif */
@import url('https://fonts.googleapis.com/css?family=Noto+Serif'); /* Serif (print) */
@import url('https://fonts.googleapis.com/css?family=Roboto+Mono'); /* Monospace */

@viewport {
  zoom: 1.0;
  width: extend-to-zoom;
}
@-ms-viewport {
  width: extend-to-zoom;
  zoom: 1.0;
}
/* general and mobile first */
html {
}
body {
  max-width: 90%;
  margin: 1.5em auto;
  color: #222;
  background-color: #fff;
  font-size: 14px;
  font-family: 'Noto Sans', Arial, Helvetica, sans-serif;
  line-height: 1.6;
  scroll-behavior: smooth;
}
.ears {
  display: none;
}

/* headings */
#title, h1, h2, h3, h4, h5, h6 {
  margin: 1em 0 0.5em;
  font-weight: bold;
  line-height: 1.3;
}
#title {
  clear: both;
  border-bottom: 1px solid #ddd;
  margin: 0 0 0.5em 0;
  padding: 1em 0 0.5em;
}
.author {
  padding-bottom: 4px;
}
h1 {
  font-size: 26px;
  margin: 1em 0;
}
h2 {
  font-size: 22px;
  margin-top: -20px;  /* provide offset for in-page anchors */
  padding-top: 33px;
}
h3 {
  font-size: 18px;
  margin-top: -36px;  /* provide offset for in-page anchors */
  padding-top: 42px;
}
h4 {
  font-size: 16px;
  margin-top: -36px;  /* provide offset for in-page anchors */
  padding-top: 42px;
}
h5, h6 {
  font-size: 14px;
}
#n-copyright-notice {
  border-bottom: 1px solid #ddd;
  padding-bottom: 1em;
  margin-bottom: 1em;
}
/* general structure */
p {
  padding: 0;
  margin: 0 0 1em 0;
  text-align: left;
}
div, span {
  position: relative;
}
div {
  margin: 0;
}
.alignRight.art-text {
  background-color: #f9f9f9;
  border: 1px solid #eee;
  border-radius: 3px;
  padding: 1em 1em 0;
  margin-bottom: 1.5em;
}
.alignRight.art-text pre {
  padding: 0;
}
.alignRight {
  margin: 1em 0;
}
.alignRight > *:first-child {
  border: none;
  margin: 0;
  float: right;
  clear: both;
}
.alignRight > *:nth-child(2) {
  clear: both;
  display: block;
  border: none;
}
svg {
  display: block;
}
.alignCenter.art-text {
  background-color: #f9f9f9;
  border: 1px solid #eee;
  border-radius: 3px;
  padding: 1em 1em 0;
  margin-bottom: 1.5em;
}
.alignCenter.art-text pre {
  padding: 0;
}
.alignCenter {
  margin: 1em 0;
}
.alignCenter > *:first-child {
  border: none;
  /* this isn't optimal, but it's an existence proof.  PrinceXML doesn't
     support flexbox yet.
  */
  display: table;
  margin: 0 auto;
}

/* lists */
ol, ul {
  padding: 0;
  margin: 0 0 1em 2em;
}
ol ol, ul ul, ol ul, ul ol {
  margin-left: 1em;
}
li {
  margin: 0 0 0.25em 0;
}
.ulCompact li {
  margin: 0;
}
ul.empty, .ulEmpty {
  list-style-type: none;
}
ul.empty li, .ulEmpty li {
  margin-top: 0.5em;
}
ul.ulBare, li.ulBare {
  margin-left: 0em !important;
}
ul.compact, .ulCompact,
ol.compact, .olCompact {
  line-height: 100%;
  margin: 0 0 0 2em;
}

/* definition lists */
dl {
}
dl > dt {
  float: left;
  margin-right: 1em;
}
/* 
dl.nohang > dt {
  float: none;
}
*/
dl > dd {
  margin-bottom: .8em;
  min-height: 1.3em;
}
dl.compact > dd, .dlCompact > dd {
  margin-bottom: 0em;
}
dl > dd > dl {
  margin-top: 0.5em;
  margin-bottom: 0em;
}

/* links */
a {
  text-decoration: none;
}
a[href] {
  color: #22e; /* Arlen: WCAG 2019 */
}
a[href]:hover {
  background-color: #f2f2f2;
}
figcaption a[href],
a[href].selfRef {
  color: #222;
}
/* XXX probably not this:
a.selfRef:hover {
  background-color: transparent;
  cursor: default;
} */

/* Figures */
tt, code, pre, code {
  background-color: #f9f9f9;
  font-family: 'Roboto Mono', monospace;
}
pre {
  border: 1px solid #eee;
  margin: 0;
  padding: 1em;
}
img {
  max-width: 100%;
}
figure {
  margin: 0;
}
figure blockquote {
  margin: 0.8em 0.4em 0.4em;
}
figcaption {
  font-style: italic;
  margin: 0 0 1em 0;
}
@media screen {
  pre {
    overflow-x: auto;
    max-width: 100%;
    max-width: calc(100% - 22px);
  }
}

/* aside, blockquote */
aside, blockquote {
  margin-left: 0;
  padding: 1.2em 2em;
}
blockquote {
  background-color: #f9f9f9;
  color: #111; /* Arlen: WCAG 2019 */
  border: 1px solid #ddd;
  border-radius: 3px;
  margin: 1em 0;
}
cite {
  display: block;
  text-align: right;
  font-style: italic;
}

/* tables */
table {
  width: 100%;
  margin: 0 0 1em;
  border-collapse: collapse;
  border: 1px solid #eee;
}
th, td {
  text-align: left;
  vertical-align: top;
  padding: 0.5em 0.75em;
}
th {
  text-align: left;
  background-color: #e9e9e9;
}
tr:nth-child(2n+1) > td {
  background-color: #f5f5f5;
}
table caption {
  font-style: italic;
  margin: 0;
  padding: 0;
  text-align: left;
}
table p {
  /* XXX to avoid bottom margin on table row signifiers. If paragraphs should
     be allowed within tables more generally, it would be far better to select on a class. */
  margin: 0;
}

/* pilcrow */
a.pilcrow {
  color: #666; /* Arlen: AHDJ 2019 */
  text-decoration: none;
  visibility: hidden;
  user-select: none;
  -ms-user-select: none;
  -o-user-select:none;
  -moz-user-select: none;
  -khtml-user-select: none;
  -webkit-user-select: none;
  -webkit-touch-callout: none;
}
@media screen {
  aside:hover > a.pilcrow,
  p:hover > a.pilcrow,
  blockquote:hover > a.pilcrow,
  div:hover > a.pilcrow,
  li:hover > a.pilcrow,
  pre:hover > a.pilcrow {
    visibility: visible;
  }
  a.pilcrow:hover {
    background-color: transparent;
  }
}

/* misc */
hr {
  border: 0;
  border-top: 1px solid #eee;
}
.bcp14 {
  font-variant: small-caps;
}

.role {
  font-variant: all-small-caps;
}

/* info block */
#identifiers {
  margin: 0;
  font-size: 0.9em;
}
#identifiers dt {
  width: 3em;
  clear: left;
}
#identifiers dd {
  float: left;
  margin-bottom: 0;
}
/* Fix PDF info block run off issue */
@media print {
  #identifiers dd {
    float: none;
  }
}
#identifiers .authors .author {
  display: inline-block;
  margin-right: 1.5em;
}
#identifiers .authors .org {
  font-style: italic;
}

/* The prepared/rendered info at the very bottom of the page */
.docInfo {
  color: #666; /* Arlen: WCAG 2019 */
  font-size: 0.9em;
  font-style: italic;
  margin-top: 2em;
}
.docInfo .prepared {
  float: left;
}
.docInfo .prepared {
  float: right;
}

/* table of contents */
#toc  {
  padding: 0.75em 0 2em 0;
  margin-bottom: 1em;
}
nav.toc ul {
  margin: 0 0.5em 0 0;
  padding: 0;
  list-style: none;
}
nav.toc li {
  line-height: 1.3em;
  margin: 0.75em 0;
  padding-left: 1.2em;
  text-indent: -1.2em;
}
/* references */
.references dt {
  text-align: right;
  font-weight: bold;
  min-width: 7em;
}
.references dd {
  margin-left: 8em;
  overflow: auto;
}

.refInstance {
  margin-bottom: 1.25em;
}

.references .ascii {
  margin-bottom: 0.25em;
}

/* index */
.index ul {
  margin: 0 0 0 1em;
  padding: 0;
  list-style: none;
}
.index ul ul {
  margin: 0;
}
.index li {
  margin: 0;
  text-indent: -2em;
  padding-left: 2em;
  padding-bottom: 5px;
}
.indexIndex {
  margin: 0.5em 0 1em;
}
.index a {
  font-weight: 700;
}
/* make the index two-column on all but the smallest screens */
@media (min-width: 600px) {
  .index ul {
    -moz-column-count: 2;
    -moz-column-gap: 20px;
  }
  .index ul ul {
    -moz-column-count: 1;
    -moz-column-gap: 0;
  }
}

/* authors */
address.vcard {
  font-style: normal;
  margin: 1em 0;
}

address.vcard .nameRole {
  font-weight: 700;
  margin-left: 0;
}
address.vcard .label {
  font-family: "Noto Sans",Arial,Helvetica,sans-serif;
  margin: 0.5em 0;
}
address.vcard .type {
  display: none;
}
.alternative-contact {
  margin: 1.5em 0 1em;
}
hr.addr {
  border-top: 1px dashed;
  margin: 0;
  color: #ddd;
  max-width: calc(100% - 16px);
}

/* temporary notes */
.rfcEditorRemove::before {
  position: absolute;
  top: 0.2em;
  right: 0.2em;
  padding: 0.2em;
  content: "The RFC Editor will remove this note";
  color: #9e2a00; /* Arlen: WCAG 2019 */
  background-color: #ffd; /* Arlen: WCAG 2019 */
}
.rfcEditorRemove {
  position: relative;
  padding-top: 1.8em;
  background-color: #ffd; /* Arlen: WCAG 2019 */
  border-radius: 3px;
}
.cref {
  background-color: #ffd; /* Arlen: WCAG 2019 */
  padding: 2px 4px;
}
.crefSource {
  font-style: italic;
}
/* alternative layout for smaller screens */
@media screen and (max-width: 1023px) {
  body {
    padding-top: 2em;
  }
  #title {
    padding: 1em 0;
  }
  h1 {
    font-size: 24px;
  }
  h2 {
    font-size: 20px;
    margin-top: -18px;  /* provide offset for in-page anchors */
    padding-top: 38px;
  }
  #identifiers dd {
    max-width: 60%;
  }
  #toc {
    position: fixed;
    z-index: 2;
    top: 0;
    right: 0;
    padding: 0;
    margin: 0;
    background-color: inherit;
    border-bottom: 1px solid #ccc;
  }
  #toc h2 {
    margin: -1px 0 0 0;
    padding: 4px 0 4px 6px;
    padding-right: 1em;
    min-width: 190px;
    font-size: 1.1em;
    text-align: right;
    background-color: #444;
    color: white;
    cursor: pointer;
  }
  #toc h2::before { /* css hamburger */
    float: right;
    position: relative;
    width: 1em;
    height: 1px;
    left: -164px;
    margin: 6px 0 0 0;
    background: white none repeat scroll 0 0;
    box-shadow: 0 4px 0 0 white, 0 8px 0 0 white;
    content: "";
  }
  #toc nav {
    display: none;
    padding: 0.5em 1em 1em;
    overflow: auto;
    height: calc(100vh - 48px);
    border-left: 1px solid #ddd;
  }
}

/* alternative layout for wide screens */
@media screen and (min-width: 1024px) {
  body {
    max-width: 724px;
    margin: 42px auto;
    padding-left: 1.5em;
    padding-right: 29em;
  }
  #toc {
    position: fixed;
    top: 42px;
    right: 42px;
    width: 25%;
    margin: 0;
    padding: 0 1em;
    z-index: 1;
  }
  #toc h2 {
    border-top: none;
    border-bottom: 1px solid #ddd;
    font-size: 1em;
    font-weight: normal;
    margin: 0;
    padding: 0.25em 1em 1em 0;
  }
  #toc nav {
    display: block;
    height: calc(90vh - 84px);
    bottom: 0;
    padding: 0.5em 0 0;
    overflow: auto;
  }
  img { /* future proofing */
    max-width: 100%;
    height: auto;
  }
}

/* pagination */
@media print {
  body {

    width: 100%;
  }
  p {
    orphans: 3;
    widows: 3;
  }
  #n-copyright-notice {
    border-bottom: none;
  }
  #toc, #n-introduction {
    page-break-before: always;
  }
  #toc {
    border-top: none;
    padding-top: 0;
  }
  figure, pre {
    page-break-inside: avoid;
  }
  figure {
    overflow: scroll;
  }
  h1, h2, h3, h4, h5, h6 {
    page-break-after: avoid;
  }
  h2+*, h3+*, h4+*, h5+*, h6+* {
    page-break-before: avoid;
  }
  pre {
    white-space: pre-wrap;
    word-wrap: break-word;
    font-size: 10pt;
  }
  table {
    border: 1px solid #ddd;
  }
  td {
    border-top: 1px solid #ddd;
  }
}

/* This is commented out here, as the string-set: doesn't
   pass W3C validation currently */
/*
.ears thead .left {
  string-set: ears-top-left content();
}

.ears thead .center {
  string-set: ears-top-center content();
}

.ears thead .right {
  string-set: ears-top-right content();
}

.ears tfoot .left {
  string-set: ears-bottom-left content();
}

.ears tfoot .center {
  string-set: ears-bottom-center content();
}

.ears tfoot .right {
  string-set: ears-bottom-right content();
}
*/

@page :first {
  padding-top: 0;
  @top-left {
    content: normal;
    border: none;
  }
  @top-center {
    content: normal;
    border: none;
  }
  @top-right {
    content: normal;
    border: none;
  }
}

@page {
  size: A4;
  margin-bottom: 45mm;
  padding-top: 20px;
  /* The follwing is commented out here, but set appropriately by in code, as
     the content depends on the document */
  /*
  @top-left {
    content: 'Internet-Draft';
    vertical-align: bottom;
    border-bottom: solid 1px #ccc;
  }
  @top-left {
    content: string(ears-top-left);
    vertical-align: bottom;
    border-bottom: solid 1px #ccc;
  }
  @top-center {
    content: string(ears-top-center);
    vertical-align: bottom;
    border-bottom: solid 1px #ccc;
  }
  @top-right {
    content: string(ears-top-right);
    vertical-align: bottom;
    border-bottom: solid 1px #ccc;
  }
  @bottom-left {
    content: string(ears-bottom-left);
    vertical-align: top;
    border-top: solid 1px #ccc;
  }
  @bottom-center {
    content: string(ears-bottom-center);
    vertical-align: top;
    border-top: solid 1px #ccc;
  }
  @bottom-right {
      content: '[Page ' counter(page) ']';
      vertical-align: top;
      border-top: solid 1px #ccc;
  }
  */

}

/* Changes introduced to fix issues found during implementation */
/* Make sure links are clickable even if overlapped by following H* */
a {
  z-index: 2;
}
/* Separate body from document info even without intervening H1 */
section {
  clear: both;
}


/* Top align author divs, to avoid names without organization dropping level with org names */
.author {
  vertical-align: top;
}

/* Leave room in document info to show Internet-Draft on one line */
#identifiers dt {
  width: 8em;
}

/* Don't waste quite as much whitespace between label and value in doc info */
#identifiers dd {
  margin-left: 1em;
}

/* Give floating toc a background color (needed when it's a div inside section */
#toc {
  background-color: white;
}

/* Make the collapsed ToC header render white on gray also when it's a link */
@media screen and (max-width: 1023px) {
  #toc h2 a,
  #toc h2 a:link,
  #toc h2 a:focus,
  #toc h2 a:hover,
  #toc a.toplink,
  #toc a.toplink:hover {
    color: white;
    background-color: #444;
    text-decoration: none;
  }
}

/* Give the bottom of the ToC some whitespace */
@media screen and (min-width: 1024px) {
  #toc {
    padding: 0 0 1em 1em;
  }
}

/* Style section numbers with more space between number and title */
.section-number {
  padding-right: 0.5em;
}

/* prevent monospace from becoming overly large */
tt, code, pre, code {
  font-size: 95%;
}

/* Fix the height/width aspect for ascii art*/
pre.sourcecode,
.art-text pre {
  line-height: 1.12;
}


/* Add styling for a link in the ToC that points to the top of the document */
a.toplink {
  float: right;
  margin-right: 0.5em;
}

/* Fix the dl styling to match the RFC 7992 attributes */
dl > dt,
dl.dlParallel > dt {
  float: left;
  margin-right: 1em;
}
dl.dlNewline > dt {
  float: none;
}

/* Provide styling for table cell text alignment */
table td.text-left,
table th.text-left {
  text-align: left;
}
table td.text-center,
table th.text-center {
  text-align: center;
}
table td.text-right,
table th.text-right {
  text-align: right;
}

/* Make the alternative author contact informatio look less like just another
   author, and group it closer with the primary author contact information */
.alternative-contact {
  margin: 0.5em 0 0.25em 0;
}
address .non-ascii {
  margin: 0 0 0 2em;
}

/* With it being possible to set tables with alignment
  left, center, and right, { width: 100%; } does not make sense */
table {
  width: auto;
}

/* Avoid reference text that sits in a block with very wide left margin,
   because of a long floating dt label.*/
.references dd {
  overflow: visible;
}

/* Control caption placement */
caption {
  caption-side: bottom;
}

/* Limit the width of the author address vcard, so names in right-to-left
   script don't end up on the other side of the page. */

address.vcard {
  max-width: 30em;
  margin-right: auto;
}

/* For address alignment dependent on LTR or RTL scripts */
address div.left {
  text-align: left;
}
address div.right {
  text-align: right;
}

/* Provide table alignment support.  We can't use the alignX classes above
   since they do unwanted things with caption and other styling. */
table.right {
 margin-left: auto;
 margin-right: 0;
}
table.center {
 margin-left: auto;
 margin-right: auto;
}
table.left {
 margin-left: 0;
 margin-right: auto;
}

/* Give the table caption label the same styling as the figcaption */
caption a[href] {
  color: #222;
}

@media print {
  .toplink {
    display: none;
  }

  /* avoid overwriting the top border line with the ToC header */
  #toc {
    padding-top: 1px;
  }

  /* Avoid page breaks inside dl and author address entries */
  .vcard {
    page-break-inside: avoid;
  }

}
/* Tweak the bcp14 keyword presentation */
.bcp14 {
  font-variant: small-caps;
  font-weight: bold;
  font-size: 0.9em;
}
/* Tweak the invisible space above H* in order not to overlay links in text above */
 h2 {
  margin-top: -18px;  /* provide offset for in-page anchors */
  padding-top: 31px;
 }
 h3 {
  margin-top: -18px;  /* provide offset for in-page anchors */
  padding-top: 24px;
 }
 h4 {
  margin-top: -18px;  /* provide offset for in-page anchors */
  padding-top: 24px;
 }
/* Float artwork pilcrow to the right */
@media screen {
  .artwork a.pilcrow {
    display: block;
    line-height: 0.7;
    margin-top: 0.15em;
  }
}
/* Make pilcrows on dd visible */
@media screen {
  dd:hover > a.pilcrow {
    visibility: visible;
  }
}
/* Make the placement of figcaption match that of a table's caption
   by removing the figure's added bottom margin */
.alignLeft.art-text,
.alignCenter.art-text,
.alignRight.art-text {
   margin-bottom: 0;
}
.alignLeft,
.alignCenter,
.alignRight {
  margin: 1em 0 0 0;
}
/* In print, the pilcrow won't show on hover, so prevent it from taking up space,
   possibly even requiring a new line */
@media print {
  a.pilcrow {
    display: none;
  }
}
/* Styling for the external metadata */
div#external-metadata {
  background-color: #eee;
  padding: 0.5em;
  margin-bottom: 0.5em;
  display: none;
}
div#internal-metadata {
  padding: 0.5em;                       /* to match the external-metadata padding */
}
/* Styling for title RFC Number */
h1#rfcnum {
  clear: both;
  margin: 0 0 -1em;
  padding: 1em 0 0 0;
}
/* Make .olPercent look the same as <ol><li> */
dl.olPercent > dd {
  margin-bottom: 0.25em;
  min-height: initial;
}
/* Give aside some styling to set it apart */
aside {
  border-left: 1px solid #ddd;
  margin: 1em 0 1em 2em;
  padding: 0.2em 2em;
}
aside > dl,
aside > ol,
aside > ul,
aside > table,
aside > p {
  margin-bottom: 0.5em;
}
/* Additional page break settings */
@media print {
  figcaption, table caption {
    page-break-before: avoid;
  }
}
/* Font size adjustments for print */
@media print {
  body  { font-size: 10pt;      line-height: normal; max-width: 96%; }
  h1    { font-size: 1.72em;    padding-top: 1.5em; } /* 1*1.2*1.2*1.2 */
  h2    { font-size: 1.44em;    padding-top: 1.5em; } /* 1*1.2*1.2 */
  h3    { font-size: 1.2em;     padding-top: 1.5em; } /* 1*1.2 */
  h4    { font-size: 1em;       padding-top: 1.5em; }
  h5, h6 { font-size: 1em;      margin: initial; padding: 0.5em 0 0.3em; }
}
/* Sourcecode margin in print, when there's no pilcrow */
@media print {
  .artwork,
  .sourcecode {
    margin-bottom: 1em;
  }
}
/* Avoid narrow tables forcing too narrow table captions, which may render badly */
table {
  min-width: 20em;
}
/* ol type a */
ol.type-a { list-style-type: lower-alpha; }
ol.type-A { list-style-type: upper-alpha; }
ol.type-i { list-style-type: lower-roman; }
ol.type-I { list-style-type: lower-roman; }
/* Apply the print table and row borders in general, on request from the RPC,
and increase the contrast between border and odd row background sligthtly */
table {
  border: 1px solid #ddd;
}
td {
  border-top: 1px solid #ddd;
}
tr:nth-child(2n+1) > td {
  background-color: #f8f8f8;
}
/* Use style rules to govern display of the TOC. */
@media screen and (max-width: 1023px) {
  #toc nav { display: none; }
  #toc.active nav { display: block; }
}
/* Add support for keepWithNext */
.keepWithNext {
  break-after: avoid-page;
  break-after: avoid-page;
}
/* Add support for keepWithPrevious */
.keepWithPrevious {
  break-before: avoid-page;
}
/* Change the approach to avoiding breaks inside artwork etc. */
figure, pre, table, .artwork, .sourcecode  {
  break-before: auto;
  break-after: auto;
}
/* Avoid breaks between <dt> and <dd> */
dl {
  break-before: auto;
  break-inside: auto;
}
dt {
  break-before: auto;
  break-after: avoid-page;
}
dd {
  break-before: avoid-page;
  break-after: auto;
  orphans: 3;
  widows: 3
}
span.break, dd.break {
  margin-bottom: 0;
  min-height: 0;
  break-before: auto;
  break-inside: auto;
  break-after: auto;
}
/* Undo break-before ToC */
@media print {
  #toc {
    break-before: auto;
  }
}
/* Text in compact lists should not get extra bottim margin space,
   since that would makes the list not compact */
ul.compact p, .ulCompact p,
ol.compact p, .olCompact p {
 margin: 0;
}
/* But the list as a whole needs the extra space at the end */
section ul.compact,
section .ulCompact,
section ol.compact,
section .olCompact {
  margin-bottom: 1em;                    /* same as p not within ul.compact etc. */
}
/* The tt and code background above interferes with for instance table cell
   backgrounds.  Changed to something a bit more selective. */
tt, code {
  background-color: transparent;
}
p tt, p code, li tt, li code {
  background-color: #f8f8f8;
}
/* Tweak the pre margin -- 0px doesn't come out well */
pre {
   margin-top: 0.5px;
}
/* Tweak the comact list text */
ul.compact, .ulCompact,
ol.compact, .olCompact,
dl.compact, .dlCompact {
  line-height: normal;
}
/* Don't add top margin for nested lists */
li > ul, li > ol, li > dl,
dd > ul, dd > ol, dd > dl,
dl > dd > dl {
  margin-top: initial;
}
/* Elements that should not be rendered on the same line as a <dt> */
/* This should match the element list in writer.text.TextWriter.render_dl() */
dd > div.artwork:first-child,
dd > aside:first-child,
dd > figure:first-child,
dd > ol:first-child,
dd > div:first-child > pre.sourcecode,
dd > table:first-child,
dd > ul:first-child {
  clear: left;
}
/* fix for weird browser behaviour when <dd/> is empty */
dt+dd:empty::before{
  content: "\00a0";
}
/* Make paragraph spacing inside <li> smaller than in body text, to fit better within the list */
li > p {
  margin-bottom: 0.5em
}
/* Don't let p margin spill out from inside list items */
li > p:last-of-type {
  margin-bottom: 0;
}
</style>
<link href="rfc-local.css" rel="stylesheet" type="text/css">
<script type="application/javascript">async function addMetadata(){try{const e=document.styleSheets[0].cssRules;for(let t=0;t<e.length;t++)if(/#identifiers/.exec(e[t].selectorText)){const a=e[t].cssText.replace("#identifiers","#external-updates");document.styleSheets[0].insertRule(a,document.styleSheets[0].cssRules.length)}}catch(e){console.log(e)}const e=document.getElementById("external-metadata");if(e)try{var t,a="",o=function(e){const t=document.getElementsByTagName("meta");for(let a=0;a<t.length;a++)if(t[a].getAttribute("name")===e)return t[a].getAttribute("content");return""}("rfc.number");if(o){t="https://www.rfc-editor.org/rfc/rfc"+o+".json";try{const e=await fetch(t);a=await e.json()}catch(e){t=document.URL.indexOf("html")>=0?document.URL.replace(/html$/,"json"):document.URL+".json";const o=await fetch(t);a=await o.json()}}if(!a)return;e.style.display="block";const s="",d="https://datatracker.ietf.org/doc",n="https://datatracker.ietf.org/ipr/search",c="https://www.rfc-editor.org/info",l=a.doc_id.toLowerCase(),i=a.doc_id.slice(0,3).toLowerCase(),f=a.doc_id.slice(3).replace(/^0+/,""),u={status:"Status",obsoletes:"Obsoletes",obsoleted_by:"Obsoleted By",updates:"Updates",updated_by:"Updated By",see_also:"See Also",errata_url:"Errata"};let h="<dl style='overflow:hidden' id='external-updates'>";["status","obsoletes","obsoleted_by","updates","updated_by","see_also","errata_url"].forEach(e=>{if("status"==e){a[e]=a[e].toLowerCase();var t=a[e].split(" "),o=t.length,w="",p=1;for(let e=0;e<o;e++)p<o?w=w+r(t[e])+" ":w+=r(t[e]),p++;a[e]=w}else if("obsoletes"==e||"obsoleted_by"==e||"updates"==e||"updated_by"==e){var g,m="",b=1;g=a[e].length;for(let t=0;t<g;t++)a[e][t]&&(a[e][t]=String(a[e][t]).toLowerCase(),m=b<g?m+"<a href='"+s+"/rfc/".concat(a[e][t])+"'>"+a[e][t].slice(3)+"</a>, ":m+"<a href='"+s+"/rfc/".concat(a[e][t])+"'>"+a[e][t].slice(3)+"</a>",b++);a[e]=m}else if("see_also"==e){var y,L="",C=1;y=a[e].length;for(let t=0;t<y;t++)if(a[e][t]){a[e][t]=String(a[e][t]);var _=a[e][t].slice(0,3),v=a[e][t].slice(3).replace(/^0+/,"");L=C<y?"RFC"!=_?L+"<a href='"+s+"/info/"+_.toLowerCase().concat(v.toLowerCase())+"'>"+_+" "+v+"</a>, ":L+"<a href='"+s+"/info/"+_.toLowerCase().concat(v.toLowerCase())+"'>"+v+"</a>, ":"RFC"!=_?L+"<a href='"+s+"/info/"+_.toLowerCase().concat(v.toLowerCase())+"'>"+_+" "+v+"</a>":L+"<a href='"+s+"/info/"+_.toLowerCase().concat(v.toLowerCase())+"'>"+v+"</a>",C++}a[e]=L}else if("errata_url"==e){var R="";R=a[e]?R+"<a href='"+a[e]+"'>Errata exist</a> | <a href='"+d+"/"+l+"'>Datatracker</a>| <a href='"+n+"/?"+i+"="+f+"&submit="+i+"'>IPR</a> | <a href='"+c+"/"+l+"'>Info page</a>":"<a href='"+d+"/"+l+"'>Datatracker</a> | <a href='"+n+"/?"+i+"="+f+"&submit="+i+"'>IPR</a> | <a href='"+c+"/"+l+"'>Info page</a>",a[e]=R}""!=a[e]?"Errata"==u[e]?h+=`<dt>More info:</dt><dd>${a[e]}</dd>`:h+=`<dt>${u[e]}:</dt><dd>${a[e]}</dd>`:"Errata"==u[e]&&(h+=`<dt>More info:</dt><dd>${a[e]}</dd>`)}),h+="</dl>",e.innerHTML=h}catch(e){console.log(e)}else console.log("Could not locate metadata <div> element");function r(e){return e.charAt(0).toUpperCase()+e.slice(1)}}window.removeEventListener("load",addMetadata),window.addEventListener("load",addMetadata);</script>
</head>
<body>
<script src="metadata.min.js"></script>
<table class="ears">
<thead><tr>
<td class="left">Internet-Draft</td>
<td class="center">remctl</td>
<td class="right">January 2014</td>
</tr></thead>
<tfoot><tr>
<td class="left">Allbery</td>
<td class="center">Expires 4 August 2014</td>
<td class="right">[Page]</td>
</tr></tfoot>
</table>
<div id="external-metadata" class="document-information"></div>
<div id="internal-metadata" class="document-information">
<dl id="identifiers">
<dt class="label-workgroup">Workgroup:</dt>
<dd class="workgroup">Network Working Group</dd>
<dt class="label-internet-draft">Internet-Draft:</dt>
<dd class="internet-draft">draft-allbery-remctl-00</dd>
<dt class="label-published">Published:</dt>
<dd class="published">
<time datetime="2014-01" class="published">January 2014</time>
    </dd>
<dt class="label-intended-status">Intended Status:</dt>
<dd class="intended-status">Informational</dd>
<dt class="label-expires">Expires:</dt>
<dd class="expires"><time datetime="2014-08-04">4 August 2014</time></dd>
<dt class="label-authors">Author:</dt>
<dd class="authors">
<div class="author">
      <div class="author-name">R. Allbery</div>
<div class="org">AURA</div>
</div>
</dd>
</dl>
</div>
<h1 id="title">remctl: Remote Authenticated Command Service</h1>
<section id="section-abstract">
      <h2 id="abstract"><a href="#abstract" class="selfRef">Abstract</a></h2>
<p id="section-abstract-1">This document specifies the remctl wire protocol, used to send
      commands and arguments to a remote system and receive the results of
      executing that command.  The protocol uses GSS-API and Kerberos v5
      for authentication, confidentiality, and integrity protection.  Both
      the current (version 3) protocol and the older version 1 protocol
      are described.  The version 1 protocol should only be implemented
      for backward compatibility.<a href="#section-abstract-1" class="pilcrow">¶</a></p>
</section>
<div id="status-of-memo">
<section id="section-boilerplate.1">
        <h2 id="name-status-of-this-memo-2">
<a href="#name-status-of-this-memo-2" class="section-name selfRef">Status of This Memo</a>
        </h2>
<p id="section-boilerplate.1-1">
        This Internet-Draft is submitted in full conformance with the
        provisions of BCP 78 and BCP 79.<a href="#section-boilerplate.1-1" class="pilcrow">¶</a></p>
<p id="section-boilerplate.1-2">
        Internet-Drafts are working documents of the Internet Engineering Task
        Force (IETF). Note that other groups may also distribute working
        documents as Internet-Drafts. The list of current Internet-Drafts is
        at <span><a href="http://datatracker.ietf.org/drafts/current/">http://datatracker.ietf.org/drafts/current/</a></span>.<a href="#section-boilerplate.1-2" class="pilcrow">¶</a></p>
<p id="section-boilerplate.1-3">
        Internet-Drafts are draft documents valid for a maximum of six months
        and may be updated, replaced, or obsoleted by other documents at any
        time. It is inappropriate to use Internet-Drafts as reference
        material or to cite them other than as "work in progress."<a href="#section-boilerplate.1-3" class="pilcrow">¶</a></p>
<p id="section-boilerplate.1-4">
        This Internet-Draft will expire on 5 July 2014.<a href="#section-boilerplate.1-4" class="pilcrow">¶</a></p>
</section>
</div>
<div id="copyright">
<section id="section-boilerplate.2">
        <h2 id="name-copyright-notice-2">
<a href="#name-copyright-notice-2" class="section-name selfRef">Copyright Notice</a>
        </h2>
<p id="section-boilerplate.2-1">
            Copyright (c) 2014 IETF Trust and the persons identified as the
            document authors. All rights reserved.<a href="#section-boilerplate.2-1" class="pilcrow">¶</a></p>
<p id="section-boilerplate.2-2">
            This document is subject to BCP 78 and the IETF Trust's Legal
            Provisions Relating to IETF Documents
            (<span><a href="http://trustee.ietf.org/license-info">http://trustee.ietf.org/license-info</a></span>) in effect on the date of
            publication of this document. Please review these documents
            carefully, as they describe your rights and restrictions with
            respect to this document.<a href="#section-boilerplate.2-2" class="pilcrow">¶</a></p>
</section>
</div>
<div id="toc">
<section id="section-toc.1">
        <a href="#" onclick="scroll(0,0)" class="toplink">▲</a><h2 id="name-table-of-contents-2">
<a href="#name-table-of-contents-2" class="section-name selfRef">Table of Contents</a>
        </h2>
<nav class="toc"><ul class="compact toc ulBare ulEmpty">
<li class="compact toc ulBare ulEmpty" id="section-toc.1-1.1">
            <p id="section-toc.1-1.1.1" class="keepWithNext"><a href="#section-1" class="xref">1</a>.  <a href="#name-basic-packet-format-2" class="xref">Basic Packet Format</a></p>
</li>
          <li class="compact toc ulBare ulEmpty" id="section-toc.1-1.2">
            <p id="section-toc.1-1.2.1"><a href="#section-2" class="xref">2</a>.  <a href="#name-network-protocol-version-3-2" class="xref">Network Protocol (version 3)</a></p>
<ul class="compact toc ulBare ulEmpty">
<li class="compact toc ulBare ulEmpty" id="section-toc.1-1.2.2.1">
                <p id="section-toc.1-1.2.2.1.1" class="keepWithNext"><a href="#section-2.1" class="xref">2.1</a>.  <a href="#name-session-sequence-2" class="xref">Session Sequence</a></p>
</li>
              <li class="compact toc ulBare ulEmpty" id="section-toc.1-1.2.2.2">
                <p id="section-toc.1-1.2.2.2.1" class="keepWithNext"><a href="#section-2.2" class="xref">2.2</a>.  <a href="#name-message-format-2" class="xref">Message Format</a></p>
</li>
              <li class="compact toc ulBare ulEmpty" id="section-toc.1-1.2.2.3">
                <p id="section-toc.1-1.2.2.3.1"><a href="#section-2.3" class="xref">2.3</a>.  <a href="#name-protocol-version-negotiation" class="xref">Protocol Version Negotiation</a></p>
</li>
              <li class="compact toc ulBare ulEmpty" id="section-toc.1-1.2.2.4">
                <p id="section-toc.1-1.2.2.4.1"><a href="#section-2.4" class="xref">2.4</a>.  <a href="#name-message_command-2" class="xref">MESSAGE_COMMAND</a></p>
</li>
              <li class="compact toc ulBare ulEmpty" id="section-toc.1-1.2.2.5">
                <p id="section-toc.1-1.2.2.5.1"><a href="#section-2.5" class="xref">2.5</a>.  <a href="#name-message_output-and-message_s" class="xref">MESSAGE_OUTPUT and MESSAGE_STATUS</a></p>
</li>
              <li class="compact toc ulBare ulEmpty" id="section-toc.1-1.2.2.6">
                <p id="section-toc.1-1.2.2.6.1"><a href="#section-2.6" class="xref">2.6</a>.  <a href="#name-message_error-2" class="xref">MESSAGE_ERROR</a></p>
</li>
              <li class="compact toc ulBare ulEmpty" id="section-toc.1-1.2.2.7">
                <p id="section-toc.1-1.2.2.7.1"><a href="#section-2.7" class="xref">2.7</a>.  <a href="#name-message_quit-2" class="xref">MESSAGE_QUIT</a></p>
</li>
              <li class="compact toc ulBare ulEmpty" id="section-toc.1-1.2.2.8">
                <p id="section-toc.1-1.2.2.8.1"><a href="#section-2.8" class="xref">2.8</a>.  <a href="#name-message_noop-2" class="xref">MESSAGE_NOOP</a></p>
</li>
            </ul>
</li>
          <li class="compact toc ulBare ulEmpty" id="section-toc.1-1.3">
            <p id="section-toc.1-1.3.1"><a href="#section-3" class="xref">3</a>.  <a href="#name-network-protocol-version-1-2" class="xref">Network Protocol (version 1)</a></p>
</li>
          <li class="compact toc ulBare ulEmpty" id="section-toc.1-1.4">
            <p id="section-toc.1-1.4.1"><a href="#section-4" class="xref">4</a>.  <a href="#name-security-considerations-2" class="xref">Security Considerations</a></p>
</li>
          <li class="compact toc ulBare ulEmpty" id="section-toc.1-1.5">
            <p id="section-toc.1-1.5.1"><a href="#appendix-A" class="xref">Appendix A</a>.  <a href="#name-acknowledgements-2" class="xref">Acknowledgements</a></p>
</li>
          <li class="compact toc ulBare ulEmpty" id="section-toc.1-1.6">
            <p id="section-toc.1-1.6.1"><a href="#appendix-B" class="xref">Appendix B</a>.  <a href="#name-additional-license-2" class="xref">Additional License</a></p>
</li>
          <li class="compact toc ulBare ulEmpty" id="section-toc.1-1.7">
            <p id="section-toc.1-1.7.1"><a href="#appendix-C" class="xref"></a><a href="#name-authors-address-2" class="xref">Author's Address</a></p>
</li>
        </ul>
</nav>
</section>
</div>
<div id="format">
<section id="section-1">
      <h2 id="name-basic-packet-format-2">
<a href="#section-1" class="section-number selfRef">1. </a><a href="#name-basic-packet-format-2" class="section-name selfRef">Basic Packet Format</a>
      </h2>
<p id="section-1-1">The remctl network protocol consists of data packets sent from a
      client to a server or a server to a client over a TCP connection.
      The remctl protocol may be used over any port, but the
      IANA-registered port and the RECOMMENDED default for the protocol is
      4373.  Each data packet has the following format:<a href="#section-1-1" class="pilcrow">¶</a></p>
<div class="alignLeft art-text artwork" id="section-1-2">
<pre>
    1 octet     flags
    4 octets    length
    &lt;length&gt;    data payload
</pre><a href="#section-1-2" class="pilcrow">¶</a>
</div>
<p id="section-1-3">The total size of each token, including the five octet prefix,
      MUST NOT be larger than 1,048,576 octets (1MB).<a href="#section-1-3" class="pilcrow">¶</a></p>
<p id="section-1-4" class="keepWithNext">The flag octet contains one or more of the following
        values, combined with binary xor:<a href="#section-1-4" class="pilcrow">¶</a></p>
<div class="alignLeft art-text artwork" id="section-1-5">
<pre>
    0x01        TOKEN_NOOP
    0x02        TOKEN_CONTEXT
    0x04        TOKEN_DATA
    0x08        TOKEN_MIC
    0x10        TOKEN_CONTEXT_NEXT
    0x20        TOKEN_SEND_MIC
    0x40        TOKEN_PROTOCOL
</pre><a href="#section-1-5" class="pilcrow">¶</a>
</div>
<p id="section-1-6" class="keepWithPrevious">Only TOKEN_CONTEXT, TOKEN_CONTEXT_NEXT, TOKEN_DATA, and
        TOKEN_PROTOCOL are used for packets for versions 2 and 3 of the
        protocol.  The other flags are used only with the legacy version 1
        protocol.<a href="#section-1-6" class="pilcrow">¶</a></p>
<p id="section-1-7">The length field is a four-octet length in network byte order,
      specifying the number of octets in the following data payload.<a href="#section-1-7" class="pilcrow">¶</a></p>
<p id="section-1-8">The data payload is empty, the results of gss_accept_sec_context,
      the results of gss_init_sec_context, or a data payload protected
      with gss_wrap.  The length of the data passed to gss_wrap MUST NOT
      be larger than 65,536 octets (64KB), even if the underlying Kerberos
      implementation supports longer input buffers.<a href="#section-1-8" class="pilcrow">¶</a></p>
</section>
</div>
<div id="proto3">
<section id="section-2">
      <h2 id="name-network-protocol-version-3-2">
<a href="#section-2" class="section-number selfRef">2. </a><a href="#name-network-protocol-version-3-2" class="section-name selfRef">Network Protocol (version 3)</a>
      </h2>
<div id="packet">
<section id="section-2.1">
        <h3 id="name-session-sequence-2">
<a href="#section-2.1" class="section-number selfRef">2.1. </a><a href="#name-session-sequence-2" class="section-name selfRef">Session Sequence</a>
        </h3>
<p id="section-2.1-1">A remctl connection is always initiated by a client opening a
        TCP connection to a server.  The protocol then proceeds as
        follows:<a href="#section-2.1-1" class="pilcrow">¶</a></p>
<ol start="1" type="1" class="normal type-1" id="section-2.1-2">
<li id="section-2.1-2.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.<a href="#section-2.1-2.1" class="pilcrow">¶</a>
</li>
          <li id="section-2.1-2.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.<a href="#section-2.1-2.2" class="pilcrow">¶</a>
</li>
          <li id="section-2.1-2.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.<a href="#section-2.1-2.3" class="pilcrow">¶</a>
</li>
          <li id="section-2.1-2.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.<a href="#section-2.1-2.4" class="pilcrow">¶</a>
</li>
          <li id="section-2.1-2.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.<a href="#section-2.1-2.5" class="pilcrow">¶</a>
</li>
          <li id="section-2.1-2.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.<a href="#section-2.1-2.6" class="pilcrow">¶</a>
</li>
        </ol>
</section>
</div>
<div id="messages">
<section id="section-2.2">
        <h3 id="name-message-format-2">
<a href="#section-2.2" class="section-number selfRef">2.2. </a><a href="#name-message-format-2" class="section-name selfRef">Message Format</a>
        </h3>
<p id="section-2.2-1">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.<a href="#section-2.2-1" class="pilcrow">¶</a></p>
<div class="alignLeft art-text artwork" id="section-2.2-2">
<pre>
    1 octet     protocol version
    1 octet     message type
    &lt;command-specific data&gt;
</pre><a href="#section-2.2-2" class="pilcrow">¶</a>
</div>
<p id="section-2.2-3">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.<a href="#section-2.2-3" class="pilcrow">¶</a></p>
<p id="section-2.2-4" class="keepWithNext">The message type is one of the following
          constants:<a href="#section-2.2-4" class="pilcrow">¶</a></p>
<div class="alignLeft art-text artwork" id="section-2.2-5">
<pre>
    1   MESSAGE_COMMAND
    2   MESSAGE_QUIT
    3   MESSAGE_OUTPUT
    4   MESSAGE_STATUS
    5   MESSAGE_ERROR
    6   MESSAGE_VERSION
    7   MESSAGE_NOOP
</pre><a href="#section-2.2-5" class="pilcrow">¶</a>
</div>
<p id="section-2.2-6">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.<a href="#section-2.2-6" class="pilcrow">¶</a></p>
<p id="section-2.2-7">All of these message types were introduced in protocol version
        2 except for MESSAGE_NOOP, which is a protocol version 3
        message.<a href="#section-2.2-7" class="pilcrow">¶</a></p>
</section>
</div>
<div id="negotiation">
<section id="section-2.3">
        <h3 id="name-protocol-version-negotiation">
<a href="#section-2.3" class="section-number selfRef">2.3. </a><a href="#name-protocol-version-negotiation" class="section-name selfRef">Protocol Version Negotiation</a>
        </h3>
<p id="section-2.3-1">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:<a href="#section-2.3-1" class="pilcrow">¶</a></p>
<div class="alignLeft art-text artwork" id="section-2.3-2">
<pre>
    1 octet     highest supported version
</pre><a href="#section-2.3-2" class="pilcrow">¶</a>
</div>
<p id="section-2.3-3">The client MUST then either send only messages supported at
        that protocol version or lower or send MESSAGE_QUIT and close the
        connection.<a href="#section-2.3-3" class="pilcrow">¶</a></p>
<p id="section-2.3-4">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.<a href="#section-2.3-4" class="pilcrow">¶</a></p>
</section>
</div>
<div id="command">
<section id="section-2.4">
        <h3 id="name-message_command-2">
<a href="#section-2.4" class="section-number selfRef">2.4. </a><a href="#name-message_command-2" class="section-name selfRef">MESSAGE_COMMAND</a>
        </h3>
<p id="section-2.4-1">Most client messages will be of type MESSAGE_COMMAND, which has
        the following format:<a href="#section-2.4-1" class="pilcrow">¶</a></p>
<div class="alignLeft art-text artwork" id="section-2.4-2">
<pre>
    1 octet     keep-alive flag
    1 octet     continue status
    4 octets    number of arguments
    4 octets    argument length
    &lt;length&gt;    argument
    ...
</pre><a href="#section-2.4-2" class="pilcrow">¶</a>
</div>
<p id="section-2.4-3">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.<a href="#section-2.4-3" class="pilcrow">¶</a></p>
<p id="section-2.4-4">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 href="#section-2.4-4" class="pilcrow">¶</a></p>
<p id="section-2.4-5">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.<a href="#section-2.4-5" class="pilcrow">¶</a></p>
<p id="section-2.4-6">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.<a href="#section-2.4-6" class="pilcrow">¶</a></p>
<p id="section-2.4-7">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.<a href="#section-2.4-7" class="pilcrow">¶</a></p>
<p id="section-2.4-8">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.<a href="#section-2.4-8" class="pilcrow">¶</a></p>
<p id="section-2.4-9">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.<a href="#section-2.4-9" class="pilcrow">¶</a></p>
<p id="section-2.4-10">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.<a href="#section-2.4-10" class="pilcrow">¶</a></p>
</section>
</div>
<div id="output">
<section id="section-2.5">
        <h3 id="name-message_output-and-message_s">
<a href="#section-2.5" class="section-number selfRef">2.5. </a><a href="#name-message_output-and-message_s" class="section-name selfRef">MESSAGE_OUTPUT and MESSAGE_STATUS</a>
        </h3>
<p id="section-2.5-1">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:<a href="#section-2.5-1" class="pilcrow">¶</a></p>
<div class="alignLeft art-text artwork" id="section-2.5-2">
<pre>
    1 octet     output stream
    4 octets    output length
    &lt;length&gt;    output
</pre><a href="#section-2.5-2" class="pilcrow">¶</a>
</div>
<p id="section-2.5-3">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.<a href="#section-2.5-3" class="pilcrow">¶</a></p>
<p id="section-2.5-4">The MESSAGE_STATUS message has the following format:<a href="#section-2.5-4" class="pilcrow">¶</a></p>
<div class="alignLeft art-text artwork" id="section-2.5-5">
<pre>
    1 octet     exit status
</pre><a href="#section-2.5-5" class="pilcrow">¶</a>
</div>
<p id="section-2.5-6">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.)<a href="#section-2.5-6" class="pilcrow">¶</a></p>
<p id="section-2.5-7">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.<a href="#section-2.5-7" class="pilcrow">¶</a></p>
</section>
</div>
<div id="error">
<section id="section-2.6">
        <h3 id="name-message_error-2">
<a href="#section-2.6" class="section-number selfRef">2.6. </a><a href="#name-message_error-2" class="section-name selfRef">MESSAGE_ERROR</a>
        </h3>
<p id="section-2.6-1">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:<a href="#section-2.6-1" class="pilcrow">¶</a></p>
<div class="alignLeft art-text artwork" id="section-2.6-2">
<pre>
    4 octets    error code
    4 octets    message length
    &lt;length&gt;    error message
</pre><a href="#section-2.6-2" class="pilcrow">¶</a>
</div>
<p id="section-2.6-3">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:<a href="#section-2.6-3" class="pilcrow">¶</a></p>
<div class="alignLeft art-text artwork" id="section-2.6-4">
<pre>
    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
</pre><a href="#section-2.6-4" class="pilcrow">¶</a>
</div>
<p id="section-2.6-5">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.<a href="#section-2.6-5" class="pilcrow">¶</a></p>
<p id="section-2.6-6">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.<a href="#section-2.6-6" class="pilcrow">¶</a></p>
<p id="section-2.6-7">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.<a href="#section-2.6-7" class="pilcrow">¶</a></p>
</section>
</div>
<div id="quit">
<section id="section-2.7">
        <h3 id="name-message_quit-2">
<a href="#section-2.7" class="section-number selfRef">2.7. </a><a href="#name-message_quit-2" class="section-name selfRef">MESSAGE_QUIT</a>
        </h3>
<p id="section-2.7-1">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.<a href="#section-2.7-1" class="pilcrow">¶</a></p>
</section>
</div>
<div id="noop">
<section id="section-2.8">
        <h3 id="name-message_noop-2">
<a href="#section-2.8" class="section-number selfRef">2.8. </a><a href="#name-message_noop-2" class="section-name selfRef">MESSAGE_NOOP</a>
        </h3>
<p id="section-2.8-1">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.<a href="#section-2.8-1" class="pilcrow">¶</a></p>
<p id="section-2.8-2">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.<a href="#section-2.8-2" class="pilcrow">¶</a></p>
</section>
</div>
</section>
</div>
<div id="proto1">
<section id="section-3">
      <h2 id="name-network-protocol-version-1-2">
<a href="#section-3" class="section-number selfRef">3. </a><a href="#name-network-protocol-version-1-2" class="section-name selfRef">Network Protocol (version 1)</a>
      </h2>
<p id="section-3-1">The old network protocol supported only 64KB of data payload,
      only a single command and response, and had some additional
      unnecessary protocol components.  It SHOULD NOT be used by clients,
      but MAY be supported by servers for backward compatibility.  It is
      recognized by the server and client by the lack of TOKEN_PROTOCOL in
      the flags of the initial security context negotiation.<a href="#section-3-1" class="pilcrow">¶</a></p>
<p id="section-3-2">The old protocol always uses the following steps:<a href="#section-3-2" class="pilcrow">¶</a></p>
<ol start="1" type="1" class="normal type-1" id="section-3-3">
<li id="section-3-3.1">Client opens TCP connection to server.<a href="#section-3-3.1" class="pilcrow">¶</a>
</li>
        <li id="section-3-3.2">Client sends message with flags TOKEN_NOOP and
          TOKEN_CONTEXT_NEXT and an empty payload.<a href="#section-3-3.2" class="pilcrow">¶</a>
</li>
        <li id="section-3-3.3">Client calls gss_init_sec_context and sends message with the
          results and flags TOKEN_CONTEXT.  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, although the version one protocol does not
          check the results of this negotiation.<a href="#section-3-3.3" class="pilcrow">¶</a>
</li>
        <li id="section-3-3.4">Server replies with the results of gss_accept_sec_context and
          flags TOKEN_CONTEXT.<a href="#section-3-3.4" class="pilcrow">¶</a>
</li>
        <li id="section-3-3.5">Client calls gss_init_sec_context again with the data from
          the server and replies with the results and flags TOKEN_CONTEXT,
          using the same requested flags as described above.<a href="#section-3-3.5" class="pilcrow">¶</a>
</li>
        <li id="section-3-3.6">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.  Each of these packets
          have only TOKEN_CONTEXT set in the flags.<a href="#section-3-3.6" class="pilcrow">¶</a>
</li>
        <li id="section-3-3.7">Client sends command with flags TOKEN_DATA and TOKEN_SEND_MIC
          and the following payload format:  four-octet number of
          arguments, and then for each argument, a four-octet length and
          then the argument value.  All numbers are in network type order.
          The payload MUST be protected with gss_wrap and the
          conf_req_flag parameter of gss_wrap MUST be set to non-zero,
          requesting both confidentiality and integrity services.<a href="#section-3-3.7" class="pilcrow">¶</a>
</li>
        <li id="section-3-3.8">Server accepts and decrypts data, generates a MIC with
          gss_get_mic, and sends the MIC back to the client with flags
          TOKEN_MIC.  This is the only packet that isn't encrypted with
          gss_wrap.  Client receives and then SHOULD verify this MIC.<a href="#section-3-3.8" class="pilcrow">¶</a>
</li>
        <li id="section-3-3.9">Server runs the command, collects the output, and sends the
          output back with flags TOKEN_DATA and the following payload
          format:  four-octet exit status, four-octet data length, data.
          All numbers are in network byte order.  The exit status is 0 if
          there were no errors and non-zero otherwise, where the meaning
          of non-zero values are defined by the application.  The payload
          MUST be protected with gss_wrap with a conf_req_flag set to
          non-zero.<a href="#section-3-3.9" class="pilcrow">¶</a>
</li>
        <li id="section-3-3.10">Server and client close connection.<a href="#section-3-3.10" class="pilcrow">¶</a>
</li>
      </ol>
</section>
</div>
<div id="security">
<section id="section-4">
      <h2 id="name-security-considerations-2">
<a href="#section-4" class="section-number selfRef">4. </a><a href="#name-security-considerations-2" class="section-name selfRef">Security Considerations</a>
      </h2>
<p id="section-4-1">It would be preferrable to insist on replay and sequence
      protection (GSS_C_REPLAY_FLAG and GSS_C_SEQUENCE_FLAG) for all
      contexts, but some older Kerberos GSS-API implementations don't
      support this and hence it is not mandatory in the protocol.  Clients
      SHOULD always request replay and sequence protection, however, and
      servers MAY require such protection be negotiated.<a href="#section-4-1" class="pilcrow">¶</a></p>
<p id="section-4-2">The old protocol doesn't provide integrity protection for the
      flags, but since it always follows the same fixed sequence of
      operations, this should pose no security concerns in practice.  The
      new protocol only uses the flag field outside of the encrypted
      section of the packet for initial negotiation and closes the
      connection if the flags aren't what was expected (avoiding a
      down-negotiation attack).<a href="#section-4-2" class="pilcrow">¶</a></p>
<p id="section-4-3">In the old protocol, the server calculated and sent a MIC back to
      the client, which then verified that the command as received by the
      server was correct.  Not only does GSS-API already provide integrity
      protection, but this verification also happens after the server has
      already started running the command.  It has been dropped in the new
      protocol.<a href="#section-4-3" class="pilcrow">¶</a></p>
<p id="section-4-4">The old protocol doesn't require the client and server check the
      results of the GSS-API flag negotiation, although all old protocol
      clients passed GSS_C_MUTUAL_FLAG.  However, the old protocol
      requires gss_wrap be used for all payload with conf_req_flag set to
      non-zero, so any context that didn't negotiate confidentiality and
      integrity services would fail later.<a href="#section-4-4" class="pilcrow">¶</a></p>
</section>
</div>
<div id="credits">
<section id="appendix-A">
      <h2 id="name-acknowledgements-2">
<a href="#appendix-A" class="section-number selfRef">Appendix A. </a><a href="#name-acknowledgements-2" class="section-name selfRef">Acknowledgements</a>
      </h2>
<p id="appendix-A-1">The original remctl protocol design was done by Anton Ushakov,
      with input from Russ Allbery and Roland Schemers.  Thank you to
      David Hoffman and Mike Newton for their review of the version 2
      remctl protocol.<a href="#appendix-A-1" class="pilcrow">¶</a></p>
</section>
</div>
<div id="license">
<section id="appendix-B">
      <h2 id="name-additional-license-2">
<a href="#appendix-B" class="section-number selfRef">Appendix B. </a><a href="#name-additional-license-2" class="section-name selfRef">Additional License</a>
      </h2>
<p id="appendix-B-1">This section supplements the Copyright Notice section at the
      start of this document.  It states an additional copyright notice
      and grants a much less restrictive license than the default IETF
      Trust license.  You may copy and distribute this document, with or
      without modification, under your choice of the license specified in
      the Copyright Notice section or the license below.<a href="#appendix-B-1" class="pilcrow">¶</a></p>
<p id="appendix-B-2">Copyright 2006-2009, 2011, 2013-2014 The Board of Trustees of the
      Leland Stanford Junior University<a href="#appendix-B-2" class="pilcrow">¶</a></p>
<p id="appendix-B-3">Copying and distribution of this file, with or without
      modification, are permitted in any medium without royalty provided
      the copyright notice and this notice are preserved.  This file is
      offered as-is, without any warranty.<a href="#appendix-B-3" class="pilcrow">¶</a></p>
</section>
</div>
<div id="authors-addresses">
<section id="appendix-C">
      <h2 id="name-authors-address-2">
<a href="#name-authors-address-2" class="section-name selfRef">Author's Address</a>
      </h2>
<address class="vcard">
        <div dir="auto" class="left"><span class="fn nameRole">Russ Allbery</span></div>
<div dir="auto" class="left"><span class="org">AURA</span></div>
<div class="email">
<span>Email:</span>
<a href="mailto:eagle@eyrie.org" class="email">eagle@eyrie.org</a>
</div>
<div class="url">
<span>URI:</span>
<a href="https://www.eyrie.org/~eagle/" class="url">https://www.eyrie.org/~eagle/</a>
</div>
</address>
</section>
</div>
<script>const toc = document.getElementById("toc");
toc.querySelector("h2").addEventListener("click", e => {
  toc.classList.toggle("active");
});
toc.querySelector("nav").addEventListener("click", e => {
  toc.classList.remove("active");
});
</script>
</body>
</html>