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 977b25a7 2020-08-14 rsc .IR authsrv (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.
118 9bce1d1e 2005-02-13 devnull DSA signatures, used by SSH
120 d93fca6a 2005-02-11 devnull .B mschap
121 d93fca6a 2005-02-11 devnull a proprietary Microsoft protocol also used by PPP and PPTP.
124 9bce1d1e 2005-02-13 devnull RSA encryption and signatures, used by SSH and TLS.
127 d93fca6a 2005-02-11 devnull passwords in the clear.
130 d32deab1 2020-08-16 rsc .MR vnc (1) 's
131 d93fca6a 2005-02-11 devnull challenge/response.
134 d93fca6a 2005-02-11 devnull WEP passwords for wireless ethernet cards.
136 9bce1d1e 2005-02-13 devnull The ``Protocols'' section below describes these protocols in more detail.
138 9bce1d1e 2005-02-13 devnull The options to
139 9bce1d1e 2005-02-13 devnull .I factotum
143 d93fca6a 2005-02-11 devnull supplies the address of the authentication server to use.
144 d93fca6a 2005-02-11 devnull Without this option, it will attempt to find an authentication server by
145 d93fca6a 2005-02-11 devnull querying the connection server, the file
146 d93fca6a 2005-02-11 devnull .BR <mtpt>/ndb ,
147 d93fca6a 2005-02-11 devnull and finally the network database in
148 d93fca6a 2005-02-11 devnull .BR /lib/ndb .
151 d93fca6a 2005-02-11 devnull specifies the mount point to use, by default
152 d93fca6a 2005-02-11 devnull .BR /mnt .
155 d93fca6a 2005-02-11 devnull specifies the service name to use.
156 d93fca6a 2005-02-11 devnull Without this option,
157 d93fca6a 2005-02-11 devnull .I factotum
158 d93fca6a 2005-02-11 devnull does not create a service file in
159 d93fca6a 2005-02-11 devnull .BR /srv .
162 d93fca6a 2005-02-11 devnull turns on 9P tracing, written to standard error.
165 d93fca6a 2005-02-11 devnull turns on debugging, written to standard error.
168 d93fca6a 2005-02-11 devnull causes the agent to prompt for the key, write it
171 d93fca6a 2005-02-11 devnull file, and exit.
172 d93fca6a 2005-02-11 devnull The agent will prompt for values for any of the
173 d93fca6a 2005-02-11 devnull attributes ending with a question mark
174 d93fca6a 2005-02-11 devnull .RB ( ? )
175 d93fca6a 2005-02-11 devnull and will append all the supplied
176 d93fca6a 2005-02-11 devnull .I attribute = value
177 d93fca6a 2005-02-11 devnull pairs. See the section on key templates below.
180 d93fca6a 2005-02-11 devnull don't look for a secstore.
183 d93fca6a 2005-02-11 devnull indicates that the agent is running on a
184 d93fca6a 2005-02-11 devnull cpu server. On starting, it will attempt to get a
185 d93fca6a 2005-02-11 devnull .B 9psk1
186 d93fca6a 2005-02-11 devnull key from NVRAM using
187 d93fca6a 2005-02-11 devnull .B readnvram
189 d32deab1 2020-08-16 rsc .MR authsrv (3) ),
190 d93fca6a 2005-02-11 devnull prompting for anything it needs.
191 d93fca6a 2005-02-11 devnull It will never subsequently prompt for a
192 d93fca6a 2005-02-11 devnull key that it doesn't have.
193 d93fca6a 2005-02-11 devnull This option is typically used by
194 d93fca6a 2005-02-11 devnull the kernel at boot time.
197 d93fca6a 2005-02-11 devnull causes the NVRAM to be written.
198 d93fca6a 2005-02-11 devnull It is only valid with the
201 d93fca6a 2005-02-11 devnull This option is typically used by
202 d93fca6a 2005-02-11 devnull the kernel at boot time.
205 d93fca6a 2005-02-11 devnull causes the agent to prompt for user
206 d93fca6a 2005-02-11 devnull id and writes it to
207 d93fca6a 2005-02-11 devnull .BR /dev/hostowner .
208 d93fca6a 2005-02-11 devnull It is mutually exclusive with
211 d93fca6a 2005-02-11 devnull .BR \-S .
212 d93fca6a 2005-02-11 devnull This option is typically used by
213 d93fca6a 2005-02-11 devnull the kernel at boot time.
216 d93fca6a 2005-02-11 devnull .\" .I Fgui
217 d93fca6a 2005-02-11 devnull .\" is a graphic user interface for confirming key usage and
218 d93fca6a 2005-02-11 devnull .\" entering new keys. It hides the window in which it starts
219 d93fca6a 2005-02-11 devnull .\" and waits reading requests from
220 d93fca6a 2005-02-11 devnull .\" .B confirm
222 d93fca6a 2005-02-11 devnull .\" .BR needkey .
223 d93fca6a 2005-02-11 devnull .\" For each requests, it unhides itself and waits for
224 d93fca6a 2005-02-11 devnull .\" user input.
225 d93fca6a 2005-02-11 devnull .\" See the sections on key confirmation and key prompting below.
226 d93fca6a 2005-02-11 devnull .SS "Key Tuples
229 d93fca6a 2005-02-11 devnull .I "key tuple
230 977b25a7 2020-08-14 rsc is a space delimited list of
231 d93fca6a 2005-02-11 devnull .IB attribute = value
232 d93fca6a 2005-02-11 devnull pairs. An attribute whose name begins with an exclamation point
233 d93fca6a 2005-02-11 devnull .RB ( ! )
234 d93fca6a 2005-02-11 devnull does not appear when reading the
237 9bce1d1e 2005-02-13 devnull Here are some examples:
239 9bce1d1e 2005-02-13 devnull proto=p9sk1 dom=avayalabs.com user=presotto !password=lucent
240 d93fca6a 2005-02-11 devnull proto=apop server=mit.edu user=rsc !password=nerdsRus
241 9bce1d1e 2005-02-13 devnull proto=pass user=tb service=ssh !password=does.it.matter
243 9bce1d1e 2005-02-13 devnull The ``Protocols'' section below describes the attributes
244 9bce1d1e 2005-02-13 devnull specific to each supported protocol.
246 d93fca6a 2005-02-11 devnull All keys can have additional attibutes that act either as comments
247 d93fca6a 2005-02-11 devnull or as selectors to distinguish them in the
248 d32deab1 2020-08-16 rsc .MR auth (3)
249 d93fca6a 2005-02-11 devnull library calls.
251 d93fca6a 2005-02-11 devnull The factotum owner can use any key stored by factotum.
252 d93fca6a 2005-02-11 devnull Any key may have one or more
253 d93fca6a 2005-02-11 devnull .B owner
254 d93fca6a 2005-02-11 devnull attributes listing the users who can use the key
255 d93fca6a 2005-02-11 devnull as though they were the owner.
256 d93fca6a 2005-02-11 devnull For example, the TLS and SSH host keys on a server
257 d93fca6a 2005-02-11 devnull often have an attribute
258 d93fca6a 2005-02-11 devnull .B owner=*
259 d93fca6a 2005-02-11 devnull to allow any user (and in particular,
260 d93fca6a 2005-02-11 devnull .L none )
261 d93fca6a 2005-02-11 devnull to run the TLS or SSH server-side protocol.
263 d93fca6a 2005-02-11 devnull Any key may have a
265 d93fca6a 2005-02-11 devnull attribute for restricting how it can be used.
266 d93fca6a 2005-02-11 devnull If this attribute is missing, the key can be used in any role.
267 9bce1d1e 2005-02-13 devnull Common values are:
269 d93fca6a 2005-02-11 devnull .B client
270 d93fca6a 2005-02-11 devnull for authenticating outbound calls
272 d93fca6a 2005-02-11 devnull .B server
273 d93fca6a 2005-02-11 devnull for authenticating inbound calls
275 d93fca6a 2005-02-11 devnull .B speaksfor
276 d93fca6a 2005-02-11 devnull for authenticating processes whose
277 d93fca6a 2005-02-11 devnull user id does not match
278 d93fca6a 2005-02-11 devnull .IR factotum 's.
280 9bce1d1e 2005-02-13 devnull .B encrypt
281 9bce1d1e 2005-02-13 devnull for encrypting data
283 9bce1d1e 2005-02-13 devnull .B decrypt
284 9bce1d1e 2005-02-13 devnull for decrypting data
287 9bce1d1e 2005-02-13 devnull for cryptographically signing data
289 9bce1d1e 2005-02-13 devnull .B verify
290 9bce1d1e 2005-02-13 devnull for verifying cryptographic signatures
293 d93fca6a 2005-02-11 devnull Whenever
294 d93fca6a 2005-02-11 devnull .I factotum
295 d93fca6a 2005-02-11 devnull runs as a server, it must have a
296 d93fca6a 2005-02-11 devnull .B p9sk1
297 d93fca6a 2005-02-11 devnull key in order to communicate with the authentication
298 d93fca6a 2005-02-11 devnull server for validating passwords and challenge/responses of
299 d93fca6a 2005-02-11 devnull other users.
300 d93fca6a 2005-02-11 devnull .SS "Key Templates
301 d93fca6a 2005-02-11 devnull Key templates are used by routines that interface to
302 d93fca6a 2005-02-11 devnull .I factotum
304 d93fca6a 2005-02-11 devnull .B auth_proxy
306 d93fca6a 2005-02-11 devnull .B auth_challenge
308 d32deab1 2020-08-16 rsc .MR auth (3) )
309 d93fca6a 2005-02-11 devnull to specify which key and protocol to use for an authentication.
310 977b25a7 2020-08-14 rsc Like a key tuple, a key template is also a list of
311 d93fca6a 2005-02-11 devnull .IB attribute = value
313 d93fca6a 2005-02-11 devnull It must specify at least the protocol and enough
314 d93fca6a 2005-02-11 devnull other attributes to uniquely identify a key, or set of keys, to use.
315 d93fca6a 2005-02-11 devnull The keys chosen are those that match all the attributes specified
316 d93fca6a 2005-02-11 devnull in the template. The possible attribute/value formats are:
318 d93fca6a 2005-02-11 devnull .IB attr = val
319 d93fca6a 2005-02-11 devnull The attribute
321 d93fca6a 2005-02-11 devnull must exist in the key and its value must exactly
325 d93fca6a 2005-02-11 devnull .IB attr ?
326 d93fca6a 2005-02-11 devnull The attribute
328 d93fca6a 2005-02-11 devnull must exist in the key but its value doesn't matter.
331 d93fca6a 2005-02-11 devnull The attribute
333 d93fca6a 2005-02-11 devnull must exist in the key with a null value
336 d93fca6a 2005-02-11 devnull Key templates are also used by factotum to request a key either via
337 d93fca6a 2005-02-11 devnull an RPC error or via the
338 d93fca6a 2005-02-11 devnull .B needkey
339 d93fca6a 2005-02-11 devnull interface.
340 d93fca6a 2005-02-11 devnull The possible attribute/value formats are:
342 d93fca6a 2005-02-11 devnull .IB attr = val
343 d93fca6a 2005-02-11 devnull This pair must remain unchanged
345 d93fca6a 2005-02-11 devnull .IB attr ?
346 d93fca6a 2005-02-11 devnull This attribute needs a value
349 d93fca6a 2005-02-11 devnull The pair must remain unchanged
351 d93fca6a 2005-02-11 devnull .SS "Control and Key Management
353 d93fca6a 2005-02-11 devnull A number of messages can be written to the control file.
354 d93fca6a 2005-02-11 devnull The mesages are:
356 d93fca6a 2005-02-11 devnull .B "key \fIattribute-value-list\fP
357 d93fca6a 2005-02-11 devnull add a new key. This will replace any old key whose
358 d93fca6a 2005-02-11 devnull public, i.e. non ! attributes, match.
360 d93fca6a 2005-02-11 devnull .B "delkey \fIattribute-value-list\fP
361 d93fca6a 2005-02-11 devnull delete a key whose attributes match those given.
363 d93fca6a 2005-02-11 devnull .B debug
364 d93fca6a 2005-02-11 devnull toggle debugging on and off, i.e., the debugging also
365 d93fca6a 2005-02-11 devnull turned on by the
369 d93fca6a 2005-02-11 devnull By default when factotum starts it looks for a
370 d32deab1 2020-08-16 rsc .MR secstore (1)
371 d93fca6a 2005-02-11 devnull account on $auth for the user and, if one exists,
372 d93fca6a 2005-02-11 devnull prompts for a secstore password in order to fetch
373 d93fca6a 2005-02-11 devnull the file
374 d93fca6a 2005-02-11 devnull .IR factotum ,
375 d93fca6a 2005-02-11 devnull which should contain control file commands.
376 d93fca6a 2005-02-11 devnull An example would be
378 d93fca6a 2005-02-11 devnull key dom=x.com proto=p9sk1 user=boyd !hex=26E522ADE2BBB2A229
379 d93fca6a 2005-02-11 devnull key proto=rsa service=ssh size=1024 ek=3B !dk=...
381 d93fca6a 2005-02-11 devnull where the first line sets a password for
382 d93fca6a 2005-02-11 devnull challenge/response authentication, strong against dictionary
383 d93fca6a 2005-02-11 devnull attack by being a long random string, and the second line
384 d93fca6a 2005-02-11 devnull sets a public/private keypair for ssh authentication,
385 d93fca6a 2005-02-11 devnull generated by
386 d93fca6a 2005-02-11 devnull .B ssh_genkey
388 d32deab1 2020-08-16 rsc .MR ssh (1) ).
390 d93fca6a 2005-02-11 devnull .SS "Confirming key use
393 d93fca6a 2005-02-11 devnull .B confirm
394 d93fca6a 2005-02-11 devnull file provides a connection from
395 d93fca6a 2005-02-11 devnull .I factotum
396 d93fca6a 2005-02-11 devnull to a confirmation server, normally the program
397 d93fca6a 2005-02-11 devnull .IR auth/fgui .
398 d93fca6a 2005-02-11 devnull Whenever a key with the
399 d93fca6a 2005-02-11 devnull .B confirm
400 977b25a7 2020-08-14 rsc attribute is used,
401 d93fca6a 2005-02-11 devnull .I factotum
402 d93fca6a 2005-02-11 devnull requires confirmation of its use. If no process has
403 d93fca6a 2005-02-11 devnull .B confirm
404 d93fca6a 2005-02-11 devnull opened, use of the key will be denied.
405 d93fca6a 2005-02-11 devnull However, if the file is opened a request can be read from it
406 d93fca6a 2005-02-11 devnull with the following format:
408 d93fca6a 2005-02-11 devnull .B confirm
409 d93fca6a 2005-02-11 devnull .BI tag= tagno
410 d93fca6a 2005-02-11 devnull .I "<key template>
412 d93fca6a 2005-02-11 devnull The reply, written back to
413 d93fca6a 2005-02-11 devnull .BR confirm ,
414 d93fca6a 2005-02-11 devnull consists of string:
416 d93fca6a 2005-02-11 devnull .BI tag= tagno
417 d93fca6a 2005-02-11 devnull .BI answer= xxx
421 d93fca6a 2005-02-11 devnull is the string
423 d93fca6a 2005-02-11 devnull then the use is confirmed and the authentication will proceed.
424 d93fca6a 2005-02-11 devnull Otherwise, it fails.
426 d93fca6a 2005-02-11 devnull .B Confirm
427 d93fca6a 2005-02-11 devnull is exclusive open and can only be opened by a process with
428 d93fca6a 2005-02-11 devnull the same user id as
429 d93fca6a 2005-02-11 devnull .IR factotum .
430 d93fca6a 2005-02-11 devnull .SS "Prompting for keys
433 d93fca6a 2005-02-11 devnull .B needkey
434 d93fca6a 2005-02-11 devnull file provides a connection from
435 d93fca6a 2005-02-11 devnull .I factotum
436 d93fca6a 2005-02-11 devnull to a key server, normally the program
437 d93fca6a 2005-02-11 devnull .IR auth/fgui .
438 d93fca6a 2005-02-11 devnull Whenever
439 d93fca6a 2005-02-11 devnull .I factotum
440 d93fca6a 2005-02-11 devnull needs a new key, it first checks to see if
441 d93fca6a 2005-02-11 devnull .B needkey
442 d93fca6a 2005-02-11 devnull is opened. If it isn't, it returns a error to its client.
443 d93fca6a 2005-02-11 devnull If the file is opened a request can be read from it
444 d93fca6a 2005-02-11 devnull with the following format:
446 d93fca6a 2005-02-11 devnull .B needkey
447 d93fca6a 2005-02-11 devnull .BI tag= tagno
448 d93fca6a 2005-02-11 devnull .I "<key template>
450 d93fca6a 2005-02-11 devnull It is up to the reader to then query the user for any missing fields,
451 d93fca6a 2005-02-11 devnull write the key tuple into the
453 d93fca6a 2005-02-11 devnull file, and then reply by writing into the
454 d93fca6a 2005-02-11 devnull .B needkey
455 d93fca6a 2005-02-11 devnull file the string:
457 d93fca6a 2005-02-11 devnull .BI tag= tagno
459 d93fca6a 2005-02-11 devnull .B Needkey
460 d93fca6a 2005-02-11 devnull is exclusive open and can only be opened by a process with
461 d93fca6a 2005-02-11 devnull the same user id as
462 d93fca6a 2005-02-11 devnull .IR factotum .
463 d93fca6a 2005-02-11 devnull .SS "The RPC Protocol
464 d93fca6a 2005-02-11 devnull Authentication is performed by
469 d93fca6a 2005-02-11 devnull setting up the protocol and key to be used (see the
470 d93fca6a 2005-02-11 devnull .B start
471 d93fca6a 2005-02-11 devnull RPC below),
473 d93fca6a 2005-02-11 devnull shuttling messages back and forth between
474 d93fca6a 2005-02-11 devnull .IR factotum
475 d93fca6a 2005-02-11 devnull and the other party (see the
478 d93fca6a 2005-02-11 devnull .B write
479 d93fca6a 2005-02-11 devnull RPC's) until done
481 d93fca6a 2005-02-11 devnull if successful, reading back an
482 d93fca6a 2005-02-11 devnull .I AuthInfo
483 d93fca6a 2005-02-11 devnull structure (see
484 d32deab1 2020-08-16 rsc .MR authsrv (3) ).
486 d93fca6a 2005-02-11 devnull The RPC protocol is normally embodied by one of the
487 d93fca6a 2005-02-11 devnull routines in
488 d32deab1 2020-08-16 rsc .MR auth (3) .
489 d93fca6a 2005-02-11 devnull We describe it here should anyone want to extend
490 d93fca6a 2005-02-11 devnull the library.
492 d93fca6a 2005-02-11 devnull An RPC consists of writing a request message to
494 d93fca6a 2005-02-11 devnull followed by reading a reply message back.
495 d93fca6a 2005-02-11 devnull RPC's are strictly ordered; requests and replies of
496 d93fca6a 2005-02-11 devnull different RPC's cannot be interleaved.
497 d93fca6a 2005-02-11 devnull Messages consist of a verb, a single space, and data.
498 d93fca6a 2005-02-11 devnull The data format depends on the verb. The request verbs are:
500 d93fca6a 2005-02-11 devnull .B "start \fIattribute-value-list\fP
501 d93fca6a 2005-02-11 devnull start a new authentication.
502 d93fca6a 2005-02-11 devnull .I Attribute-value-pair-list
503 d93fca6a 2005-02-11 devnull must include a
504 d93fca6a 2005-02-11 devnull .B proto
505 d93fca6a 2005-02-11 devnull attribute, a
507 d93fca6a 2005-02-11 devnull attribute with value
508 d93fca6a 2005-02-11 devnull .B client
510 d93fca6a 2005-02-11 devnull .BR server ,
511 d93fca6a 2005-02-11 devnull and enough other attibutes to uniquely identify a key to use.
513 d93fca6a 2005-02-11 devnull .B start
514 d93fca6a 2005-02-11 devnull RPC is required before any others. The possible replies are:
518 d93fca6a 2005-02-11 devnull start succeeded.
520 d93fca6a 2005-02-11 devnull .B "error \fIstring\fP
522 d93fca6a 2005-02-11 devnull .I string
523 d93fca6a 2005-02-11 devnull is the reason.
528 d93fca6a 2005-02-11 devnull get data from
529 d93fca6a 2005-02-11 devnull .I factotum
530 d93fca6a 2005-02-11 devnull to send to the other party. The possible replies are:
534 d93fca6a 2005-02-11 devnull read succeeded, this is zero length message.
536 d93fca6a 2005-02-11 devnull .B "ok \fIdata\fP
537 d93fca6a 2005-02-11 devnull read succeeded, the data follows the space and is
538 d93fca6a 2005-02-11 devnull unformatted.
540 d93fca6a 2005-02-11 devnull .B "done
541 d93fca6a 2005-02-11 devnull authentication has succeeded, no further RPC's are
542 d93fca6a 2005-02-11 devnull necessary
544 d93fca6a 2005-02-11 devnull .B "done haveai
545 d93fca6a 2005-02-11 devnull authentication has succeeded, an
546 d93fca6a 2005-02-11 devnull .B AuthInfo
547 d93fca6a 2005-02-11 devnull structure (see
548 d32deab1 2020-08-16 rsc .MR auth (3) )
549 d93fca6a 2005-02-11 devnull can be retrieved with an
550 d93fca6a 2005-02-11 devnull .B authinfo
553 d93fca6a 2005-02-11 devnull .B "phase \fIstring\fP
554 d93fca6a 2005-02-11 devnull its not your turn to read, get some data from
555 d93fca6a 2005-02-11 devnull the other party and return it with a write RPC.
557 d93fca6a 2005-02-11 devnull .B "error \fIstring\fP
558 d93fca6a 2005-02-11 devnull authentication failed,
559 d93fca6a 2005-02-11 devnull .I string
560 d93fca6a 2005-02-11 devnull is the reason.
562 d93fca6a 2005-02-11 devnull .B "protocol not started
564 d93fca6a 2005-02-11 devnull .B start
565 d93fca6a 2005-02-11 devnull RPC needs to precede reads and writes
567 d93fca6a 2005-02-11 devnull .B "needkey \fIattribute-value-list\fP
568 d93fca6a 2005-02-11 devnull a key matching the argument is needed. This argument
569 d93fca6a 2005-02-11 devnull may be passed as an argument to
570 d93fca6a 2005-02-11 devnull .I factotum
572 d93fca6a 2005-02-11 devnull in order to prompt for a key. After that, the
573 d93fca6a 2005-02-11 devnull authentication may proceed, i.e., the read restarted.
577 d93fca6a 2005-02-11 devnull .B "write \fIdata\fP
578 d93fca6a 2005-02-11 devnull send data from the other party to
579 d93fca6a 2005-02-11 devnull .IR factotum .
580 d93fca6a 2005-02-11 devnull The possible replies are:
584 d93fca6a 2005-02-11 devnull the write succeeded
586 d93fca6a 2005-02-11 devnull .B "needkey \fIattribute-value-list\fP
587 d93fca6a 2005-02-11 devnull see above
589 d93fca6a 2005-02-11 devnull .B "toosmall \fIn\fP
590 d93fca6a 2005-02-11 devnull the write is too short, get more data from the
591 d93fca6a 2005-02-11 devnull other party and retry the write.
593 d93fca6a 2005-02-11 devnull specifies the maximun total number of bytes.
595 d93fca6a 2005-02-11 devnull .B "phase \fIstring\fP
596 d93fca6a 2005-02-11 devnull its not your turn to write, get some data from
597 d93fca6a 2005-02-11 devnull .I factotum
600 d93fca6a 2005-02-11 devnull .B "done
601 d93fca6a 2005-02-11 devnull see above
603 d93fca6a 2005-02-11 devnull .B "done haveai
604 d93fca6a 2005-02-11 devnull see above
607 9bce1d1e 2005-02-13 devnull .B readhex\fR, \fPwritehex
611 9bce1d1e 2005-02-13 devnull .BR write ,
612 9bce1d1e 2005-02-13 devnull except that an
614 9bce1d1e 2005-02-13 devnull response to
615 9bce1d1e 2005-02-13 devnull .B readhex
616 9bce1d1e 2005-02-13 devnull returns the data encoded as
617 9bce1d1e 2005-02-13 devnull a long hexadecimal string,
618 9bce1d1e 2005-02-13 devnull and the argument to
619 9bce1d1e 2005-02-13 devnull .B writehex
620 9bce1d1e 2005-02-13 devnull is expected to be a long hexadecimal string.
621 9bce1d1e 2005-02-13 devnull These are useful for manually debugging of binary protocols.
623 d93fca6a 2005-02-11 devnull .B authinfo
624 977b25a7 2020-08-14 rsc retrieve the AuthInfo structure.
625 d93fca6a 2005-02-11 devnull The possible replies are:
628 d93fca6a 2005-02-11 devnull .B "ok \fIdata\fP
630 d93fca6a 2005-02-11 devnull is a marshaled form of the AuthInfo structure.
632 d93fca6a 2005-02-11 devnull .B "error \fIstring\fP
634 d93fca6a 2005-02-11 devnull .I string
635 d93fca6a 2005-02-11 devnull is the reason for the error.
640 d93fca6a 2005-02-11 devnull retrieve the attributes used in the
641 d93fca6a 2005-02-11 devnull .B start
643 d93fca6a 2005-02-11 devnull The possible replies are:
646 d93fca6a 2005-02-11 devnull .B "ok \fIattribute-value-list\fP
648 d93fca6a 2005-02-11 devnull .B "error \fIstring\fP
650 d93fca6a 2005-02-11 devnull .I string
651 d93fca6a 2005-02-11 devnull is the reason for the error.
654 9bce1d1e 2005-02-13 devnull .SS Protocols
655 9bce1d1e 2005-02-13 devnull Factotum supports many authentication types, each
656 9bce1d1e 2005-02-13 devnull with its own roles and required key attributes.
658 9bce1d1e 2005-02-13 devnull .IR P9any ,
659 9bce1d1e 2005-02-13 devnull .IR p9sk1 ,
660 9bce1d1e 2005-02-13 devnull .IR p9sk2 ,
663 9bce1d1e 2005-02-13 devnull are used to authenticate to Plan 9 systems;
665 9bce1d1e 2005-02-13 devnull .BR role s
667 9bce1d1e 2005-02-13 devnull .B client
669 9bce1d1e 2005-02-13 devnull .BR server .
670 9bce1d1e 2005-02-13 devnull All require
671 9bce1d1e 2005-02-13 devnull .B proto=p9sk1
672 9bce1d1e 2005-02-13 devnull keys with
673 9bce1d1e 2005-02-13 devnull .BR user ,
675 9bce1d1e 2005-02-13 devnull (authentication domain),
677 9bce1d1e 2005-02-13 devnull .B !password
678 9bce1d1e 2005-02-13 devnull attributes.
680 9bce1d1e 2005-02-13 devnull .I P9sk1
682 9bce1d1e 2005-02-13 devnull .I p9sk2
683 9bce1d1e 2005-02-13 devnull are the Plan 9 shared-key authentication protocols.
684 9bce1d1e 2005-02-13 devnull .I P9sk2
685 9bce1d1e 2005-02-13 devnull is a deprecated form of
686 9bce1d1e 2005-02-13 devnull .I p9sk1
687 9bce1d1e 2005-02-13 devnull that neglects to authenticate the server.
689 9bce1d1e 2005-02-13 devnull .I P9any
690 9bce1d1e 2005-02-13 devnull is a meta-protocol that negotiates a protocol
691 9bce1d1e 2005-02-13 devnull .RB ( p9sk1
693 9bce1d1e 2005-02-13 devnull .BR p9sk2 )
694 977b25a7 2020-08-14 rsc and an authentication domain and then invokes the
695 9bce1d1e 2005-02-13 devnull given protocol with a
697 9bce1d1e 2005-02-13 devnull attribute.
699 9bce1d1e 2005-02-13 devnull .IR P9any ,
700 9bce1d1e 2005-02-13 devnull .IR p9sk1 ,
702 9bce1d1e 2005-02-13 devnull .I p9sk2
703 9bce1d1e 2005-02-13 devnull are intended to be proxied via
704 9bce1d1e 2005-02-13 devnull .I auth_proxy
706 d32deab1 2020-08-16 rsc .MR auth (3) ).
707 30f6ae14 2005-02-13 devnull .\" The protocols follow
708 30f6ae14 2005-02-13 devnull .\" .IR p9any (7)
710 30f6ae14 2005-02-13 devnull .\" .IR p9sk1 (7).
711 9bce1d1e 2005-02-13 devnull .\" XXX - write about how server keys are selected and used
712 9bce1d1e 2005-02-13 devnull .\" XXX - write about protocol itself
713 9bce1d1e 2005-02-13 devnull .\" XXX - write about server ai
716 9bce1d1e 2005-02-13 devnull is a textual challenge-response protocol;
717 9bce1d1e 2005-02-13 devnull roles are
718 9bce1d1e 2005-02-13 devnull .B client
720 9bce1d1e 2005-02-13 devnull .BR server .
722 9bce1d1e 2005-02-13 devnull .I p9sk1
723 9bce1d1e 2005-02-13 devnull keys as described above.
724 9bce1d1e 2005-02-13 devnull The protocol with
725 9bce1d1e 2005-02-13 devnull .I factotum
726 9bce1d1e 2005-02-13 devnull is textual:
727 9bce1d1e 2005-02-13 devnull client writes a user name,
728 9bce1d1e 2005-02-13 devnull server responds with a challenge,
729 9bce1d1e 2005-02-13 devnull client writes a response,
730 9bce1d1e 2005-02-13 devnull server responds with
733 9bce1d1e 2005-02-13 devnull .BR bad .
734 9bce1d1e 2005-02-13 devnull Typically this information is wrapped in other protocols
735 9bce1d1e 2005-02-13 devnull before being sent over the network.
738 9bce1d1e 2005-02-13 devnull is the challenge-response protocol used by
739 d32deab1 2020-08-16 rsc .MR vnc (1) ;
740 9bce1d1e 2005-02-13 devnull valid roles are
741 9bce1d1e 2005-02-13 devnull .B client
743 9bce1d1e 2005-02-13 devnull .BR server .
744 9bce1d1e 2005-02-13 devnull The client protocol requires a
745 9bce1d1e 2005-02-13 devnull .B proto=vnc
746 9bce1d1e 2005-02-13 devnull key with attribute
747 9bce1d1e 2005-02-13 devnull .BR !password .
748 9bce1d1e 2005-02-13 devnull Conventionally, client keys also have
751 9bce1d1e 2005-02-13 devnull .B server
752 9bce1d1e 2005-02-13 devnull attributes.
753 9bce1d1e 2005-02-13 devnull The server protocol requires a
754 9bce1d1e 2005-02-13 devnull .I p9sk1
755 9bce1d1e 2005-02-13 devnull key as described above.
756 9bce1d1e 2005-02-13 devnull The protocol with
757 9bce1d1e 2005-02-13 devnull .I factotum
758 9bce1d1e 2005-02-13 devnull is the same as
759 9bce1d1e 2005-02-13 devnull .IR p9cr ,
760 9bce1d1e 2005-02-13 devnull except that the challenge and response are not textual.
765 9bce1d1e 2005-02-13 devnull are challenge-response protocols typically
766 977b25a7 2020-08-14 rsc used to authenticate
767 9bce1d1e 2005-02-13 devnull to mail servers.
768 9bce1d1e 2005-02-13 devnull The client protocols require
769 9bce1d1e 2005-02-13 devnull .B proto=apop
771 9bce1d1e 2005-02-13 devnull .B proto=cram
772 9bce1d1e 2005-02-13 devnull keys with
775 9bce1d1e 2005-02-13 devnull .B !password
776 9bce1d1e 2005-02-13 devnull attributes.
777 977b25a7 2020-08-14 rsc Conventionally, client keys also have
778 9bce1d1e 2005-02-13 devnull .B server
779 9bce1d1e 2005-02-13 devnull attributes.
780 9bce1d1e 2005-02-13 devnull The server protocol requires a
781 9bce1d1e 2005-02-13 devnull .I p9sk1
782 9bce1d1e 2005-02-13 devnull key as described above.
783 9bce1d1e 2005-02-13 devnull The protocol with
784 9bce1d1e 2005-02-13 devnull .I factotum
785 9bce1d1e 2005-02-13 devnull is textual:
786 9bce1d1e 2005-02-13 devnull server writes a challenge of the form
787 9bce1d1e 2005-02-13 devnull .IB random @ domain \fR,
788 9bce1d1e 2005-02-13 devnull client responds with user name
789 9bce1d1e 2005-02-13 devnull and then a hexadecimal response
790 9bce1d1e 2005-02-13 devnull (two separate writes),
791 9bce1d1e 2005-02-13 devnull and then the server responds with
794 9bce1d1e 2005-02-13 devnull .BR bad .
798 9bce1d1e 2005-02-13 devnull .I mschap
799 9bce1d1e 2005-02-13 devnull are challenge-response protocols used in PPP sessions;
800 9bce1d1e 2005-02-13 devnull valid roles are
801 9bce1d1e 2005-02-13 devnull .B client
803 9bce1d1e 2005-02-13 devnull .BR server .
804 9bce1d1e 2005-02-13 devnull The client protocols require
805 9bce1d1e 2005-02-13 devnull .B proto=chap
807 9bce1d1e 2005-02-13 devnull .B proto=mschap
808 9bce1d1e 2005-02-13 devnull keys with
811 9bce1d1e 2005-02-13 devnull .B !password
812 9bce1d1e 2005-02-13 devnull attributes.
813 9bce1d1e 2005-02-13 devnull Conventionally, client keys also have
814 9bce1d1e 2005-02-13 devnull .B server
815 9bce1d1e 2005-02-13 devnull attributes.
816 9bce1d1e 2005-02-13 devnull The server protocol requires a
817 9bce1d1e 2005-02-13 devnull .I p9sk1
818 9bce1d1e 2005-02-13 devnull key as described above.
819 9bce1d1e 2005-02-13 devnull The protocol with factotum is:
820 9bce1d1e 2005-02-13 devnull server writes an 8-byte binary challenge,
821 9bce1d1e 2005-02-13 devnull client responds with user name
822 9bce1d1e 2005-02-13 devnull and then a
823 9bce1d1e 2005-02-13 devnull .B Chapreply
825 9bce1d1e 2005-02-13 devnull .B MSchapreply
826 9bce1d1e 2005-02-13 devnull structure (defined in
827 9bce1d1e 2005-02-13 devnull .B <auth.h> ).
830 9bce1d1e 2005-02-13 devnull is a client-only protocol that hands out passwords
832 9bce1d1e 2005-02-13 devnull .B proto=pass
833 9bce1d1e 2005-02-13 devnull keys with
836 9bce1d1e 2005-02-13 devnull .B !password
837 9bce1d1e 2005-02-13 devnull attributes.
838 9bce1d1e 2005-02-13 devnull The protocol is a single read that returns
839 9bce1d1e 2005-02-13 devnull a string: a space-separated quoted user name and password
840 9bce1d1e 2005-02-13 devnull that can be parsed with
841 9bce1d1e 2005-02-13 devnull .I tokenize
843 d32deab1 2020-08-16 rsc .MR getfields (3) ).
844 9bce1d1e 2005-02-13 devnull Conventionally, client keys have distinguishing attributes
846 9bce1d1e 2005-02-13 devnull .B service
848 9bce1d1e 2005-02-13 devnull .B server
849 9bce1d1e 2005-02-13 devnull that can be specified in the
850 9bce1d1e 2005-02-13 devnull .B start
851 9bce1d1e 2005-02-13 devnull message to select a key.
854 9bce1d1e 2005-02-13 devnull is a client-only pseudo-protocol that initializes the encryption
855 9bce1d1e 2005-02-13 devnull key on a wireless ethernet device.
857 9bce1d1e 2005-02-13 devnull .B proto=wep
858 9bce1d1e 2005-02-13 devnull keys with
859 9bce1d1e 2005-02-13 devnull .BR !key1 ,
860 9bce1d1e 2005-02-13 devnull .BR !key2 ,
862 9bce1d1e 2005-02-13 devnull .B !key3
864 9bce1d1e 2005-02-13 devnull The protocol with
865 9bce1d1e 2005-02-13 devnull .I factotum
867 9bce1d1e 2005-02-13 devnull the client writes a device name
868 9bce1d1e 2005-02-13 devnull that must begin with
869 9bce1d1e 2005-02-13 devnull .LR #l .
870 9bce1d1e 2005-02-13 devnull In response,
871 9bce1d1e 2005-02-13 devnull .I factotum
872 9bce1d1e 2005-02-13 devnull opens the device's control file, sets the wireless secret using the key,
873 9bce1d1e 2005-02-13 devnull and turns on encryption.
874 9bce1d1e 2005-02-13 devnull If the key has an
875 9bce1d1e 2005-02-13 devnull .B essid
877 9bce1d1e 2005-02-13 devnull .I factotum
878 9bce1d1e 2005-02-13 devnull uses it to set the wireless station ID.
881 9bce1d1e 2005-02-13 devnull is an implementation of the RSA protocol.
882 9bce1d1e 2005-02-13 devnull Valid roles are
883 9bce1d1e 2005-02-13 devnull .BR decrypt ,
884 9bce1d1e 2005-02-13 devnull .BR encrypt ,
885 9bce1d1e 2005-02-13 devnull .BR sign ,
887 9bce1d1e 2005-02-13 devnull .BR verify .
890 9bce1d1e 2005-02-13 devnull .B proto=rsa
891 9bce1d1e 2005-02-13 devnull keys with
895 9bce1d1e 2005-02-13 devnull attributes, large integers specifying the public half
896 9bce1d1e 2005-02-13 devnull of the key.
897 9bce1d1e 2005-02-13 devnull If a key is to be used for decryption or signing,
898 9bce1d1e 2005-02-13 devnull then it must also have attributes
899 9bce1d1e 2005-02-13 devnull .BR !p ,
900 9bce1d1e 2005-02-13 devnull .BR !q ,
901 9bce1d1e 2005-02-13 devnull .BR !kp ,
902 9bce1d1e 2005-02-13 devnull .BR !kq ,
903 9bce1d1e 2005-02-13 devnull .BR !c2 ,
906 9bce1d1e 2005-02-13 devnull specifying the private half of the key;
908 d32deab1 2020-08-16 rsc .MR rsa (3) .
909 9bce1d1e 2005-02-13 devnull Conventionally,
911 9bce1d1e 2005-02-13 devnull keys also have
912 9bce1d1e 2005-02-13 devnull .B service
913 9bce1d1e 2005-02-13 devnull attributes specifying the context in which the key is used:
915 9bce1d1e 2005-02-13 devnull (SSH version 1),
916 9bce1d1e 2005-02-13 devnull .B ssh-rsa
917 9bce1d1e 2005-02-13 devnull (SSH version 2),
920 9bce1d1e 2005-02-13 devnull (SSL and TLS).
921 9bce1d1e 2005-02-13 devnull If an SSH key has a
922 9bce1d1e 2005-02-13 devnull .B comment
923 9bce1d1e 2005-02-13 devnull attribute, that comment is presented to remote SSH servers
924 9bce1d1e 2005-02-13 devnull during key negotiation.
925 9bce1d1e 2005-02-13 devnull The protocol for
926 9bce1d1e 2005-02-13 devnull encryption (decryption) is:
927 9bce1d1e 2005-02-13 devnull write the message, then read back the encrypted (decrypted) form.
928 9bce1d1e 2005-02-13 devnull The protocol for signing is:
929 9bce1d1e 2005-02-13 devnull write a hash of the actual message,
930 9bce1d1e 2005-02-13 devnull then read back the signature.
931 9bce1d1e 2005-02-13 devnull The protocol for verifying a signature is:
932 9bce1d1e 2005-02-13 devnull write the message hash,
933 9bce1d1e 2005-02-13 devnull write the purported signature,
934 9bce1d1e 2005-02-13 devnull then read back
938 9bce1d1e 2005-02-13 devnull telling whether the signature could be verified.
939 9bce1d1e 2005-02-13 devnull The hash defaults to SHA1 but can be specified by a
941 9bce1d1e 2005-02-13 devnull attribute on the key.
942 9bce1d1e 2005-02-13 devnull Valid hash functions are
945 9bce1d1e 2005-02-13 devnull .BR sha1 .
946 9bce1d1e 2005-02-13 devnull The hash function must be known to
947 9bce1d1e 2005-02-13 devnull .I factotum
948 9bce1d1e 2005-02-13 devnull because the signature encodes the type of hash used.
950 9bce1d1e 2005-02-13 devnull .B encrypt
952 9bce1d1e 2005-02-13 devnull .B verify
953 9bce1d1e 2005-02-13 devnull operations are included as a convenience;
954 9bce1d1e 2005-02-13 devnull .I factotum
955 9bce1d1e 2005-02-13 devnull is not using any private information to perform them.
958 9bce1d1e 2005-02-13 devnull is an implementation of the NIST digital signature algorithm.
959 9bce1d1e 2005-02-13 devnull Valid roles are
962 9bce1d1e 2005-02-13 devnull .BR verify .
964 9bce1d1e 2005-02-13 devnull .B proto=dsa
965 9bce1d1e 2005-02-13 devnull keys with
968 9bce1d1e 2005-02-13 devnull .BR alpha ,
971 9bce1d1e 2005-02-13 devnull attributes.
972 9bce1d1e 2005-02-13 devnull If the key is to be used for signing, it must also have a
973 9bce1d1e 2005-02-13 devnull .B !secret
974 9bce1d1e 2005-02-13 devnull attribute; see
975 d32deab1 2020-08-16 rsc .MR dsa (3) .
976 9bce1d1e 2005-02-13 devnull Conventionally,
980 9bce1d1e 2005-02-13 devnull .B service
981 9bce1d1e 2005-02-13 devnull attributes specifying the context in which the key is used:
982 9bce1d1e 2005-02-13 devnull .B ssh-dss
983 9bce1d1e 2005-02-13 devnull (SSH version 2)
984 9bce1d1e 2005-02-13 devnull is the only one.
985 9bce1d1e 2005-02-13 devnull If an SSH key has a
986 9bce1d1e 2005-02-13 devnull .B comment
987 9bce1d1e 2005-02-13 devnull attribute, that comment is presented to SSH servers during
988 9bce1d1e 2005-02-13 devnull key negotiation.
989 9bce1d1e 2005-02-13 devnull The protocol for signing and verifying
990 9bce1d1e 2005-02-13 devnull is the same as the RSA protocol.
992 9bce1d1e 2005-02-13 devnull .IR rsa ,
995 977b25a7 2020-08-14 rsc protocol ignores the
997 9bce1d1e 2005-02-13 devnull attribute; it always uses SHA1.
999 9bce1d1e 2005-02-13 devnull .I Httpdigest
1000 9bce1d1e 2005-02-13 devnull is a client-only MD5-based challenge-response protocol used in HTTP; see RFC 2617.
1001 9bce1d1e 2005-02-13 devnull It uses
1002 9bce1d1e 2005-02-13 devnull .B proto=httpdigest
1003 9bce1d1e 2005-02-13 devnull keys with
1004 9bce1d1e 2005-02-13 devnull .BR user ,
1005 9bce1d1e 2005-02-13 devnull .BR realm ,
1007 9bce1d1e 2005-02-13 devnull .BR !password
1008 9bce1d1e 2005-02-13 devnull attributes.
1009 9bce1d1e 2005-02-13 devnull The protocol with factotum is textual:
1010 9bce1d1e 2005-02-13 devnull write the challenge, read the response.
1011 9bce1d1e 2005-02-13 devnull The challenge is a string with three space-separated fields
1012 9bce1d1e 2005-02-13 devnull .IR nonce ,
1013 9bce1d1e 2005-02-13 devnull .IR method ,
1015 9bce1d1e 2005-02-13 devnull .IR uri ,
1016 9bce1d1e 2005-02-13 devnull parseable with
1017 9bce1d1e 2005-02-13 devnull .IR tokenize .
1018 9bce1d1e 2005-02-13 devnull The response is a hexadecimal string of length 32.
1019 d93fca6a 2005-02-11 devnull .SH SOURCE
1020 30f6ae14 2005-02-13 devnull .B \*9/src/cmd/auth/factotum
1021 30f6ae14 2005-02-13 devnull .SH SEE ALSO
1022 d32deab1 2020-08-16 rsc .MR ssh-agent (1)
