6843e69b69c56ee0d2fd93fb4528be590ea537cc
[ikiwiki.git] / docs / handbook / handbook-kerberos5.mdwn
1
2
3 ## Kerberos5 
4
5
6
7 ***Contributed by Tillman Hodgson. Based on a contribution by Mark Murray. ***
8
9
10
11 The following information only applies to  **Kerberos5** . Users who wish to use the  **KerberosIV**  package may install the [security/krb4](http://pkgsrc.se/security/krb4) port.
12
13
14
15  **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.
16
17
18
19  **Kerberos**  can be described as an identity-verifying proxy system. It can also be described as a trusted third-party authentication system.  **Kerberos**  provides only one function -- the secure authentication of users on the network. It does not provide authorization functions (what users are allowed to do) or auditing functions (what those users did). After a client and server have used  **Kerberos**  to prove their identity, they can also encrypt all of their communications to assure privacy and data integrity as they go about their business.
20
21
22
23 Therefore it is highly recommended that  **Kerberos**  be used with other security methods which provide authorization and audit services.
24
25
26
27 The following instructions can be used as a guide on how to set up  **Kerberos**  as distributed for DragonFly. However, you should refer to the relevant manual pages for a complete description.
28
29
30
31 For purposes of demonstrating a  **Kerberos**  installation, the various namespaces will be handled as follows:
32
33
34
35
36 * The DNS domain (***zone***) will be example.org.
37
38
39 * The  **Kerberos**  realm will be EXAMPLE.ORG.
40
41
42
43  **Note:** Please use real domain names when setting up  **Kerberos**  even if you intend to run it internally. This avoids DNS problems and assures inter-operation with other  **Kerberos**  realms.
44
45
46
47 ### History 
48
49
50
51  **Kerberos**  was created by MIT as a solution to network security problems. The  **Kerberos**  protocol uses strong cryptography so that a client can prove its identity to a server (and vice versa) across an insecure network connection.
52
53
54
55  **Kerberos**  is both the name of a network authentication protocol and an adjective to describe programs that implement the program ( **Kerberos**  telnet, for example). The current version of the protocol is version 5, described in RFC 1510.
56
57
58
59 Several free implementations of this protocol are available, covering a wide range of operating systems. The Massachusetts Institute of Technology (MIT), where  **Kerberos**  was originally developed, continues to develop their  **Kerberos**  package. It is commonly used in the US as a cryptography product, as such it has historically been affected by US export regulations. The MIT  **Kerberos**  is available as a port ([`security/krb5`](http://pkgsrc.se/security/krb5)). Heimdal  **Kerberos**  is another version 5 implementation, and was explicitly developed outside of the US to avoid export regulations (and is thus often included in non-commercial UNIX® variants). The Heimdal  **Kerberos**  distribution is available as a port ([`security/heimdal`](http://pkgsrc.se/security/heimdal)), and a minimal installation of it is included in the base DragonFly install.
60
61
62
63 In order to reach the widest audience, these instructions assume the use of the Heimdal distribution included in DragonFly.
64
65
66
67 ### Setting up a Heimdal KDC 
68
69
70
71 The Key Distribution Center (KDC) is the centralized authentication service that  **Kerberos**  provides -- it is the computer that issues  **Kerberos**  tickets. The KDC is considered ***trusted*** by all other computers in the  **Kerberos**  realm, and thus has heightened security concerns.
72
73
74
75 Note that while running the  **Kerberos**  server requires very few computing resources, a dedicated machine acting only as a KDC is recommended for security reasons.
76
77
78
79 To begin setting up a KDC, ensure that your `/etc/rc.conf` file contains the correct settings to act as a KDC (you may need to adjust paths to reflect your own system):
80
81
82
83     
84
85     kerberos5_server_enable="YES"
86
87     kadmind5_server_enable="YES"
88
89     kerberos_stash="YES"
90
91
92
93
94
95 Next we will set up your  **Kerberos**  config file, `/etc/krb5.conf`:
96
97
98
99     
100
101     [libdefaults]
102
103         default_realm = EXAMPLE.ORG
104
105     [realms]
106
107         EXAMPLE.ORG = {
108
109             kdc = kerberos.example.org
110
111         }
112
113     [domain_realm]
114
115         .example.org = EXAMPLE.ORG
116
117
118
119
120
121 Note that this `/etc/krb5.conf` file implies that your KDC will have the fully-qualified hostname of `kerberos.example.org`. You will need to add a CNAME (alias) entry to your zone file to accomplish this if your KDC has a different hostname.
122
123
124
125  **Note:** For large networks with a properly configured BIND DNS server, the above example could be trimmed to:
126
127
128
129     
130
131     [libdefaults]
132
133           default_realm = EXAMPLE.ORG
134
135
136
137
138
139 With the following lines being appended to the `example.org` zonefile:
140
141
142
143     
144
145     _kerberos._udp      IN  SRV     01 00 88 kerberos.example.org.
146
147     _kerberos._tcp      IN  SRV     01 00 88 kerberos.example.org.
148
149     _kpasswd._udp       IN  SRV     01 00 464 kerberos.example.org.
150
151     _kerberos-adm._tcp  IN  SRV     01 00 749 kerberos.example.org.
152
153     _kerberos           IN  TXT     EXAMPLE.ORG.
154
155
156
157
158
159 Next we will create the  **Kerberos**  database. This database contains the keys of all principals encrypted with a master password. You are not required to remember this password, it will be stored in a file (`/var/heimdal/m-key`). To create the master key, run `kstash` and enter a password.
160
161
162
163 Once the master key has been created, you can initialize the database using the `kadmin` program with the `-l` option (standing for ***local***). This option instructs `kadmin` to modify the database files directly rather than going through the `kadmind` network service. This handles the chicken-and-egg problem of trying to connect to the database before it is created. Once you have the `kadmin` prompt, use the `init` command to create your realms initial database.
164
165
166
167 Lastly, while still in `kadmin`, create your first principal using the `add` command. Stick to the defaults options for the principal for now, you can always change them later with the `modify` command. Note that you can use the `?` command at any prompt to see the available options.
168
169
170
171 A sample database creation session is shown below:
172
173
174
175     
176
177     # kstash
178
179     Master key: xxxxxxxx
180
181     Verifying password - Master key: xxxxxxxx
182
183     
184
185     # kadmin -l
186
187     kadmin> init EXAMPLE.ORG
188
189     Realm max ticket life [unlimited]:
190
191     kadmin> add tillman
192
193     Max ticket life [unlimited]:
194
195     Max renewable life [unlimited]:
196
197     Attributes []:
198
199     Password: xxxxxxxx
200
201     Verifying password - Password: xxxxxxxx
202
203
204
205
206
207 Now it is time to start up the KDC services. Run `/etc/rc.d/kerberos start` and `/etc/rc.d/kadmind start` to bring up the services. Note that you won't have any kerberized daemons running at this point but you should be able to confirm that the KDC is functioning by obtaining and listing a ticket for the principal (user) that you just created from the command-line of the KDC itself:
208
209
210
211     
212
213     % k5init `***tillman***`
214
215     tillman@EXAMPLE.ORG's Password:
216
217     
218
219     % k5list
220
221     Credentials cache: FILE:`/tmp/krb5cc_500`
222
223         Principal: tillman@EXAMPLE.ORG
224
225     
226
227       Issued           Expires          Principal
228
229     Aug 27 15:37:58  Aug 28 01:37:58  krbtgt/EXAMPLE.ORG@EXAMPLE.ORG
230
231
232
233
234
235 ### 10.6.3  **Kerberos**  enabling a server with Heimdal services 
236
237
238
239 First, we need a copy of the  **Kerberos**  configuration file, `/etc/krb5.conf`. To do so, simply copy it over to the client computer from the KDC in a secure fashion (using network utilities, such as [scp(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#scp&section1&manpath=OpenBSD+3.3), or physically via a floppy disk).
240
241
242
243 Next you need a `/etc/krb5.keytab` file. This is the major difference between a server providing  **Kerberos**  enabled daemons and a workstation -- the server must have a `keytab` file. This file contains the servers host key, which allows it and the KDC to verify each others identity. It must be transmitted to the server in a secure fashion, as the security of the server can be broken if the key is made public. This explicitly means that transferring it via a clear text channel, such as FTP, is a very bad idea.
244
245
246
247 Typically, you transfer to the `keytab` to the server using the `kadmin` program. This is handy because you also need to create the host principal (the KDC end of the `krb5.keytab`) using `kadmin`.
248
249
250
251 Note that you must have already obtained a ticket and that this ticket must be allowed to use the `kadmin` interface in the `kadmind.acl`. See the section titled ***Remote administration*** in the Heimdal info pages (`info heimdal`) for details on designing access control lists. If you do not want to enable remote `kadmin` access, you can simply securely connect to the KDC (via local console, [ssh(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#ssh&section1&manpath=OpenBSD+3.3) or  **Kerberos**  [telnet(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=telnet&section=1)) and perform administration locally using `kadmin -l`.
252
253
254
255 After installing the `/etc/krb5.conf` file, you can use `kadmin` from the  **Kerberos**  server. The `add --random-key` command will let you add the servers host principal, and the `ext` command will allow you to extract the servers host principal to its own keytab. For example:
256
257
258
259     
260
261     # kadmin
262
263     kadmin> add --random-key host/myserver.example.org
264
265     Max ticket life [unlimited]:
266
267     Max renewable life [unlimited]:
268
269     Attributes []:
270
271     kadmin> ext host/myserver.example.org
272
273     kadmin> exit
274
275
276
277
278
279 Note that the `ext` command (short for ***extract***) stores the extracted key in `/etc/krb5.keytab` by default.
280
281
282
283 If you do not have `kadmind` running on the KDC (possibly for security reasons) and thus do not have access to `kadmin` remotely, you can add the host principal (`host/myserver.EXAMPLE.ORG`) directly on the KDC and then extract it to a temporary file (to avoid over-writing the `/etc/krb5.keytab` on the KDC) using something like this:
284
285
286
287     
288
289     # kadmin
290
291     kadmin> ext --keytab=/tmp/example.keytab host/myserver.example.org
292
293     kadmin> exit
294
295
296
297
298
299 You can then securely copy the keytab to the server computer (using `scp` or a floppy, for example). Be sure to specify a non-default keytab name to avoid over-writing the keytab on the KDC.
300
301
302
303 At this point your server can communicate with the KDC (due to its `krb5.conf` file) and it can prove its own identity (due to the `krb5.keytab` file). It is now ready for you to enable some  **Kerberos**  services. For this example we will enable the `telnet` service by putting a line like this into your `/etc/inetd.conf` and then restarting the [inetd(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#inetd&section8) service with `/etc/rc.d/inetd restart`:
304
305
306
307     
308
309     telnet    stream  tcp     nowait  root    /usr/libexec/telnetd  telnetd -a user
310
311
312
313
314
315 The critical bit is that the `-a` (for authentication) type is set to user. Consult the [telnetd(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#telnetd&section8) manual page for more details.
316
317
318
319 ### Kerberos enabling a client with Heimdal 
320
321
322
323 Setting up a client computer is almost trivially easy. As far as  **Kerberos**  configuration goes, you only need the  **Kerberos**  configuration file, located at `/etc/krb5.conf`. Simply securely copy it over to the client computer from the KDC.
324
325
326
327 Test your client computer by attempting to use `kinit`, `klist`, and `kdestroy` from the client to obtain, show, and then delete a ticket for the principal you created above. You should also be able to use  **Kerberos**  applications to connect to  **Kerberos**  enabled servers, though if that does not work and obtaining a ticket does the problem is likely with the server and not with the client or the KDC.
328
329
330
331 When testing an application like `telnet`, try using a packet sniffer (such as [tcpdump(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#tcpdump&section1)) to confirm that your password is not sent in the clear. Try using `telnet` with the `-x` option, which encrypts the entire data stream (similar to `ssh`).
332
333
334
335 The core  **Kerberos**  client applications (traditionally named `kinit`, `klist`, `kdestroy`, and `kpasswd`) are installed in the base DragonFly install. Note that DragonFly versions prior to 5.0 renamed them to `k5init`, `k5list`, `k5destroy`, `k5passwd`, and `k5stash` (though it is typically only used once).
336
337
338
339 Various non-core  **Kerberos**  client applications are also installed by default. This is where the ***minimal*** nature of the base Heimdal installation is felt: `telnet` is the only  **Kerberos**  enabled service.
340
341
342
343 The Heimdal port adds some of the missing client applications:  **Kerberos**  enabled versions of `ftp`, `rsh`, `rcp`, `rlogin`, and a few other less common programs. The MIT port also contains a full suite of  **Kerberos**  client applications.
344
345
346
347 ### 10.6.5 User configuration files: `.k5login` and `.k5users` 
348
349
350
351 Users within a realm typically have their  **Kerberos**  principal (such as `tillman@EXAMPLE.ORG`) mapped to a local user account (such as a local account named `tillman`). Client applications such as `telnet` usually do not require a user name or a principal.
352
353
354
355 Occasionally, however, you want to grant access to a local user account to someone who does not have a matching  **Kerberos**  principal. For example, `tillman@EXAMPLE.ORG` may need access to the local user account `webdevelopers`. Other principals may also need access to that local account.
356
357
358
359 The `.k5login` and `.k5users` files, placed in a users home directory, can be used similar to a powerful combination of `.hosts` and `.rhosts`, solving this problem. For example, if a `.k5login` with the following contents:
360
361
362
363     
364
365     tillman@example.org
366
367     jdoe@example.org
368
369
370
371
372
373 Were to be placed into the home directory of the local user `webdevelopers` then both principals listed would have access to that account without requiring a shared password.
374
375
376
377 Reading the manual pages for these commands is recommended. Note that the `ksu` manual page covers `.k5users`.
378
379
380
381 ### Kerberos Tips, Tricks, and Troubleshooting 
382
383
384
385
386 * When using either the Heimdal or MIT  **Kerberos**  ports ensure that your `PATH` environment variable lists the  **Kerberos**  versions of the client applications before the system versions.
387
388
389 * Is your time in sync? Are you sure? If the time is not in sync (typically within five minutes) authentication will fail.
390
391
392 * MIT and Heimdal inter-operate nicely. Except for `kadmin`, the protocol for which is not standardized.
393
394
395 * If you change your hostname, you also need to change your `host/` principal and update your keytab. This also applies to special keytab entries like the `www/` principal used for Apache's [`www/mod_auth_kerb`](http://pkgsrc.se/www/mod_auth_kerb).
396
397
398 * All hosts in your realm must be resolvable (both forwards and reverse) in DNS (or `/etc/hosts` as a minimum). CNAMEs will work, but the A and PTR records must be correct and in place. The error message isn't very intuitive: ***`Kerberos5 refuses authentication because Read req failed: Key table entry not found`***.
399
400
401 * Some operating systems that may being acting as clients to your KDC do not set the permissions for `ksu` to be setuid `root`. This means that `ksu` does not work, which is a good security idea but annoying. This is not a KDC error.
402
403
404 * With MIT  **Kerberos** , if you want to allow a principal to have a ticket life longer than the default ten hours, you must use `modify_principal` in `kadmin` to change the maxlife of both the principal in question and the `krbtgt` principal. Then the principal can use the `-l` option with `kinit` to request a ticket with a longer lifetime.
405
406
407 *  **Note:** If you run a packet sniffer on your KDC to add in troubleshooting and then run `kinit` from a workstation, you will notice that your TGT is sent immediately upon running `kinit` -- even before you type your password! The explanation is that the  **Kerberos**  server freely transmits a TGT (Ticket Granting Ticket) to any unauthorized request; however, every TGT is encrypted in a key derived from the user's password. Therefore, when a user types their password it is not being sent to the KDC, it is being used to decrypt the TGT that `kinit` already obtained. If the decryption process results in a valid ticket with a valid time stamp, the user has valid  **Kerberos**  credentials. These credentials include a session key for establishing secure communications with the  **Kerberos**  server in the future, as well as the actual ticket-granting ticket, which is actually encrypted with the  **Kerberos**  server's own key. This second layer of encryption is unknown to the user, but it is what allows the  **Kerberos**  server to verify the authenticity of each TGT.
408
409
410 * You have to keep the time in sync between all the computers in your realm. NTP is perfect for this. For more information on NTP, see [network-ntp.html Section 19.12].
411
412
413 * If you want to use long ticket lifetimes (a week, for example) and you are using  **OpenSSH**  to connect to the machine where your ticket is stored, make sure that  **Kerberos**  `TicketCleanup` is set to `no` in your `sshd_config` or else your tickets will be deleted when you log out.
414
415
416 * Remember that host principals can have a longer ticket lifetime as well. If your user principal has a lifetime of a week but the host you are connecting to has a lifetime of nine hours, you will have an expired host principal in your cache and the ticket cache will not work as expected.
417
418
419 * When setting up a `krb5.dict` file to prevent specific bad passwords from being used (the manual page for `kadmind` covers this briefly), remember that it only applies to principals that have a password policy assigned to them. The `krb5.dict` files format is simple: one string per line. Creating a symbolic link to `/usr/share/dict/words` might be useful.
420
421
422
423 ### Differences with the MIT port 
424
425
426
427 The major difference between the MIT and Heimdal installs relates to the `kadmin` program which has a different (but equivalent) set of commands and uses a different protocol. This has a large implications if your KDC is MIT as you will not be able to use the Heimdal `kadmin` program to administer your KDC remotely (or vice versa, for that matter).
428
429
430
431 The client applications may also take slightly different command line options to accomplish the same tasks. Following the instructions on the MIT  **Kerberos**  web site (http://web.mit.edu/Kerberos/www/) is recommended. Be careful of path issues: the MIT port installs into `/usr/local/` by default, and the ***normal*** system applications may be run instead of MIT if your `PATH` environment variable lists the system directories first.
432
433
434
435  **Note:** With the MIT [`security/krb5`](http://pkgsrc.se/security/krb5) port that is provided by DragonFly, be sure to read the `/usr/local/share/doc/krb5/README.FreeBSD` file installed by the port if you want to understand why logins via `telnetd` and `klogind` behave somewhat oddly. Most importantly, correcting the ***incorrect permissions on cache file*** behavior requires that the `login.krb5` binary be used for authentication so that it can properly change ownership for the forwarded credentials.
436
437
438
439 ### Mitigating limitations found in Kerberos 
440
441
442
443 #### Kerberos is an all-or-nothing approach 
444
445
446
447 Every service enabled on the network must be modified to work with  **Kerberos**  (or be otherwise secured against network attacks) or else the users credentials could be stolen and re-used. An example of this would be  **Kerberos**  enabling all remote shells (via `rsh` and `telnet`, for example) but not converting the POP3 mail server which sends passwords in plaintext.
448
449
450
451 #### Kerberos is intended for single-user workstations 
452
453
454
455 In a multi-user environment,  **Kerberos**  is less secure. This is because it stores the tickets in the `/tmp` directory, which is readable by all users. If a user is sharing a computer with several other people simultaneously (i.e. multi-user), it is possible that the user's tickets can be stolen (copied) by another user.
456
457
458
459 This can be overcome with the `-c` filename command-line option or (preferably) the `KRB5CCNAME` environment variable, but this is rarely done. In principal, storing the ticket in the users home directory and using simple file permissions can mitigate this problem.
460
461
462
463 #### The KDC is a single point of failure 
464
465
466
467 By design, the KDC must be as secure as the master password database is contained on it. The KDC should have absolutely no other services running on it and should be physically secured. The danger is high because  **Kerberos**  stores all passwords encrypted with the same key (the ***master*** key), which in turn is stored as a file on the KDC.
468
469
470
471 As a side note, a compromised master key is not quite as bad as one might normally fear. The master key is only used to encrypt the  **Kerberos**  database and as a seed for the random number generator. As long as access to your KDC is secure, an attacker cannot do much with the master key.
472
473
474
475 Additionally, if the KDC is unavailable (perhaps due to a denial of service attack or network problems) the network services are unusable as authentication can not be performed, a recipe for a denial-of-service attack. This can alleviated with multiple KDCs (a single master and one or more slaves) and with careful implementation of secondary or fall-back authentication (PAM is excellent for this).
476
477
478
479 #### Kerberos Shortcomings 
480
481
482
483  **Kerberos**  allows users, hosts and services to authenticate between themselves. It does not have a mechanism to authenticate the KDC to the users, hosts or services. This means that a trojanned `kinit` (for example) could record all user names and passwords. Something like [`security/tripwire`](http://pkgsrc.se/security/tripwire) or other file system integrity checking tools can alleviate this.
484
485
486
487 ### 10.6.9 Resources and further information 
488
489
490
491
492 * [The  **Kerberos**  FAQ](http://www.faqs.org/faqs/Kerberos-faq/general/preamble.html)
493
494
495 * [Designing an Authentication System: a Dialogue in Four Scenes](http://web.mit.edu/Kerberos/www/dialogue.html)
496
497
498 * [RFC 1510, The  **Kerberos**  Network Authentication Service (V5)](http://www.ietf.org/rfc/rfc1510.txt?number=1510)
499
500
501 * [MIT  **Kerberos**  home page](http://web.mit.edu/Kerberos/www/)
502
503
504 * [Heimdal  **Kerberos**  home page](http://www.pdc.kth.se/heimdal/)
505
506
507
508
509
510
511
512 CategoryHandbook
513
514 CategoryHandbook-security
515