source: web/old/remctl-2.14/docs/design.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: 7.4 KB
Line 
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
2<HTML><HEAD>
3<META http-equiv=Content-Type content="text/html; charset=windows-1252">
4<META content="MSHTML 6.00.2800.1106" name=GENERATOR></HEAD>
5<BODY>
6<H1>Old Remctl Design Document</H1>
7
8<P>This is the original design document for version 1.0 of remctl.  It
9is now fairly thoroughly obsolete and is included only for historical
10information and reference.</P>
11
12<H2>Design Document for Remctl</H2>
13
14<P>Anton Ushakov, November 2002.</P>
15
16<P>Conceptually remctl is an RPC service for remote execution of
17commands. However unlike many system-utility RPC services, is employs
18Kerberos authentication, fine-grained authorization, and command requests
19are mapped to predefined system executables that perform concrete services
20- the requested command is never executed directly by a shell. The a
21"type", and a "service" within that type are specified as part of the
22request and are mapped to an executable program on the server. Additional
23arguments are passed to that predefined command as parameters. Only one
24command is allowed per a transaction, with one response. </P>
25
26<P>Remctld is a deamon implemented in C and compilable on Linux, AIX and
27Solaris. The client-side program, remctl, is implemented in C and Java -
28for system independence. Authentication uses Kerberos V through the use of
29GSS-API, which is a language independent standard that's more general,
30easier to code and debug then direct Kerberos V API. Client's identity is
31taken from the Kerberos V ticket cache that should be availble in the
32client's environment. Server's identity is taken from the host principal
33of the machine that remctld is run on, using the default keytab file,
34unless an environemnt variable is set to point to a different one. The
35identity of the server can be changed to a principal other that the host
36principal using command like options, and the client also has command like
37options to specify a different server principal.</P>
38
39<P>The Client and Server sections below detail the communication
40protocol and packet formats. All communication packets are encrypted
41using </P>
42
43<H2>Client</H2>
44
45<H3>Authentication</H3>
46
47  <P>Client connects and authenticates using tokens from gssapi
48  calls. Format of all tokens is the same, including request and response
49  tokens.</P>
50
51<pre>
52    flags                 1 byte
53    length of data        4 bytes
54    data payload          &lt;length of data&gt;
55</pre>
56
57  <P>The authentication communication sequence is initiated by an empty
58  token sent by the Client. Thereafter the tokens are passed to and
59  received from gssapi calls and are sent over the network in the format
60  specified above. The authentication sequence continues until gssapi sets
61  a status variable signifying "authentication context established".
62
63  <P>Flags in the above token format are for signifying the stage in
64  communication, such as "establishing authentication context", "end of
65  tokens", "request token", "response token", or "error token".
66
67<H3>Request</H3>
68
69  <P>Client accepts these command line arguments: <BR>
70  <EM>type service arg1 .. argN</EM><BR>
71  Client gets the arguments in the standard argv format: array of strings.
72
73  <P>Client passes these arguments packed into a data payload section of a
74  token. Payload format is the argc following by pairs of a lendth of an
75  argument and the argument itself:</P>
76
77<pre>
78    number of arguments    4 bytes
79    length of argument     4 bytes                | This is part is repeated
80    argument               &lt;length of argument&gt;   | &lt;number of arguments&gt; times
81</pre>
82
83  <P>After the payload request token is sent, a MIC checksum token is
84  expected from the server. The payload data is of type "MIC" and is
85  passed directly to the gssapi for verification. It is a checksum
86  computed on the server after decrypting the request payload token. It is
87  not a proof of message authenticity or integrity, as that is inherent in
88  the Kerberos V mechanism, it is a confirmation of wire encryption used
89  for the transmission. Technically it is not necessary, but is used for
90  extra confirmation here.
91
92<H3>Response</H3>
93
94  <P>Client waits for a response which is expected in the same token
95  format. The flags for a response can be "response" and "error".
96
97  <P>The payload format in the response message is:</P>
98
99<pre>
100    return code                 4 bytes
101    length of return message    4 bytes
102    return message              &lt;length of return message&gt;
103</pre>
104
105  <P>After decrypting the response token, the MIC checksum token is sent
106  back to the Server, ending the transaction. </P>
107
108<H2>Server</H2>
109
110  <P>The server is written to work with <EM>tcpserver</EM> or
111  <EM>inetd</EM>, which provide simultanous connection handling.  As a
112  side-effect the conf file gets re-read on every request since a new
113  process of remctld is spawned on every connection.
114
115<H3>Authentication</H3>
116 
117  <P>The gssapi context establishment takes place the same way as
118  described the Client section above.</P>
119
120<H3>Authorization</H3>
121 
122  <P>Upon startup Server reads, parses and stores the conf file. Its
123  format per line is:
124
125  <P><I>type service command {aclfile}+</I></P>
126
127  <TABLE cellSpacing=0 cellPadding=5 background="" border=1 valign="top">
128    <TBODY>
129    <TR>
130      <TD vAlign=top background="">type</TD>
131      <TD>
132        <P>Specifies the "domain" of commands, like ss (service server -
133        the srvtab generation system) or cgi (for approval and creation of
134        cgi accounts).</P>
135      </TD>
136    </TR>
137    <TR>
138      <TD vAlign=top background="">service</TD>
139      <TD>
140        <P>A particular service within the type. If the entire type is
141        specified with one line, the keyword ALL can be used instead of a
142        service name.</P>
143      </TD>
144    </TR>
145    <TR>
146      <TD vAlign=top background="">command</TD>
147      <TD>Path and filename of a program to execute as part of the
148      request.</TD>
149    </TR>
150    <TR>
151      <TD vAlign=top background="">aclfile</TD>
152      <TD>
153        <P>A file containing a list of identities, one per line, of those
154        authorized to request this service. One or more aclfiles may be
155        provided. The keyword ANYUSER may be used to signify a service
156        that is not access restricted.</P>
157      </TD>
158    </TR>
159    </TBODY>
160  </TABLE>
161
162  <P>Both the conf file and aclfiles allow empty lines and comments that
163  start with a '#' character.
164
165<H3>Request</H3>
166
167  <P>Packet format is described in the Client section. A MIC checksum is
168  sent back to the Client after decrypting the request token.
169
170  <P>Once the request's <EM>type</EM> and <EM>service</EM> arguments are
171  mapped to an executable, and the authorization of the client is
172  established, remctld forks and does an execv call to run the executable
173  in question. Pipes are set up to collect STDOUT and STDERR as well as
174  the return code. This information is then packed up and sent back to the
175  client.
176
177<H3>Response</H3>
178
179  <P>Packet format is described in the Client section. The token flag
180  signifies a positive or erroneous response. A MIC checksum is expected
181  from the Client after the response token is decrypted by the
182  Client. This ends the transaction.</P>
183
184<H2>Shared Code</H2>
185
186  <P>A utility library is used by the C implementations of both Client and
187  Server. This provides the common functionality of sending a message with
188  payload and receiving one, as well as sending and receiving a raw token
189  (used in context establishment).</P>
190
191</BODY>
192</HTML>
Note: See TracBrowser for help on using the repository browser.