aboutsummaryrefslogtreecommitdiff
path: root/handbook/kerberos.sgml
blob: bbe2dd5ff7a525aa85525fe02469c6b0a28bc42a (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
<!-- $Id: kerberos.sgml,v 1.2 1995-05-11 22:31:28 jfieber Exp $ -->
<!-- The FreeBSD Documentation Project -->

<sect><heading>Kerberos</heading>

<p><em>Contributed by &a.mark; (based on contribution by &a.md;).</em>

    Kerberos is a network add-on system/protocol that allows users to
    authenticate themselves through the services of a secure server.
    Services such as remote login, remote copy, secure inter-system
    file copying and other high-risk tasks are made considerably safer
    and more controllable.

    The following instructions can be used as a guide on how to
    set up Kerberos as distributed for FreeBSD. However, you should refer
    to the relevant manual pages for a complete description.

    In FreeBSD, the Kerberos is not that from the original 4.4 BSD,
    distribution, but eBones, which had been previously ported to
    FreeBSD 1.1.5.1, and was sourced from outside the USA/Canada,
    and is thus available to system owners outside those countries.

    For those needing to get a legal foreign distribution of this
    software, please <em>DO NOT</em> get it from a USA or Canada site.
    You will get that site in <em>big</em> trouble! A legal copy of this is
    available from <tt>skeleton.mikom.csir.co.za</tt>, which is in South
    Africa.

 <sect1>
 <heading>Creating the initial database</heading>

 <p>This is done on the Kerberos server only. First make sure that your
    don't have any old Kerberos databases around. You should change to the
    directory <tt>/etc/kerberosIV</tt> and check that only the following
    files are present:

<tscreen><verb>
grunt# cd /etc/kerberosIV
grunt# ls
README          krb.conf        krb.realms
</verb></tscreen>

 <p>If any additional files (such as <tt>principal.*</tt> or
    <tt>master_key</tt>) exist, then use the <tt>kdb_destroy</tt>
    command to destroy the old Kerberos database, of if Kerberos
    is not running, simply delete the extra files with <tt>rm</tt>.

    You should now edit the <tt>krb.conf</tt> and <tt>krb.realms</tt>
    files to define your Kerberos realm. In this case the realm will
    be <it>GRONDAR.ZA</it> and the server is <it>grunt.grondar.za</it>.
    We edit or create the <tt>krb.conf</tt> file:

<tscreen><verb>
grunt# cat krb.conf
GRONDAR.ZA
GRONDAR.ZA grunt.grondar.za admin server
CS.BERKELEY.EDU okeeffe.berkeley.edu
ATHENA.MIT.EDU kerberos.mit.edu
ATHENA.MIT.EDU kerberos-1.mit.edu
ATHENA.MIT.EDU kerberos-2.mit.edu
ATHENA.MIT.EDU kerberos-3.mit.edu
LCS.MIT.EDU kerberos.lcs.mit.edu
TELECOM.MIT.EDU bitsy.mit.edu
ARC.NASA.GOV trident.arc.nasa.gov
</verb></tscreen>

 <p>In this case, the other realms do not need to be there.
    They are here as an example of how a machine may be made aware
    of multiple realms. You may wish to not include them for simplicity.

    The first line names the realm in which this system works. The other
    lines contain realm/host entries. The first item on a line is a realm,
    and the second is a host in that realm that is acting as a ``key
    distribution centre''. The words ``admin server'' following a hosts
    name means that host also provides an administrative database server.
    For further explanation of these terms, please consult the Kerberos
    man pages.

    Now we have to add <it>grunt.grondar.za</it> to the <it>GRONDAR.ZA</it>
    realm and also add an entry to put all hosts in the <it>.grondar.za</it>
    domain in the <it>GRONDAR.ZA</it> realm.  The <tt>krb.realms</tt> file
    would be updated as follows:

<tscreen><verb>
 grunt# cat krb.realms
 grunt.grondar.za GRONDAR.ZA
 .grondar.za GRONDAR.ZA
 .berkeley.edu CS.BERKELEY.EDU
 .MIT.EDU ATHENA.MIT.EDU
 .mit.edu ATHENA.MIT.EDU
</verb></tscreen>

 <p>Again, the other realms do not need to be there.
    They are here as an example of how a machine may be made aware
    of multiple realms. You may wish to remove them to simplify things.

    The first line puts the <it>specific</it> system into the named
    realm. The rest of the lines show how to default systems of a
    particular subdomain to a named realm.

    Now we're ready to create the database. This only needs to run on
    the Kerberos server (or Key Distribution Centre). Issue the
    <tt>kdb_init</tt> command to do this:

<tscreen><verb>
grunt# kdb_init
Realm name [default  ATHENA.MIT.EDU ]: GRONDAR.ZA
You will be prompted for the database Master Password.
It is important that you NOT FORGET this password.

Enter Kerberos master key: 
</verb></tscreen>

 <p>Now we have to save the key so that servers on the local
    machine can pick it up.  Use the <tt>kstash</tt> command to
    do this.

<tscreen><verb>
grunt# kstash

Enter Kerberos master key: 

Current Kerberos master key version is 1.

Master key entered.  BEWARE!
</verb></tscreen>

 <p>This saves the encrypted master password in
    <tt>/etc/kerberosIV/master_key</tt>.

 <sect1>
  <heading>Making it all run</heading>

 <p>Two principals need to be added to the database for <it>each</it>
    system that will be secured with Kerberos. Their names are
    <tt>kpasswd</tt> and <tt>rcmd</tt> These two principals are
    made for each system, with the instance being the name of the
    individual system.

    These daemons, <tt>kpasswd</tt> and <tt>rcmd</tt> allow other systems
    to change Kerberos passwords and run commands like <tt>rcp</tt>,
    <tt>rlogin</tt> and <tt>rsh</tt>.

   Now lets add these entries:

<tscreen><verb>
grunt# kdb_edit
Opening database...

Enter Kerberos master key: 

Current Kerberos master key version is 1.

Master key entered.  BEWARE!
Previous or default values are in [brackets] ,
enter return to leave the same, or new value.

Principal name: passwd
Instance: grunt

<Not found>, Create [y] ? y

Principal: passwd, Instance: grunt, kdc_key_ver: 1
New Password:                    <---- enter RANDOM here
Verifying password

New Password:                    <---- enter RANDOM here

Random password [y] ? y

Principal's new key version = 1
Expiration date (enter yyyy-mm-dd) [ 2000-01-01 ] ? 
Max ticket lifetime (*5 minutes) [ 255 ] ? 
Attributes [ 0 ] ? 
Edit O.K.
Principal name: rcmd
Instance: grunt

<Not found>, Create [y] ? 

Principal: rcmd, Instance: grunt, kdc_key_ver: 1
New Password:                    <---- enter RANDOM here
Verifying password

New Password:                    <---- enter RANDOM here

Random password [y] ? 

Principal's new key version = 1
Expiration date (enter yyyy-mm-dd) [ 2000-01-01 ] ? 
Max ticket lifetime (*5 minutes) [ 255 ] ? 
Attributes [ 0 ] ? 
Edit O.K.
Principal name:                  <---- null entry here will cause an exit
</verb></tscreen>

 <sect1>
  <heading>Creating the server file</heading>

 <p>We now have to extract all the instances which define the services
    on each machine.  For this we use the <tt>ext_srvtab</tt> command.
    This will create a file which must be copied or moved <it>by secure
    means</it> to each Kerberos client's /etc/kerberosIV directory. This
    file must be present on each server and client, and is crucial to the
    operation of Kerberos.

<tscreen><verb>
grunt# ext_srvtab grunt

Enter Kerberos master key: 

Current Kerberos master key version is 1.

Master key entered.  BEWARE!
Generating 'grunt-new-srvtab'....
</verb></tscreen>

 <p>Now, this command only generates a temporary file
    which must be renamed to <tt>srvtab</tt> so that all the
    server can pick it up.  Use the <tt>mv</tt> command to move it
    into place on the original system:

<tscreen><verb>
grunt# mv grunt-new-srvtab srvtab
</verb></tscreen>

 <p>If the file is for a client system, and the network is not
    deemed safe, then copy the <tt>&lt;client&gt;-new-srvtab</tt> to
    removeable media and transport it by secure physical means. Be
    sure to rename it to <tt>srvtab</tt> in the client's
    <tt>/etc/kerberosIV</tt> directory, and make sure it is mode 600:

<tscreen><verb>
grumble# mv grumble-new-srvtab srvtab
grumble# chmod 600 srvtab
</verb></tscreen>

 <sect1>
  <heading>Populating the database</heading>

 <p>We now have to add some user entries into the database.
    First lets create an entry for the user <it>jane</it>.  Use
    the <tt>kdb_edit</tt> command to do this:

<tscreen><verb>
grunt# kdb_edit
Opening database...

Enter Kerberos master key: 

Current Kerberos master key version is 1.

Master key entered.  BEWARE!
Previous or default values are in [brackets] ,
enter return to leave the same, or new value.

Principal name: jane
Instance:

<Not found>, Create [y] ? y

Principal: jane, Instance: , kdc_key_ver: 1
New Password:                    <---- enter a secure password here
Verifying password

New Password:                    <---- re-enter the password here

Principal's new key version = 1
Expiration date (enter yyyy-mm-dd) [ 2000-01-01 ] ? 
Max ticket lifetime (*5 minutes) [ 255 ] ? 
Attributes [ 0 ] ? 
Edit O.K.
Principal name:                  <---- null entry here will cause an exit
</verb></tscreen>

 <sect1>
  <heading>Testing it all out</heading>

 <p>First we have to start the Kerberos daemons. NOTE that if you have
    correctly edited your <tt>/etc/sysconfig</tt> then this will happen
    automatically when you reboot. This is only necessary on the Kerberos
    server. Kerberos clients will automagically get what they need from
    the <tt>/etc/kerberosIV</tt> directory.

<tscreen><verb>
grunt# kerberos &
grunt# Kerberos server starting
        Sleep forever on error
        Log file is /var/log/kerberos.log
Current Kerberos master key version is 1.

Master key entered.  BEWARE!

Current Kerberos master key version is 1
Local realm: GRONDAR.ZA
grunt# kadmin -n &
grunt# KADM Server KADM0.0A initializing
Please do not use 'kill -9' to kill this job, use a
regular kill instead

Current Kerberos master key version is 1.

Master key entered.  BEWARE!
</verb></tscreen>

 <p>Now we can try using the <tt>kinit</tt> command to get a ticket for
    the id <it>jane</it> that we created above:

<tscreen><verb>
grunt$ kinit jane
MIT Project Athena (grunt.grondar.za)
Kerberos Initialization for "jane"
Password: 
</verb></tscreen>

 <p>Try listing the tokens using <tt>klist</tt> to see if we really have them:

<tscreen><verb>
grunt$ klist
Ticket file:    /tmp/tkt245
Principal:    jane@GRONDAR.ZA

  Issued           Expires          Principal
Apr 30 11:23:22  Apr 30 19:23:22  krbtgt.GRONDAR.ZA@GRONDAR.ZA
</verb></tscreen>

 <p>Now try changing the password using <tt>passwd</tt> to check if the
    kpasswd daemon can get authorisation to the Kerberos database:

<tscreen><verb>
grunt$ passwd
realm GRONDAR.ZA
Old password for jane:
New Password for jane:
Verifying password
New Password for jane:
Password changed.
</verb></tscreen>

 <sect1>
  <heading>Adding <tt>su</tt> privileges</heading>

 <p>Kerberos allows us to give <it>each</it> user who needs root
    privileges their own <it>separate</it> <tt>su</tt>password. We
    could now add an id which is authorised to <tt>su</tt> to <it>root</it>.
    This is controlled by having an instance of <it>root</it> associated
    with a principal.  Using <tt>kdb_edit</tt> we can create the entry
    <it>jane.root</it> in the Kerberos database:

<tscreen><verb>
grunt# kdb_edit
Opening database...

Enter Kerberos master key: 

Current Kerberos master key version is 1.

Master key entered.  BEWARE!
Previous or default values are in [brackets] ,
enter return to leave the same, or new value.

Principal name: jane
Instance: root

<Not found>, Create [y] ? y

Principal: jane, Instance: root, kdc_key_ver: 1
New Password:                    <---- enter a SECURE password here
Verifying password

New Password:                    <---- re-enter the password here

Principal's new key version = 1
Expiration date (enter yyyy-mm-dd) [ 2000-01-01 ] ? 
Max ticket lifetime (*5 minutes) [ 255 ] ? 12 <--- Keep this short!
Attributes [ 0 ] ? 
Edit O.K.
Principal name:                  <---- null entry here will cause an exit
</verb></tscreen>

 <p>Now try getting tokens for it to make sure it works:

<tscreen><verb>
grunt# kinit jane.root
MIT Project Athena (grunt.grondar.za)
Kerberos Initialization for "jane.root"
Password: 
 </verb></tscreen>

 <p>Now we need to add the user to root's <tt>.klogin</tt> file:

<tscreen><verb>
grunt# cat /root/.klogin
jane.root@GRONDAR.ZA
</verb></tscreen>

 <p>Now try doing the <tt>su</tt>:

<tscreen><verb>
[jane@grunt 10407] su
Password: 
grunt#
      </verb></tscreen>

    and take a look at what tokens we have:

<tscreen><verb>
grunt# klist
Ticket file:	/tmp/tkt_root_245
Principal:	jane.root@GRONDAR.ZA

  Issued           Expires          Principal
May  2 20:43:12  May  3 04:43:12  krbtgt.GRONDAR.ZA@GRONDAR.ZA
</verb></tscreen>

 <sect1>
  <heading>Using other commands</heading>

 <p>In an earlier example, we created a principal called <tt>jane</tt>
    with an instance <tt>root</tt>. This was based on a user with the
    same name as the principal, and this is a Kerberos default; that a
    <em>&lt;principal&gt;.&lt;instance&gt;</em> of the form
    <em>&lt;username&gt;.</em><tt>root</tt> will allow that
    <em>&lt;username&gt;</em> to <tt>su</tt> to root if the necessary
    entries are in the <tt>.klogin</tt> file in <tt>root</tt>'s home
    directory:

<tscreen><verb>
grunt# cat /root/.klogin
jane.root@GRONDAR.ZA
</verb></tscreen>

 <p>Likewise, if a user has in their own home directory lines of the
    form:

<tscreen><verb>
[jane@grunt 10543] cat ~/.klogin
jane@GRONDAR.ZA
jack@GRONDAR.ZA
</verb></tscreen>

 <p>This allows anyone in the <em>GRONDAR.ZA</em> realm who has
    authenticated themselves to <em>jane</em> or <em>jack</em> (via
    <tt>kinit</tt>, see above) access to <tt>rlogin</tt> to <em>jane</em>'s
    account or files on this system (<em>grunt</em>) via <tt>rlogin</tt>,
    <tt>rsh</tt> or <tt>rcp</tt>.

    For example, Jane now logs into another system, using Kerberos:

<tscreen><verb>
[jane@grumble 573] kinit
MIT Project Athena (grunt.grondar.za)
Password: 
[jane@grumble 574] rlogin grunt
Last login: Mon May  1 21:14:47 from grumble
Copyright (c) 1980, 1983, 1986, 1988, 1990, 1991, 1993, 1994
	The Regents of the University of California.   All rights reserved.

FreeBSD BUILT-19950429 (GR386) #0: Sat Apr 29 17:50:09 SAT 1995

[jane@grunt 10567]
</verb></tscreen>

 <p>Or Jack logs into Jane's account on the same machine (Jane having set up
    the <tt>.klogin</tt> file as above, and the person in charge of Kerberos
    having set up principal <em>jack</em> with a null instance:

<tscreen><verb>
[jack@grumble 573] kinit
[jack@grumble 574] rlogin grunt -l jane
MIT Project Athena (grunt.grondar.za)
Password: 
Last login: Mon May  1 21:16:55 from grumble
Copyright (c) 1980, 1983, 1986, 1988, 1990, 1991, 1993, 1994
	The Regents of the University of California.   All rights reserved.

FreeBSD BUILT-19950429 (GR386) #0: Sat Apr 29 17:50:09 SAT 1995

[jane@grunt 10578]
</verb></tscreen>