Merge 1.8.0~pre4 packaging into master
[pkg-k5-afs_openafs.git] / src / kauth / AuthServer.mss
blob090a8d9a196497f8c254f42fe952765713660b5a
1 @comment (
2 /*
3  * Copyright 2000, International Business Machines Corporation and others.
4  * All Rights Reserved.
5  * 
6  * This software has been released under the terms of the IBM Public
7  * License.  For details, see the LICENSE file in the top-level source
8  * directory or online at http://www.openafs.org/dl/license10.html
9  */
12 @comment (
13   Revision 1.2  89/02/20  13:08:52
14   Fixed copyright notice to not interfere w/ comment syntax.
15   
16   Revision 1.1  89/02/20  13:02:10
17   Initial revision
18   
19   Revision 1.2  89/01/30  09:49:04
20   Added copyright notice
21   )
22 @comment(From template)
23 @device{postscript}
24 @make{report}
25 @style[size 12, indent 0, spread 1 line, fontfamily timesroman, References=IEEE]
26 @modify[subheading, size +0]
27 @define[F, facecode f, tabexport]
28 @modify[verbatim, facecode t, above 2 lines]@Comment[I use verbatim]
29                                             @Comment[later with a]
30                                             @Comment[different size]
31 @tabset[8 characters]
33 @comment(This is a special macro I use for indexing)
34 @textform(indexed="@parm(text)@index(@parm(text))")
36 @begin(comment)
37             --Old Header stuff--
38     @device(postscript)
39     @make(manual, form 1)
40     @style(indent 0)
41     @style(font TimesRoman)
43     @begin(titlepage)
44     @begin(titlebox)
45     @Majorheading(Authentication Server)
47     @heading(Prepared for the Nationwide File System Workshop)
48     @heading(August 23-24, 1988)
49     @end(titlebox)
50     @end(titlepage)
51 @end(comment)
53 @Chapter(Authentication Server)
54                                              
55 @begin(abstract, above 2)
57 We define a @b(Kerberos) based authentication server.  In the @b(Andrew)
58 system, clients communicate with servers using an RPC package called RX.
59 RX contains support for using Kerberos tickets to provide security
60 for parameters passed between client and server.  The authentication
61 server maintains a database of registered identities for whom it can
62 create tickets.  The tickets and their associated session keys are
63 safely delivered to a user community supported by public workstations
64 and interconnection networks.  The Data Encryption Standard is used to
65 provide privacy and integrity from attack in this insecure environment.
66 @end(abstract)
68 @b(PLEASE NOTE: This chapter contains @i(preliminary) information on a
69 program that has not been used in service.  The details of the design,
70 especially including the interface specifications, are @i(subject to
71 change) without notice.)
73 @Section[Overview]
75 The Authentication Server, or AuthServer, is a program that runs on one
76 or more machines in a @i(distributed workstation environment).  In such
77 an environment it is common for a collection of server processes to
78 provide facilities to the network community that are not available to
79 individual workstations.  In a large community a formal mechanism to
80 confidently identify clients to servers and visa versa is necessary.
81 The AuthServer mediates this identification process.  It provides
82 information to the server that allows it to name its client.  Conversely
83 the client can be confident he is in communication with the desired
84 server, and not with a Trojan Horse.  This identification is not perfect
85 but can be relied upon given certain assumptions about the security of
86 the network, the integrity of the human administrators, and the
87 crytographic effort that might be expended to forge an identification.
89 The basis of authentication in this system is a @i(@indexed(shared secret))
90 known by both parties in a communication.  This secret is usually called
91 a @i(key)@index(key), or sometimes an @indexed(Encryption Key), or
92 @indexed(password).  A simple protocol can be used by each side to
93 determine that the other truly does know the correct key without
94 actually sending the key across the network.  The @i[Data Encryption
95 Standard (DES)]@index(Data Encryption Standard)@index(DES) is used to
96 provide this determination, although other key based encryption systems
97 could be used as well.  The AuthServer provides the client, directly,
98 and the server, indirectly, with the shared secret which they use to
99 identify each other.
101 To deliver keys to the client and server the AuthServer must use an
102 untrustworthy communication channel.  Because of this fundamental
103 problem, each identity, including both clients and servers, must be
104 registered with the AuthServer through secure means.  Generally, this
105 involves a face-to-face meeting with a new user and a system
106 administrator to establish a user name and initial password.  Such a
107 registered user is called a principal identity, or just a
108 @i(@indexed[principal)].  The password is used to generate an encryption
109 key which is used in all further transactions; the password itself is
110 discarded.  The user should change his password periodically and can do
111 so without the intervention of a system administrator.
113 The key, known only to the user and the AuthServer, is then used to
114 @i(mutually authenticate)@index(mutual authentication) any client-server
115 pair.  The basic algorithm is quite simple.  The client calls the
116 AuthServer with the name of the server it wishes to contact and a random
117 number which has been encrypted with the client's password.  The
118 AuthServer decrypts the packet with the client's password, which it
119 knows, to obtain the random number.  It then looks up the password of
120 the server and creates a @i[@indexed(ticket)] encrypted with that
121 password containing the client's name and a @i(@indexed(session key)).
122 Then the AuthServer creates a packet for return to the client which
123 contains the random number, the session key, and the ticket prepared for
124 the desired server, all encrypted with the client's password.  Note that
125 this packet contains two copies of the session key: one encrypted with
126 the client's password and one encrypted twice: first with the server's
127 password then with the client's password.  This @indexed(session key)
128 will be the secret shared by the client and server when they establish
129 communications.
131 The client decrypts the packet returned from the AuthServer.  He checks
132 the random number to see that it matches the one he sent.  If it does,
133 he can be sure the AuthServer is genuine and really knows his password.
134 The client saves the session key and delivers the ticket, which he can
135 not interpret, to the server when the connection is opened.  The server
136 decrypts the ticket and verifies that the user name it contains is
137 allowed to use its service.  The session key can be used to encrypt
138 communication between the two.  The server knows who his client is
139 because his name was in the ticket encrypted by the AuthServer.  The
140 client knows he is in communication with the real server since the
141 server was able to obtain the session key from the the ticket created by
142 the AuthServer.  The parties can work in privacy, both confident of the
143 identity of the other: @b(secure mutually authenticated communication).
145 In practice a slightly more complicated system is employed for creating
146 server tickets.  The process of getting a ticket for a server is divided
147 into two steps.  The first involves contacting the AuthServer using the
148 protocol outlined above.  This produces a ticket, called the AuthTicket,
149 to an intermediate server called the Ticket Granting Service (TGS).
150 The second step is to contact the TGS, using the AuthTicket as proof of
151 authentication, to obtain a ticket for the desired server.  This second
152 step may be repeated many times during a login session to get tickets
153 for various servers as they are needed.  The advantage of dividing the
154 process this way is that the user's password is used only for the first
155 step.  Since the AuthTicket has a lifetime of a few hours, it is a
156 smaller security risk to keep it in memory for the duration of a login
157 session than to keep a password for the same period.
159 The design of this system has borrowed heavily from the work of Needham
160 and Schroeder@cite(Needham&Schroeder) on using encryption in an insecure
161 network environment.  A good deal of effort has gone into making the
162 system compatible with Kerberos@cite(Kerberos).  Many ideas have been
163 adapted from their work, especially the format of the tickets and much
164 of their terminology.  In this paper we refer to @i(@indexed(cells))
165 which are broadly equivalent to the @i(@indexed(realms)) of Kerberos.
166 We have mostly adopted the name @i(@indexed(ticket)), but earlier
167 descriptions of the Andrew system referred to them as
168 @i(@indexed(tokens)).  The term tokens is used here to refer to a
169 structure containing a ticket and the associated session key.
171 @Section(Assumptions)
173 The security and reliability of the AuthServer depends on several
174 assumptions about its environment.  Making these assumptions explicit
175 should help prevent security violations or other problems caused by
176 inadvertently changing some aspect of the system on which the AuthServer
177 relies.  In this section we cover all the parts of the system that are
178 unusual or critical to correct operation.
180 It is critical to the secure operation of the AuthServer that the
181 computer on which it runs is @indexed(physically secure)@index(secure
182 machine).  There are many ways to compromise the integrity of the
183 AuthServer if access to the hardware is possible.  Many of these are
184 difficult to combat or even detect.  Providing physical security is an
185 established technique with well known advantages and well understood
186 weaknesses.
188 To obtain the many advantages of multiprocessing, the AuthServer is
189 usually run as a distributed process on several machines.  Each of these
190 machines must be physically secure, but in addition, the connection
191 between them must also be secure@index(secure interconnect).  This is
192 not as important as physical protection of the machines, but allows much
193 more efficient, unencrypted communication between the processes
194 comprising the AuthServer.  After a crash, for instance, when the
195 individual processes are attempting to resynchronized their versions of
196 the database, considerable quantities of data may have to be exchanged.
197 If it is impossible to provide protection for this interconnection
198 network there are still measures that might be taken to insure safe
199 communication, including data compression or providing fast encryption
200 hardware to the machines supporting the AuthServer.
202 The connection between the AuthServer's machines and the rest of the
203 system, including both servers and clients, is not required to be
204 secure@index(insecure interconnect).  The protocols used to establish
205 and maintain communication between the AuthServer and clients and
206 between clients and servers attempts to protect against all types of
207 attacks on the interconnection network.  In addition, the physical
208 security of neither the client nor server machines is depended upon, as
209 they may be owned and operated by individuals or groups throughout the
210 user community@index(insecure machines).
212 The protocols also depend upon a small degree of @indexed(time
213 synchrony).  This is used to detect stale or replayed messages which may
214 be used in an attack on system security.  Since excellent
215 synchronization is often unrealistic, this protocol assumes that clocks
216 on different machines are within fifteen minutes of each
217 other@index(clock skew).  This requirement is only important for
218 changing passwords, since this is an operation with a side-effect.  This
219 synchronization limit means that a user who changed his password twice
220 within fifteen minutes could have it changed back by an attacker
221 replaying his first change request.
223 The security of the system critically depends on the security of user's
224 passwords@index(secure passwords).  Most users are notoriously bad at
225 keeping their passwords safe and this is usually the largest source of
226 security problems in any system.  These problems, however, are limited
227 to the compromise of individual users.  Individuals with access to
228 sensitive data or important facilities
229 need to be especially careful about their passwords.  The problem of managing
230 @indexed(server passwords) is much more critical@index(passwords,
231 server).  The ability to reboot a server, without human intervention to
232 enter the server's password, is very important for operating a large
233 system that needs to provide good availability.  To accomplish this,
234 server passwords are stored on the local, and hence physically secure,
235 disk.  This approach is a reasonable interim solution but one which has
236 many potential risks.  More work is needed on this problem.  The
237 AuthServer simply assumes that all passwords are safe.
239 A related problem is the possibility of a @indexed(Trojan Horse)
240 replacing the standard login program.  Since fetching the login program
241 over the network usually precedes the authentication process there is no
242 protection from having a rogue file server supply a copy of login that
243 steals passwords.  The same general problem applies to booting a
244 workstation from a network server.  These problems are not addressed by
245 the AuthServer and are assumed to be controlled in other ways.
247 There are also software packages used to provide basic services to the
248 AuthServer.  These are the @indexed(RPC) package for connecting the
249 AuthServer to its clients and the @indexed(Ubik) package for providing a
250 reliable database manager, both of which are described else where.  The
251 AuthServer also assumes the existence of a key based @indexed(encryption
252 package).  The assumption is that this package implements @indexed(DES),
253 but any equivalent system that provides enough security to satisfy the
254 requirements of the installation is sufficient.
256 @Section(Security Considerations)
258 The basic @indexed(authentication) problem has two parts: establishing
259 identity and defeating attempts to forge identities.  The latter almost
260 totally dictates the details of the process.  The job of establishing
261 the identity of the user is simply a matter of determining whether or
262 not a user knows the password associated with a principal.  This could
263 be as simple as having the user sit down at a terminal and type in his
264 name and password which is then sent over the network to the AuthServer.
265 To provide security in a potentially hostile environment various
266 counter-measures must be taken to prevent a user's password from being
267 revealed and to prevent one user from masquerading as another.  The
268 basic source of security loopholes comes from the fact that both the
269 local workstations and the network that connects them to the AuthServer
270 are easily accessible to an attacker.  These weaknesses are, however, a
271 intrinsic part of a distributed workstation environment so the design of
272 the protocols takes them into account.
274 @SubSection(Security through Encryption)
276 The security problems are primarily addressed by encrypting sensitive
277 messages with DES@index(encryption).  The choice of key and the details
278 of the message contents vary according to the situation.  The
279 @indexed(DES) algorithm has various features that are important to its
280 use in authentication@cite(Meyer&Matyas).
281 @begin(itemize)
283 It has a relatively compact, eight byte @indexed(key) that can be formed
284 from several convenient sources such as passwords, or random numbers.
286 Data of any length can be encrypted and decrypted given the key, but it
287 is very difficult to do either without the key.  The data must be
288 padded@index(padding) to a multiple of eight bytes.  The standard method
289 of encrypting a sequence of data longer than eight bytes is called
290 @indexed(cipher block chaining).  This method uses some data from the
291 encryption of the previous eight byte chunk to encrypt the current
292 chunk.  This means that a change to a message will affect the
293 translation of all subsequent data in the message.
295 The key must be kept hidden.
296 @end(itemize)
298 The basic paradigm for achieving @indexed(mutual authentication)
299 involves exchanging messages that can be recognized as correct when
300 decrypted using the shared secret as the key.  The properties of DES are
301 such that without knowledge of the key, it is not feasible to create a
302 properly encrypted message, nor to decrypt a message to reveal anything
303 intelligible.  The choice of the message contents results from a
304 consideration of the various methods of attack that the system must with
305 protect itself against.
307 @SubSection(Methods of Attack)
309 The attacks that the design attempts to cope with fall into these
310 categories:
312 @begin(text, break,continue,leftmargin +0.5in)
313 @begin(Description)
315 @indexed(eavesdropping)@\This assumes that an attacker can listen in on a
316 conversation and obtain private information.  This include both
317 intercepting keys or passwords, which would be very serious, to just
318 snooping on the contents of personal files.
320 @indexed(tampering)@\This is modification of data, either in transit or by
321 intercepting a packet, altering it and reinjecting it into the network.
323 @indexed(replay)@\This is where old packets are reinsert into the network in an
324 attempt to deceive the recipient.  The advantage of this approach is that
325 the attacker does not need full knowledge of the innards of the packets.
326 This is conceptually similar to tampering except that it assumes that
327 the original packet was received, or that the delay between interception
328 and reinjection is relatively long.
330 @indexed(server misrepresentation)@\This is a specific case of a
331 @indexed(Trojan Horse) where an attacker pretends to be a server.  This
332 is where mutual authentication is important.
334 @indexed(cryptographic attack)@\Besides using a encryption algorithm
335 blessed by the @indexed(National Security Agency) (DES), little attempt
336 is made to worry about this.
338 @end(Description)
339 @end(text)
341 @indexed(Eavesdropping) implies that anything sent over the network can
342 be read.  This means that sensitive data must be encrypted when sent
343 over the network.  This primarily means keys.
345 Encryptions can also be used to detect @indexed(tampering).  The data to
346 be protected must be encrypted even though the data itself is not
347 sensitive.  If an encrypted message is tampered with the decryption
348 process will tend to scramble it in ways impossible for the attacker to
349 predict.  With suitable consistency checks on the decrypted message
350 tampering can be detected and such messages rejected.  The overall
351 effect of encryption to prevent tampering is that the recipient can
352 assume that the data in a message is internally consistent.
354 @indexed(Replay) attacks can be defeated in one of two ways.  Either the
355 communication includes a timestamp that causes old messages to be
356 rejected, or the message includes an identifier specified by the
357 recipient in an earlier message.  The advantage of timestamps is that
358 they are easy to use; a single test by the server can detect a replayed
359 message.  The disadvantage is that the inevitable skew between the
360 clocks of different machines and the routing delays imposed by the
361 network puts a lower bound on the delay that can be detected by
362 rejecting messages with ``old'' timestamps.  Since may systems contain
363 clock skews of several minutes this test for ``old''ness can not be made
364 very rigorous.
366 Using a handshaking algorithm that exchanges identifiers has the
367 advantage that the identifiers are only used once and so after a
368 transaction has completed that identifier if encountered in a replayed
369 message will always be rejected.  The problem is that the protocol for
370 exchanging identifiers is more complex.
371 The basic scenario is as follows:
372 @begin(example)
373 @f(client): @t[{r@-{1} = random()}@+(key)] -->
374 @><-- @t[{r@-(1)+1, r@-(2) = random()}@+(key)] :@f(server)
375 @end(example)
376 At this point the client knows that the server is real, but the
377 server is still not sure about the client.  Since the transaction is
378 initiated by the client he gets the first information back.  It takes
379 one more message:
380 @begin(example)
381 @f(client): @t[{r@-(2)+1}@+(key)] -->
382 @end(example)
383 to convince the server and complete the @indexed(mutual authentication).
385 An additional safeguard against replay is to test the source of each
386 packet against the host the previous packet came from and make sure that
387 all packets are from the same host.  This would make hijacking an
388 ongoing connection more difficult.  There are several problems with
389 using the host address, including the fact that the hardware that
390 inserts the host address may be altered to fake any desired return
391 address, and the user may intentionally change hosts from time to time
392 which would limit the strictness of this test to the lifetime of a
393 single connection.
395 The problem of @indexed(server misrepresentation) is resolved whenever
396 mutual authentication happens before sensitive data is exchanged.
397 Alternatively, if sensitive data is encrypted, and assuming incorrect
398 decryption can be detected with consistency checks, then illegitimate
399 servers can be rejected without authentication.  In this case the
400 encrypted data transfer accomplishes the authentication.
402 Protection from @indexed(cryptographic attack) is beyond the scope of this
403 mechanism.  It is implicitly assumed that anyone prepared to do a
404 serious cryptographic attack on DES encrypted data in this system can
405 have whatever he can get.  Any data so sensitive that this might be a
406 problem should be subject to additional safety measures.  No such data
407 should be stored in the Andrew File System.
409 Several simple design rules should serve to make such attacks more
410 difficult.  The goal of these rules is not to give away any more
411 information than necessary.
412 @begin(itemize)
414 Keep messages short.
416 Make the contents of an encrypted message as difficult to predict as
417 possible.
419 Put the most random data at the front of the message so that the cipher
420 block chaining will randomize the encrypted text as much as possible.
422 Do not repeat an encrypted message more often that strictly necessary.
424 Do not provide ``free'' samples of encrypted text.
425 @end(itemize)
427 @Section(Database)
429 The raison d'@ovp(^)etre of the AuthServer is the database it maintains.
430 The database provides the mapping from user names to
431 passwords@index(password mapping), and is the only repository for user
432 passwords in the system.  The inconvenience caused by its loss or
433 compromise is so large that considerable effort must be made to insure
434 that neither happens.
436 @SubSection(Requirements)
438 In addition to storing information, the AuthServer also supports two
439 modes of access.  The most common is looking up the password for a user
440 name.  This is required for every initial authentication operation (part
441 of login) and is performed twice, once for the user and once for the
442 server, during every @i(get ticket) operation.  A @i(get ticket) must be
443 done for every server contacted by a user.  During peak periods the
444 database may be required to perform as many as 100 name to password
445 mappings per minute.  Since this is a read-only operation, multiple
446 AuthServers can easily access a replicated database with very high
447 throughput.
449 The second mode of access allows system administrators to update the
450 database: adding new users, deleting old ones, setting the password of a
451 user who forgot his, etc.  The mode also allows users to change their
452 own passwords.  These operations mostly require write access; with a
453 distributed database this can involve considerable overhead.
454 Fortunately, these operations are considerably less frequent, perhaps
455 1000 per month, although registering an entire freshman class might
456 require 1000 updates at a time.  This operation could be done overnight
457 and take several hours without inconveniencing anyone.
459 @SubSection(Principals and Passwords)
461 Following the standards established by @indexed(Kerberos), user
462 names are actually composed of two parts: a @indexed(name) and
463 an @indexed(instance).  Together these identify a responsible agent that
464 is known to the system.  The convention is that the name will
465 identify a person and the instance will be used as a modifier: perhaps
466 naming the group he is a member of (e.g. class_of_93) or the project he
467 is working on.  The instances will likely reflect some locally defined
468 administrative grouping that may be used for accounting and/or access
469 control.
471 The AuthServer makes no interpretation of the meaning of either part of
472 a user name; the combination must be unique within the database and both
473 must match exactly for lookup operations.  Since they are always used
474 together they can be referred to collectively as a @indexed(principal)
475 or informally as a user name.  Both are strings containing any character
476 except null, and not more than 63 characters in length.  The instance
477 may be empty but the name may not.
479 A @indexed(password) is associated with each principal.  For most human
480 users this will be a character string that has been run through a
481 one-way, keyless encryption algorithm that reduces it to an eight byte
482 sequence.  The sequence is used as the @indexed(shared secret) known
483 only to the AuthServer and the user.  The authentication protocols use
484 this secret as a DES encryption key.  It is also, informally, called a
485 password, even though the key is designed to be unrecognizably related
486 to the original password.  DES keys contain only 56 significant bits:
487 the least significant seven bits of each byte.  The original character
488 string password is not stored and, in fact, is never seen by the
489 AuthServer.  Thus a non-human principal (such as a server), that always
490 interacts directly with the AuthServer, may choose his 56 bit key
491 directly and never use a character string password at all.
493 @SubSection(Database Layout)
495 The database consists of a header followed by an array of fixed length
496 entries, one for each principal.  The header contains a
497 @indexed(hashtable) for rapid access to a principal's entry.  The hash
498 function includes both the principal's name and instance.  The header
499 contains other fields: a version number, the free pointer, and some
500 statistics.  For efficiency reasons these statistics only relate to
501 operations that would modify the database in the normal course of
502 operation.  Dynamic statistics like the number of authentications are
503 collected but must be recorded without requiring expensive database
504 updates.
506 Though the principal and his password are the only critical pieces of
507 information stored in the database, several other fields are also
508 maintained for each identity.
510 @begin(text, break,continue,leftmargin +0.5in)
511 @begin(description)
513 flags@\This specifies to the AuthServer several things about an entry:
514 it may be free, it may be an inactive user, or it may be a user with
515 privileged to modify the database.
517 user_expiration@\This is the date that this entry expires.  Any attempt to
518 look up its password after this date will fail.
520 modification_id, modification_time@\As a simple audit mechanism the
521 AuthServer records the principal and date of the last modification to
522 an entry.
524 change_password_time@\@index(change password)This is the date that this
525 principal last changed his own password.
527 max_ticket_lifetime@\This is the maximum lifetime of any ticket issued
528 to this user.
530 key_version@\This version number is attached to tickets encrypted with
531 this principal's key.  In cases where a server may have several keys
532 outstanding, the version number allows him to select the proper key to
533 decrypt the ticket.  The ability to manage multiple keys permits a
534 smooth transition from an old key to a new one.  It also handles the case
535 where a server is registered in several cells with different keys.
536 @end(description)
537 @end(text)
539 @SubSection(Reliable Substrate)
541 The AuthServer's database is implemented using a data abstraction called
542 @indexed(Ubik) that uses multiple processors, replication, and
543 transactions to provide reliable updates to a distributed database.  It
544 can also provides a great deal of parallelism for read-only operations on
545 the database.  Every operation calls Ubik to begin a transaction and
546 lock the database for read or write, as appropriate.  Several callers
547 may hold read locks simultaneously but write locks are exclusive.  If a
548 failure occurs during an operation, the lock is released and the
549 transaction is aborted.  No changes are made to the database by an
550 aborted transaction.  If a transaction successfully completes then the
551 changes are visible everywhere as soon as the lock is released.
553 @Section(Server Organization)
555 The AuthServer is organized into three parts, each of which functions as
556 a logically independent server, all sharing the same database.  These
557 three services cater to different clientele and require different
558 protocols to establish communications.  The first service
559 @indexed(authenticates) users and provides them with a ticket for a
560 @indexed(Ticket Granting Service) (TGS).  Second, the TGS provides
561 authenticated users with tickets for servers they wish to communicate
562 with.  Last is the @indexed(Administrative Service) which allows users
563 specially known to the AuthServer to update the database.
565 @SubSection(User Authentication)
567 There are two functions in this service: @i(@indexed[authentication])
568 and @i(@indexed[change password]).  Both make no assumptions about the
569 user's current identity, and therefore require the user to supply his
570 password explicitly.  Authentication is the term for the process which
571 makes a user known to the system when he first logs in.  A program (e.g.
572 login) contacts the AuthServer on the user's behalf and engages in the
573 authentication protocol which requires knowledge of the user's password.
574 Once the AuthServer is confident of the identity of the user, it returns
575 a ticket for the TGS and a session key.  This ticket is typically valid
576 for many hours and is used throughout a login session.  The possession of
577 this ticket, and the ability to encrypt data using the session key
578 created with it, is evidence of authentication.
580 The authentication service also allows a user to change his own
581 password.  A user can change his password periodically without the need
582 to go through a system administrator.  For reasons of security this
583 procedure requires the user to supply his password, even though he may
584 be authenticated at the time.  This prevents someone from walking up to
585 a workstation and changing the password of whoever is logged in.
587 @SubSection(Ticket Granting Service)
589 The @indexed(Ticket Granting Service) provides one very simple function.
590 It creates tickets that will be recognized as valid by any server whose
591 principal is registered with the AuthServer.  The prospective client
592 presents his authentication ticket along with the name of the server he
593 wishes to contact.  If the ticket is valid and the server is known the
594 TGS creates and returns a new ticket for that server which the client
595 can use.
597 @SubSection(Administrative Functions)
599 The @indexed(Administrative Service) is used to perform all the
600 functions necessary to maintain the AuthServer database.  A ticket for
601 this service needs to be obtained from the TGS.  In that sense, this is
602 an ordinary server just like any other.  The @indexed(RPC) protocol
603 assures the server that the client principal extracted from the ticket
604 is really the identity using the connection.  But the server is still
605 responsible for verifying that the client is allowed to use the service.
606 In this case the client's entry in the AuthServer database must mark it
607 as a privileged user.  Once this is verified the requested operation
608 can be performed.
610 These are the operations supported by the administrative service of the
611 AuthServer.  Any requests that need a user name require both a name and
612 instance.  Passwords are eight byte sequences and are assumed to be
613 directly usable as DES encryption keys.
615 @begin(Description)
617 CreateUser@\This registers a new principal given a name and password.
619 DeleteUser@\This deletes an existing principal.
621 SetFields@\This sets miscellaneous parameters of a user's entry.
623 SetPassword@\This allows the password for a user to be explicitly set.
624 This is very useful if a user forgets his password.
626 ListEntry@\Repeated calls return the names of all the registered users.
628 GetEntry@\This returns the contents of the database entry for a user,
629 including the principal that last modified the entry.
631 GetStats@\This returns the static statistics from the database, as well
632 as the number of users with admin privileges.
633 @end(Description)
635 @Section(Authentication Protocols)
637 The design of the protocols used by the AuthServer has not been
638 finalized.  The protocols described here use the timestamp method of
639 foiling replay.  There are several complicated trade-offs to be made
640 between efficiency and safety.  Although an attempt has been made to
641 take the security considerations outlined earlier into account not all
642 designs will be equally good in all situations.
644 The protocol involves the exchange of messages between a client and the
645 server.  An exchange takes the form of an unauthenticated @indexed(RPC)
646 call.  Each call passes a set of arguments to the AuthServer and accepts
647 some output values in return.  The caller passes his name and instance
648 in the clear but the important part of the protocol is the format of the
649 encrypted byte sequences. These are the last two arguments to the
650 procedure: the @t(request) sent by the caller and the @t(answer)
651 returned by the AuthServer.
653 These sequences are described by a list enclosed in curly braces.
654 Each item inside the braces is inserted into a byte sequence in the
655 order specified.  Integers, unless otherwise specified, are 32 bits long
656 and are packed in network byte order.  String constants are fixed length
657 and do not include a trailing null.  A superscripted identifier
658 following the close brace specifies a key used to encrypt the sequence.
660 @SubSection(Authentication)
662 To obtain the initial @indexed(authentication) ticket the @t(request)
663 and @t(answer) sequences are as follows:
664 @begin(Example, size -1)
665 @f(Authenticate):
666   request: @t[{t@-(1), "gTGS"}@+(K@-(client))]
667   answer:  @t[{t@-(1)+1, K@-(session), ticket length, ticket, "tgsT"}@+(K@-(client))]
668 @end(Example)
670 where:
671 @begin(text,leftmargin +0.5in,break,continue)
672 @begin(description)
673 @t[t@-(1)]@\is the time the client initiates the request.
675 @t[K@-(client)]@\is the client's key.
677 @t[K@-(session)]@\is a key created by the AuthServer to be used for
678 encrypting communications authenticated with the ticket.
680 @t(ticket length)@\is the length of the ticket in bytes.
682 @t[ticket]@\is used to authenticate a connection to the TGS.  The format of
683 tickets is described on page @pageref(ticket description).
684 @end(description)
685 @end(text)
687 If there is an authentication failure (e.g. the request was encrypted
688 with the wrong key) the RPC call will return an error code.  Otherwise, the client
689 decrypts the response and checks @t[t@-(1)+1] and the string @t["tgsT"]
690 to make sure the packet was decrypted properly and that the AuthServer
691 correctly interpreted the request.  This verifies that the AuthServer is
692 genuine.  Then the @t(K@-(session)) and the @t(ticket) are saved for
693 later use.
695 @SubSection(Changing Passwords)
697 The protocol for changing passwords is similar.
698 @begin(Example, size -1)
699 @f(ChangePassword)
700   request: @t[{t@-(1), K@-(new), kvno, "CPW"}@+(K@-(client))]
701   answer:  @t[{t@-(1)+1, "Pass"}@+(K@-(client))]
702 @end(Example)
704 where:
705 @begin(text,leftmargin +0.5in,break,continue)
706 @begin(description)
707 @t[t@-(1)]@\is the time the client initiates the request.
709 @t[K@-(client)]@\is the client's old key.
711 @t[K@-(new)]@\is the key corresponding to the user's new password.
713 @t(kvno)@\is a @b(one byte) key identifier associated with the key.  It
714 will be included in any ticket created by the AuthServer encrypted with
715 this key.
716 @end(description)
717 @end(text)
719 The client's response is the the same as before.  Note that both request
720 and response are encrypted with the user's old key.  If any failure
721 occurs, the user assumes his password was not changed since either the
722 AuthServer did not recognize the request as valid or the AuthServer was
723 not genuine.
725 @SubSection(Ticket Based Authentication)
727 All ticket based authentication is mediated through the @indexed(RPC)
728 facility called RX.  On the client end, RX is supplied with a
729 procedure which it will call periodically to get the @indexed(session
730 key) and ticket for a connection.  On the server end, RX is supplied
731 with a procedure that is called periodically with the @indexed(ticket)
732 provided by the client and from which it must extract the session key by
733 decrypting the ticket with its password.  Once this process is complete
734 both ends of the RX connection have access to the session key and
735 the rest of the transaction can proceed with encryption.  Both the input
736 and output arguments to an RPC interface procedure on an encrypted
737 connection are transmitted after encryption begins and so are passed safely.
738 The details of providing secure connections with RX are discussed in
739 section @ref(RXSECURITY).
741 @Section(Interface)
743 The interface to the AuthServer has four basic parts.  The most
744 primitive but complete interface is the set of RPC procedures that
745 connect to the server itself.  In addition there are three facets of the
746 AuthServer each of which has an interface that makes it easier to use
747 and integrate into existing programs.  These are the client interface,
748 the server interface and the administration interface.
750 Several data types are common to many of these routines.  The
751 principal's name, instance, and cell are all strings which are limited
752 to 63 characters plus a terminating null.  Passwords are always passed
753 in their one-way encrypted form as a type @t(EncryptionKey) implemented
754 as an array of eight bytes.  It should be emphasized that the key version
755 number (@t(@indexed(kvno))) is a single byte.  The value of the version
756 number must be between zero and 127; the values 128 through 255 are
757 reserved.  Absolute time values are passed as a type @t(Date) which is
758 implemented as a 32 bit unsigned integer.
760 Unless otherwise specified all these routines return an error code.  By
761 convention a zero means an error has occurred and both positive and
762 negative values are used to report errors.
764 @SubSection(AuthServer)
766 The procedures that form the RPC interface to the AuthServer are described
767 below.  In addition to the data types described above several others are
768 used by these interface routines.  The encrypted sequences @t(request)
769 and @t(answer), used by the authentication protocol described above, are
770 passed in as the type @t(CBS) and returned with the type @t(BBS).  These
771 are structures describing byte sequences, including length information,
772 that RX knows how to transfer.
774 The administrative functions operate on sensitive data and therefore
775 require that the caller be a privileged user.  A privileged user is one
776 whose AuthServer database entry has been marked as such.  To use the
777 administrative functions the caller requests a ticket for the server
778 called @t("AuthServer.Admin"); a ticket of this type is called an
779 AdminTicket.  When this ticket is presented to the AuthServer by RX at
780 the beginning of a call, the database entry of the caller is consulted.
781 If the @t(flags) field is not set to indicate a privileged user an error
782 is returned immediately.  The AuthServer counts the number of users who
783 are identified as privileged and if the number is not at least one this
784 check is not performed.  This allows the database to be initialized using
785 the standard facilities before any privileged users have been defined.
787 Unless otherwise specified, any modification to a database entry also
788 records the modification time and the principal of the user making the
789 change.  This allows a minimal auditing capability.
791 The @t(GetEntry) and @t(GetStats) procedures return information in the
792 form of structures.  To allow future versions of the server to coexist
793 with older software a major and minor version number are associated with
794 the server interface.  A change in the major version number will mean
795 that recompilation will be necessary because size or other incompatible
796 changes have been made.  Minor version number changes will indicate that
797 upward compatible changes have been made and recompilation may be
798 advisable but not necessary.  The major version number is an input
799 parameter to these two routines and they will return an error if it is
800 not correct.  The returned structures include the minor version number
801 which can be checked and a warning issued if it is different than
802 expected.
804 This interface does not provide any way to salvage the database or to
805 resize the hashtable, although one will probably be required eventually.
806 The database manager Ubik will need additional hooks to make this possible.
808 @define(indentedtext=text, below 1.5, leftmargin +0.5in)
809 @define(interface=verbatim, size -1)
811 @paragraph(User Authentication)
812 @begin(interface)
813 @f(Authenticate)
814   (IN string name, IN string instance,
815    IN Date start_time, IN Date end_time,
816    IN struct CBS request, INOUT struct BBS *answer)
817 @end(interface)
818 @begin(indentedtext)
820 Calling this routine invokes the authentication protocol described
821 earlier.  It uses the @t(name) and @t(instance) to look up the user's
822 key in the database.  The key allows the @t(request) to be decrypted
823 and, if it is properly formed, a ticket is created.  The ticket and
824 newly invented a session key are assembled into the @t(answer),
825 encrypted with the key, and returned.  This ticket is referred to as the
826 AuthTicket.  The lifetime of the ticket is specified by @t(start_time)
827 and @t(end_time), although the actual expiration time may be earlier if
828 the requested interval exceeds the @t(max_ticket_lifetime) field of the
829 user's AuthServer entry.  This request does not modify the database.
830 @end(indentedtext)
832 @begin(interface)
833 @f(ChangePassword)
834   (IN string name, IN string instance,
835    IN struct CBS request, INOUT struct BBS *answer)
836 @end(interface)
837 @begin(indentedtext)
839 This call invokes the protocol for changing passwords described above.
840 The encryption key used for both the @t(request) and @t(answer)
841 sequences is the old one.  The new key takes effect as soon a the lock
842 associated with this operation is released.  This request modifies the
843 database but instead of updating the modification data a separate field
844 called @t(change_password_time) is set.
845 @end(indentedtext)
847 @paragraph(Ticket Granting Service)
849 @begin(interface)
850 @f(GetTicket)
851   (IN string name, IN string instance,
852    IN Date start_time, IN Date end_time, OUT Date *exp_time,
853    INOUT struct BBS *okey, INOUT struct BBS *oticket)
854 @end(interface)
855 @begin(indentedtext)
857 This call requires an RPC connection encrypted with the AuthTicket.  As
858 long as that ticket is valid, the @t(name) and @t(instance) of a server
859 are used to create a ticket and associated session key for that server.
860 The desired lifetime of the ticket is specified by @t(start_time) and
861 @t(end_time).  The actual lifetime of the returned ticket is constrained
862 by a combination of factors.  The @t(max_ticket_lifetime) field of the
863 user's AuthServer entry provides an upper bound.  The same field in the
864 server's entry also provides a limit.  Lastly, the expiration time of
865 the AuthTicket must be no earlier than the expiration time of any ticket
866 created from it.  All these constraints reduce the expiration time, the
867 @t(start_time) is unaffected.  The time actually inserted in the ticket
868 is returned as @t(exp_time).  The new ticket is returned in @t(oticket)
869 and its session key is returned in @t(okey).  This operation does not
870 modify the database.
871 @end(indentedtext)
873 @paragraph(Administration Functions)
875 @begin(interface)
876 @f(CreateUser)
877   (IN string name, IN string instance, IN EncryptionKey password)
878 @end(interface)
879 @begin(indentedtext)
881 This adds a user to the database.  The key version number will be zero.
882 The user's flags and maximum ticket lifetime will be set to default
883 values.  The registration will not have an expiration time.  The
884 modification data is set.  This call requires an RPC connection
885 encrypted with an AdminTicket.
886 @end(indentedtext)
888 @begin(interface)
889 @f(DeleteUser) (IN string name, IN string instance)
890 @end(interface)
891 @begin(indentedtext)
893 This removes a user from the AuthServer database.  This call requires an RPC connection
894 encrypted with an AdminTicket.
895 @end(indentedtext)
897 @begin(interface)
898 @f(SetFields)
899   (IN string name, IN string instance,
900    IN long flags, IN Date user_expiration,
901    IN long max_ticket_lifetime)
902 @end(interface)
903 @begin(indentedtext)
905 This procedure alters the miscellaneous parameters associated with a
906 user.   The @t(flags) field can be set to one of three values.
907 @begin(text,leftmargin +0.5in)
908 @begin(description)
909 normal@\This is the default state: a regular user.
911 admin@\This user is privileged and can modify the AuthServer database.
913 inactive@\This makes the entry a placeholder.  The user is not deleted
914 but authentication attempts will fail.
915 @end(description)
916 @end(text)
918 The @t(user_expiration) is the time after which attempts to authenticate
919 as this user will fail.  The @t(max_ticket_lifetime) can be set to limit
920 the lifetime of an authentication ticket created for a user.  This call
921 requires an RPC connection encrypted with an AdminTicket.
922 @end(indentedtext)
924 @begin(interface)
925 @f(SetPassword)
926   (IN string name, IN string instance,
927    IN char kvno, IN EncryptionKey password)
928 @end(interface)
929 @begin(indentedtext)
931 The key and key version number of the user are set to the provided
932 values.  This call requires an RPC connection encrypted with an
933 AdminTicket.
934 @end(indentedtext)
936 @begin(interface)
937 @f(ListEntry)
938   (IN long previous_index, OUT long *index,
939    OUT long *count, OUT kaident *name)
941 #define MAXKANAMELEN 64
942 struct kaident {
943   char name[MAXKANAMELEN];
944   char instance[MAXKANAMELEN];
946 @end(interface)
947 @begin(indentedtext)
949 This routine provides a way to step through all the entries in the
950 database.  The first call should be made with @t(previous_index) set to
951 zero.  The function returns @t(count), which is an estimate of the
952 number of entries remaining to be returned, and @t(index), which should
953 be passed in as @t(previous_index) on the next call.  Each call which
954 returns a non-zero @t(index) also returns a structure @t(kaident), which
955 gives the name and instance of an entry.  A negative @t(count), or a
956 non-zero return code indicates that an error occurred.  A zero @t(index)
957 means there were no more entries.  A zero @t(count) means the last entry
958 has been returned.  This call does not modify the database and requires
959 an RPC connection encrypted with an AdminTicket.
960 @end(indentedtext)
962 @begin(interface)
963 @f(GetEntry)
964   (IN string name, IN string instance,
965    IN long major_version, OUT struct kaentryinfo *entry)
967 struct kaentryinfo {
968   long          minor_version;
969   long          flags;
970   Date          user_expiration;
971   Date          modification_time;
972   kaident       modification_user;
973   Date          change_password_time;
974   long          max_ticket_lifetime;
975   long          key_version;
976   EncryptionKey key;
977   long          reserved[4];
979 @end(interface)
980 @begin(indentedtext)
982 This routine returns information about an entry.  If the major_version
983 does not match that in use by the server the call returns an error code.
984 This request does not modify the database.  This call requires an RPC
985 connection encrypted with an AdminTicket.
986 @end(indentedtext)
988 @begin(interface)
989 @f(GetStats)
990   (IN long major_version, OUT long *admin_accounts,
991    OUT struct kasstats *statics, OUT struct kadstats dynamics)
992 @end(interface)
993 @begin(indentedtext)
995 This routine returns statistics about the AuthServer and its database.
996 If the major_version does not match that used by the server the call
997 returns an error code.  The database is not modified.  This call
998 requires an RPC connection encrypted with an AdminTicket.  The
999 statistics interface is not completely specified.  Additional facilities
1000 are needed to monitor the dynamic behavior of the AuthServer as a
1001 program running on a distributed multiprocessor.
1002 @end(indentedtext)
1004 @comment{
1005 The DES description isn't appropriate here!
1006 @paragraph(DES Interface)
1008 There are also several routines that different parts of the
1009 Authentication system will need and are described here.  They are not
1010 part of the AuthServer but are available in a library.
1012 @begin(interface)
1013 @f(des_set_key) (key, schedule)
1014   EncryptionKey *key;
1015   Key_schedule   schedule;
1016 @end(interface)
1017 @begin(indentedtext)
1019 This creates a key schedule from an encryption key.  This does some
1020 processing on the key that is needed for every block encrypted.
1021 @end(indentedtext)
1023 @begin(interface)
1024 @f(des_encrypt) (input, output, length, schedule, encrypt)
1025   char        *input;
1026   char        *output;
1027   int          length;
1028   Key_schedule schedule;
1029   int          encrypt;
1030 @end(interface)
1031 @begin(indentedtext)
1033 This takes an @t(input) string @t(length) bytes long and either encrypts
1034 it using cipher block chaining if the parameter @t(encrypt) is non-zero
1035 or decrypts it otherwise.  The length should be a multiple of eight
1036 bytes, if it is not the input will be padded with zeros.  The @t(output)
1037 is always a multiple of eight bytes in length.  The @t(schedule)
1038 provides the key, as transformed by @t(des_set_key), for the conversion.
1039 @end(indentedtext)
1041 @begin(interface)
1042 @f(des_random_key) (key)
1043   EncryptionKey *key;
1044 @end(interface)
1045 @begin(indentedtext)
1047 This generates a random number from the current time in a format
1048 compatible with encryption keys.  The @t(des_set_key) procedure must be
1049 called before this key can be used to encrypt data.
1050 @end(indentedtext)
1052 @begin(interface)
1053 @f(des_string_to_key) (password, key)
1054   char          *password;
1055   EncryptionKey *key;
1056 @end(interface)
1057 @begin(indentedtext)
1059 This routine takes a password string, as might be entered by a user, and
1060 converts it, via a one-way encoding algorithm into an encryption key.
1061 This is a key, not a schedule, so @t(des_set_key) must be called before
1062 any encryption can be performed.
1063 @end(indentedtext)
1066 @SubSection(Client facilities)
1068 These two routine are used to simplify writing user interface programs
1069 that contact the AuthServer on behalf of a user.
1071 @begin(interface)
1072 @f(C_ParseLoginName) (login, name, instance, cell)
1073   IN  char *login;
1074   OUT char  name[MAXKANAMELEN];
1075   OUT char  instance[MAXKANAMELEN];
1076   OUT char  cell[MAXKANAMELEN];
1077 @end(interface)
1078 @begin(indentedtext)
1080 This defines a simple syntax to allow a user to specify his identity
1081 with a single string.  This string, @t(login), is parsed and the
1082 @t(name), @t(instance), and @t(cell) are returned.  They must be
1083 allocated by the caller to their maximum length.  The syntax is very
1084 simple: the first dot (@t('.')) separates the name from the instance and
1085 the first atsign (@t('@')) begins the cell name.  A backslash (@t('\'))
1086 can be used to quote these special characters.  A backslash followed by
1087 an octal digit (zero through seven) introduces a three digit octal
1088 number which is interpreted as the ascii value of a single character.
1089 @end(indentedtext)
1091 @begin(interface)
1092 @f(C_ReadPassword) (key)
1093   OUT EncryptionKey *key;
1094 @end(interface)
1095 @begin(indentedtext)
1097 This reads a password from the terminal, taking precautions like turning
1098 off echoing that are possible, and performs the one-way encoding on it
1099 to produce an encryption key.
1100 @end(indentedtext)
1102 The following routines implement a proposed @i(@indexed(ticket cache))
1103 which manages the tickets needed for secure communication with servers
1104 using RX.  It is initialized by calling @t(TC_Authenticate) with the
1105 user's name and password obtained using the above procedures.  This will
1106 contact the AuthServer to get the AuthTicket.  Whenever a ticket is
1107 requested for a server, the cache is consulted and, if necessary, a new
1108 one is obtained using the AuthTicket.
1110 @begin(interface)
1111 @f(TC_Authenticate) (name, instance, cell, key, exp_time)
1112   IN char          *name;
1113   IN char          *instance;
1114   IN char          *cell;
1115   IN EncryptionKey *key;
1116   IN Date           exp_time;
1117 @end(interface)
1118 @begin(indentedtext)
1120 This routine initializes the ticket cache manager.  The parameters are
1121 used to contact the AuthServer in the specified @t(cell) and obtain an
1122 AuthTicket which is inserted in the ticket cache.  This ticket may be
1123 retrieved later by requesting a token for the special server called
1124 @t("AuthServer.TGS").
1125 @end(indentedtext)
1127 @begin(interface)
1128 @f(TC_ForgetTokens) ()
1129 @end(interface)
1130 @begin(indentedtext)
1132 This routine flushes all the entries from the ticket cache.  It leaves
1133 the user completely unauthenticated.  This would be appropriate if a
1134 logged in workstation was going to be left unattended for a significant
1135 period.
1136 @end(indentedtext)
1138 @begin(interface)
1139 @f(TC_GetServerToken) (name, instance, cell, stoken)
1140   IN  char  *name;
1141   IN  char  *instance;
1142   IN  char  *cell;
1143   OUT token *stoken;
1145 #define MAXKATICKETLEN 217
1146 struct token {
1147   EncryptionKey session_key;
1148   long          ticket_length;
1149   char          ticket[MAXKATICKETLEN];
1150 };      
1151 @end(interface)
1152 @begin(indentedtext)
1154 This procedure asks the ticket cache for a ticket to the server
1155 specified by the @t(name), @t(instance), and @t(cell).  If one is not
1156 available, it is obtained using the AuthTicket provided earlier.  The
1157 @t(stoken) returned contains all the information needed by RX to provide
1158 security on a connection with that server.
1159 @end(indentedtext)
1161 @begin(interface)
1162 @f(TC_GetTokenInfo) (previous_index, index, info)
1163   IN  long        previous_index;
1164   OUT long       *index;
1165   OUT token_info *info;
1167 struct token_info {
1168   char name[MAXKANAMELEN];
1169   char instance[MAXKANAMELEN];
1170   char cell[MAXKANAMELEN];
1171   Date expiration;
1172 @end(interface)
1173 @begin(indentedtext)
1175 This is used to extract information about the tickets in the ticket
1176 cache.  Repeatedly calling this routine, starting with
1177 @t(previous_index) set to zero, and subsequently set to the value of
1178 @t(index) returned by the last call, will return information about all
1179 tickets stored by the ticket cache.
1180 @end(indentedtext)
1182 This client interface does not provide a secure channel for transmitting
1183 tickets to a different workstation.  Such a facility is needed to
1184 support the sharing of computational resources.  One possibility is to
1185 define a compute server that would accept a ticket from a client and
1186 create a process on its machine with an already initialized ticket
1187 cache.
1189 @SubSection(Server facilities)
1191 This is a proposed interface for use by servers who need the
1192 authentication or encryption facilities provided by the AuthServer.  It
1193 is intended to interface directly to RX and also provides a
1194 convenient way to manage keys.
1196 @begin(interface)
1197 @f(S_InitializeKeys) (keyfile, encryption_level, user_ok);
1198   IN char *keyfile;
1199   IN int   encryption_level;
1200   IN int (*user_ok)();
1201 @end(interface)
1202 @begin(indentedtext)
1204 This routine initializes the handling of RX connections that require the
1205 use of tickets.  The @t(keyfile) specifies a file, which the the server
1206 can trust, in which the keys used by the server are maintained.  The
1207 @t(encryption_level) is passed to the RX security facility and specifies
1208 the type of encryption desired.  The @t(user_ok) parameter points to a
1209 function provided by the server which is called when a new connection
1210 from a client is made.  It is passed the name, instance, and cell of the
1211 client, as well as the key version number of the ticket.  The function
1212 will be called during the authentication process as a test to see if the
1213 client is acceptable to the server.  A return value of zero mean the
1214 client is @b(not) acceptable and non-zero means the user is ok.  If this
1215 test function is not supplied (the pointer is null) then it is assumed
1216 that the server will call @t(S_GetClient) once the connection is
1217 established to decide later if the client is allowed to use the
1218 service.
1219 @end(indentedtext)
1221 @begin(interface)
1222 int @f(user_ok) (name, instance, cell, kvno)
1223   IN char *name;
1224   IN char *instance;
1225   IN char *cell;
1226   IN char  kvno;
1227 @end(interface)
1228 @begin(indentedtext)
1230 This routine may be provided by the server, and if provided, is called
1231 when a new connection is established with the identity of the client.
1232 If the client is acceptable to the server a non-zero value should be
1233 returned.  If the client is to be rejected a zero value is returned.
1234 @end(indentedtext)
1236 @begin(interface)
1237 @f(S_GetClient) (conn, name, instance, cell, kvno)
1238   IN  r_connection *conn;
1239   OUT char         *name;
1240   OUT char         *instance;
1241   OUT char         *cell;
1242   OUT char         *kvno;
1243 @end(interface)
1244 @begin(indentedtext)
1246 This routine is called with the connection passed to an RPC interface
1247 routine.  If the @t(S_InitializeKeys) was called without a @t(user_ok)
1248 test function then this procedure will return the authenticated
1249 information about the client using this connection.  This information is
1250 stored in addition to the normal connection data so if this facility is
1251 not needed @t(user_ok) should be used instead.  The @t(name),
1252 @t(instance), and @t(cell) are all strings that must be allocated by the
1253 caller to their maximum length.  The @t(kvno) parameter points to a
1254 single byte which is extracted from the ticket and indicates which
1255 server key was used to decrypt it.
1256 @end(indentedtext)
1258 @begin(interface)
1259 @f(S_AddKey) (key, kvno, category, max_age, deleted)
1260   IN  EncryptionKey *key;
1261   IN  char           kvno;
1262   IN  char          *category;
1263   IN  long           max_age;
1264   OUT int           *deleted;
1265 @end(interface)
1266 @begin(indentedtext)
1268 This routine can be called from time to time during a server's operation
1269 to add a new key to its repertoire.  Each @t(key) is identified by a
1270 @t(kvno) and it is an error to reuse a key version number still known to
1271 this package.  The @t(key) is remembered in the file whose name was
1272 specified in the @t(S_InitializeKeys) call.  The @t(category) is an
1273 arbitrary string used to define groups of keys.  For instance, if a
1274 server has keys known to different cells the name of the cell could be
1275 used as the category.  The @t(max_age) parameter instructs the procedure
1276 to expunge any key in the same category which was added more than
1277 @t(max_age) seconds ago.  The number of old keys removed is returned in
1278 the parameter @t(deleted).  This is intended to be used for routine key
1279 changes to remove the obsolete keys.  If the interval of key changes is
1280 a week then specifying a @t(max_age) of slightly over a week will keep
1281 the only two most recent keys.
1282 @end(indentedtext)
1284 @begin(interface)
1285 @f(S_GetKey) (category, key)
1286   IN  char          *category;
1287   OUT EncryptionKey *key;
1288 @end(interface)
1289 @begin(indentedtext)
1291 This routine returns the most recent @t(key) associated with the
1292 specified @t(category).
1293 @end(indentedtext)
1295 @paragraph(Ticket Format)
1296 @label(TicketDescription)
1298 If the server implements his own RPC interface he will have to
1299 understand the ticket format.  The tickets are intended to be compatible
1300 with the format used by Kerberos.  It is described in a style similar to
1301 that used previously for describing the authentication protocol.
1303 @begin(interface)
1304 {kvno, {flags, K@-{session}, name@-{p}, instance@-{p}, cell@-{p},
1305         address@-{p}, starttime, endtime, label}@+{K@-{s@-{kvno}}}}
1306 @end(interface)
1308 where:
1310 @begin(text,leftmargin +0.5in)
1311 @begin(description)
1312 @t(kvno)@\1 byte: identifies the encryption key to the server
1314 @t(flags)@\1 byte: flag bits; reserved.
1316 @t(K@-{session})@\8 bytes: an EncryptionKey created for use with this ticket.
1318 @t(name@-{p})@\> 0 chars, null terminated string: principal of user
1319 requesting this ticket.
1321 @t(instance@-{p})@\>= 0 chars, null terminated string
1323 @t(cell@-{p})@\>= 0 chars, null terminated string: cell where principal
1324 is authenticated.  If empty the cell is same as the one in which the
1325 server is authenticated.
1327 @t(address@-{p})@\4 bytes: IP address of principal's host.
1329 @t(starttime)@\4 bytes: time ticket becomes valid
1331 @t(endtime)@\4 bytes: time ticket expires
1333 @t(label)@\>= 2 chars: a string to verify correct decryption.  This
1334 label uses at least two characters of the string "TicketEnd" and enough
1335 additional characters to pad the length of the encrypted part of the
1336 ticket to a multiple of eight bytes.
1338 @t(K@-{s@-{kvno}})@\8 bytes: Server's key specified by @t(kvno).
1339 @end(description)
1340 @end(text)
1342 @SubSection(Database Administration)
1344 The administrative function will take two forms.  For small changes to
1345 the database an interactive program will allow a system administrator to
1346 performs the various functions provided by the AuthServer RPC interface.
1347 For larger operations, such as registering an entire freshman class, a
1348 batch facility will take a file of new user identities to create and old
1349 ones to delete.  A more sophisticated interface that might provide
1350 search commands such as ``list all users who have not changed their
1351 passwords in more than six months'' would be desirable but has yet to be
1352 defined.
1354 @Section(References)
1356 @bibliography