1 d93fca6a 2005-02-11 devnull .TH FACTOTUM 4
3 d93fca6a 2005-02-11 devnull factotum \- authentication agent
4 d93fca6a 2005-02-11 devnull .SH SYNOPSIS
5 d93fca6a 2005-02-11 devnull .B factotum
7 d93fca6a 2005-02-11 devnull .B -DdkSun
9 d93fca6a 2005-02-11 devnull .B -a authaddr
12 d93fca6a 2005-02-11 devnull .I srvname
15 d93fca6a 2005-02-11 devnull .\" .B -m
16 d93fca6a 2005-02-11 devnull .\" .I mtpt
19 d93fca6a 2005-02-11 devnull .B factotum
21 d93fca6a 2005-02-11 devnull .IB attribute = value
23 d93fca6a 2005-02-11 devnull .IB attribute ?
26 d93fca6a 2005-02-11 devnull .\" .B auth/fgui
27 d93fca6a 2005-02-11 devnull .SH DESCRIPTION
28 d93fca6a 2005-02-11 devnull .I Factotum
29 d93fca6a 2005-02-11 devnull is a user-level file system that
30 d93fca6a 2005-02-11 devnull acts as the authentication agent for a user.
31 d93fca6a 2005-02-11 devnull It does so by managing a set of
32 d93fca6a 2005-02-11 devnull .IR keys .
33 d93fca6a 2005-02-11 devnull A key is a collection of information used to authenticate a particular action.
34 d93fca6a 2005-02-11 devnull Stored as a list of
35 d93fca6a 2005-02-11 devnull .IB attribute = value
36 d93fca6a 2005-02-11 devnull pairs, a key typically contains a user, an authentication domain, a protocol, and
37 d93fca6a 2005-02-11 devnull some secret data.
39 d93fca6a 2005-02-11 devnull .I Factotum
40 d93fca6a 2005-02-11 devnull presents the following files:
41 d93fca6a 2005-02-11 devnull .TF needkey
44 d93fca6a 2005-02-11 devnull each open represents a new private channel to
45 d93fca6a 2005-02-11 devnull .I factotum
48 d93fca6a 2005-02-11 devnull when read lists the protocols available
50 d93fca6a 2005-02-11 devnull .B confirm
51 d93fca6a 2005-02-11 devnull for confiming the use of key
53 d93fca6a 2005-02-11 devnull .B needkey
54 d93fca6a 2005-02-11 devnull allows external programs to control the addition of new keys
57 d93fca6a 2005-02-11 devnull a log of actions
60 d93fca6a 2005-02-11 devnull for maintaining keys; when read, it returns a list of keys.
61 d93fca6a 2005-02-11 devnull For secret attributes, only the attribute name follow by a
63 d93fca6a 2005-02-11 devnull is returned.
66 d93fca6a 2005-02-11 devnull In any authentication, the caller typically acts as a client
67 d93fca6a 2005-02-11 devnull and the callee as a server. The server determines
68 d93fca6a 2005-02-11 devnull the authentication domain, sometimes after a negotiation with
69 d93fca6a 2005-02-11 devnull the client. Authentication always requires the client to
70 d93fca6a 2005-02-11 devnull prove its identity to the server. Under some protocols, the
71 d93fca6a 2005-02-11 devnull authentication is mutual.
72 d93fca6a 2005-02-11 devnull Proof is accomplished using secret information kept by factotum
73 d93fca6a 2005-02-11 devnull in conjunction with a cryptographic protocol.
75 d93fca6a 2005-02-11 devnull .I Factotum
76 d93fca6a 2005-02-11 devnull can act in the role of client for any process possessing the
77 d93fca6a 2005-02-11 devnull same user id as it. For select protocols such as
79 d93fca6a 2005-02-11 devnull it can also act as a client for other processes provided
80 d93fca6a 2005-02-11 devnull its user id may speak for the other process' user id (see
82 d93fca6a 2005-02-11 devnull \fIauthsrv\fR(6)).
83 d93fca6a 2005-02-11 devnull .I Factotum
84 d93fca6a 2005-02-11 devnull can act in the role of server for any process.
86 d93fca6a 2005-02-11 devnull .IR Factotum 's
87 d93fca6a 2005-02-11 devnull structure is independent of
88 d93fca6a 2005-02-11 devnull any particular authentication protocol.
89 d93fca6a 2005-02-11 devnull .I Factotum
90 d93fca6a 2005-02-11 devnull supports the following protocols:
91 d93fca6a 2005-02-11 devnull .TF mschap
94 d93fca6a 2005-02-11 devnull a metaprotocol used to negotiate which actual protocol to use.
97 d93fca6a 2005-02-11 devnull a Plan 9 shared key protocol.
100 d93fca6a 2005-02-11 devnull a variant of
101 d93fca6a 2005-02-11 devnull .B p9sk1.
104 d93fca6a 2005-02-11 devnull a Plan 9 protocol that can use either
105 d93fca6a 2005-02-11 devnull .B p9sk1
106 d93fca6a 2005-02-11 devnull keys or SecureID tokens.
109 d93fca6a 2005-02-11 devnull the challenge/response protocol used by POP3 mail servers.
112 d93fca6a 2005-02-11 devnull the challenge/response protocol also used by POP3 mail servers.
115 d93fca6a 2005-02-11 devnull the challenge/response protocols used by PPP and PPTP.
117 d93fca6a 2005-02-11 devnull .B mschap
118 d93fca6a 2005-02-11 devnull a proprietary Microsoft protocol also used by PPP and PPTP.
121 d93fca6a 2005-02-11 devnull RSA public key decryption, used by SSH and TLS.
124 d93fca6a 2005-02-11 devnull passwords in the clear.
127 d93fca6a 2005-02-11 devnull .IR vnc (1)'s
128 d93fca6a 2005-02-11 devnull challenge/response.
131 d93fca6a 2005-02-11 devnull WEP passwords for wireless ethernet cards.
134 d93fca6a 2005-02-11 devnull The options are:
137 d93fca6a 2005-02-11 devnull supplies the address of the authentication server to use.
138 d93fca6a 2005-02-11 devnull Without this option, it will attempt to find an authentication server by
139 d93fca6a 2005-02-11 devnull querying the connection server, the file
140 d93fca6a 2005-02-11 devnull .BR <mtpt>/ndb ,
141 d93fca6a 2005-02-11 devnull and finally the network database in
142 d93fca6a 2005-02-11 devnull .BR /lib/ndb .
145 d93fca6a 2005-02-11 devnull specifies the mount point to use, by default
146 d93fca6a 2005-02-11 devnull .BR /mnt .
149 d93fca6a 2005-02-11 devnull specifies the service name to use.
150 d93fca6a 2005-02-11 devnull Without this option,
151 d93fca6a 2005-02-11 devnull .I factotum
152 d93fca6a 2005-02-11 devnull does not create a service file in
153 d93fca6a 2005-02-11 devnull .BR /srv .
156 d93fca6a 2005-02-11 devnull turns on 9P tracing, written to standard error.
159 d93fca6a 2005-02-11 devnull turns on debugging, written to standard error.
162 d93fca6a 2005-02-11 devnull causes the agent to prompt for the key, write it
165 d93fca6a 2005-02-11 devnull file, and exit.
166 d93fca6a 2005-02-11 devnull The agent will prompt for values for any of the
167 d93fca6a 2005-02-11 devnull attributes ending with a question mark
168 d93fca6a 2005-02-11 devnull .RB ( ? )
169 d93fca6a 2005-02-11 devnull and will append all the supplied
170 d93fca6a 2005-02-11 devnull .I attribute = value
171 d93fca6a 2005-02-11 devnull pairs. See the section on key templates below.
174 d93fca6a 2005-02-11 devnull don't look for a secstore.
177 d93fca6a 2005-02-11 devnull indicates that the agent is running on a
178 d93fca6a 2005-02-11 devnull cpu server. On starting, it will attempt to get a
179 d93fca6a 2005-02-11 devnull .B 9psk1
180 d93fca6a 2005-02-11 devnull key from NVRAM using
181 d93fca6a 2005-02-11 devnull .B readnvram
183 d93fca6a 2005-02-11 devnull .IR authsrv (3)),
184 d93fca6a 2005-02-11 devnull prompting for anything it needs.
185 d93fca6a 2005-02-11 devnull It will never subsequently prompt for a
186 d93fca6a 2005-02-11 devnull key that it doesn't have.
187 d93fca6a 2005-02-11 devnull This option is typically used by
188 d93fca6a 2005-02-11 devnull the kernel at boot time.
191 d93fca6a 2005-02-11 devnull causes the NVRAM to be written.
192 d93fca6a 2005-02-11 devnull It is only valid with the
195 d93fca6a 2005-02-11 devnull This option is typically used by
196 d93fca6a 2005-02-11 devnull the kernel at boot time.
199 d93fca6a 2005-02-11 devnull causes the agent to prompt for user
200 d93fca6a 2005-02-11 devnull id and writes it to
201 d93fca6a 2005-02-11 devnull .BR /dev/hostowner .
202 d93fca6a 2005-02-11 devnull It is mutually exclusive with
205 d93fca6a 2005-02-11 devnull .BR \-S .
206 d93fca6a 2005-02-11 devnull This option is typically used by
207 d93fca6a 2005-02-11 devnull the kernel at boot time.
210 d93fca6a 2005-02-11 devnull .\" .I Fgui
211 d93fca6a 2005-02-11 devnull .\" is a graphic user interface for confirming key usage and
212 d93fca6a 2005-02-11 devnull .\" entering new keys. It hides the window in which it starts
213 d93fca6a 2005-02-11 devnull .\" and waits reading requests from
214 d93fca6a 2005-02-11 devnull .\" .B confirm
216 d93fca6a 2005-02-11 devnull .\" .BR needkey .
217 d93fca6a 2005-02-11 devnull .\" For each requests, it unhides itself and waits for
218 d93fca6a 2005-02-11 devnull .\" user input.
219 d93fca6a 2005-02-11 devnull .\" See the sections on key confirmation and key prompting below.
220 d93fca6a 2005-02-11 devnull .SS "Key Tuples
223 d93fca6a 2005-02-11 devnull .I "key tuple
224 d93fca6a 2005-02-11 devnull is a space delimited list of
225 d93fca6a 2005-02-11 devnull .IB attribute = value
226 d93fca6a 2005-02-11 devnull pairs. An attribute whose name begins with an exclamation point
227 d93fca6a 2005-02-11 devnull .RB ( ! )
228 d93fca6a 2005-02-11 devnull does not appear when reading the
231 d93fca6a 2005-02-11 devnull The required attributes depend on the authentication protocol.
233 d93fca6a 2005-02-11 devnull .BR P9sk1 ,
234 d93fca6a 2005-02-11 devnull .BR p9sk2 ,
236 d93fca6a 2005-02-11 devnull .BR p9cr
237 d93fca6a 2005-02-11 devnull all require a key with
238 d93fca6a 2005-02-11 devnull .BR proto = p9sk1 ,
241 d93fca6a 2005-02-11 devnull attribute identifying the authentication domain, a
243 d93fca6a 2005-02-11 devnull name valid in that domain, and either a
244 d93fca6a 2005-02-11 devnull .B !password
247 d93fca6a 2005-02-11 devnull attribute specifying the password or hexadecimal secret
248 d93fca6a 2005-02-11 devnull to be used. Here is an example:
251 d93fca6a 2005-02-11 devnull proto=p9sk1 dom=avayalabs.com user=presotto !password=lucent
254 d93fca6a 2005-02-11 devnull .BR Apop ,
255 d93fca6a 2005-02-11 devnull .BR cram ,
256 d93fca6a 2005-02-11 devnull .BR chap ,
258 d93fca6a 2005-02-11 devnull .BR mschap ,
259 d93fca6a 2005-02-11 devnull require a key with a
260 d93fca6a 2005-02-11 devnull .B proto
261 d93fca6a 2005-02-11 devnull attribute whose value matches the protocol,
262 d93fca6a 2005-02-11 devnull in addition to
263 d93fca6a 2005-02-11 devnull .BR server ,
264 d93fca6a 2005-02-11 devnull .BR user ,
266 d93fca6a 2005-02-11 devnull .B !password
267 d93fca6a 2005-02-11 devnull attributes;
271 d93fca6a 2005-02-11 devnull proto=apop server=mit.edu user=rsc !password=nerdsRus
273 d93fca6a 2005-02-11 devnull Vnc is similar but does not require a
275 d93fca6a 2005-02-11 devnull attribute.
278 d93fca6a 2005-02-11 devnull requires a key with
279 d93fca6a 2005-02-11 devnull .B proto=pass
280 d93fca6a 2005-02-11 devnull in addition to
283 d93fca6a 2005-02-11 devnull .B !password
284 d93fca6a 2005-02-11 devnull attributes; e.g.
287 d93fca6a 2005-02-11 devnull proto=pass user=tb !password=does.it.matter
291 d93fca6a 2005-02-11 devnull requires a key with
292 d93fca6a 2005-02-11 devnull .B proto=rsa
293 d93fca6a 2005-02-11 devnull in addition to all the hex attributes defining an RSA key:
294 d93fca6a 2005-02-11 devnull .BR ek ,
296 d93fca6a 2005-02-11 devnull .BR !p ,
297 d93fca6a 2005-02-11 devnull .BR !q ,
298 d93fca6a 2005-02-11 devnull .BR !kp ,
299 d93fca6a 2005-02-11 devnull .BR !kq ,
300 d93fca6a 2005-02-11 devnull .BR !c2 ,
302 d93fca6a 2005-02-11 devnull .BR !dk .
303 d93fca6a 2005-02-11 devnull By convention, programs using the RSA protocol also require a
304 d93fca6a 2005-02-11 devnull .B service
305 d93fca6a 2005-02-11 devnull attribute set to
306 d93fca6a 2005-02-11 devnull .BR ssh ,
307 d93fca6a 2005-02-11 devnull .BR sshserve ,
309 d93fca6a 2005-02-11 devnull .BR tls .
312 d93fca6a 2005-02-11 devnull requires a
313 d93fca6a 2005-02-11 devnull .BR key1 ,
314 d93fca6a 2005-02-11 devnull .BR key2 ,
316 d93fca6a 2005-02-11 devnull .BR key3
317 d93fca6a 2005-02-11 devnull set to the password to be used.
318 d93fca6a 2005-02-11 devnull Starting the protocol causes
319 d93fca6a 2005-02-11 devnull .I factotum
320 d93fca6a 2005-02-11 devnull to configure the wireless ethernet card
321 d93fca6a 2005-02-11 devnull .B #l/ether0
322 d93fca6a 2005-02-11 devnull for WEP encryption with the given password.
324 d93fca6a 2005-02-11 devnull All keys can have additional attibutes that act either as comments
325 d93fca6a 2005-02-11 devnull or as selectors to distinguish them in the
326 83c4506a 2005-02-11 devnull .IR auth (3)
327 d93fca6a 2005-02-11 devnull library calls.
329 d93fca6a 2005-02-11 devnull The factotum owner can use any key stored by factotum.
330 d93fca6a 2005-02-11 devnull Any key may have one or more
331 d93fca6a 2005-02-11 devnull .B owner
332 d93fca6a 2005-02-11 devnull attributes listing the users who can use the key
333 d93fca6a 2005-02-11 devnull as though they were the owner.
334 d93fca6a 2005-02-11 devnull For example, the TLS and SSH host keys on a server
335 d93fca6a 2005-02-11 devnull often have an attribute
336 d93fca6a 2005-02-11 devnull .B owner=*
337 d93fca6a 2005-02-11 devnull to allow any user (and in particular,
338 d93fca6a 2005-02-11 devnull .L none )
339 d93fca6a 2005-02-11 devnull to run the TLS or SSH server-side protocol.
341 d93fca6a 2005-02-11 devnull Any key may have a
343 d93fca6a 2005-02-11 devnull attribute for restricting how it can be used.
344 d93fca6a 2005-02-11 devnull If this attribute is missing, the key can be used in any role.
345 d93fca6a 2005-02-11 devnull The possible values are:
347 d93fca6a 2005-02-11 devnull .B client
348 d93fca6a 2005-02-11 devnull for authenticating outbound calls
350 d93fca6a 2005-02-11 devnull .B server
351 d93fca6a 2005-02-11 devnull for authenticating inbound calls
353 d93fca6a 2005-02-11 devnull .B speaksfor
354 d93fca6a 2005-02-11 devnull for authenticating processes whose
355 d93fca6a 2005-02-11 devnull user id does not match
356 d93fca6a 2005-02-11 devnull .IR factotum 's.
359 d93fca6a 2005-02-11 devnull Whenever
360 d93fca6a 2005-02-11 devnull .I factotum
361 d93fca6a 2005-02-11 devnull runs as a server, it must have a
362 d93fca6a 2005-02-11 devnull .B p9sk1
363 d93fca6a 2005-02-11 devnull key in order to communicate with the authentication
364 d93fca6a 2005-02-11 devnull server for validating passwords and challenge/responses of
365 d93fca6a 2005-02-11 devnull other users.
366 d93fca6a 2005-02-11 devnull .SS "Key Templates
367 d93fca6a 2005-02-11 devnull Key templates are used by routines that interface to
368 d93fca6a 2005-02-11 devnull .I factotum
370 d93fca6a 2005-02-11 devnull .B auth_proxy
372 d93fca6a 2005-02-11 devnull .B auth_challenge
374 d93fca6a 2005-02-11 devnull .IR auth (3))
375 d93fca6a 2005-02-11 devnull to specify which key and protocol to use for an authentication.
376 d93fca6a 2005-02-11 devnull Like a key tuple, a key template is also a list of
377 d93fca6a 2005-02-11 devnull .IB attribute = value
379 d93fca6a 2005-02-11 devnull It must specify at least the protocol and enough
380 d93fca6a 2005-02-11 devnull other attributes to uniquely identify a key, or set of keys, to use.
381 d93fca6a 2005-02-11 devnull The keys chosen are those that match all the attributes specified
382 d93fca6a 2005-02-11 devnull in the template. The possible attribute/value formats are:
384 d93fca6a 2005-02-11 devnull .IB attr = val
385 d93fca6a 2005-02-11 devnull The attribute
387 d93fca6a 2005-02-11 devnull must exist in the key and its value must exactly
391 d93fca6a 2005-02-11 devnull .IB attr ?
392 d93fca6a 2005-02-11 devnull The attribute
394 d93fca6a 2005-02-11 devnull must exist in the key but its value doesn't matter.
397 d93fca6a 2005-02-11 devnull The attribute
399 d93fca6a 2005-02-11 devnull must exist in the key with a null value
402 d93fca6a 2005-02-11 devnull Key templates are also used by factotum to request a key either via
403 d93fca6a 2005-02-11 devnull an RPC error or via the
404 d93fca6a 2005-02-11 devnull .B needkey
405 d93fca6a 2005-02-11 devnull interface.
406 d93fca6a 2005-02-11 devnull The possible attribute/value formats are:
408 d93fca6a 2005-02-11 devnull .IB attr = val
409 d93fca6a 2005-02-11 devnull This pair must remain unchanged
411 d93fca6a 2005-02-11 devnull .IB attr ?
412 d93fca6a 2005-02-11 devnull This attribute needs a value
415 d93fca6a 2005-02-11 devnull The pair must remain unchanged
417 d93fca6a 2005-02-11 devnull .SS "Control and Key Management
419 d93fca6a 2005-02-11 devnull A number of messages can be written to the control file.
420 d93fca6a 2005-02-11 devnull The mesages are:
422 d93fca6a 2005-02-11 devnull .B "key \fIattribute-value-list\fP
423 d93fca6a 2005-02-11 devnull add a new key. This will replace any old key whose
424 d93fca6a 2005-02-11 devnull public, i.e. non ! attributes, match.
426 d93fca6a 2005-02-11 devnull .B "delkey \fIattribute-value-list\fP
427 d93fca6a 2005-02-11 devnull delete a key whose attributes match those given.
429 d93fca6a 2005-02-11 devnull .B debug
430 d93fca6a 2005-02-11 devnull toggle debugging on and off, i.e., the debugging also
431 d93fca6a 2005-02-11 devnull turned on by the
435 d93fca6a 2005-02-11 devnull By default when factotum starts it looks for a
436 d93fca6a 2005-02-11 devnull .IR secstore (1)
437 d93fca6a 2005-02-11 devnull account on $auth for the user and, if one exists,
438 d93fca6a 2005-02-11 devnull prompts for a secstore password in order to fetch
439 d93fca6a 2005-02-11 devnull the file
440 d93fca6a 2005-02-11 devnull .IR factotum ,
441 d93fca6a 2005-02-11 devnull which should contain control file commands.
442 d93fca6a 2005-02-11 devnull An example would be
444 d93fca6a 2005-02-11 devnull key dom=x.com proto=p9sk1 user=boyd !hex=26E522ADE2BBB2A229
445 d93fca6a 2005-02-11 devnull key proto=rsa service=ssh size=1024 ek=3B !dk=...
447 d93fca6a 2005-02-11 devnull where the first line sets a password for
448 d93fca6a 2005-02-11 devnull challenge/response authentication, strong against dictionary
449 d93fca6a 2005-02-11 devnull attack by being a long random string, and the second line
450 d93fca6a 2005-02-11 devnull sets a public/private keypair for ssh authentication,
451 d93fca6a 2005-02-11 devnull generated by
452 d93fca6a 2005-02-11 devnull .B ssh_genkey
454 d93fca6a 2005-02-11 devnull .IR ssh (1)).
456 d93fca6a 2005-02-11 devnull .SS "Confirming key use
459 d93fca6a 2005-02-11 devnull .B confirm
460 d93fca6a 2005-02-11 devnull file provides a connection from
461 d93fca6a 2005-02-11 devnull .I factotum
462 d93fca6a 2005-02-11 devnull to a confirmation server, normally the program
463 d93fca6a 2005-02-11 devnull .IR auth/fgui .
464 d93fca6a 2005-02-11 devnull Whenever a key with the
465 d93fca6a 2005-02-11 devnull .B confirm
466 d93fca6a 2005-02-11 devnull attribute is used,
467 d93fca6a 2005-02-11 devnull .I factotum
468 d93fca6a 2005-02-11 devnull requires confirmation of its use. If no process has
469 d93fca6a 2005-02-11 devnull .B confirm
470 d93fca6a 2005-02-11 devnull opened, use of the key will be denied.
471 d93fca6a 2005-02-11 devnull However, if the file is opened a request can be read from it
472 d93fca6a 2005-02-11 devnull with the following format:
474 d93fca6a 2005-02-11 devnull .B confirm
475 d93fca6a 2005-02-11 devnull .BI tag= tagno
476 d93fca6a 2005-02-11 devnull .I "<key template>
478 d93fca6a 2005-02-11 devnull The reply, written back to
479 d93fca6a 2005-02-11 devnull .BR confirm ,
480 d93fca6a 2005-02-11 devnull consists of string:
482 d93fca6a 2005-02-11 devnull .BI tag= tagno
483 d93fca6a 2005-02-11 devnull .BI answer= xxx
487 d93fca6a 2005-02-11 devnull is the string
489 d93fca6a 2005-02-11 devnull then the use is confirmed and the authentication will proceed.
490 d93fca6a 2005-02-11 devnull Otherwise, it fails.
492 d93fca6a 2005-02-11 devnull .B Confirm
493 d93fca6a 2005-02-11 devnull is exclusive open and can only be opened by a process with
494 d93fca6a 2005-02-11 devnull the same user id as
495 d93fca6a 2005-02-11 devnull .IR factotum .
496 d93fca6a 2005-02-11 devnull .SS "Prompting for keys
499 d93fca6a 2005-02-11 devnull .B needkey
500 d93fca6a 2005-02-11 devnull file provides a connection from
501 d93fca6a 2005-02-11 devnull .I factotum
502 d93fca6a 2005-02-11 devnull to a key server, normally the program
503 d93fca6a 2005-02-11 devnull .IR auth/fgui .
504 d93fca6a 2005-02-11 devnull Whenever
505 d93fca6a 2005-02-11 devnull .I factotum
506 d93fca6a 2005-02-11 devnull needs a new key, it first checks to see if
507 d93fca6a 2005-02-11 devnull .B needkey
508 d93fca6a 2005-02-11 devnull is opened. If it isn't, it returns a error to its client.
509 d93fca6a 2005-02-11 devnull If the file is opened a request can be read from it
510 d93fca6a 2005-02-11 devnull with the following format:
512 d93fca6a 2005-02-11 devnull .B needkey
513 d93fca6a 2005-02-11 devnull .BI tag= tagno
514 d93fca6a 2005-02-11 devnull .I "<key template>
516 d93fca6a 2005-02-11 devnull It is up to the reader to then query the user for any missing fields,
517 d93fca6a 2005-02-11 devnull write the key tuple into the
519 d93fca6a 2005-02-11 devnull file, and then reply by writing into the
520 d93fca6a 2005-02-11 devnull .B needkey
521 d93fca6a 2005-02-11 devnull file the string:
523 d93fca6a 2005-02-11 devnull .BI tag= tagno
525 d93fca6a 2005-02-11 devnull .B Needkey
526 d93fca6a 2005-02-11 devnull is exclusive open and can only be opened by a process with
527 d93fca6a 2005-02-11 devnull the same user id as
528 d93fca6a 2005-02-11 devnull .IR factotum .
529 d93fca6a 2005-02-11 devnull .SS "The RPC Protocol
530 d93fca6a 2005-02-11 devnull Authentication is performed by
535 d93fca6a 2005-02-11 devnull setting up the protocol and key to be used (see the
536 d93fca6a 2005-02-11 devnull .B start
537 d93fca6a 2005-02-11 devnull RPC below),
539 d93fca6a 2005-02-11 devnull shuttling messages back and forth between
540 d93fca6a 2005-02-11 devnull .IR factotum
541 d93fca6a 2005-02-11 devnull and the other party (see the
544 d93fca6a 2005-02-11 devnull .B write
545 d93fca6a 2005-02-11 devnull RPC's) until done
547 d93fca6a 2005-02-11 devnull if successful, reading back an
548 d93fca6a 2005-02-11 devnull .I AuthInfo
549 d93fca6a 2005-02-11 devnull structure (see
550 d93fca6a 2005-02-11 devnull .IR authsrv (3)).
552 d93fca6a 2005-02-11 devnull The RPC protocol is normally embodied by one of the
553 d93fca6a 2005-02-11 devnull routines in
554 d93fca6a 2005-02-11 devnull .IR auth (3).
555 d93fca6a 2005-02-11 devnull We describe it here should anyone want to extend
556 d93fca6a 2005-02-11 devnull the library.
558 d93fca6a 2005-02-11 devnull An RPC consists of writing a request message to
560 d93fca6a 2005-02-11 devnull followed by reading a reply message back.
561 d93fca6a 2005-02-11 devnull RPC's are strictly ordered; requests and replies of
562 d93fca6a 2005-02-11 devnull different RPC's cannot be interleaved.
563 d93fca6a 2005-02-11 devnull Messages consist of a verb, a single space, and data.
564 d93fca6a 2005-02-11 devnull The data format depends on the verb. The request verbs are:
566 d93fca6a 2005-02-11 devnull .B "start \fIattribute-value-list\fP
567 d93fca6a 2005-02-11 devnull start a new authentication.
568 d93fca6a 2005-02-11 devnull .I Attribute-value-pair-list
569 d93fca6a 2005-02-11 devnull must include a
570 d93fca6a 2005-02-11 devnull .B proto
571 d93fca6a 2005-02-11 devnull attribute, a
573 d93fca6a 2005-02-11 devnull attribute with value
574 d93fca6a 2005-02-11 devnull .B client
576 d93fca6a 2005-02-11 devnull .BR server ,
577 d93fca6a 2005-02-11 devnull and enough other attibutes to uniquely identify a key to use.
579 d93fca6a 2005-02-11 devnull .B start
580 d93fca6a 2005-02-11 devnull RPC is required before any others. The possible replies are:
584 d93fca6a 2005-02-11 devnull start succeeded.
586 d93fca6a 2005-02-11 devnull .B "error \fIstring\fP
588 d93fca6a 2005-02-11 devnull .I string
589 d93fca6a 2005-02-11 devnull is the reason.
594 d93fca6a 2005-02-11 devnull get data from
595 d93fca6a 2005-02-11 devnull .I factotum
596 d93fca6a 2005-02-11 devnull to send to the other party. The possible replies are:
600 d93fca6a 2005-02-11 devnull read succeeded, this is zero length message.
602 d93fca6a 2005-02-11 devnull .B "ok \fIdata\fP
603 d93fca6a 2005-02-11 devnull read succeeded, the data follows the space and is
604 d93fca6a 2005-02-11 devnull unformatted.
606 d93fca6a 2005-02-11 devnull .B "done
607 d93fca6a 2005-02-11 devnull authentication has succeeded, no further RPC's are
608 d93fca6a 2005-02-11 devnull necessary
610 d93fca6a 2005-02-11 devnull .B "done haveai
611 d93fca6a 2005-02-11 devnull authentication has succeeded, an
612 d93fca6a 2005-02-11 devnull .B AuthInfo
613 d93fca6a 2005-02-11 devnull structure (see
614 d93fca6a 2005-02-11 devnull .IR auth (3))
615 d93fca6a 2005-02-11 devnull can be retrieved with an
616 d93fca6a 2005-02-11 devnull .B authinfo
619 d93fca6a 2005-02-11 devnull .B "phase \fIstring\fP
620 d93fca6a 2005-02-11 devnull its not your turn to read, get some data from
621 d93fca6a 2005-02-11 devnull the other party and return it with a write RPC.
623 d93fca6a 2005-02-11 devnull .B "error \fIstring\fP
624 d93fca6a 2005-02-11 devnull authentication failed,
625 d93fca6a 2005-02-11 devnull .I string
626 d93fca6a 2005-02-11 devnull is the reason.
628 d93fca6a 2005-02-11 devnull .B "protocol not started
630 d93fca6a 2005-02-11 devnull .B start
631 d93fca6a 2005-02-11 devnull RPC needs to precede reads and writes
633 d93fca6a 2005-02-11 devnull .B "needkey \fIattribute-value-list\fP
634 d93fca6a 2005-02-11 devnull a key matching the argument is needed. This argument
635 d93fca6a 2005-02-11 devnull may be passed as an argument to
636 d93fca6a 2005-02-11 devnull .I factotum
638 d93fca6a 2005-02-11 devnull in order to prompt for a key. After that, the
639 d93fca6a 2005-02-11 devnull authentication may proceed, i.e., the read restarted.
643 d93fca6a 2005-02-11 devnull .B "write \fIdata\fP
644 d93fca6a 2005-02-11 devnull send data from the other party to
645 d93fca6a 2005-02-11 devnull .IR factotum .
646 d93fca6a 2005-02-11 devnull The possible replies are:
650 d93fca6a 2005-02-11 devnull the write succeeded
652 d93fca6a 2005-02-11 devnull .B "needkey \fIattribute-value-list\fP
653 d93fca6a 2005-02-11 devnull see above
655 d93fca6a 2005-02-11 devnull .B "toosmall \fIn\fP
656 d93fca6a 2005-02-11 devnull the write is too short, get more data from the
657 d93fca6a 2005-02-11 devnull other party and retry the write.
659 d93fca6a 2005-02-11 devnull specifies the maximun total number of bytes.
661 d93fca6a 2005-02-11 devnull .B "phase \fIstring\fP
662 d93fca6a 2005-02-11 devnull its not your turn to write, get some data from
663 d93fca6a 2005-02-11 devnull .I factotum
666 d93fca6a 2005-02-11 devnull .B "done
667 d93fca6a 2005-02-11 devnull see above
669 d93fca6a 2005-02-11 devnull .B "done haveai
670 d93fca6a 2005-02-11 devnull see above
673 d93fca6a 2005-02-11 devnull .B authinfo
674 d93fca6a 2005-02-11 devnull retrieve the AuthInfo structure.
675 d93fca6a 2005-02-11 devnull The possible replies are:
678 d93fca6a 2005-02-11 devnull .B "ok \fIdata\fP
680 d93fca6a 2005-02-11 devnull is a marshaled form of the AuthInfo structure.
682 d93fca6a 2005-02-11 devnull .B "error \fIstring\fP
684 d93fca6a 2005-02-11 devnull .I string
685 d93fca6a 2005-02-11 devnull is the reason for the error.
690 d93fca6a 2005-02-11 devnull retrieve the attributes used in the
691 d93fca6a 2005-02-11 devnull .B start
693 d93fca6a 2005-02-11 devnull The possible replies are:
696 d93fca6a 2005-02-11 devnull .B "ok \fIattribute-value-list\fP
698 d93fca6a 2005-02-11 devnull .B "error \fIstring\fP
700 d93fca6a 2005-02-11 devnull .I string
701 d93fca6a 2005-02-11 devnull is the reason for the error.
704 d93fca6a 2005-02-11 devnull .SH SOURCE
705 d93fca6a 2005-02-11 devnull .B \*9/src/cmd/factotum
