diff options
Diffstat (limited to 'doc/install.texinfo')
| -rw-r--r-- | doc/install.texinfo | 223 |
1 files changed, 191 insertions, 32 deletions
diff --git a/doc/install.texinfo b/doc/install.texinfo index 8744b0f..2ecd8bd 100644 --- a/doc/install.texinfo +++ b/doc/install.texinfo @@ -229,7 +229,10 @@ BOSTON.@value{SECONDREALM} and HOUSTON.@value{SECONDREALM}. @node Mapping Hostnames onto Kerberos Realms, Ports for the KDC and Admin Services, Kerberos Realms, Realm Configuration Decisions @section Mapping Hostnames onto Kerberos Realms -Mapping hostnames onto Kerberos realms is done through a set of rules in +Mapping hostnames onto Kerberos realms is done in one of two ways. + +The first mechanism, which has been in use for years in MIT-based +Kerberos distributions, works through a set of rules in the @code{krb5.conf} configuration file. (@xref{krb5.conf}.) You can specify mappings for an entire domain or subdomain, and/or on a hostname-by-hostname basis. Since greater specificity takes precedence, @@ -240,7 +243,35 @@ The @value{PRODUCT} System Administrator's Guide contains a thorough description of the parts of the @code{krb5.conf} file and what may be specified in each. A sample @code{krb5.conf} file appears in @ref{krb5.conf}. You should be able to use this file, substituting the -relevant information for your Kerberos instllation for the samples. +relevant information for your Kerberos installation for the samples. + +The second mechanism, recently introduced into the MIT code base but not +currently used by default, works by looking up the information in +special @code{TXT} records in the Domain Name Service. If this +mechanism is enabled on the client, it will try to look up a @code{TXT} +record for the DNS name formed by putting the prefix @code{_kerberos} in +front of the hostname in question. If that record is not found, it will +try using @code{_kerberos} and the host's domain name, then its parent +domain, and so forth. So for the hostname +BOSTON.ENGINEERING.FOOBAR.COM, the names looked up would be: + +@smallexample +_kerberos.boston.engineering.foobar.com +_kerberos.engineering.foobar.com +_kerberos.foobar.com +_kerberos.com +@end smallexample + +The value of the first TXT record found is taken as the realm name. +(Obviously, this doesn't work all that well if a host and a subdomain +have the same name, and different realms. For example, if all the hosts +in the ENGINEERING.FOOBAR.COM domain are in the ENGINEERING.FOOBAR.COM +realm, but a host named ENGINEERING.FOOBAR.COM is for some reason in +another realm. In that case, you would set up TXT records for all +hosts, rather than relying on the fallback to the domain name.) + +Even if you do not choose to use this mechanism within your site, you +may wish to set up anyways, for use when interacting with other sites. @node Ports for the KDC and Admin Services, Slave KDCs, Mapping Hostnames onto Kerberos Realms, Realm Configuration Decisions @section Ports for the KDC and Admin Services @@ -293,11 +324,86 @@ disasters. @section Hostnames for the Master and Slave KDCs @value{COMPANY} recommends that your KDCs have a predefined set of -CNAMEs, such as @code{@value{KDCSERVER}} for the master KDC and +CNAME records (DNS hostname aliases), such as @code{@value{KDCSERVER}} +for the master KDC and @code{@value{KDCSLAVE1}}, @code{@value{KDCSLAVE2}}, @dots{} for the slave KDCs. This way, if you need to swap a machine, you only need to change a DNS entry, rather than having to change hostnames. +A new mechanism for locating KDCs of a realm through DNS has been added +to the @value{COMPANY} @value{PRODUCT} distribution. A relatively new +record type called @code{SRV} has been added to DNS. Looked up by a +service name and a domain name, these records indicate the hostname and +port number to contact for that service, optionally with weighting and +prioritization. (See RFC 2782 if you want more information. You can +follow the example below for straightforward cases.) + +The use with Kerberos is fairly straightforward. The domain name used +in the SRV record name is the domain-style Kerberos realm name. (It is +possible to have Kerberos realm names that are not DNS-style names, but +we don't recommend it for Internet use, and our code does not support it +well.) Several different Kerberos-related service names are used: + +@table @code +@item _kerberos._udp +This is for contacting any KDC. This entry will be used the most often. +Normally you should list ports 88 and 750 on each of your KDCs. + +@item _kerberos-master._udp +This entry should refer to those KDCs, if any, that will immediately see +password changes to the Kerberos database. This entry is used only in +one case, when the user is logging in and the password appears to be +incorrect; the master KDC is then contacted, and the same password used +to try to decrypt the response, in case the user's password had recently +been changed and the first KDC contacted hadn't been updated. Only if +that fails is an ``incorrect password'' error given. + +If you have only one KDC, or for whatever reason there is no accessible +KDC that would get database changes faster than the others, you do not +need to define this entry. + +@item _kerberos-adm._tcp +This should list port 749 on your master KDC. Support for it is not +complete at this time, but it will eventually be used by the +@code{kadmin} program and related utilities. For now, you will also +need the @code{admin_server} entry in @code{krb5.conf}. + +@item _kpasswd._udp +This should list port 464 on your master KDC. It is used when a user +changes her password. + +@end table + +Be aware, however, that the DNS SRV specification requires that the +hostnames listed be the canonical names, not aliases. So, for example, +you might include the following records in your (BIND-style) zone file: + +@smallexample +$ORIGIN foobar.com. +_kerberos TXT "FOOBAR.COM" +kerberos CNAME daisy +kerberos-1 CNAME use-the-force-luke +kerberos-2 CNAME bunny-rabbit +_kerberos._udp SRV 0 0 88 daisy + SRV 0 0 88 use-the-force-luke + SRV 0 0 88 bunny-rabbit +_kerberos-master._udp SRV 0 0 88 daisy +_kerberos-adm._tcp SRV 0 0 749 daisy +_kpasswd._udp SRV 0 0 464 daisy +@end smallexample + +As with the DNS-based mechanism for determining the Kerberos realm of a +host, we recommend distributing the information this way for use by +other sites that may want to interact with yours using Kerberos, even if +you don't immediately make use of it within your own site. If you +anticipate installing a very large number of machines on which it will +be hard to update the Kerberos configuration files, you may wish to do +all of your Kerberos service lookups via DNS and not put the information +(except for @code{admin_server} as noted above) in future versions of +your @code{krb5.conf} files at all. Eventually, we hope to phase out +the listing of server hostnames in the client-side configuration files; +making preparations now will make the transition easier in the future. + @node Database Propagation, , Hostnames for the Master and Slave KDCs, Realm Configuration Decisions @section Database Propagation @@ -421,7 +527,8 @@ encrypted form on the KDC's local disk. The stash file is used to authenticate the KDC to itself automatically before starting the @code{kadmind} and @code{krb5kdc} daemons (@i{e.g.,} as part of the machine's boot sequence). The stash file, like the keytab file -(@xref{The Keytab File}) is a potential point-of-entry for a break-in, +(see @xref{The Keytab File}, for more information) is a potential +point-of-entry for a break-in, and if compromised, would allow unrestricted access to the Kerberos database. If you choose to install a stash file, it should be readable only by root, and should exist only on the KDC's local disk. The file @@ -560,8 +667,8 @@ instance ``root'', you would add the following line to the acl file: Next you need to add administrative principals to the Kerberos database. (You must add at least one now.) To do this, use @code{kadmin.local} @emph{on the master KDC}. The administrative principals you create -should be the ones you added to the ACL file (see @xref{Add -Administrators to the Acl File}). In the following example, the +should be the ones you added to the ACL file. (See @xref{Add +Administrators to the Acl File}.) In the following example, the administration principal @code{admin/admin} is created: @smallexample @@ -639,8 +746,8 @@ to the KDC's @code{/etc/rc} or @code{/etc/inittab} file. You need to have a stash file in order to do this. You can verify that they started properly by checking for their startup -messages in the logging locations you defined in @code{/etc/krb5.conf} -(see @xref{Edit the Configuration Files}). For example: +messages in the logging locations you defined in @code{/etc/krb5.conf}. +(See @xref{Edit the Configuration Files}.) For example: @smallexample @b{shell%} tail /var/log/krb5kdc.log @@ -909,7 +1016,7 @@ Once your KDCs are set up and running, you are ready to use @code{kadmin} to load principals for your users, hosts, and other services into the Kerberos database. This procedure is described fully in the ``Adding or Modifying Principals'' section of the @value{PRODUCT} System -Administrator's Guide. (@xref{Create Host Keys for the Slave KDCs} for a +Administrator's Guide. (@xref{Create Host Keys for the Slave KDCs}, for a brief description.) The keytab is generated by running @code{kadmin} and issuing the @code{ktadd} command. @@ -987,7 +1094,11 @@ Disable the cron job that propagates the database. @item Run your database propagation script manually, to ensure that the slaves all have the latest copy of the database. (@xref{Propagate the Database -to Each Slave KDC}.) +to Each Slave KDC}.) As of the 1.2.2 release, it is no longer necessary +to use ``kdb5_util dump -ov'' in order to preserve per-principal policy +information, as the default dump format now supports it. Note you +should update your slaves prior to your master, so that they will +understand the new dump format. (This is a good policy anyway.) @end enumerate On the @emph{new} master KDC: @@ -1007,6 +1118,7 @@ Database to Each Slave KDC}.) Switch the CNAMEs of the old and new master KDCs. (If you don't do this, you'll need to change the @code{krb5.conf} file on every client machine in your Kerberos realm.) + @end enumerate @node Installing and Configuring UNIX Client Machines, UNIX Application Servers, Installing KDCs, Installing Kerberos V5 @@ -1050,7 +1162,7 @@ counterparts @c @code{from} @code{su}, @code{passwd}, and @code{rdist}. -@node Client Machine Configuration Files, Mac OS X Configuration, Client Programs, Installing and Configuring UNIX Client Machines +@node Client Machine Configuration Files, , Client Programs, Installing and Configuring UNIX Client Machines @subsection Client Machine Configuration Files Each machine running Kerberos must have a @code{/etc/krb5.conf} file. @@ -1357,27 +1469,29 @@ should be readable only by root. If you already have an existing Kerberos database that you created with a prior release of Kerberos 5, you can upgrade it to work with the -current release with the @code{kdb5_util} command. The process for -upgrading a Master KDC involves the following steps (the lines beginning -with => indicate a continuation of the previous line): +current release with the @code{kdb5_util} command. It is only necessary +to perform this dump/undump procedure if you were running a krb5-1.0.x +KDC and are migrating to a krb5-1.1.x or newer KDC. The process for +upgrading a Master KDC involves the following steps: @enumerate -@item Stopping your current KDC and administration +@item Stop your current KDC and administration server processes, if any. -@item Dumping your existing Kerberos database to an ASCII file with +@item Dump your existing Kerberos database to an ASCII file with @code{kdb5_util}'s ``dump'' command: @smallexample @group -@b{shell%} kdb5_util -r @value{PRIMARYREALM} dump -@result{} @value{ROOTDIR}/var/krb5kdc/old-kdb-dump +@b{shell%} cd @value{ROOTDIR}/var/krb5kdc +@b{shell%} kdb5_util dump old-kdb-dump +@b{shell%} kdb5_util dump -ov old-kdb-dump.ov @b{shell%} @end group @end smallexample -@item Creating a new Master KDC installation (@xref{Install the Master +@item Create a new Master KDC installation (@xref{Install the Master KDC}). If you have a stash file for your current database, choose any new master password but then copy your existing stash file to the location specified by your kdc.conf; if you do not have a stash file for @@ -1388,17 +1502,64 @@ your current database, you must choose the same master password. @smallexample @group -@b{shell%} kdb5_util load @value{ROOTDIR}/var/krb5kdc/old-kdb-dump +@b{shell%} cd @value{ROOTDIR}/var/krb5kdc +@b{shell%} kdb5_util load old-kdb-dump +@b{shell%} kdb5_util load -update old-kdb-dump.ov @b{shell%} @end group @end smallexample @end enumerate +The ``dump -ov'' and ``load -update'' commands are necessary in order to +preserve per-principal policy information, since the dump format in +releases prior to 1.2.2 filters out that information. If you omit those +steps, the loaded database database will lose the policy information for +each principal that has a policy. + To update a Slave KDC, you must stop the old server processes on the Slave KDC, install the new server binaries, reload the most recent slave dump file, and re-start the server processes. +@menu +* Upgrading to Triple-DES Encryption Keys:: +@end menu + +@node Upgrading to Triple-DES Encryption Keys, , Upgrading Existing Kerberos V5 Installations, Upgrading Existing Kerberos V5 Installations +@section Upgrading to Triple-DES Encryption Keys + +Beginning with the 1.2 release from MIT, Kerberos includes a stronger +encryption algorithm called ``triple DES'' -- essentially, three +applications of the basic DES encryption algorithm, greatly increasing +the resistance to a brute-force search for the key by an attacker. This +algorithm is more secure, but encryption is much slower. We expect to +add other, faster encryption algorithms at some point in the future. + +Release 1.1 had some support for triple-DES service keys, but with +release 1.2 we have added support for user keys and session keys as +well. Release 1.0 had very little support for multiple cryptosystems, +and some of that software may not function properly in an environment +using triple-DES as well as plain DES. + +Because of the way the MIT Kerberos database is structured, the KDC will +assume that a service supports only those encryption types for which +keys are found in the database. Thus, if a service has only a +single-DES key in the database, the KDC will not issue tickets for that +service that use triple-DES session keys; it will instead issue only +single-DES session keys, even if other services are already capable of +using triple-DES. So if you make sure your application server software +is updated before adding a triple-DES key for the service, clients +should be able to talk to services at all times during the updating +process. + +Normally, the listed @code{supported_enctypes} in @code{kdc.conf} are +all used when a new key is generated. You can control this with +command-line flags to @code{kadmin} and @code{kadmin.local}. You may +want to exclude triple-DES by default until you have updated a lot of +your application servers, and then change the default to include +triple-DES. We recommend that you always include @code{des-cbc-crc} in +the default list. + @node Bug Reports for Kerberos V5, Files, Upgrading Existing Kerberos V5 Installations, Top @chapter Bug Reports for @value{PRODUCT} @@ -1422,8 +1583,8 @@ Here is an example @code{krb5.conf} file: [libdefaults] ticket_lifetime = 600 default_realm = @value{PRIMARYREALM} - default_tkt_enctypes = des-cbc-crc - default_tgs_enctypes = des-cbc-crc + default_tkt_enctypes = des3-hmac-sha1 des-cbc-crc + default_tgs_enctypes = des3-hmac-sha1 des-cbc-crc [realms] @value{PRIMARYREALM} = @{ @@ -1478,17 +1639,14 @@ Here's an example of a kdc.conf file: kadmind_port = 749 max_life = 10h 0m 0s max_renewable_life = 7d 0h 0m 0s - master_key_type = des-cbc-crc - supported_enctypes = des-cbc-crc:normal + master_key_type = des3-hmac-sha1 + supported_enctypes = des3-hmac-sha1:normal des-cbc-crc:normal @} @end group @end smallexample -To add Kerberos V4 support, change the @code{supported_enctypes} line to: - -@smallexample - supported_enctypes = des-cbc-crc:normal des-cbc-crc:v4 -@end smallexample +To add Kerberos V4 support, add @code{des-cbc-crc:v4} to the +@code{supported_enctypes} line. @menu * Encryption Types and Salt Types:: @@ -1497,9 +1655,8 @@ To add Kerberos V4 support, change the @code{supported_enctypes} line to: @node Encryption Types and Salt Types, , kdc.conf, kdc.conf @appendixsubsec Encryption Types and Salt Types -Currently, @value{PRODUCT} supports only DES and triple-DES encryption; -however, triple-DES is currently supported only for service keys, not -for user keys or session keys. The encoding types include +Currently, @value{PRODUCT} supports only DES and triple-DES encryption. +The encoding types include @code{des-cbc-crc} and @code{des3-cbc-sha1}. The @dfn{salt} is additional information encoded within the key that tells what kind of key it is. The only salts that you will be likely to encounter are: @@ -1509,6 +1666,8 @@ key it is. The only salts that you will be likely to encounter are: your @value{PRODUCT} keys @item @dfn{v4}, which is necessary only for compatibility with a v4 KDC +or a v4 version of @code{kinit}, and then only with @code{des-cbc-crc} +encryption @item @dfn{afs}, which you will never need to generate, and which you will encounter only if you dump an AFS database into a Kerberos database |