diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/ChangeLog | 24 | ||||
| -rw-r--r-- | doc/admin.texinfo | 18 | ||||
| -rw-r--r-- | doc/build.texinfo | 38 | ||||
| -rw-r--r-- | doc/copyright.texinfo | 2 | ||||
| -rw-r--r-- | doc/definitions.texinfo | 4 | ||||
| -rw-r--r-- | doc/install.texinfo | 82 | ||||
| -rw-r--r-- | doc/krb425.texinfo | 8 | ||||
| -rw-r--r-- | doc/send-pr.texinfo | 6 |
8 files changed, 155 insertions, 27 deletions
diff --git a/doc/ChangeLog b/doc/ChangeLog index 38af2b8..a7b435a 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,27 @@ +2000-06-09 Tom Yu <tlyu@mit.edu> + + * admin.texinfo: Add descriptions of the kadmin {ank,cpw,ktadd} -e + flag. + +2000-06-06 Ken Raeburn <raeburn@mit.edu> + + * install.texinfo: Describe new DNS support, and 3DES upgrade + path. Update "enctypes" config file sample lines. + + * build.texinfo: No kpasswd directory. Describe new configure + options. + + * send-pr.texinfo: Suggest caution regarding tab expansion for + patches. + +2000-06-02 Ken Raeburn <raeburn@mit.edu> + + * definitions.texinfo: Update for 1.2 release. + +2000-05-31 Ken Raeburn <raeburn@mit.edu> + + * krb425.texinfo (libdefaults): Add description of v4_realm. + 1999-09-22 Tom Yu <tlyu@mit.edu> * copyright.texinfo: Update copyright again. diff --git a/doc/admin.texinfo b/doc/admin.texinfo index 2ea716b..b739435 100644 --- a/doc/admin.texinfo +++ b/doc/admin.texinfo @@ -1418,6 +1418,12 @@ security-critical. Sets the key of the principal to the specified string and does not prompt for a password (@code{add_principal} only). @value{COMPANY} does not recommend using this option. + +@item -e @i{enc:salt...} +Uses the specified list of enctype-salttype pairs for setting the key of +the principal. The quotes are necessary if there are multiple +enctype-salttype pairs. This will not function against kadmin daemons +earlier than krb5-1.2. @end table If you want to just use the default values, all you need to do is: @@ -1529,6 +1535,12 @@ Sets the key of the principal to a random value. @item @b{-pw} @i{password} Sets the password to the string @i{password}. @value{COMPANY} does not recommend using this option. + +@item @b{-e} @i{"enc:salt..."} +Uses the specified list of enctype-salttype pairs for setting the key of +the principal. The quotes are necessary if there are multiple +enctype-salttype pairs. This will not function against kadmin daemons +earlier than krb5-1.2. @end table For example: @@ -2001,6 +2013,12 @@ The @code{ktadd} command takes the following switches: use @i{keytab} as the keytab file. Otherwise, @code{ktadd} will use the default keytab file (@code{/etc/krb5.keytab}). +@item @b{-e} @i{"enc:salt..."} +Uses the specified list of enctype-salttype pairs for setting the key of +the principal. The quotes are necessary if there are multiple +enctype-salttype pairs. This will not function against kadmin daemons +earlier than krb5-1.2. + @item -q run in quiet mode. This causes @code{ktadd} to display less verbose information. diff --git a/doc/build.texinfo b/doc/build.texinfo index 78aa8b4..d41b36a 100644 --- a/doc/build.texinfo +++ b/doc/build.texinfo @@ -59,8 +59,8 @@ only need to build Kerberos for one platform, using a single directory tree which contains both the source files and the object files is the simplest. However, if you need to maintain Kerberos for a large number of platforms, you will probably want to use separate build trees for -each platform. We recommend that you look at see @ref{OS -Incompatibilities} for notes that we have on particular operating +each platform. We recommend that you look at @ref{OS +Incompatibilities}, for notes that we have on particular operating systems. @menu @@ -208,7 +208,7 @@ Kerberos and then want to run the KADM5 tests, you will need to re-configure the tree and run @code{make} at the top level again to make sure all the proper programs are built. To save time, you actually only need to reconfigure and build in the directories src/kadmin/testing, -src/lib/rpc, src/lib/kadm5, and src/kpasswd. +src/lib/rpc, src/lib/kadm5. @node Options to Configure, osconf.h, Testing the Build, Building Kerberos V5 @section Options to Configure @@ -301,12 +301,6 @@ default, Kerberos V5 configuration will look for @code{-lnsl} and (see @ref{Solaris versions 2.0 through 2.3}) or fails to pass the tests in @file{src/tests/resolv} you will need to use this option. -@item --enable-shared - -This option will turn on the building and use of shared library objects -in the Kerberos build. This option is only supported on certain -platforms. - @item --with-vague-errors If enabled, gives vague and unhelpful error messages to the client... er, @@ -329,10 +323,30 @@ Tcl. The directory specified by @code{TCLPATH} specifies where the Tcl header file (@file{TCLPATH/include/tcl.h} as well as where the Tcl library should be found (@file{TCLPATH/lib}). +@item --enable-shared + +This option will turn on the building and use of shared library objects +in the Kerberos build. This option is only supported on certain +platforms. + +@item --enable-dns +@itemx --enable-dns-for-kdc +@itemx --enable-dns-for-realm + +Enable the use of DNS to look up a host's Kerberos realm, or a realm's +KDCs. See @x @x @xxxxx. + +@item --enable-kdc-replay-cache + +Enable a cache in the KDC to detect retransmitted messages, and resend +the previous responses to them. This protects against certain types of +attempts to extract information from the KDC through some of the +hardware preauthentication systems. + @end table For example, in order to configure Kerberos on a Solaris machine using -the @samp{suncc} with the optimizer turned on, run the configure +the @samp{suncc} compiler with the optimizer turned on, run the configure script with the following options: @example @@ -465,6 +479,10 @@ was never a problem in using GCC version 2.6.3. In version 3.2 and beyond of the operating system, we have not seen any problems with the native compiler. +@c @node Alpha Tru64 UNIX 5.0 +@c @subsection Alpha Tru64 UNIX 5.0 +@c ... login.krb5 problems + @node BSDI, HPUX, Alpha OSF/1 (Digital Unix) V2.0++, OS Incompatibilities @subsection BSDI diff --git a/doc/copyright.texinfo b/doc/copyright.texinfo index 7ea4758..83fe7ef 100644 --- a/doc/copyright.texinfo +++ b/doc/copyright.texinfo @@ -1,4 +1,4 @@ -Copyright @copyright{} 1985-1999 by the Massachusetts Institute of Technology. +Copyright @copyright{} 1985-2000 by the Massachusetts Institute of Technology. @quotation Export of software employing encryption from the United States of diff --git a/doc/definitions.texinfo b/doc/definitions.texinfo index 079809d..5a5b37c 100644 --- a/doc/definitions.texinfo +++ b/doc/definitions.texinfo @@ -19,8 +19,8 @@ @set RANDOMUSER johndoe @set RANDOMUSER1 jennifer @set RANDOMUSER2 david -@set RELEASE 1.1 -@set PREVRELEASE 1.0 +@set RELEASE 1.2 +@set PREVRELEASE 1.1 @set INSTALLDIR /usr/@value{LCPRODUCT} @set PREVINSTALLDIR @value{INSTALLDIR} @set ROOTDIR /usr/local diff --git a/doc/install.texinfo b/doc/install.texinfo index 8744b0f..05c7d9a 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,14 @@ 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 records in the Domain Name Service. This too is described in +the @value{PRODUCT} System Administrator's Guide. 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 +303,19 @@ 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. 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. + @node Database Propagation, , Hostnames for the Master and Slave KDCs, Realm Configuration Decisions @section Database Propagation @@ -1007,6 +1025,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 +1069,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. @@ -1399,6 +1418,41 @@ 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. +@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 +1476,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 +1532,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:: @@ -1514,6 +1565,11 @@ your @value{PRODUCT} keys encounter only if you dump an AFS database into a Kerberos database @end itemize +For best compatibility with Microsoft Kerberos clients, the +@code{normal} salt type should be listed ahead of other salt types for +the same encryption type in the KDC config file and (when specified) on +the @code{kadmin} command line. + Support for additional encryption types is planned in the future. @contents diff --git a/doc/krb425.texinfo b/doc/krb425.texinfo index e78d4e6..12572e5 100644 --- a/doc/krb425.texinfo +++ b/doc/krb425.texinfo @@ -140,6 +140,14 @@ This subsection allows the administrator to configure exceptions to the default_domain mapping rule. It contains V4 instances (tag name) which should be translated to some specific hostname (tag value) as the second component in a Kerberos V5 principal name. + +@itemx v4_realm +This relation allows the administrator to configure a different +realm name to be used when converting V5 principals to V4 +ones. This should only be used when running separate V4 and V5 +realms, with some external means of password sychronization +between the realms. + @end table @node kdc.conf, , krb5.conf, Configuration Files diff --git a/doc/send-pr.texinfo b/doc/send-pr.texinfo index 9209ffd..7cf9b70 100644 --- a/doc/send-pr.texinfo +++ b/doc/send-pr.texinfo @@ -4,7 +4,11 @@ built and installed @value{PRODUCT}, please use the Bug reports that include proposed fixes are especially welcome. If you do include fixes, please send them using either context diffs or unified -diffs (using @samp{diff -c} or @samp{diff -u}, respectively). +diffs (using @samp{diff -c} or @samp{diff -u}, respectively). Please be +careful when using ``cut and paste'' or other such means to copy a patch +into a bug report; depending on the system being used, that can result +in converting TAB characters into spaces, which makes applying the +patches more difficult. The @code{krb5-send-pr} program is installed in the directory @code{@value{ROOTDIR}/sbin}. |