diff -U 3 -H -d -r -N -x Makefile.in -x 'config.h.in*' -x 'output*' -x requests -x 'traces*' -x '*.loT' -x aclocal.m4 -x configure -- heimdal-1.0.1/configure.in heimdal-1.0.1.work/configure.in --- heimdal-1.0.1/configure.in 2007-08-09 10:47:23.000000000 +0300 +++ heimdal-1.0.1.work/configure.in 2007-12-05 23:58:05.000000000 +0200 @@ -17,7 +17,7 @@ AC_PREFIX_DEFAULT(/usr/heimdal) test "$sysconfdir" = '${prefix}/etc' && sysconfdir='/etc' -test "$localstatedir" = '${prefix}/var' && localstatedir='/var/heimdal' +test "$localstatedir" = '${prefix}/var' && localstatedir='/var' AC_CANONICAL_HOST CANONICAL_HOST=$host @@ -171,6 +171,15 @@ AC_CHECK_XAU +AC_ARG_WITH([dbdir], + [AC_HELP_STRING([--with-dbdir], + [Default location for KDC database @<:@default=${localstatedir}/heimdal@:>@])], + [], + [with_dbdir=$localstatedir/$PACKAGE]) + +DBDIR="$with_dbdir" +AC_SUBST([DBDIR]) + dnl AM_C_PROTOTYPES dnl Checks for typedefs, structures, and compiler characteristics. @@ -505,6 +514,10 @@ packages/Makefile \ packages/mac/Makefile \ doc/Makefile \ + doc/heimdal.info \ + doc/setup.texi \ + lib/krb5/krb5.conf.5 \ + kdc/kstash.8 \ tools/Makefile \ ) diff -U 3 -H -d -r -N -x Makefile.in -x 'config.h.in*' -x 'output*' -x requests -x 'traces*' -x '*.loT' -x aclocal.m4 -x configure -- heimdal-1.0.1/doc/heimdal.info heimdal-1.0.1.work/doc/heimdal.info --- heimdal-1.0.1/doc/heimdal.info 2007-08-09 10:51:03.000000000 +0300 +++ heimdal-1.0.1.work/doc/heimdal.info 1970-01-01 02:00:00.000000000 +0200 @@ -1,3355 +0,0 @@ -This is heimdal.info, produced by makeinfo version 4.7 from -heimdal.texi. - -INFO-DIR-SECTION Security -START-INFO-DIR-ENTRY -* Heimdal: (heimdal). The Kerberos 5 distribution from KTH -END-INFO-DIR-ENTRY - - -File: heimdal.info, Node: Top, Next: Introduction, Prev: (dir), Up: (dir) - -Heimdal -******* - -This manual is last updated $Date: 2007-07-17 13:42:57 +0200 (Tue, 17 -Jul 2007) $ for version 1.0 of Heimdal. - -* Menu: - -* Introduction:: -* What is Kerberos?:: -* Building and Installing:: -* Setting up a realm:: -* Applications:: -* Things in search for a better place:: -* Kerberos 4 issues:: -* Windows 2000 compatability:: -* Programming with Kerberos:: -* Migration:: -* Acknowledgments:: - - --- The Detailed Node Listing --- - -Setting up a realm - -* Configuration file:: -* Creating the database:: -* Modifying the database:: -* keytabs:: -* Serving Kerberos 4/524/kaserver:: -* Remote administration:: -* Password changing:: -* Testing clients and servers:: -* Slave Servers:: -* Incremental propagation:: -* Encryption types and salting:: -* Cross realm:: -* Transit policy:: -* Setting up DNS:: -* Using LDAP to store the database:: -* Providing Kerberos credentials to servers and programs:: -* Setting up PK-INIT:: - -Applications - -* Authentication modules:: -* AFS:: - -Authentication modules - -* Digital SIA:: -* IRIX:: - -Kerberos 4 issues - -* Principal conversion issues:: -* Converting a version 4 database:: -* kaserver:: - -Windows 2000 compatability - -* Configuring Windows 2000 to use a Heimdal KDC:: -* Inter-Realm keys (trust) between Windows 2000 and a Heimdal KDC:: -* Create account mappings:: -* Encryption types:: -* Authorisation data:: -* Quirks of Windows 2000 KDC:: -* Useful links when reading about the Windows 2000:: - -Programming with Kerberos - -* Kerberos 5 API Overview:: -* Walkthrough of a sample Kerberos 5 client:: -* Validating a password in a server application:: -* API differences to MIT Kerberos:: -* File formats:: - - -File: heimdal.info, Node: Introduction, Next: What is Kerberos?, Prev: Top, Up: Top - -1 Introduction -************** - -What is Heimdal? -================ - -Heimdal is a free implementation of Kerberos 5. The goals are to: - - * have an implementation that can be freely used by anyone - - * be protocol compatible with existing implementations and, if not in - conflict, with RFC 4120 (and any future updated RFC). RFC 4120 - replaced RFC 1510. - - * be reasonably compatible with the M.I.T Kerberos V5 API - - * have support for Kerberos V5 over GSS-API (RFC1964) - - * include the most important and useful application programs (rsh, - telnet, popper, etc.) - - * include enough backwards compatibility with Kerberos V4 - -Status -====== - -Heimdal has the following features (this does not mean any of this -works): - - * a stub generator and a library to encode/decode/whatever ASN.1/DER - stuff - - * a `libkrb5' library that should be possible to get to work with - simple applications - - * a GSS-API library - - * `kinit', `klist', `kdestroy' - - * `telnet', `telnetd' - - * `rsh', `rshd' - - * `popper', `push' (a movemail equivalent) - - * `ftp', and `ftpd' - - * a library `libkafs' for authenticating to AFS and a program - `afslog' that uses it - - * some simple test programs - - * a KDC that supports most things; optionally, it may also support - Kerberos V4 and kaserver, - - * simple programs for distributing databases between a KDC master and - slaves - - * a password changing daemon `kpasswdd', library functions for - changing passwords and a simple client - - * some kind of administration system - - * Kerberos V4 support in many of the applications. - -Bug reports -=========== - -If you find bugs in this software, make sure it is a genuine bug and not -just a part of the code that isn't implemented. - -Bug reports should be sent to . Please include -information on what machine and operating system (including version) -you are running, what you are trying to do, what happens, what you -think should have happened, an example for us to repeat, the output you -get when trying the example, and a patch for the problem if you have -one. Please make any patches with `diff -u' or `diff -c'. - -Suggestions, comments and other non bug reports are also welcome. - -Mailing list -============ - -There are two mailing lists with talk about Heimdal. - is a low-volume announcement list, while - is for general discussion. Send a message to - to subscribe. - -Heimdal source code, binaries and the manual -============================================ - -The source code for heimdal, links to binaries and the manual (this -document) can be found on our web-page at -`http://www.pdc.kth.se/heimdal/'. - - -File: heimdal.info, Node: What is Kerberos?, Next: Building and Installing, Prev: Introduction, Up: Top - -2 What is Kerberos? -******************* - - Now this Cerberus had three heads of dogs, - the tail of a dragon, and on his back the - heads of all sorts of snakes. - -- Pseudo-Apollodorus Library 2.5.12 - -Kerberos is a system for authenticating users and services on a network. -It is built upon the assumption that the network is "unsafe". For -example, data sent over the network can be eavesdropped and altered, and -addresses can also be faked. Therefore they cannot be used for -authentication purposes. - -Kerberos is a trusted third-party service. That means that there is a -third party (the kerberos server) that is trusted by all the entities on -the network (users and services, usually called "principals"). All -principals share a secret password (or key) with the kerberos server and -this enables principals to verify that the messages from the kerberos -server are authentic. Thus trusting the kerberos server, users and -services can authenticate each other. - -2.1 Basic mechanism -=================== - - *Note* This discussion is about Kerberos version 4, but version 5 - works similarly. - -In Kerberos, principals use "tickets" to prove that they are who they -claim to be. In the following example, A is the initiator of the -authentication exchange, usually a user, and B is the service that A -wishes to use. - -To obtain a ticket for a specific service, A sends a ticket request to -the kerberos server. The request contains A's and B's names (along with -some other fields). The kerberos server checks that both A and B are -valid principals. - -Having verified the validity of the principals, it creates a packet -containing A's and B's names, A's network address (A), the -current time (T), the lifetime of the ticket (LIFE), and a -secret "session key" (K). This packet is encrypted with B's secret -key (K). The actual ticket (T) looks like this: ({A, B, -A, T, LIFE, K}K). - -The reply to A consists of the ticket (T), B's name, the current -time, the lifetime of the ticket, and the session key, all encrypted in -A's secret key ({B, T, LIFE, K, T}K). A decrypts the -reply and retains it for later use. - - -Before sending a message to B, A creates an authenticator consisting of -A's name, A's address, the current time, and a "checksum" chosen by A, -all encrypted with the secret session key ({A, A, T, -CHECKSUM}K). This is sent together with the ticket received from -the kerberos server to B. Upon reception, B decrypts the ticket using -B's secret key. Since the ticket contains the session key that the -authenticator was encrypted with, B can now also decrypt the -authenticator. To verify that A really is A, B now has to compare the -contents of the ticket with that of the authenticator. If everything -matches, B now considers A as properly authenticated. - -2.2 Different attacks -===================== - -Impersonating A ---------------- - -An impostor, C could steal the authenticator and the ticket as it is -transmitted across the network, and use them to impersonate A. The -address in the ticket and the authenticator was added to make it more -difficult to perform this attack. To succeed C will have to either use -the same machine as A or fake the source addresses of the packets. By -including the time stamp in the authenticator, C does not have much -time in which to mount the attack. - -Impersonating B ---------------- - -C can hijack B's network address, and when A sends her credentials, C -just pretend to verify them. C can't be sure that she is talking to A. - -2.3 Defence strategies -====================== - -It would be possible to add a "replay cache" to the server side. The -idea is to save the authenticators sent during the last few minutes, so -that B can detect when someone is trying to retransmit an already used -message. This is somewhat impractical (mostly regarding efficiency), -and is not part of Kerberos 4; MIT Kerberos 5 contains it. - -To authenticate B, A might request that B sends something back that -proves that B has access to the session key. An example of this is the -checksum that A sent as part of the authenticator. One typical -procedure is to add one to the checksum, encrypt it with the session -key and send it back to A. This is called "mutual authentication". - -The session key can also be used to add cryptographic checksums to the -messages sent between A and B (known as "message integrity"). -Encryption can also be added ("message confidentiality"). This is -probably the best approach in all cases. - -2.4 Further reading -=================== - -The original paper on Kerberos from 1988 is `Kerberos: An -Authentication Service for Open Network Systems', by Jennifer Steiner, -Clifford Neuman and Jeffrey I. Schiller. - -A less technical description can be found in `Designing an -Authentication System: a Dialogue in Four Scenes' by Bill Bryant, also -from 1988. - -These documents can be found on our web-page at -`http://www.pdc.kth.se/kth-krb/'. - - -File: heimdal.info, Node: Building and Installing, Next: Setting up a realm, Prev: What is Kerberos?, Up: Top - -3 Building and Installing -************************* - -Heimdal uses GNU Autoconf to configure for specific hosts, and GNU -Automake to manage makefiles. If this is new to you, the short -instruction is to run the `configure' script in the top level -directory, and when that finishes `make'. - -If you want to build the distribution in a different directory from the -source directory, you will need a make that implements VPATH correctly, -such as GNU make. - -You will need to build the distribution: - - * A compiler that supports a "loose" ANSI C mode, such as `gcc'. - - * lex or flex - - * awk - - * yacc or bison - - * a socket library - - * NDBM or Berkeley DB for building the server side. - -When everything is built, you can install by doing `make install'. The -default location for installation is `/usr/heimdal', but this can be -changed by running `configure' with `--prefix=/some/other/place'. - -If you need to change the default behaviour, configure understands the -following options: - -`--without-berkeley-db' - DB is preferred before NDBM, but if you for some reason want to - use NDBM instead, you can use this option. - -`--with-krb4=`dir'' - Gives the location of Kerberos 4 libraries and headers. This - enables Kerberos 4 support in the applications (telnet, rsh, - popper, etc) and the KDC. It is automatically found if present - under `/usr/athena'. If you keep libraries and headers in - different places, you can instead give the path to each with the - `--with-krb4-lib=`dir'', and `--with-krb4-include=`dir'' options. - - You will need a fairly recent version of our Kerberos 4 - distribution for `rshd' and `popper' to support version 4 clients. - -`--enable-dce' - Enables support for getting DCE credentials and tokens. See the - README files in `appl/dceutils' for more information. - -`--disable-otp' - By default some of the application programs will build with - support for one-time passwords (OTP). Use this option to disable - that support. - -`--enable-osfc2' - Enable some C2 support for OSF/Digital Unix/Tru64. Use this - option if you are running your OSF operating system in C2 mode. - -`--with-readline=`dir'' - Gives the path for the GNU Readline library, which will be used in - some programs. If no readline library is found, the (simpler) - editline library will be used instead. - -`--with-hesiod=`dir'' - Enables hesiod support in push. - -`--enable-netinfo' - Add support for using netinfo to lookup configuration information. - Probably only useful (and working) on NextStep/Mac OS X. - -`--without-ipv6' - Disable the IPv6 support. - -`--with-openldap' - Compile Heimdal with support for storing the database in LDAP. - Requires OpenLDAP `http://www.openldap.org'. See - `http://www.padl.com/Research/Heimdal.html' for more information. - -`--enable-bigendian' - -`--enable-littleendian' - Normally, the build process will figure out by itself if the - machine is big or little endian. It might fail in some cases when - cross-compiling. If it does fail to figure it out, use the - relevant of these two options. - -`--with-mips-abi=ABI' - On Irix there are three different ABIs that can be used (`32', - `n32', or `64'). This option allows you to override the automatic - selection. - -`--disable-mmap' - Do not use the mmap system call. Normally, configure detects if - there is a working mmap and it is only used if there is one. Only - try this option if it fails to work anyhow. - - - -File: heimdal.info, Node: Setting up a realm, Next: Applications, Prev: Building and Installing, Up: Top - -4 Setting up a realm -******************** - -A realm is an administrative domain. The name of a Kerberos realm is -usually the Internet domain name in uppercase. Call your realm the same -as your Internet domain name if you do not have strong reasons for not -doing so. It will make life easier for you and everyone else. - -* Menu: - -* Configuration file:: -* Creating the database:: -* Modifying the database:: -* Checking the setup:: -* keytabs:: -* Serving Kerberos 4/524/kaserver:: -* Remote administration:: -* Password changing:: -* Testing clients and servers:: -* Slave Servers:: -* Incremental propagation:: -* Encryption types and salting:: -* Cross realm:: -* Transit policy:: -* Setting up DNS:: -* Using LDAP to store the database:: -* Providing Kerberos credentials to servers and programs:: -* Setting up PK-INIT:: - - -File: heimdal.info, Node: Configuration file, Next: Creating the database, Prev: Setting up a realm, Up: Setting up a realm - -4.1 Configuration file -====================== - -To setup a realm you will first have to create a configuration file: -`/etc/krb5.conf'. The `krb5.conf' file can contain many configuration -options, some of which are described here. - -There is a sample `krb5.conf' supplied with the distribution. - -The configuration file is a hierarchical structure consisting of -sections, each containing a list of bindings (either variable -assignments or subsections). A section starts with `[`section-name']'. -A binding consists of a left hand side, an equal sign (`=') and a right -hand side (the left hand side tag must be separated from the equal sign -with some whitespace). Subsections have a `{' as the first -non-whitespace character after the equal sign. All other bindings are -treated as variable assignments. The value of a variable extends to the -end of the line. - - [section1] - a-subsection = { - var = value1 - other-var = value with {} - sub-sub-section = { - var = 123 - } - } - var = some other value - [section2] - var = yet another value - -In this manual, names of sections and bindings will be given as strings -separated by slashes (`/'). The `other-var' variable will thus be -`section1/a-subsection/other-var'. - -For in-depth information about the contents of the configuration file, -refer to the `krb5.conf' manual page. Some of the more important -sections are briefly described here. - -The `libdefaults' section contains a list of library configuration -parameters, such as the default realm and the timeout for KDC -responses. The `realms' section contains information about specific -realms, such as where they hide their KDC. This section serves the same -purpose as the Kerberos 4 `krb.conf' file, but can contain more -information. Finally the `domain_realm' section contains a list of -mappings from domains to realms, equivalent to the Kerberos 4 -`krb.realms' file. - -To continue with the realm setup, you will have to create a -configuration file, with contents similar to the following. - - [libdefaults] - default_realm = MY.REALM - [realms] - MY.REALM = { - kdc = my.kdc my.slave.kdc - kdc = my.third.kdc - } - [domain_realm] - .my.domain = MY.REALM - -If you use a realm name equal to your domain name, you can omit the -`libdefaults', and `domain_realm', sections. If you have a DNS -SRV-record for your realm, or your Kerberos server has DNS CNAME -`kerberos.my.realm', you can omit the `realms' section too. - - -File: heimdal.info, Node: Creating the database, Next: Modifying the database, Prev: Configuration file, Up: Setting up a realm - -4.2 Creating the database -========================= - -The database library will look for the database in the directory -`/var/heimdal', so you should probably create that directory. Make -sure the directory has restrictive permissions. - - # mkdir /var/heimdal - -The keys of all the principals are stored in the database. If you -choose to, these can be encrypted with a master key. You do not have to -remember this key (or password), but just to enter it once and it will -be stored in a file (`/var/heimdal/m-key'). If you want to have a -master key, run `kstash' to create this master key: - - # kstash - Master key: - Verifying password - Master key: - -If you want to generate a random master key you can use the -random-key -to kstash. This will make sure you have a good key on which attackers -can't do a dictionary attack. - -If you have a master key, make sure you make a backup of your master -key file; without it backups of the database are of no use. - -To initialise the database use the `kadmin' program, with the `-l' -option (to enable local database mode). First issue a `init MY.REALM' -command. This will create the database and insert default principals -for that realm. You can have more than one realm in one database, so -`init' does not destroy any old database. - -Before creating the database, `init' will ask you some questions about -maximum ticket lifetimes. - -After creating the database you should probably add yourself to it. You -do this with the `add' command. It takes as argument the name of a -principal. The principal should contain a realm, so if you haven't set -up a default realm, you will need to explicitly include the realm. - - # kadmin -l - kadmin> init MY.REALM - Realm max ticket life [unlimited]: - Realm max renewable ticket life [unlimited]: - kadmin> add me - Max ticket life [unlimited]: - Max renewable life [unlimited]: - Attributes []: - Password: - Verifying password - Password: - -Now start the KDC and try getting a ticket. - - # kdc & - # kinit me - me@MY.REALMS's Password: - # klist - Credentials cache: /tmp/krb5cc_0 - Principal: me@MY.REALM - - Issued Expires Principal - Aug 25 07:25:55 Aug 25 17:25:55 krbtgt/MY.REALM@MY.REALM - -If you are curious you can use the `dump' command to list all the -entries in the database. It should look something similar to the -following example (note that the entries here are truncated for -typographical reasons): - - kadmin> dump - me@MY.REALM 1:0:1:0b01d3cb7c293b57:-:0:7:8aec316b9d1629e3baf8 ... - kadmin/admin@MY.REALM 1:0:1:e5c8a2675b37a443:-:0:7:cb913ebf85 ... - krbtgt/MY.REALM@MY.REALM 1:0:1:52b53b61c875ce16:-:0:7:c8943be ... - kadmin/changepw@MY.REALM 1:0:1:f48c8af2b340e9fb:-:0:7:e3e6088 ... - - -File: heimdal.info, Node: Modifying the database, Next: Checking the setup, Prev: Creating the database, Up: Setting up a realm - -4.3 Modifying the database -========================== - -All modifications of principals are done with with kadmin. - -A principal has several attributes and lifetimes associated with it. - -Principals are added, renamed, modified, and deleted with the kadmin -commands `add', `rename', `modify', `delete'. Both interactive editing -and command line flags can be used (use -help to list the available -options). - -There are different kinds of types for the fields in the database; -attributes, absolute time times and relative times. - -4.3.1 Attributes ----------------- - -When doing interactive editing, attributes are listed with `?'. - -The attributes are given in a comma (`,') separated list. Attributes -are removed from the list by prefixing them with `-'. - - kadmin> modify me - Max ticket life [1 day]: - Max renewable life [1 week]: - Principal expiration time [never]: - Password expiration time [never]: - Attributes [disallow-renewable]: requires-pre-auth,-disallow-renewable - kadmin> get me - Principal: me@MY.REALM - [...] - Attributes: requires-pre-auth - -4.3.2 Absolute times --------------------- - -The format for absolute times are any of the following: - - never - now - YYYY-mm-dd - YYYY-mm-dd HH:MM:SS - -4.3.3 Relative times --------------------- - -The format for relative times are any of the following combined: - - N year - M month - O day - P hour - Q minute - R second - - -File: heimdal.info, Node: Checking the setup, Next: keytabs, Prev: Modifying the database, Up: Setting up a realm - -4.4 Checking the setup -====================== - -There are two tools that can check the consistency of the Kerberos -configuration file and the Kerberos database. - -The Kerberos configuration file is checked using `verify_krb5_conf'. -The tool checks for common errors, but commonly there are several -uncommon configuration entries that are never added to the tool and -thus generates "unknown entry" warnings. This is usually nothing to -worry about. - -The database check is built into the kadmin tool. It will check for -common configuration error that will cause problems later. Common check -are for existence and flags on important principals. The database check -by run by the following command : - - kadmin check REALM.EXAMPLE.ORG - - -File: heimdal.info, Node: keytabs, Next: Serving Kerberos 4/524/kaserver, Prev: Checking the setup, Up: Setting up a realm - -4.5 keytabs -=========== - -To extract a service ticket from the database and put it in a keytab, -you need to first create the principal in the database with `ank' -(using the `--random-key' flag to get a random key) and then extract it -with `ext_keytab'. - - kadmin> add --random-key host/my.host.name - Max ticket life [unlimited]: - Max renewable life [unlimited]: - Attributes []: - kadmin> ext host/my.host.name - kadmin> exit - # ktutil list - Version Type Principal - 1 des-cbc-md5 host/my.host.name@MY.REALM - 1 des-cbc-md4 host/my.host.name@MY.REALM - 1 des-cbc-crc host/my.host.name@MY.REALM - 1 des3-cbc-sha1 host/my.host.name@MY.REALM - - -File: heimdal.info, Node: Serving Kerberos 4/524/kaserver, Next: Remote administration, Prev: keytabs, Up: Setting up a realm - -4.6 Serving Kerberos 4/524/kaserver -=================================== - -Heimdal can be configured to support 524, Kerberos 4 or kaserver. All -these services are turned off by default. Kerberos 4 is always -supported by the KDC, but the Kerberos 4 client support also depends on -Kerberos 4 support having been included at compile-time, using -`--with-krb4=dir'. - -4.6.1 524 ---------- - -524 is a service that allows the KDC to convert Kerberos 5 tickets to -Kerberos 4 tickets for backward compatibility. See also Using 2b tokens -with AFS in *Note Things in search for a better place::. - -524 can be turned on by adding this to the configuration file - - [kdc] - enable-524 = yes - -4.6.2 Kerberos 4 ----------------- - -Kerberos 4 is the predecessor to to Kerberos 5. It only supports single -DES. You should only enable Kerberos 4 support if you have needs for -compatibility with an installed base of Kerberos 4 clients/servers. - -Kerberos 4 can be turned on by adding this to the configuration file - - [kdc] - enable-kerberos4 = yes - -4.6.3 kaserver --------------- - -Kaserver is a Kerberos 4 that is used in AFS. The protocol has some -extra features over plain Kerberos 4, but like Kerberos 4, only uses -single DES. - -You should only enable Kaserver support if you have needs for -compatibility with an installed base of AFS machines. - -Kaserver can be turned on by adding this to the configuration file - - [kdc] - enable-kaserver = yes - - -File: heimdal.info, Node: Remote administration, Next: Password changing, Prev: Serving Kerberos 4/524/kaserver, Up: Setting up a realm - -4.7 Remote administration -========================= - -The administration server, `kadmind', can be started by `inetd' (which -isn't recommended) or run as a normal daemon. If you want to start it -from `inetd' you should add a line similar to the one below to your -`/etc/inetd.conf'. - - kerberos-adm stream tcp nowait root /usr/heimdal/libexec/kadmind kadmind - -You might need to add `kerberos-adm' to your `/etc/services' as -`749/tcp'. - -Access to the administration server is controlled by an ACL file, -(default `/var/heimdal/kadmind.acl'.) The file has the following syntax: - principal [priv1,priv2,...] [glob-pattern] - -The matching is from top to bottom for matching principals (and if -given, glob-pattern). When there is a match, the access rights of that -line are applied. - -The privileges you can assign to a principal are: `add', -`change-password' (or `cpw' for short), `delete', `get', `list', and -`modify', or the special privilege `all'. All of these roughly -correspond to the different commands in `kadmin'. - -If a GLOB-PATTERN is given on a line, it restricts the access rights -for the principal to only apply for subjects that match the pattern. -The patterns are of the same type as those used in shell globbing, see -fnmatch(3). - -In the example below `lha/admin' can change every principal in the -database. `jimmy/admin' can only modify principals that belong to the -realm `E.KTH.SE'. `mille/admin' is working at the help desk, so he -should only be able to change the passwords for single component -principals (ordinary users). He will not be able to change any `/admin' -principal. - - lha/admin@E.KTH.SE all - jimmy/admin@E.KTH.SE all *@E.KTH.SE - jimmy/admin@E.KTH.SE all */*@E.KTH.SE - mille/admin@E.KTH.SE change-password *@E.KTH.SE - - -File: heimdal.info, Node: Password changing, Next: Testing clients and servers, Prev: Remote administration, Up: Setting up a realm - -4.8 Password changing -===================== - -To allow users to change their passwords, you should run `kpasswdd'. -It is not run from `inetd'. - -You might need to add `kpasswd' to your `/etc/services' as `464/udp'. - -4.8.1 Password quality assurance --------------------------------- - -It is important that users have good passwords, both to make it harder -to guess them and to avoid off-line attacks (although -pre-authentication provides some defence against off-line attacks). To -ensure that the users choose good passwords, you can enable password -quality controls in `kpasswdd' and `kadmind'. The controls themselves -are done in a shared library or an external program that is used by -`kpasswdd'. To configure in these controls, add lines similar to the -following to your `/etc/krb5.conf': - - [password_quality] - policies = external-check builtin:minimum-length module:policyname - external_program = /bin/false - policy_libraries = LIBRARY1.SO LIBRARY2.SO - -In `[password_quality]policies' the module name is optional if the -policy name is unique in all modules (members of `policy_libraries'). - -The built-in polices are - - * external-check - - Executes the program specified by - `[password_quality]external_program'. - - A number of key/value pairs are passed as input to the program, - one per line, ending with the string `end'. The key/value lines - are of the form - principal: PRINCIPAL - new-password: PASSWORD - where PASSWORD is the password to check for the previous PRINCIPAL. - - If the external application approves the password, it should return - `APPROVED' on standard out and exit with exit code 0. If it - doesn't approve the password, an one line error message explaining - the problem should be returned on standard error and the - application should exit with exit code 0. In case of a fatal - error, the application should, if possible, print an error message - on standard error and exit with a non-zero error code. - - * minimum-length - - The minimum length password quality check reads the configuration - file stanza `[password_quality]min_length' and requires the - password to be at least this length. - - * character-class - - The character-class password quality check reads the configuration - file stanza `[password_quality]min_classes'. The policy requires - the password to have characters from at least that many character - classes. Default value if not given is 3. - - The four different characters classes are, uppercase, lowercase, - number, special characters. - - -If you want to write your own shared object to check password policies, -see the manual page `kadm5_pwcheck(3)'. - -Code for a password quality checking function that uses the cracklib -library can be found in `lib/kadm5/sample_password_check.c' in the -source code distribution. It requires that the cracklib library be -built with the patch available at -`ftp://ftp.pdc.kth.se/pub/krb/src/cracklib.patch'. - -A sample policy external program is included in -`lib/kadm5/check-cracklib.pl'. - -If no password quality checking function is configured, the only check -performed is that the password is at least six characters long. - -To check the password policy settings, use the command -`password-quality' in `kadmin' program. The password verification is -only performed locally, on the client. It may be convenient to set the -environment variable `KRB5_CONFIG' to point to a test version of -`krb5.conf' while you're testing the `[password_quality]' stanza that -way. - - -File: heimdal.info, Node: Testing clients and servers, Next: Slave Servers, Prev: Password changing, Up: Setting up a realm - -4.9 Testing clients and servers -=============================== - -Now you should be able to run all the clients and servers. Refer to the -appropriate man pages for information on how to use them. - - -File: heimdal.info, Node: Slave Servers, Next: Incremental propagation, Prev: Testing clients and servers, Up: Setting up a realm - -4.10 Slave servers, Incremental propagation, Testing clients and servers, Setting up a realm -============================================================================================ - -It is desirable to have at least one backup (slave) server in case the -master server fails. It is possible to have any number of such slave -servers but more than three usually doesn't buy much more redundancy. - -All Kerberos servers for a realm must have the same database so that -they present the same service to the users. The `hprop' program, -running on the master, will propagate the database to the slaves, -running `hpropd' processes. - -Every slave needs a database directory, the master key (if it was used -for the database) and a keytab with the principal `hprop/HOSTNAME'. -Add the principal with the `ktutil' command and start `hpropd', as -follows: - - slave# ktutil get -p foo/admin hprop/`hostname` - slave# mkdir /var/heimdal - slave# hpropd - -The master will use the principal `kadmin/hprop' to authenticate to the -slaves. This principal should be added when running `kadmin -l init' -but if you do not have it in your database for whatever reason, please -add it with `kadmin -l add'. - -Then run `hprop' on the master: - - master# hprop slave - -This was just an hands-on example to make sure that everything was -working properly. Doing it manually is of course the wrong way, and to -automate this you will want to start `hpropd' from `inetd' on the -slave(s) and regularly run `hprop' on the master to regularly propagate -the database. Starting the propagation once an hour from `cron' is -probably a good idea. - - -File: heimdal.info, Node: Incremental propagation, Next: Encryption types and salting, Prev: Slave Servers, Up: Setting up a realm - -4.11 Incremental propagation -============================ - -There is also a newer, and still somewhat experimental, mechanism for -doing incremental propagation in Heimdal. Instead of sending the whole -database regularly, it sends the changes as they happen on the master to -the slaves. The master keeps track of all the changes by assigning a -version number to every change to the database. The slaves know which -was the latest version they saw and in this way it can be determined if -they are in sync or not. A log of all the changes is kept on the -master, and when a slave is at an older version than the oldest one in -the log, the whole database has to be sent. - -Protocol-wise, all the slaves connect to the master and as a greeting -tell it the latest version that they have (`IHAVE' message). The -master then responds by sending all the changes between that version and -the current version at the master (a series of `FORYOU' messages) or -the whole database in a `TELLYOUEVERYTHING' message. There is also a -keep-alive protocol that makes sure all slaves are up and running. - -4.11.1 Configuring incremental propagation ------------------------------------------- - -The program that runs on the master is `ipropd-master' and all clients -run `ipropd-slave'. - -Create the file `/var/heimdal/slaves' on the master containing all the -slaves that the database should be propagated to. Each line contains -the full name of the principal (for example -`iprop/hemligare.foo.se@FOO.SE'). - -You should already have `iprop/tcp' defined as 2121, in your -`/etc/services'. Otherwise, or if you need to use a different port for -some peculiar reason, you can use the `--port' option. This is useful -when you have multiple realms to distribute from one server. - -Then you need to create those principals that you added in the -configuration file. Create one `iprop/hostname' for the master and for -every slave. - - master# /usr/heimdal/sbin/ktutil get iprop/`hostname` - -The next step is to start the `ipropd-master' process on the master -server. The `ipropd-master' listens on the UNIX domain socket -`/var/heimdal/signal' to know when changes have been made to the -database so they can be propagated to the slaves. There is also a -safety feature of testing the version number regularly (every 30 -seconds) to see if it has been modified by some means that do not raise -this signal. Then, start `ipropd-slave' on all the slaves: - - master# /usr/heimdal/libexec/ipropd-master & - slave# /usr/heimdal/libexec/ipropd-slave master & - -To manage the iprop log file you should use the `iprop-log' command. -With it you can dump, truncate and replay the logfile. - - -File: heimdal.info, Node: Encryption types and salting, Next: Cross realm, Prev: Incremental propagation, Up: Setting up a realm - -4.12 Encryption types and salting -================================= - -The encryption types that the KDC is going to assign by default is -possible to change. Since the keys used for user authentication is -salted the encryption types are described together with the salt -strings. - -Salting is used to make it harder to pre-calculate all possible keys. -Using a salt increases the search space to make it almost impossible to -pre-calculate all keys. Salting is the process of mixing a public -string (the salt) with the password, then sending it through an -encryption type specific string-to-key function that will output the -fixed size encryption key. - -In Kerberos 5 the salt is determined by the encryption type, except in -some special cases. - -In `des' there is the Kerberos 4 salt (none at all) or the afs-salt -(using the cell (realm in AFS lingo)). - -In `arcfour' (the encryption type that Microsoft Windows 2000 uses) -there is no salt. This is to be compatible with NTLM keys in Windows NT -4. - -`[kadmin]default_keys' in `krb5.conf' controls what salting to use. - -The syntax of `[kadmin]default_keys' is -`[etype:]salt-type[:salt-string]'. `etype' is the encryption type -(des-cbc-crc, arcfour-hmac-md5, aes256-cts-hmac-sha1-96), `salt-type' -is the type of salt (pw-salt or afs3-salt), and the salt-string is the -string that will be used as salt (remember that if the salt is -appended/prepended, the empty salt "" is the same thing as no salt at -all). - -Common types of salting include - - * `v4' (or `des:pw-salt:') - - The Kerberos 4 salting is using no salt at all. Reason there is - colon at the end of the salt string is that it makes the salt the - empty string (same as no salt). - - * `v5' (or `pw-salt') - - `pw-salt' uses the default salt for each encryption type is - specified for. If the encryption type `etype' isn't given, all - default encryption will be used. - - * `afs3-salt' - - `afs3-salt' is the salt that is used with Transarc kaserver. Its - the cell name appended to the password. - - - -File: heimdal.info, Node: Cross realm, Next: Transit policy, Prev: Encryption types and salting, Up: Setting up a realm - -4.13 Cross realm -================ - -Suppose you reside in the realm `MY.REALM', how do you authenticate to -a server in `OTHER.REALM'? Having valid tickets in `MY.REALM' allows -you to communicate with Kerberised services in that realm. However, the -computer in the other realm does not have a secret key shared with the -Kerberos server in your realm. - -It is possible to share keys between two realms that trust each other. -When a client program, such as `telnet' or `ssh', finds that the other -computer is in a different realm, it will try to get a ticket granting -ticket for that other realm, but from the local Kerberos server. With -that ticket granting ticket, it will then obtain service tickets from -the Kerberos server in the other realm. - -For a two way trust between `MY.REALM' and `OTHER.REALM' add the -following principals to each realm. The principals should be -`krbtgt/OTHER.REALM@MY.REALM' and `krbtgt/MY.REALM@OTHER.REALM' in -`MY.REALM', and `krbtgt/MY.REALM@OTHER.REALM' and -`krbtgt/OTHER.REALM@MY.REALM'in `OTHER.REALM'. - -In Kerberos 5 the trust can be configured to be one way. So that users -from `MY.REALM' can authenticate to services in `OTHER.REALM', but not -the opposite. In the example above, the `krbtgt/MY.REALM@OTHER.REALM' -then should be removed. - -The two principals must have the same key, key version number, and the -same set of encryption types. Remember to transfer the two keys in a -safe manner. - - vr$ klist - Credentials cache: FILE:/tmp/krb5cc_913.console - Principal: lha@E.KTH.SE - - Issued Expires Principal - May 3 13:55:52 May 3 23:55:54 krbtgt/E.KTH.SE@E.KTH.SE - - vr$ telnet -l lha hummel.it.su.se - Trying 2001:6b0:5:1095:250:fcff:fe24:dbf... - Connected to hummel.it.su.se. - Escape character is '^]'. - Waiting for encryption to be negotiated... - [ Trying mutual KERBEROS5 (host/hummel.it.su.se@SU.SE)... ] - [ Kerberos V5 accepts you as ``lha@E.KTH.SE'' ] - Encryption negotiated. - Last login: Sat May 3 14:11:47 from vr.l.nxs.se - hummel$ exit - - vr$ klist - Credentials cache: FILE:/tmp/krb5cc_913.console - Principal: lha@E.KTH.SE - - Issued Expires Principal - May 3 13:55:52 May 3 23:55:54 krbtgt/E.KTH.SE@E.KTH.SE - May 3 13:55:56 May 3 23:55:54 krbtgt/SU.SE@E.KTH.SE - May 3 14:10:54 May 3 23:55:54 host/hummel.it.su.se@SU.SE - - -File: heimdal.info, Node: Transit policy, Next: Setting up DNS, Prev: Cross realm, Up: Setting up a realm - -4.14 Transit policy -=================== - -If you want to use cross realm authentication through an intermediate -realm, it must be explicitly allowed by either the KDCs or the server -receiving the request. This is done in `krb5.conf' in the `[capaths]' -section. - -When the ticket transits through a realm to another realm, the -destination realm adds its peer to the "transited-realms" field in the -ticket. The field is unordered, since there is no way to know if know -if one of the transited-realms changed the order of the list. - -The syntax for `[capaths]' section: - - [capaths] - CLIENT-REALM = { - SERVER-REALM = PERMITTED-CROSS-REALMS ... - } - -The realm `STACKEN.KTH.SE' allows clients from `SU.SE' and `DSV.SU.SE' -to cross it. Since `STACKEN.KTH.SE' only has direct cross realm setup -with `KTH.SE', and `DSV.SU.SE' only has direct cross realm setup with -`SU.SE' they need to use both `SU.SE' and `KTH.SE' as transit realms. - - [capaths] - SU.SE = { - STACKEN.KTH.SE = KTH.SE - } - DSV.SU.SE = { - STACKEN.KTH.SE = SU.SE KTH.SE - } - -The order of the `PERMITTED-CROSS-REALMS' is not important when doing -transit cross realm verification. - -However, the order is important when the `[capaths]' section is used to -figure out the intermediate realm to go to when doing multi-realm -transit. When figuring out the next realm, the first realm of the list -of `PERMITTED-CROSS-REALMS' is chosen. This is done in both the client -kerberos library and the KDC. - - -File: heimdal.info, Node: Setting up DNS, Next: Using LDAP to store the database, Prev: Transit policy, Up: Setting up a realm - -4.15 Setting up DNS -=================== - -4.15.1 Using DNS to find KDC ----------------------------- - -If there is information about where to find the KDC or kadmind for a -realm in the `krb5.conf' for a realm, that information will be -preferred, and DNS will not be queried. - -Heimdal will try to use DNS to find the KDCs for a realm. First it will -try to find a `SRV' resource record (RR) for the realm. If no SRV RRs -are found, it will fall back to looking for an `A' RR for a machine -named kerberos.REALM, and then kerberos-1.REALM, etc - -Adding this information to DNS minimises the client configuration (in -the common case, resulting in no configuration needed) and allows the -system administrator to change the number of KDCs and on what machines -they are running without caring about clients. - -The downside of using DNS is that the client might be fooled to use the -wrong server if someone fakes DNS replies/data, but storing the IP -addresses of the KDC on all the clients makes it very hard to change -the infrastructure. - -An example of the configuration for the realm `EXAMPLE.COM': - - - $ORIGIN example.com. - _kerberos._tcp SRV 10 1 88 kerberos.example.com. - _kerberos._udp SRV 10 1 88 kerberos.example.com. - _kerberos._tcp SRV 10 1 88 kerberos-1.example.com. - _kerberos._udp SRV 10 1 88 kerberos-1.example.com. - _kpasswd._udp SRV 10 1 464 kerberos.example.com. - _kerberos-adm._tcp SRV 10 1 749 kerberos.example.com. - -More information about DNS SRV resource records can be found in -RFC-2782 (A DNS RR for specifying the location of services (DNS SRV)). - -4.15.2 Using DNS to map hostname to Kerberos realm --------------------------------------------------- - -Heimdal also supports a way to lookup a realm from a hostname. This to -minimise configuration needed on clients. Using this has the drawback -that clients can be redirected by an attacker to realms within the same -cross realm trust and made to believe they are talking to the right -server (since Kerberos authentication will succeed). - -An example configuration that informs clients that for the realms -it.example.com and srv.example.com, they should use the realm -EXAMPLE.COM: - - - $ORIGIN example.com. - _kerberos.it TXT "EXAMPLE.COM" - _kerberos.srv TXT "EXAMPLE.COM" - - -File: heimdal.info, Node: Using LDAP to store the database, Next: Providing Kerberos credentials to servers and programs, Prev: Setting up DNS, Up: Setting up a realm - -4.16 Using LDAP to store the database -===================================== - -This document describes how to install the LDAP backend for Heimdal. -Note that before attempting to configure such an installation, you -should be aware of the implications of storing private information -(such as users' keys) in a directory service primarily designed for -public information. Nonetheless, with a suitable authorisation policy, -it is possible to set this up in a secure fashion. A knowledge of LDAP, -Kerberos, and C is necessary to install this backend. The HDB schema -was devised by Leif Johansson. - -Requirements: - - * A current release of Heimdal, configured with - `--with-openldap=/usr/local' (adjust according to where you have - installed OpenLDAP). - - You can verify that you manage to configure LDAP support by running - `kdc --builtin-hdb', and checking that `ldap:' is one entry in the - list. - - Its also possible to configure the ldap backend as a shared module, - see option -hdb-openldap-module to configure. - - * OpenLDAP 2.0.x. Configure OpenLDAP with `--enable-local' to enable - the local transport. (A patch to support SASL EXTERNAL - authentication is necessary in order to use OpenLDAP 2.1.x.) - - * Add the hdb schema to the LDAP server, its included in the - source-tree in `lib/hdb/hdb.schema'. Example from slapd.conf: - - include /usr/local/etc/openldap/schema/hdb.schema - - * Configure the LDAP server ACLs to accept writes from clients over - the local transport. For example: - - access to * - by dn.exact="uid=heimdal,dc=services,dc=example,dc=com" write - ... - - sasl-regexp "uidNumber=0\\\+gidNumber=.*,cn=peercred,cn=external,cn=auth" - "uid=heimdal,dc=services,dc=example,dc=com" - - The sasl-regexp is for mapping between the SASL/EXTERNAL and a - user in a tree. The user that the key is mapped to should be have - a krb5Principal aux object with krb5PrincipalName set so that the - "creator" and "modifier" is right in `kadmin'. - - Another option is to create an admins group and add the dn to that - group. - - Since Heimdal talks to the LDAP server over a UNIX domain socket, - and uses external sasl authentication, its not possible to require - security layer quality (ssf in cyrus-sasl lingo). So that - requirement has to be turned off in OpenLDAP `slapd' configuration - file `slapd.conf'. - - sasl-secprops minssf=0 - - * Start `slapd' with the local listener (as well as the default - TCP/IP listener on port 389) as follows: - - slapd -h "ldapi:/// ldap:///" - - Note: These is a bug in `slapd' where it appears to corrupt the - krb5Key binary attribute on shutdown. This may be related to our - use of the V3 schema definition syntax instead of the old - UMich-style, V2 syntax. - - * You should specify the distinguished name under which your - principals will be stored in `krb5.conf'. Also you need to enter - the path to the kadmin acl file: - - [kdc] - database = { - dbname = ldap:ou=KerberosPrincipals,dc=example,dc=com - hdb-ldap-structural-object = inetOrgPerson - acl_file = /path/to/kadmind.acl - mkey_file = /path/to/mkey - } - - `mkey_file' can be excluded if you feel that you trust your ldap - directory to have the raw keys inside it. The - hdb-ldap-structural-object is not necessary if you do not need - Samba comatibility. - - * Once you have built Heimdal and started the LDAP server, run kadmin - (as usual) to initialise the database. Note that the instructions - for stashing a master key are as per any Heimdal installation. - - kdc# kadmin -l - kadmin> init EXAMPLE.COM - Realm max ticket life [unlimited]: - Realm max renewable ticket life [unlimited]: - kadmin> ank lukeh - Max ticket life [1 day]: - Max renewable life [1 week]: - Principal expiration time [never]: - Password expiration time [never]: - Attributes []: - lukeh@EXAMPLE.COM's Password: - Verifying password - lukeh@EXAMPLE.COM's Password: - kadmin> exit - - Verify that the principal database has indeed been stored in the - directory with the following command: - - kdc# ldapsearch -L -h localhost -D cn=manager \ - -w secret -b ou=KerberosPrincipals,dc=example,dc=com \ - 'objectclass=krb5KDCEntry' - - * Now consider adding indexes to the database to speed up the - access, at least theses should be added to slapd.conf. - - index objectClass eq - index cn eq,sub,pres - index uid eq,sub,pres - index displayName eq,sub,pres - index krb5PrincipalName eq - - -4.16.1 Troubleshooting guide ----------------------------- - -`https://sec.miljovern.no/bin/view/Info/TroubleshootingGuide' - -4.16.2 Using Samba LDAP password database ------------------------------------------ - -The Samba domain and the Kerberos realm can have different names since -arcfour's string to key functions principal/realm independent. So now -will be your first and only chance name your Kerberos realm without -needing to deal with old configuration files. - -First, you should set up Samba and get that working with LDAP backend. - -Now you can proceed as in *Note Using LDAP to store the database::. -Heimdal will pick up the Samba LDAP entries if they are in the same -search space as the Kerberos entries. - - -File: heimdal.info, Node: Providing Kerberos credentials to servers and programs, Next: Setting up PK-INIT, Prev: Using LDAP to store the database, Up: Setting up a realm - -4.17 Providing Kerberos credentials to servers and programs -=========================================================== - -Some services require Kerberos credentials when they start to make -connections to other services or need to use them when they have -started. - -The easiest way to get tickets for a service is to store the key in a -keytab. Both ktutil get and kadmin ext can be used to get a keytab. -ktutil get is better in that way it changes the key/password for the -user. This is also the problem with ktutil. If ktutil is used for the -same service principal on several hosts, they keytab will only be -useful on the last host. In that case, run the extract command on one -host and then securely copy the keytab around to all other hosts that -need it. - - host# ktutil -k /etc/krb5-service.keytab \ - get -p lha/admin@EXAMPLE.ORG service-principal@EXAMPLE.ORG - lha/admin@EXAMPLE.ORG's Password: - -To get a Kerberos credential file for the service, use kinit in the --keytab mode. This will not ask for a password but instead fetch the -key from the keytab. - - service@host$ kinit --cache=/var/run/service_krb5_cache \ - --keytab=/etc/krb5-service.keytab \ - service-principal@EXAMPLE.ORG - -Long running services might need credentials longer then the expiration -time of the tickets. kinit can run in a mode that refreshes the tickets -before they expire. This is useful for services that write into AFS and -other distributed file systems using Kerberos. To run the long running -script, just append the program and arguments (if any) after the -principal. kinit will stop refreshing credentials and remove the -credentials when the script-to-start-service exits. - - service@host$ kinit --cache=/var/run/service_krb5_cache \ - --keytab=/etc/krb5-service.keytab \ - service-principal@EXAMPLE.ORG \ - script-to-start-service argument1 argument2 - - -File: heimdal.info, Node: Setting up PK-INIT, Prev: Providing Kerberos credentials to servers and programs, Up: Setting up a realm - -4.18 Setting up PK-INIT -======================= - -PK-INIT is levering the existing PKI infrastructure to use certificates -to get the initial ticket, that is usually the krbtgt. - -To use PK-INIT you must first have a PKI, so if you don't have one, now -its time to create it. Note that you should read the whole chapter of -the document to see the requirements on the CA sortware. - -There needs to exist a mapping between the certificate and what -principals that certificate is allowed to use. There are several ways -to do this. The administrator can use a configuration file, storing the -principal in the SubjectAltName extension of the certificate, or store -the mapping in the principals entry in the kerberos database. - -4.19 Certificates -================= - -This section documents the requirements on the KDC and client -certificates and the format used in the id-pkinit-san OtherName -extention. - -4.19.1 KDC certificate ----------------------- - -The certificate for the KDC have serveral requirements. - -First the certificate should have an Extended Key Usage (EKU) -id-pkkdcekuoid (1.3.6.1.5.2.3.5) set. Second there must be a -subjectAltName otherName using oid id-pkinit-san (1.3.6.1.5.2.2) in the -type field and a DER encoded KRB5PrincipalName that matches the name of -the TGS of the target realm. - -Both of these two requirements are not required by the standard to be -checked by the client if it have external information what the -certificate the KDC is supposed to be used. So its in the interst of -minimum amount of configuration on the clients they should be included. - -Remember that if the client would accept any certificate as the KDC's -certificate, the client could be fooled into trusting something that -isn't a KDC and thus expose the user to giving away information (like -password or other private information) that it is supposed to secret. - -Also, if the certificate has a nameConstraints extention with a -Generalname with dNSName or iPAdress it must match the hostname or -adress of the KDC. - -4.19.2 Client certificate -------------------------- - -The client certificate may need to have a EKU id-pkekuoid -(1.3.6.1.5.2.3.4) set depending on the certifiate on the KDC. - -It possible to store the principal (if allowed by the KDC) in the -certificate and thus delegate responsibility to do the mapping between -certificates and principals to the CA. - -4.19.2.1 Using KRB5PrincipalName in id-pkinit-san -................................................. - -OtherName extention in the GeneralName is used to do the mapping -between certifiate and principal in the certifiate or storing the -krbtgt principal in the KDC certificate. - -The principal is stored in a SubjectAltName in the certificate using -OtherName. The oid in the type is id-pkinit-san. - - id-pkinit-san OBJECT IDENTIFIER ::= { iso (1) org (3) dod (6) - internet (1) security (5) kerberosv5 (2) 2 } - -The data part of the OtherName is filled with the following DER encoded -ASN.1 structure: - - KRB5PrincipalName ::= SEQUENCE { - realm [0] Realm, - principalName [1] PrincipalName - } - -where Realm and PrincipalName is defined by the Kerberos ASN.1 -specification. - -4.20 Naming certificate using hx509 -=================================== - -hx509 is the X.509 software used in Heimdal to handle certificates. -hx509 uses different syntaxes to specify the different formats the -certificates are stored in and what formats they exist in. - -There are several formats that can be used, PEM, embedded into PKCS12 -files, embedded into PKCS11 devices and raw DER encoded certificates. -Below is a list of types to use. - -DIR: - DIR is reading all certificates in a directory that is DER or PEM - formatted. - - The main feature of DIR is that the directory is read on demand - when iterating over certificates, that way applictions can for - some cases avoid to store all certificates in memory. It's very - useful for tests that iterate over larger amount of certificates. - - Syntax is: - - DIR:/path/to/der/files - -FILE: - FILE: is used to have the lib pick up a certificate chain and a - private key. The file can be either a PEM (openssl) file or a raw - DER encoded certificate. If it's a PEM file it can contain several - keys and certificates and the code will try to match the private - key and certificate together. - - Its useful to have one PEM file that contains all the trust - anchors. - - Syntax is: - - FILE:certificate.pem,private-key.key,other-cert.pem,.... - -PKCS11: - PKCS11: is used to handle smartcards via PKCS11 drivers, for - example soft-token, opensc, or muscle. The default is to use all - slots on the device/token. - - Syntax is: - - PKCS11:shared-object.so - -PKCS12: - PKCS12: is used to handle PKCS12 files. PKCS12 files commonly have - the extension pfx or p12. - - Syntax is: - - PKCS12:/path/to/file.pfx - - -4.21 Configure the Kerberos software -==================================== - -First configure the client's trust anchors and what parameters to -verify, see subsection below how to do that. Now you can use kinit to -get yourself tickets. One example how that can look like is: - - $ kinit -C FILE:$HOME/.certs/lha.crt,$HOME/.certs/lha.key lha@EXAMPLE.ORG - Enter your private key passphrase: - : lha@nutcracker ; klist - Credentials cache: FILE:/tmp/krb5cc_19100a - Principal: lha@EXAMPLE.ORG - - Issued Expires Principal - Apr 20 02:08:08 Apr 20 12:08:08 krbtgt/EXAMPLE.ORG@EXAMPLE.ORG - -Using PKCS11 it can look like this instead: - - $ kinit -C PKCS11:/tmp/pkcs11/lib/soft-pkcs11.so lha@EXAMPLE.ORG - PIN code for SoftToken (slot): - $ klist - Credentials cache: API:4 - Principal: lha@EXAMPLE.ORG - - Issued Expires Principal - Mar 26 23:40:10 Mar 27 09:40:10 krbtgt/EXAMPLE.ORG@EXAMPLE.ORG - -Write about the kdc. - -4.22 Configure the client -========================= - - [appdefaults] - pkinit_anchors = FILE:/path/to/trust-anchors.pem - - [realms] - EXAMPLE.COM = { - pkinit_require_eku = true - pkinit_require_krbtgt_otherName = true - pkinit_win2k = no - pkinit_win2k_require_binding = yes - } - -4.23 Configure the KDC -====================== - - [kdc] - enable-pkinit = yes - pkinit_identity = FILE:/secure/kdc.crt,/secure/kdc.key - pkinit_anchors = FILE:/path/to/trust-anchors.pem - pkinit_pool = PKCS12:/path/to/useful-intermediate-certs.pfx - pkinit_pool = FILE:/path/to/other-useful-intermediate-certs.pem - pkinit_allow_proxy_certificate = false - pkinit_win2k_require_binding = yes - -4.23.1 Using pki-mapping file ------------------------------ - -Note that the file name is space sensitive. - - # cat /var/heimdal/pki-mapping - # comments starts with # - lha@EXAMPLE.ORG:C=SE,O=Stockholm universitet,CN=Love,UID=lha - lha@EXAMPLE.ORG:CN=Love,UID=lha - -4.23.2 Using the Kerberos database ----------------------------------- - -4.24 Use hxtool to create certificates -====================================== - -4.24.1 Generate certificates ----------------------------- - -First you need to generate a CA certificate, change the -subject to -something appropriate, the CA certificate will be valid for 10 years. - -You need to change -subject in the command below. - - hxtool issue-certificate \ - --self-signed \ - --issue-ca \ - --generate-key=rsa \ - --subject="CN=CA,DC=test,DC=h5l,DC=se" \ - --lifetime=10years \ - --certificate="FILE:ca.pem" - -The KDC needs to have a certificate, so generate a certificate of the -type "pkinit-kdc" and set the PK-INIT specifial SubjectAltName to the -name of the krbtgt of the realm. - -You need to change -subject and -pk-init-principal in the command below. - - hxtool issue-certificate \ - --ca-certificate=FILE:ca.pem \ - --generate-key=rsa \ - --type="pkinit-kdc" \ - --pk-init-principal="krbtgt/TEST.H5L.SE@TEST.H5L.SE" \ - --subject="uid=kdc,DC=test,DC=h5l,DC=se" \ - --certificate="FILE:kdc.pem" - -The users also needs to have a certificate, so generate a certificate -of the type "pkinit-client". The client doesn't need to have the PK-INIT -SubjectAltName set, you can have the Subject DN in the ACL file -(pki-mapping) instead. - -You need to change -subject and -pk-init-principal in the command below. - - hxtool issue-certificate \ - --ca-certificate=FILE:ca.pem \ - --generate-key=rsa \ - --type="pkinit-client" \ - --pk-init-principal="lha@TEST.H5L.SE" \ - --subject="uid=lha,DC=test,DC=h5l,DC=se" \ - --certificate="FILE:user.pem" - -4.24.2 Validate the certificate -------------------------------- - -hxtool also contains a tool that will validate certificates according to -rules from the PKIX document. These checks are not complete, but a good -test to check if you got all of the basic bits right in your -certificates. - - hxtool validate FILE:user.pem - -4.25 Use OpenSSL to create certificates -======================================= - -This section tries to give the CA owners hints how to create -certificates using OpenSSL (or CA software based on OpenSSL). - -4.25.1 Using OpenSSL to create certificates with krb5PrincipalName ------------------------------------------------------------------- - -To make OpenSSL create certificates with krb5PrincipalName use -`openssl.cnf' as described below. To see a complete example of creating -client and KDC certificates, see the test-data generation script -`lib/hx509/data/gen-req.sh' in the source-tree. The certicates it -creates are used to test the PK-INIT functionality in -`tests/kdc/check-kdc.in'. - -To use this example you have to use OpenSSL 0.9.8a or later. - - - [user_certificate] - subjectAltName=otherName:1.3.6.1.5.2.2;SEQUENCE:princ_name - - [princ_name] - realm = EXP:0, GeneralString:MY.REALM - principal_name = EXP:1, SEQUENCE:principal_seq - - [principal_seq] - name_type = EXP:0, INTEGER:1 - name_string = EXP:1, SEQUENCE:principals - - [principals] - princ1 = GeneralString:userid - -Command usage - - openssl x509 -extensions user_certificate - openssl ca -extensions user_certificate - -4.26 Using PK-INIT with Windows -=============================== - -4.26.1 Client configration --------------------------- - -Clients using a Windows KDC with PK-INIT need configuration since -windows uses pre-standard format and this can't be autodetected. - -The pkinit_win2k_require_binding option requires the reply for the KDC -to be of the new, secure, type that binds the request to reply. Before -clients should fake the reply from the KDC. To use this option you have -to apply a fix from Microsoft. - - [realms] - MY.MS.REALM = { - pkinit_win2k = yes - pkinit_win2k_require_binding = no - } - -4.26.2 Certificates -------------------- - -The client certificates need to have the extended keyusage "Microsoft -Smartcardlogin" (openssl have the oid shortname msSmartcardLogin). - -See Microsoft Knowledge Base Article - 281245 "Guidelines for Enabling -Smart Card Logon with Third-Party Certification Authorities" for a more -extensive description of how set setup an external CA to it includes -all information that will make a Windows KDC happy. - -4.26.3 Configure Windows 2000 CA --------------------------------- - -To enable Microsoft Smartcardlogin> for certificates in your Windows -2000 CA, you want to look at Microsoft Knowledge Base Article - 313274 -"HOW TO: Configure a Certification Authority to Issue Smart Card -Certificates in Windows". - - -File: heimdal.info, Node: Applications, Next: Things in search for a better place, Prev: Setting up a realm, Up: Top - -5 Applications -************** - -* Menu: - -* Authentication modules:: -* AFS:: - - -File: heimdal.info, Node: Authentication modules, Next: AFS, Prev: Applications, Up: Applications - -5.1 Authentication modules -========================== - -The problem of having different authentication mechanisms has been -recognised by several vendors, and several solutions have appeared. In -most cases these solutions involve some kind of shared modules that are -loaded at run-time. Modules for some of these systems can be found in -`lib/auth'. Presently there are modules for Digital's SIA, and IRIX' -`login' and `xdm' (in `lib/auth/afskauthlib'). - -* Menu: - -* Digital SIA:: -* IRIX:: - - -File: heimdal.info, Node: Digital SIA, Next: IRIX, Prev: Authentication modules, Up: Authentication modules - -5.1.1 Digital SIA ------------------ - -How to install the SIA module depends on which OS version you're -running. Tru64 5.0 has a new command, `siacfg', which makes this -process quite simple. If you have this program, you should just be able -to run: - siacfg -a KRB5 /usr/athena/lib/libsia_krb5.so - -On older versions, or if you want to do it by hand, you have to do the -following (not tested by us on Tru64 5.0): - - * Make sure `libsia_krb5.so' is available in `/usr/athena/lib'. If - `/usr/athena' is not on local disk, you might want to put it in - `/usr/shlib' or someplace else. If you do, you'll have to edit - `krb5_matrix.conf' to reflect the new location (you will also have - to do this if you installed in some other directory than - `/usr/athena'). If you built with shared libraries, you will have - to copy the shared `libkrb.so', `libdes.so', `libkadm.so', and - `libkafs.so' to a place where the loader can find them (such as - `/usr/shlib'). - - * Copy (your possibly edited) `krb5_matrix.conf' to `/etc/sia'. - - * Apply `security.patch' to `/sbin/init.d/security'. - - * Turn on KRB5 security by issuing `rcmgr set SECURITY KRB5' and - `rcmgr set KRB5_MATRIX_CONF krb5_matrix.conf'. - - * Digital thinks you should reboot your machine, but that really - shouldn't be necessary. It's usually sufficient just to run - `/sbin/init.d/security start' (and restart any applications that - use SIA, like `xdm'.) - -Users with local passwords (like `root') should be able to login safely. - -When using Digital's xdm the `KRB5CCNAME' environment variable isn't -passed along as it should (since xdm zaps the environment). Instead you -have to set `KRB5CCNAME' to the correct value in -`/usr/lib/X11/xdm/Xsession'. Add a line similar to - KRB5CCNAME=FILE:/tmp/krb5cc`id -u`_`ps -o ppid= -p $$`; export KRB5CCNAME -If you use CDE, `dtlogin' allows you to specify which additional -environment variables it should export. To add `KRB5CCNAME' to this -list, edit `/usr/dt/config/Xconfig', and look for the definition of -`exportList'. You want to add something like: - Dtlogin.exportList: KRB5CCNAME - -Notes to users with Enhanced security -..................................... - -Digital's `ENHANCED' (C2) security, and Kerberos solve two different -problems. C2 deals with local security, adds better control of who can -do what, auditing, and similar things. Kerberos deals with network -security. - -To make C2 security work with Kerberos you will have to do the -following. - - * Replace all occurrences of `krb5_matrix.conf' with - `krb5+c2_matrix.conf' in the directions above. - - * You must enable "vouching" in the `default' database. This will - make the OSFC2 module trust other SIA modules, so you can login - without giving your C2 password. To do this use `edauth' to edit - the default entry `/usr/tcb/bin/edauth -dd default', and add a - `d_accept_alternate_vouching' capability, if not already present. - - * For each user who does _not_ have a local C2 password, you should - set the password expiration field to zero. You can do this for each - user, or in the `default' table. To do this use `edauth' to set - (or change) the `u_exp' capability to `u_exp#0'. - - * You also need to be aware that the shipped `login', `rcp', and - `rshd', don't do any particular C2 magic (such as checking for - various forms of disabled accounts), so if you rely on those - features, you shouldn't use those programs. If you configure with - `--enable-osfc2', these programs will, however, set the login UID. - Still: use at your own risk. - -At present `su' does not accept the vouching flag, so it will not work -as expected. - -Also, kerberised ftp will not work with C2 passwords. You can solve this -by using both Digital's ftpd and our on different ports. - -*Remember*, if you do these changes you will get a system that most -certainly does _not_ fulfil the requirements of a C2 system. If C2 is -what you want, for instance if someone else is forcing you to use it, -you're out of luck. If you use enhanced security because you want a -system that is more secure than it would otherwise be, you probably got -an even more secure system. Passwords will not be sent in the clear, -for instance. - - -File: heimdal.info, Node: IRIX, Prev: Digital SIA, Up: Authentication modules - -5.1.2 IRIX ----------- - -The IRIX support is a module that is compatible with Transarc's -`afskauthlib.so'. It should work with all programs that use this -library. This should include `login' and `xdm'. - -The interface is not very documented but it seems that you have to copy -`libkafs.so', `libkrb.so', and `libdes.so' to `/usr/lib', or build your -`afskauthlib.so' statically. - -The `afskauthlib.so' itself is able to reside in `/usr/vice/etc', -`/usr/afsws/lib', or the current directory (wherever that is). - -IRIX 6.4 and newer seem to have all programs (including `xdm' and -`login') in the N32 object format, whereas in older versions they were -O32. For it to work, the `afskauthlib.so' library has to be in the same -object format as the program that tries to load it. This might require -that you have to configure and build for O32 in addition to the default -N32. - -Apart from this it should "just work"; there are no configuration files. - -Note that recent Irix 6.5 versions (at least 6.5.22) have PAM, -including a `pam_krb5.so' module. Not all relevant programs use PAM, -though, e.g. `ssh'. In particular, for console graphical login you need -to turn off `visuallogin' and turn on `xdm' with `chkconfig'. - - -File: heimdal.info, Node: AFS, Prev: Authentication modules, Up: Applications - -5.2 AFS -======= - -AFS is a distributed filesystem that uses Kerberos for authentication. - -For more information about AFS see OpenAFS `http://www.openafs.org/' -and Arla `http://www.stacken.kth.se/projekt/arla/'. - -5.2.1 How to get a KeyFile --------------------------- - -`ktutil -k AFSKEYFILE:KeyFile get afs@MY.REALM' - -or you can extract it with kadmin - - kadmin> ext -k AFSKEYFILE:/usr/afs/etc/KeyFile afs@My.CELL.NAME - -You have to make sure you have a `des-cbc-md5' encryption type since -that is the enctype that will be converted. - -5.2.2 How to convert a srvtab to a KeyFile ------------------------------------------- - -You need a `/usr/vice/etc/ThisCell' containing the cellname of your -AFS-cell. - -`ktutil copy krb4:/root/afs-srvtab AFSKEYFILE:/usr/afs/etc/KeyFile'. - -If keyfile already exists, this will add the new key in afs-srvtab to -KeyFile. - -5.3 Using 2b tokens with AFS -============================ - -5.3.1 What is 2b ? ------------------- - -2b is the name of the proposal that was implemented to give basic -Kerberos 5 support to AFS in rxkad. Its not real Kerberos 5 support -since it still uses fcrypt for data encryption and not Kerberos -encryption types. - -Its only possible (in all cases) to do this for DES encryption types -because only then the token (the AFS equivalent of a ticket) will be -smaller than the maximum size that can fit in the token cache in the -OpenAFS/Transarc client. It is a so tight fit that some extra wrapping -on the ASN1/DER encoding is removed from the Kerberos ticket. - -2b uses a Kerberos 5 EncTicketPart instead of a Kerberos 4 ditto for -the part of the ticket that is encrypted with the service's key. The -client doesn't know what's inside the encrypted data so to the client -it doesn't matter. - -To differentiate between Kerberos 4 tickets and Kerberos 5 tickets, 2b -uses a special kvno, 213 for 2b tokens and 255 for Kerberos 5 tokens. - -Its a requirement that all AFS servers that support 2b also support -native Kerberos 5 in rxkad. - -5.3.2 Configuring a Heimdal kdc to use 2b tokens ------------------------------------------------- - -Support for 2b tokens in the kdc are turned on for specific principals -by adding them to the string list option `[kdc]use_2b' in the kdc's -`krb5.conf' file. - - [kdc] - use_2b = { - afs@SU.SE = yes - afs/it.su.se@SU.SE = yes - } - -5.3.3 Configuring AFS clients for 2b support --------------------------------------------- - -There is no need to configure AFS clients for 2b support. The only -software that needs to be installed/upgrade is a Kerberos 5 enabled -`afslog'. - - -File: heimdal.info, Node: Things in search for a better place, Next: Kerberos 4 issues, Prev: Applications, Up: Top - -6 Things in search for a better place -************************************* - -6.1 Making things work on Ciscos -================================ - -Modern versions of Cisco IOS has some support for authenticating via -Kerberos 5. This can be used both by having the router get a ticket when -you login (boring), and by using Kerberos authenticated telnet to access -your router (less boring). The following has been tested on IOS -11.2(12), things might be different with other versions. Old versions -are known to have bugs. - -To make this work, you will first have to configure your router to use -Kerberos (this is explained in the documentation). A sample -configuration looks like the following: - - aaa new-model - aaa authentication login default krb5-telnet krb5 enable - aaa authorization exec krb5-instance - kerberos local-realm FOO.SE - kerberos srvtab entry host/router.foo.se 0 891725446 4 1 8 012345678901234567 - kerberos server FOO.SE 10.0.0.1 - kerberos instance map admin 15 - -This tells you (among other things) that when logging in, the router -should try to authenticate with kerberised telnet, and if that fails try -to verify a plain text password via a Kerberos ticket exchange (as -opposed to a local database, RADIUS or something similar), and if that -fails try the local enable password. If you're not careful when you -specify the `login default' authentication mechanism, you might not be -able to login at all. The `instance map' and `authorization exec' lines -says that people with `admin' instances should be given `enabled' shells -when logging in. - -The numbers after the principal on the `srvtab' line are principal type, -time stamp (in seconds since 1970), key version number (4), keytype (1 -== des), key length (always 8 with des), and then the key. - -To make the Heimdal KDC produce tickets that the Cisco can decode you -might have to turn on the `encode_as_rep_as_tgs_rep' flag in the KDC. -You will also have to specify that the router can't handle anything but -`des-cbc-crc'. This can be done with the `del_enctype' command of -`kadmin'. - -This all fine and so, but unless you have an IOS version with encryption -(available only in the U.S) it doesn't really solve any problems. Sure -you don't have to send your password over the wire, but since the telnet -connection isn't protected it's still possible for someone to steal your -session. This won't be fixed until someone adds integrity to the telnet -protocol. - -A working solution would be to hook up a machine with a real operating -system to the console of the Cisco and then use it as a backwards -terminal server. - - -File: heimdal.info, Node: Kerberos 4 issues, Next: Windows 2000 compatability, Prev: Things in search for a better place, Up: Top - -7 Kerberos 4 issues -******************* - -The KDC has built-in version 4 support. It is not enabled by default, -see setup how to set it up. - -The KDC will also have kaserver emulation and be able to handle -AFS-clients that use `klog'. - -* Menu: - -* Principal conversion issues:: -* Converting a version 4 database:: -* kaserver:: - - -File: heimdal.info, Node: Principal conversion issues, Next: Converting a version 4 database, Prev: Kerberos 4 issues, Up: Kerberos 4 issues - -7.1 Principal conversion issues -=============================== - -First, Kerberos 4 and Kerberos 5 principals are different. A version 4 -principal consists of a name, an instance, and a realm. A version 5 -principal has one or more components, and a realm (the terms "name" and -"instance" are still used, for the first and second component, -respectively). Also, in some cases the name of a version 4 principal -differs from the first component of the corresponding version 5 -principal. One notable example is the "host" type principals, where the -version 4 name is `rcmd' (for "remote command"), and the version 5 name -is `host'. For the class of principals that has a hostname as instance, -there is an other major difference, Kerberos 4 uses only the first -component of the hostname, whereas Kerberos 5 uses the fully qualified -hostname. - -Because of this it can be hard or impossible to correctly convert a -version 4 principal to a version 5 principal (1). The biggest problem is -to know if the conversion resulted in a valid principal. To give an -example, suppose you want to convert the principal `rcmd.foo'. - -The `rcmd' name suggests that the instance is a hostname (even if there -are exceptions to this rule). To correctly convert the instance `foo' -to a hostname, you have to know which host it is referring to. You can -to this by either guessing (from the realm) which domain name to -append, or you have to have a list of possible hostnames. In the -simplest cases you can cover most principals with the first rule. If you -have several domains sharing a single realm this will not usually work. -If the exceptions are few you can probably come by with a lookup table -for the exceptions. - -In a complex scenario you will need some kind of host lookup mechanism. -Using DNS for this is tempting, but DNS is error prone, slow and unsafe -(2). - -Fortunately, the KDC has a trump on hand: it can easily tell if a -principal exists in the database. The KDC will use -`krb5_425_conv_principal_ext' to convert principals when handling to -version 4 requests. - ----------- Footnotes ---------- - -(1) the other way is not always trivial either, but usually easier - -(2) at least until secure DNS is commonly available - - -File: heimdal.info, Node: Converting a version 4 database, Next: kaserver, Prev: Principal conversion issues, Up: Kerberos 4 issues - -7.2 Converting a version 4 database -=================================== - -If you want to convert an existing version 4 database, the principal -conversion issue arises too. - -If you decide to convert your database once and for all, you will only -have to do this conversion once. It is also possible to run a version 5 -KDC as a slave to a version 4 KDC. In this case this conversion will -happen every time the database is propagated. When doing this -conversion, there are a few things to look out for. If you have stale -entries in the database, these entries will not be converted. This might -be because these principals are not used anymore, or it might be just -because the principal couldn't be converted. - -You might also see problems with a many-to-one mapping of principals. -For instance, if you are using DNS lookups and you have two principals -`rcmd.foo' and `rcmd.bar', where `foo' is a CNAME for `bar', the -resulting principals will be the same. Since the conversion function -can't tell which is correct, these conflicts will have to be resolved -manually. - -7.2.1 Conversion example ------------------------- - -Given the following set of hosts and services: - - foo.se rcmd - mail.foo.se rcmd, pop - ftp.bar.se rcmd, ftp - -you have a database that consists of the following principals: - -`rcmd.foo', `rcmd.mail', `pop.mail', `rcmd.ftp', and `ftp.ftp'. - -lets say you also got these extra principals: `rcmd.gone', -`rcmd.old-mail', where `gone.foo.se' was a machine that has now passed -away, and `old-mail.foo.se' was an old mail machine that is now a CNAME -for `mail.foo.se'. - -When you convert this database you want the following conversions to be -done: - rcmd.foo host/foo.se - rcmd.mail host/mail.foo.se - pop.mail pop/mail.foo.se - rcmd.ftp host/ftp.bar.se - ftp.ftp ftp/ftp.bar.se - rcmd.gone removed - rcmd.old-mail removed - -A `krb5.conf' that does this looks like: - - [realms] - FOO.SE = { - v4_name_convert = { - host = { - ftp = ftp - pop = pop - rcmd = host - } - } - v4_instance_convert = { - foo = foo.se - ftp = ftp.bar.se - } - default_domain = foo.se - } - -The `v4_name_convert' section says which names should be considered -having an instance consisting of a hostname, and it also says how the -names should be converted (for instance `rcmd' should be converted to -`host'). The `v4_instance_convert' section says how a hostname should -be qualified (this is just a hosts-file in disguise). Host-instances -that aren't covered by `v4_instance_convert' are qualified by appending -the contents of the `default_domain'. - -Actually, this example doesn't work. Or rather, it works to well. Since -it has no way of knowing which hostnames are valid and which are not, it -will happily convert `rcmd.gone' to `host/gone.foo.se'. This isn't a -big problem, but if you have run your kerberos realm for a few years, -chances are big that you have quite a few `junk' principals. - -If you don't want this you can remove the `default_domain' statement, -but then you will have to add entries for _all_ your hosts in the -`v4_instance_convert' section. - -Instead of doing this you can use DNS to convert instances. This is not -a solution without problems, but it is probably easier than adding lots -of static host entries. - -To enable DNS lookup you should turn on `v4_instance_resolve' in the -`[libdefaults]' section. - -7.2.2 Converting a database ---------------------------- - -The database conversion is done with `hprop'. You can run this command -to propagate the database to the machine called `slave-server' (which -should be running a `hpropd'). - - hprop --source=krb4-db --master-key=/.m slave-server - -This command can also be to use for converting the v4 database on the -server: - - hprop -n --source=krb4-db -d /var/kerberos/principal --master-key=/.m | hpropd -n - -7.3 Version 4 Kadmin -==================== - -`kadmind' can act as a version 4 kadmind, and you can do most -operations, but with some restrictions (since the version 4 kadmin -protocol is, lets say, very ad hoc.) One example is that it only passes -des keys when creating principals and changing passwords (modern kpasswd -clients do send the password, so it's possible to to password quality -checks). Because of this you can only create principals with des keys, -and you can't set any flags or do any other fancy stuff. - -To get this to work, you have to add another entry to inetd (since -version 4 uses port 751, not 749). - -_And then there are a many more things you can do; more on this in a -later version of this manual. Until then, UTSL._ - - -File: heimdal.info, Node: kaserver, Prev: Converting a version 4 database, Up: Kerberos 4 issues - -7.4 kaserver -============ - -7.4.1 kaserver emulation ------------------------- - -The Heimdal kdc can emulate a kaserver. The kaserver is a Kerberos 4 -server with pre-authentication using Rx as the on-wire protocol. The kdc -contains a minimalistic Rx implementation. - -There are three parts of the kaserver; KAA (Authentication), KAT (Ticket -Granting), and KAM (Maintenance). The KAA interface and KAT interface -both passes over DES encrypted data-blobs (just like the -Kerberos-protocol) and thus do not need any other protection. The KAM -interface uses `rxkad' (Kerberos authentication layer for Rx) for -security and data protection, and is used for example for changing -passwords. This part is not implemented in the kdc. - -Another difference between the ka-protocol and the Kerberos 4 protocol -is that the pass-phrase is salted with the cellname in the `string to -key' function in the ka-protocol, while in the Kerberos 4 protocol there -is no salting of the password at all. To make sure AFS-compatible keys -are added to each principals when they are created or their password are -changed, `afs3-salt' should be added to `[kadmin]default_keys'. - -7.4.2 Transarc AFS Windows client ---------------------------------- - -The Transarc Windows client uses Kerberos 4 to obtain tokens, and thus -does not need a kaserver. The Windows client assumes that the Kerberos -server is on the same machine as the AFS-database server. If you do not -like to do that you can add a small program that runs on the database -servers that forward all kerberos requests to the real kerberos server. -A program that does this is `krb-forward' -(`ftp://ftp.stacken.kth.se/pub/projekts/krb-forward'). - - -File: heimdal.info, Node: Windows 2000 compatability, Next: Programming with Kerberos, Prev: Kerberos 4 issues, Up: Top - -8 Windows 2000 compatability -**************************** - -Windows 2000 (formerly known as Windows NT 5) from Microsoft implements -Kerberos 5. Their implementation, however, has some quirks, -peculiarities, and bugs. This chapter is a short summary of the things -that we have found out while trying to test Heimdal against Windows -2000. Another big problem with the Kerberos implementation in Windows -2000 is that the available documentation is more focused on getting -things to work rather than how they work, and not that useful in -figuring out how things really work. - -This information should apply to Heimdal 1.0 and Windows 2000 -Professional. It's of course subject to change all the time and mostly -consists of our not so inspired guesses. Hopefully it's still somewhat -useful. - -* Menu: - -* Configuring Windows 2000 to use a Heimdal KDC:: -* Inter-Realm keys (trust) between Windows 2000 and a Heimdal KDC:: -* Create account mappings:: -* Encryption types:: -* Authorisation data:: -* Quirks of Windows 2000 KDC:: -* Useful links when reading about the Windows 2000:: - - -File: heimdal.info, Node: Configuring Windows 2000 to use a Heimdal KDC, Next: Inter-Realm keys (trust) between Windows 2000 and a Heimdal KDC, Prev: Windows 2000 compatability, Up: Windows 2000 compatability - -8.1 Configuring Windows 2000 to use a Heimdal KDC -================================================= - -You need the command line program called `ksetup.exe' which is available -in the file `SUPPORT/TOOLS/SUPPORT.CAB' on the Windows 2000 Professional -CD-ROM. This program is used to configure the Kerberos settings on a -Workstation. - -`Ksetup' store the domain information under the registry key: -`HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\LSA\Kerberos\Domains'. - -Use the `kadmin' program in Heimdal to create a host principal in the -Kerberos realm. - - unix% kadmin - kadmin> ank --password=password host/datan.example.com - -The name `datan.example.com' should be replaced with DNS name of the -workstation. - -You must configure the workstation as a member of a workgroup, as -opposed to a member in an NT domain, and specify the KDC server of the -realm as follows: - C:> ksetup /setdomain EXAMPLE.COM - C:> ksetup /addkdc EXAMPLE.COM kdc.example.com - -Set the machine password, i.e. create the local keytab: - C:> ksetup /SetComputerPassword password - -The password used in `ksetup /setmachpassword' must be the same as the -password used in the `kadmin ank' command. - -The workstation must now be rebooted. - -A mapping between local NT users and Kerberos principals must be -specified. You have two choices. First: - - C:> ksetup /mapuser user@MY.REALM nt_user - -This will map a user to a specific principal; this allows you to have -other usernames in the realm than in your NT user database. (Don't ask -me why on earth you would want that....) - -You can also say: - C:> ksetup /mapuser * * -The Windows machine will now map any user to the corresponding -principal, for example `nisse' to the principal `nisse@MY.REALM'. -(This is most likely what you want.) - - -File: heimdal.info, Node: Inter-Realm keys (trust) between Windows 2000 and a Heimdal KDC, Next: Create account mappings, Prev: Configuring Windows 2000 to use a Heimdal KDC, Up: Windows 2000 compatability - -8.2 Inter-Realm keys (trust) between Windows 2000 and a Heimdal KDC -=================================================================== - -See also the Step-by-Step guide from Microsoft, referenced below. - -Install Windows 2000, and create a new controller (Active Directory -Server) for the domain. - -By default the trust will be non-transitive. This means that only users -directly from the trusted domain may authenticate. This can be changed -to transitive by using the `netdom.exe' tool. `netdom.exe' can also be -used to add the trust between two realms. - -You need to tell Windows 2000 on what hosts to find the KDCs for the -non-Windows realm with `ksetup', see *Note Configuring Windows 2000 to -use a Heimdal KDC::. - -This needs to be done on all computers that want enable cross-realm -login with `Mapped Names'. Then you need to add the inter-realm keys -on the Windows KDC. Start the Domain Tree Management tool (found in -Programs, Administrative tools, Active Directory Domains and Trusts). - -Right click on Properties of your domain, select the Trust tab. Press -Add on the appropriate trust windows and enter domain name and -password. When prompted if this is a non-Windows Kerberos realm, press -OK. - -Do not forget to add trusts in both directions (if that's what you -want). - -If you want to use `netdom.exe' instead of the Domain Tree Management -tool, you do it like this: - - netdom trust NT.REALM.EXAMPLE.COM /Domain:EXAMPLE.COM /add /realm /passwordt:TrustPassword - -You also need to add the inter-realm keys to the Heimdal KDC. Make sure -you have matching encryption types (DES, Arcfour and AES in case of -Longhorn) - -Another issue is salting. Since Windows 2000 does not seem to -understand Kerberos 4 salted hashes you might need to turn off anything -similar to the following if you have it, at least while adding the -principals that are going to share keys with Windows 2000. - - [kadmin] - default_keys = v5 v4 - -So remove v4 from default keys. - -What you probably want to use is this: - - [kadmin] - default_keys = des-cbc-crc:pw-salt arcfour-hmac-md5:pw-salt - -Once that is also done, you can add the required inter-realm keys: - - kadmin add krbtgt/NT.REALM.EXAMPLE.COM@EXAMPLE.COM - kadmin add krbtgt/REALM.EXAMPLE.COM@NT.EXAMPLE.COM - -Use the same passwords for both keys. - -Do not forget to reboot before trying the new realm-trust (after -running `ksetup'). It looks like it might work, but packets are never -sent to the non-Windows KDC. - - -File: heimdal.info, Node: Create account mappings, Next: Encryption types, Prev: Inter-Realm keys (trust) between Windows 2000 and a Heimdal KDC, Up: Windows 2000 compatability - -8.3 Create account mappings -=========================== - -Start the `Active Directory Users and Computers' tool. Select the View -menu, that is in the left corner just below the real menu (or press -Alt-V), and select Advanced Features. Right click on the user that you -are going to do a name mapping for and choose Name mapping. - -Click on the Kerberos Names tab and add a new principal from the -non-Windows domain. - -This adds `authorizationNames' entry to the users LDAP entry to the -Active Directory LDAP catalog. When you create users by script you can -add this entry instead. - - -File: heimdal.info, Node: Encryption types, Next: Authorisation data, Prev: Create account mappings, Up: Windows 2000 compatability - -8.4 Encryption types -==================== - -Windows 2000 supports both the standard DES encryptions (`des-cbc-crc' -and `des-cbc-md5') and its own proprietary encryption that is based on -MD4 and RC4 that is documented in and is supposed to be described in -`draft-brezak-win2k-krb-rc4-hmac-03.txt'. New users will get both MD4 -and DES keys. Users that are converted from a NT4 database, will only -have MD4 passwords and will need a password change to get a DES key. - - -File: heimdal.info, Node: Authorisation data, Next: Quirks of Windows 2000 KDC, Prev: Encryption types, Up: Windows 2000 compatability - -8.5 Authorisation data -====================== - -The Windows 2000 KDC also adds extra authorisation data in tickets. It -is at this point unclear what triggers it to do this. The format of -this data is only available under a "secret" license from Microsoft, -which prohibits you implementing it. - -A simple way of getting hold of the data to be able to understand it -better is described here. - - 1. Find the client example on using the SSPI in the SDK documentation. - - 2. Change "AuthSamp" in the source code to lowercase. - - 3. Build the program. - - 4. Add the "authsamp" principal with a known password to the - database. Make sure it has a DES key. - - 5. Run `ktutil add' to add the key for that principal to a keytab. - - 6. Run `appl/test/nt_gss_server -p 2000 -s authsamp --dump-auth=FILE' - where FILE is an appropriate file. - - 7. It should authenticate and dump for you the authorisation data in - the file. - - 8. The tool `lib/asn1/asn1_print' is somewhat useful for analysing - the data. - - -File: heimdal.info, Node: Quirks of Windows 2000 KDC, Next: Useful links when reading about the Windows 2000, Prev: Authorisation data, Up: Windows 2000 compatability - -8.6 Quirks of Windows 2000 KDC -============================== - -There are some issues with salts and Windows 2000. Using an empty -salt--which is the only one that Kerberos 4 supported, and is therefore -known as a Kerberos 4 compatible salt--does not work, as far as we can -tell from out experiments and users' reports. Therefore, you have to -make sure you keep around keys with all the different types of salts -that are required. Microsoft have fixed this issue post Windows 2003. - -Microsoft seems also to have forgotten to implement the checksum -algorithms `rsa-md4-des' and `rsa-md5-des'. This can make Name mapping -(*note Create account mappings::) fail if a `des-cbc-md5' key is used. -To make the KDC return only `des-cbc-crc' you must delete the -`des-cbc-md5' key from the kdc using the `kadmin del_enctype' command. - - kadmin del_enctype lha des-cbc-md5 - -You should also add the following entries to the `krb5.conf' file: - - [libdefaults] - default_etypes = des-cbc-crc - default_etypes_des = des-cbc-crc - -These configuration options will make sure that no checksums of the -unsupported types are generated. - - -File: heimdal.info, Node: Useful links when reading about the Windows 2000, Prev: Quirks of Windows 2000 KDC, Up: Windows 2000 compatability - -8.7 Useful links when reading about the Windows 2000 -==================================================== - -See also our paper presented at the 2001 Usenix Annual Technical -Conference, available in the proceedings or at -`http://www.usenix.org/publications/library/proceedings/usenix01/freenix01/westerlund.html'. - -There are lots of texts about Kerberos on Microsoft's web site, here is -a short list of the interesting documents that we have managed to find. - - * Step-by-Step Guide to Kerberos 5 (krb5 1.0) Interoperability: - `http://www.microsoft.com/technet/prodtechnol/windows2000serv/howto/kerbstep.mspx'. - Kerberos GSS-API (in Windows-eze SSPI), Windows as a client in a - non-Windows KDC realm, adding unix clients to a Windows 2000 KDC, - and adding cross-realm trust (*note Inter-Realm keys (trust) - between Windows 2000 and a Heimdal KDC::). - - * Windows 2000 Kerberos Authentication: - `www.microsoft.com/technet/prodtechnol/windows2000serv/deploy/confeat/kerberos.mspx'. - White paper that describes how Kerberos is used in Windows 2000. - - * Overview of Kerberos: - `http://support.microsoft.com/support/kb/articles/Q248/7/58.ASP'. - Links to useful other links. - - * Event logging for Kerberos: - `http://support.microsoft.com/support/kb/articles/Q262/1/77.ASP'. - Basically it say that you can add a registry key - `HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Lsa\Kerberos\Parameters\LogLevel' - with value DWORD equal to 1, and then you'll get logging in the - Event Logger. - - -Other useful programs include these: - - * pwdump2 - `http://www.bindview.com/Support/RAZOR/Utilities/Windows/pwdump2_readme.cfm' - - -File: heimdal.info, Node: Programming with Kerberos, Next: Migration, Prev: Windows 2000 compatability, Up: Top - -9 Programming with Kerberos -*************************** - -First you need to know how the Kerberos model works, go read the -introduction text (*note What is Kerberos?::). - -* Menu: - -* Kerberos 5 API Overview:: -* Walkthrough of a sample Kerberos 5 client:: -* Validating a password in a server application:: -* API differences to MIT Kerberos:: -* File formats:: - - -File: heimdal.info, Node: Kerberos 5 API Overview, Next: Walkthrough of a sample Kerberos 5 client, Prev: Programming with Kerberos, Up: Programming with Kerberos - -9.1 Kerberos 5 API Overview -=========================== - -All functions are documented in manual pages. This section tries to -give an overview of the major components used in Kerberos library, and -point to where to look for a specific function. - -9.1.1 Kerberos context ----------------------- - -A kerberos context (`krb5_context') holds all per thread state. All -global variables that are context specific are stored in this -structure, including default encryption types, credential cache (for -example, a ticket file), and default realms. - -See the manual pages for `krb5_context(3)' and `krb5_init_context(3)'. - -9.1.2 Kerberos authentication context -------------------------------------- - -Kerberos authentication context (`krb5_auth_context') holds all context -related to an authenticated connection, in a similar way to the -kerberos context that holds the context for the thread or process. - -The `krb5_auth_context' is used by various functions that are directly -related to authentication between the server/client. Example of data -that this structure contains are various flags, addresses of client and -server, port numbers, keyblocks (and subkeys), sequence numbers, replay -cache, and checksum types. - -See the manual page for `krb5_auth_context(3)'. - -9.1.3 Kerberos principal ------------------------- - -The Kerberos principal is the structure that identifies a user or -service in Kerberos. The structure that holds the principal is the -`krb5_principal'. There are function to extract the realm and elements -of the principal, but most applications have no reason to inspect the -content of the structure. - -The are several ways to create a principal (with different degree of -portability), and one way to free it. - -See manual page for `krb5_principal(3)' for more information about the -functions. - -9.1.4 Credential cache ----------------------- - -A credential cache holds the tickets for a user. A given user can have -several credential caches, one for each realm where the user have the -initial tickets (the first krbtgt). - -The credential cache data can be stored internally in different way, -each of them for different proposes. File credential (FILE) caches and -processes based (KCM) caches are for permanent storage. While memory -caches (MEMORY) are local caches to the local process. - -Caches are opened with `krb5_cc_resolve(3)' or created with -`krb5_cc_gen_unique(3)'. - -If the cache needs to be opened again (using `krb5_cc_resolve(3)') -`krb5_cc_close(3)' will close the handle, but not the remove the cache. -`krb5_cc_destroy(3)' will zero out the cache, remove the cache so it -can no longer be referenced. - -See also manual page for `krb5_ccache(3)' - -9.1.5 Kerberos errors ---------------------- - -Kerberos errors are based on the com_err library. All error codes are -32-bit signed numbers, the first 24 bits define what subsystem the -error originates from, and last 8 bits are 255 error codes within the -library. Each error code have fixed string associated with it. For -example, the error-code -1765328383 have the symbolic name -KRB5KDC_ERR_NAME_EXP, and associated error string "Client's entry in -database has expired". - -This is a great improvement compared to just getting one of the unix -error-codes back. However, Heimdal have an extention to pass back -customised errors messages. Instead of getting "Key table entry not -found", the user might back "failed to find -host/host.example.com@EXAMLE.COM(kvno 3) in keytab /etc/krb5.keytab -(des-cbc-crc)". This improves the chance that the user find the cause -of the error so you should use the customised error message whenever -its available. - -See also manual page for `krb5_get_error_string(3)' and -`krb5_get_err_text(3)'. - -9.1.6 Keytab management ------------------------ - -A keytab is a storage for locally stored keys. Heimdal includes keytab -support for Kerberos 5 keytabs, Kerberos 4 srvtab, AFS-KeyFile's, and -for storing keys in memory. - -Keytabs are used for servers and long-running services. - -See also manual page for `krb5_keytab(3)' - -9.1.7 Kerberos crypto ---------------------- - -Heimdal includes a implementation of the Kerberos crypto framework, all -crypto operations. - -See also manual page for `krb5_crypto_init(3)', `krb5_keyblock(3)', -`krb5_create_checksum(3)', and `krb5_encrypt(3)'. - - -File: heimdal.info, Node: Walkthrough of a sample Kerberos 5 client, Next: Validating a password in a server application, Prev: Kerberos 5 API Overview, Up: Programming with Kerberos - -9.2 Walkthrough of a sample Kerberos 5 client -============================================= - -This example contains parts of a sample TCP Kerberos 5 clients, if you -want a real working client, please look in `appl/test' directory in the -Heimdal distribution. - -All Kerberos error-codes that are returned from kerberos functions in -this program are passed to `krb5_err', that will print a descriptive -text of the error code and exit. Graphical programs can convert -error-code to a human readable error-string with the -`krb5_get_err_text(3)' function. - -Note that you should not use any Kerberos function before -`krb5_init_context()' have completed successfully. That is the reason -`err()' is used when `krb5_init_context()' fails. - -First the client needs to call `krb5_init_context' to initialise the -Kerberos 5 library. This is only needed once per thread in the program. -If the function returns a non-zero value it indicates that either the -Kerberos implementation is failing or its disabled on this host. - - #include - - int - main(int argc, char **argv) - { - krb5_context context; - - if (krb5_context(&context)) - errx (1, "krb5_context"); - -Now the client wants to connect to the host at the other end. The -preferred way of doing this is using `getaddrinfo(3)' (for operating -system that have this function implemented), since getaddrinfo is -neutral to the address type and can use any protocol that is available. - - struct addrinfo *ai, *a; - struct addrinfo hints; - int error; - - memset (&hints, 0, sizeof(hints)); - hints.ai_socktype = SOCK_STREAM; - hints.ai_protocol = IPPROTO_TCP; - - error = getaddrinfo (hostname, "pop3", &hints, &ai); - if (error) - errx (1, "%s: %s", hostname, gai_strerror(error)); - - for (a = ai; a != NULL; a = a->ai_next) { - int s; - - s = socket (a->ai_family, a->ai_socktype, a->ai_protocol); - if (s < 0) - continue; - if (connect (s, a->ai_addr, a->ai_addrlen) < 0) { - warn ("connect(%s)", hostname); - close (s); - continue; - } - freeaddrinfo (ai); - ai = NULL; - } - if (ai) { - freeaddrinfo (ai); - errx ("failed to contact %s", hostname); - } - -Before authenticating, an authentication context needs to be created. -This context keeps all information for one (to be) authenticated -connection (see `krb5_auth_context(3)'). - - status = krb5_auth_con_init (context, &auth_context); - if (status) - krb5_err (context, 1, status, "krb5_auth_con_init"); - -For setting the address in the authentication there is a help function -`krb5_auth_con_setaddrs_from_fd' that does everything that is needed -when given a connected file descriptor to the socket. - - status = krb5_auth_con_setaddrs_from_fd (context, - auth_context, - &sock); - if (status) - krb5_err (context, 1, status, - "krb5_auth_con_setaddrs_from_fd"); - -The next step is to build a server principal for the service we want to -connect to. (See also `krb5_sname_to_principal(3)'.) - - status = krb5_sname_to_principal (context, - hostname, - service, - KRB5_NT_SRV_HST, - &server); - if (status) - krb5_err (context, 1, status, "krb5_sname_to_principal"); - -The client principal is not passed to `krb5_sendauth(3)' function, this -causes the `krb5_sendauth' function to try to figure it out itself. - -The server program is using the function `krb5_recvauth(3)' to receive -the Kerberos 5 authenticator. - -In this case, mutual authentication will be tried. That means that the -server will authenticate to the client. Using mutual authentication is -good since it enables the user to verify that they are talking to the -right server (a server that knows the key). - -If you are using a non-blocking socket you will need to do all work of -`krb5_sendauth' yourself. Basically you need to send over the -authenticator from `krb5_mk_req(3)' and, in case of mutual -authentication, verifying the result from the server with -`krb5_rd_rep(3)'. - - status = krb5_sendauth (context, - &auth_context, - &sock, - VERSION, - NULL, - server, - AP_OPTS_MUTUAL_REQUIRED, - NULL, - NULL, - NULL, - NULL, - NULL, - NULL); - if (status) - krb5_err (context, 1, status, "krb5_sendauth"); - -Once authentication has been performed, it is time to send some data. -First we create a krb5_data structure, then we sign it with -`krb5_mk_safe(3)' using the `auth_context' that contains the -session-key that was exchanged in the -`krb5_sendauth(3)'/`krb5_recvauth(3)' authentication sequence. - - data.data = "hej"; - data.length = 3; - - krb5_data_zero (&packet); - - status = krb5_mk_safe (context, - auth_context, - &data, - &packet, - NULL); - if (status) - krb5_err (context, 1, status, "krb5_mk_safe"); - -And send it over the network. - - len = packet.length; - net_len = htonl(len); - - if (krb5_net_write (context, &sock, &net_len, 4) != 4) - err (1, "krb5_net_write"); - if (krb5_net_write (context, &sock, packet.data, len) != len) - err (1, "krb5_net_write"); - -To send encrypted (and signed) data `krb5_mk_priv(3)' should be used -instead. `krb5_mk_priv(3)' works the same way as `krb5_mk_safe(3)', -with the exception that it encrypts the data in addition to signing it. - - data.data = "hemligt"; - data.length = 7; - - krb5_data_free (&packet); - - status = krb5_mk_priv (context, - auth_context, - &data, - &packet, - NULL); - if (status) - krb5_err (context, 1, status, "krb5_mk_priv"); - -And send it over the network. - - len = packet.length; - net_len = htonl(len); - - if (krb5_net_write (context, &sock, &net_len, 4) != 4) - err (1, "krb5_net_write"); - if (krb5_net_write (context, &sock, packet.data, len) != len) - err (1, "krb5_net_write"); - -The server is using `krb5_rd_safe(3)' and `krb5_rd_priv(3)' to verify -the signature and decrypt the packet. - - -File: heimdal.info, Node: Validating a password in a server application, Next: API differences to MIT Kerberos, Prev: Walkthrough of a sample Kerberos 5 client, Up: Programming with Kerberos - -9.3 Validating a password in an application -=========================================== - -See the manual page for `krb5_verify_user(3)'. - - -File: heimdal.info, Node: API differences to MIT Kerberos, Next: File formats, Prev: Validating a password in a server application, Up: Programming with Kerberos - -9.4 API differences to MIT Kerberos -=================================== - -This section is somewhat disorganised, but so far there is no overall -structure to the differences, though some of the have their root in -that Heimdal uses an ASN.1 compiler and MIT doesn't. - -9.4.1 Principal and realms --------------------------- - -Heimdal stores the realm as a `krb5_realm', that is a `char *'. MIT -Kerberos uses a `krb5_data' to store a realm. - -In Heimdal `krb5_principal' doesn't contain the component `name_type'; -it's instead stored in component `name.name_type'. To get and set the -nametype in Heimdal, use `krb5_principal_get_type(3)' and -`krb5_principal_set_type(3)'. - -For more information about principal and realms, see -`krb5_principal(3)'. - -9.4.2 Error messages --------------------- - -To get the error string, Heimdal uses `krb5_get_error_string(3)' or, if -`NULL' is returned, `krb5_get_err_text(3)'. This is to return custom -error messages (like "Can't find host/datan.example.com@EXAMPLE.COM in -/etc/krb5.conf." instead of a "Key table entry not found" that -`error_message(3)' returns. - -Heimdal uses a threadsafe(r) version of the com_err interface; the -global `com_err' table isn't initialised. Then `error_message(3)' -returns quite a boring error string (just the error code itself). - - -File: heimdal.info, Node: File formats, Prev: API differences to MIT Kerberos, Up: Programming with Kerberos - -9.5 File formats -================ - -This section documents the diffrent file formats that are used in -Heimdal and other Kerberos implementations. - -9.5.1 keytab ------------- - -The keytab binary format is not a standard format. The format has -evolved and may continue to. It is however understood by several -Kerberos implementations including Heimdal, MIT, Sun's Java ktab and -are created by the ktpass.exe utility from Windows. So it has -established itself as the defacto format for storing Kerberos keys. - -The following C-like structure definitions illustrate the MIT keytab -file format. All values are in network byte order. All text is ASCII. - - keytab { - uint16_t file_format_version; /* 0x502 */ - keytab_entry entries[*]; - }; - - keytab_entry { - int32_t size; - uint16_t num_components; /* subtract 1 if version 0x501 */ - counted_octet_string realm; - counted_octet_string components[num_components]; - uint32_t name_type; /* not present if version 0x501 */ - uint32_t timestamp; - uint8_t vno8; - keyblock key; - uint32_t vno; /* only present if >= 4 bytes left in entry */ - }; - - counted_octet_string { - uint16_t length; - uint8_t data[length]; - }; - - keyblock { - uint16_t type; - counted_octet_string; - }; - -All numbers are stored in network byteorder (big endian) format. - -The keytab file format begins with the 16 bit file_format_version which -at the time this document was authored is 0x502. The format of older -keytabs is described at the end of this document. - -The file_format_version is immediately followed by an array of -keytab_entry structures which are prefixed with a 32 bit size indicating -the number of bytes that follow in the entry. Note that the size should -be evaluated as signed. This is because a negative value indicates that -the entry is in fact empty (e.g. it has been deleted) and that the -negative value of that negative value (which is of course a positive -value) is the offset to the next keytab_entry. Based on these size -values alone the entire keytab file can be traversed. - -The size is followed by a 16 bit num_components field indicating the -number of counted_octet_string components in the components array. - -The num_components field is followed by a counted_octet_string -representing the realm of the principal. - -A counted_octet_string is simply an array of bytes prefixed with a 16 -bit length. For the realm and name components, the counted_octet_string -bytes are ASCII encoded text with no zero terminator. - -Following the realm is the components array that represents the name of -the principal. The text of these components may be joined with slashs -to construct the typical SPN representation. For example, the service -principal HTTP/www.foo.net@FOO.NET would consist of name components -"HTTP" followed by "www.foo.net". - -Following the components array is the 32 bit name_type (e.g. 1 is -KRB5_NT_PRINCIPAL, 2 is KRB5_NT_SRV_INST, 5 is KRB5_NT_UID, etc). In -practice the name_type is almost certainly 1 meaning KRB5_NT_PRINCIPAL. - -The 32 bit timestamp indicates the time the key was established for that -principal. The value represents the number of seconds since Jan 1, 1970. - -The 8 bit vno8 field is the version number of the key. This value is -overridden by the 32 bit vno field if it is present. The vno8 field is -filled with the lower 8 bits of the 32 bit protocol kvno field. - -The keyblock structure consists of a 16 bit value indicating the -encryption type and is a counted_octet_string containing the key. The -encryption type is the same as the Kerberos standard (e.g. 3 is -des-cbc-md5, 23 is arcfour-hmac-md5, etc). - -The last field of the keytab_entry structure is optional. If the size of -the keytab_entry indicates that there are at least 4 bytes remaining, a -32 bit value representing the key version number is present. This value -supersedes the 8 bit vno8 value preceeding the keyblock. - -Older keytabs with a file_format_version of 0x501 are different in -three ways: - -All integers are in host byte order [1]. - -The num_components field is 1 too large (i.e. after decoding, decrement by 1). - -The 32 bit name_type field is not present. - -[1] The file_format_version field should really be treated as two -separate 8 bit quantities representing the major and minor version -number respectively. - -9.5.2 Heimdal database dump file --------------------------------- - -Format of the Heimdal text dump file as of Heimdal 0.6.3: - -Each line in the dump file is one entry in the database. - -Each field of a line is separated by one or more spaces, with the -exception of fields consisting of principals containing spaces, where -space can be quoted with \ and \ is quoted by \. - -Fields and their types are: - - Quoted princial (quote character is \) [string] - Keys [keys] - Created by [event] - Modified by [event optional] - Valid start time [time optional] - Valid end time [time optional] - Password end valid time [time optional] - Max lifetime of ticket [time optional] - Max renew time of ticket [integer optional] - Flags [hdb flags] - Generation number [generation optional] - Extensions [extentions optional] - -Fields following these silently are ignored. - -All optional fields will be skipped if they fail to parse (or comprise -the optional field marker of "-", w/o quotes). - -Example: - - fred@EXAMPLE.COM 27:1:16:e8b4c8fc7e60b9e641dcf4cff3f08a701d982a2f89ba373733d26ca59ba6c789666f6b8bfcf169412bb1e5dceb9b33cda29f3412:-:1:3:4498a933881178c744f4232172dcd774c64e81fa6d05ecdf643a7e390624a0ebf3c7407a:-:1:2:b01934b13eb795d76f3a80717d469639b4da0cfb644161340ef44fdeb375e54d684dbb85:-:1:1:ea8e16d8078bf60c781da90f508d4deccba70595258b9d31888d33987cd31af0c9cced2e:- 20020415130120:admin@EXAMPLE.COM 20041221112428:fred@EXAMPLE.COM - - - 86400 604800 126 20020415130120:793707:28 - - -Encoding of types are as follows: - -keys - kvno:[masterkvno:keytype:keydata:salt]{zero or more separated by :} - - kvno is the key version number. - - keydata is hex-encoded - - masterkvno is the kvno of the database master key. If this field - is empty, the kadmin load and merge operations will encrypt the - key data with the master key if there is one. Otherwise the key - data will be imported asis. - - salt is encoded as "-" (no/default salt) or - - salt-type / - salt-type / "string" - salt-type / hex-encoded-data - - keytype is the protocol enctype number; see enum ENCTYPE in - include/krb5_asn1.h for values. - - Example: - 27:1:16:e8b4c8fc7e60b9e641dcf4cff3f08a701d982a2f89ba373733d26ca59ba6c789666f6b8bfcf169412bb1e5dceb9b33cda29f3412:-:1:3:4498a933881178c744f4232172dcd774c64e81fa6d05ecdf643a7e390624a0ebf3c7407a:-:1:2:b01934b13eb795d76f3a80717d469639b4da0cfb644161340ef44fdeb375e54d684dbb85:-:1:1:ea8e16d8078bf60c781da90f508d4deccba70595258b9d31888d33987cd31af0c9cced2e:- - - kvno=27,{key: masterkvno=1,keytype=des3-cbc-sha1,keydata=..., default salt}... - -time - Format of the time is: YYYYmmddHHMMSS, corresponding to strftime - format "%Y%m%d%k%M%S". - - Time is expressed in UTC. - - Time can be optional (using -), when the time 0 is used. - - Example: - - 20041221112428 - -event - time:principal - - time is as given in format time - - principal is a string. Not quoting it may not work in earlier - versions of Heimdal. - - Example: - 20041221112428:bloggs@EXAMPLE.COM - -hdb flags - Integer encoding of HDB flags, see HDBFlags in lib/hdb/hdb.asn1. - Each bit in the integer is the same as the bit in the - specification. - -generation: - time:usec:gen - - usec is a the microsecond, integer. gen is generation number, - integer. - - The generation can be defaulted (using '-') or the empty string - -extensions: - first-hex-encoded-HDB-Extension[:second-...] - - HDB-extension is encoded the DER encoded HDB-Extension from - lib/hdb/hdb.asn1. Consumers HDB extensions should be aware that - unknown entires needs to be preserved even thought the ASN.1 data - content might be unknown. There is a critical flag in the data to - show to the KDC that the entry MUST be understod if the entry is - to be used. - - - -File: heimdal.info, Node: Migration, Next: Acknowledgments, Prev: Programming with Kerberos, Up: Top - -10 Migration -************ - -10.1 General issues -=================== - -When migrating from a Kerberos 4 KDC. - -10.2 Order in what to do things: -================================ - - * Convert the database, check all principals that hprop complains - about. - - `hprop -n --source=| hpropd -n' - - Replace with whatever source you have, like krb4-db or - krb4-dump. - - * Run a Kerberos 5 slave for a while. - - * Figure out if it does everything you want it to. - - Make sure that all things that you use works for you. - - * Let a small number of controlled users use Kerberos 5 tools. - - Find a sample population of your users and check what programs - they use, you can also check the kdc-log to check what ticket are - checked out. - - * Burn the bridge and change the master. - - * Let all users use the Kerberos 5 tools by default. - - * Turn off services that do not need Kerberos 4 authentication. - - Things that might be hard to get away is old programs with support - for Kerberos 4. Example applications are old Eudora installations - using KPOP, and Zephyr. Eudora can use the Kerberos 4 kerberos in - the Heimdal kdc. - - - -File: heimdal.info, Node: Acknowledgments, Prev: Migration, Up: Top - -Appendix A Acknowledgments -************************** - -Eric Young wrote "libdes". Heimdal used to use libdes, without it -kth-krb would never have existed. Since there are no longer any Eric -Young code left in the library, we renamed it to libhcrypto. - -All functions in libhcrypto have been re-implemented or used available -public domain code. The core AES function where written by Vincent -Rijmen, Antoon Bosselaers and Paulo Barreto. The core DES SBOX -transformation was written by Richard Outerbridge. `imath' that is used -for public key crypto support is written by Michael J. Fromberger. - -The University of California at Berkeley initially wrote `telnet', and -`telnetd'. The authentication and encryption code of `telnet' and -`telnetd' was added by David Borman (then of Cray Research, Inc). The -encryption code was removed when this was exported and then added back -by Juha Eskelinen. - -The `popper' was also a Berkeley program initially. - -Some of the functions in `libroken' also come from Berkeley by way of -NetBSD/FreeBSD. - -`editline' was written by Simmule Turner and Rich Salz. Heimdal -contains a modifed copy. - -The `getifaddrs' implementation for Linux was written by Hideaki -YOSHIFUJI for the Usagi project. - -The `pkcs11.h' headerfile was written by the Scute project. - -Bugfixes, documentation, encouragement, and code has been contributed -by: -Alexander Boström - -Andreaw Bartlett - -Björn Sandell - -Brandon S. Allbery KF8NH - -Brian A May - -Chaskiel M Grundman - -Cizzi Storm - -Daniel Kouril - -David Love - -Derrick J Brashear - -Douglas E Engert - -Frank van der Linden - -Jason McIntyre - -Johan Ihrén - -Jun-ichiro itojun Hagino - -Ken Hornstein - -Magnus Ahltorp - -Marc Horowitz - -Mario Strasser - -Mark Eichin - -Mattias Amnefelt - -Michael B Allen - -Michael Fromberger - -Michal Vocu - -Miroslav Ruda - -Petr Holub - -Phil Fisher - -Rafal Malinowski - -Richard Nyberg - -Åke Sandgren - -and we hope that those not mentioned here will forgive us. - -All bugs were introduced by ourselves. - - - -Tag Table: -Node: Top211 -Node: Introduction1916 -Node: What is Kerberos?4724 -Node: Building and Installing9837 -Node: Setting up a realm13472 -Node: Configuration file14394 -Node: Creating the database17177 -Node: Modifying the database20101 -Node: Checking the setup21694 -Node: keytabs22546 -Node: Serving Kerberos 4/524/kaserver23414 -Node: Remote administration24990 -Node: Password changing26920 -Node: Testing clients and servers30618 -Node: Slave Servers30946 -Node: Incremental propagation32701 -Node: Encryption types and salting35491 -Node: Cross realm37649 -Node: Transit policy40194 -Node: Setting up DNS41866 -Node: Using LDAP to store the database44341 -Node: Providing Kerberos credentials to servers and programs50121 -Node: Setting up PK-INIT52216 -Node: Applications63946 -Node: Authentication modules64146 -Node: Digital SIA64740 -Node: IRIX69124 -Node: AFS70414 -Node: Things in search for a better place73058 -Node: Kerberos 4 issues75787 -Node: Principal conversion issues76249 -Ref: Principal conversion issues-Footnote-178480 -Ref: Principal conversion issues-Footnote-278548 -Node: Converting a version 4 database78601 -Node: kaserver83669 -Node: Windows 2000 compatability85440 -Node: Configuring Windows 2000 to use a Heimdal KDC86640 -Node: Inter-Realm keys (trust) between Windows 2000 and a Heimdal KDC88630 -Node: Create account mappings91324 -Node: Encryption types92086 -Node: Authorisation data92691 -Node: Quirks of Windows 2000 KDC93843 -Node: Useful links when reading about the Windows 200095147 -Node: Programming with Kerberos96976 -Node: Kerberos 5 API Overview97452 -Node: Walkthrough of a sample Kerberos 5 client101878 -Node: Validating a password in a server application109666 -Node: API differences to MIT Kerberos110001 -Node: File formats111459 -Node: Migration119941 -Node: Acknowledgments121221 - -End Tag Table diff -U 3 -H -d -r -N -x Makefile.in -x 'config.h.in*' -x 'output*' -x requests -x 'traces*' -x '*.loT' -x aclocal.m4 -x configure -- heimdal-1.0.1/doc/heimdal.info.in heimdal-1.0.1.work/doc/heimdal.info.in --- heimdal-1.0.1/doc/heimdal.info.in 1970-01-01 02:00:00.000000000 +0200 +++ heimdal-1.0.1.work/doc/heimdal.info.in 2007-12-05 22:59:38.000000000 +0200 @@ -0,0 +1,3355 @@ +This is heimdal.info, produced by makeinfo version 4.7 from +heimdal.texi. + +INFO-DIR-SECTION Security +START-INFO-DIR-ENTRY +* Heimdal: (heimdal). The Kerberos 5 distribution from KTH +END-INFO-DIR-ENTRY + + +File: heimdal.info, Node: Top, Next: Introduction, Prev: (dir), Up: (dir) + +Heimdal +******* + +This manual is last updated $Date: 2007-07-17 13:42:57 +0200 (Tue, 17 +Jul 2007) $ for version 1.0 of Heimdal. + +* Menu: + +* Introduction:: +* What is Kerberos?:: +* Building and Installing:: +* Setting up a realm:: +* Applications:: +* Things in search for a better place:: +* Kerberos 4 issues:: +* Windows 2000 compatability:: +* Programming with Kerberos:: +* Migration:: +* Acknowledgments:: + + --- The Detailed Node Listing --- + +Setting up a realm + +* Configuration file:: +* Creating the database:: +* Modifying the database:: +* keytabs:: +* Serving Kerberos 4/524/kaserver:: +* Remote administration:: +* Password changing:: +* Testing clients and servers:: +* Slave Servers:: +* Incremental propagation:: +* Encryption types and salting:: +* Cross realm:: +* Transit policy:: +* Setting up DNS:: +* Using LDAP to store the database:: +* Providing Kerberos credentials to servers and programs:: +* Setting up PK-INIT:: + +Applications + +* Authentication modules:: +* AFS:: + +Authentication modules + +* Digital SIA:: +* IRIX:: + +Kerberos 4 issues + +* Principal conversion issues:: +* Converting a version 4 database:: +* kaserver:: + +Windows 2000 compatability + +* Configuring Windows 2000 to use a Heimdal KDC:: +* Inter-Realm keys (trust) between Windows 2000 and a Heimdal KDC:: +* Create account mappings:: +* Encryption types:: +* Authorisation data:: +* Quirks of Windows 2000 KDC:: +* Useful links when reading about the Windows 2000:: + +Programming with Kerberos + +* Kerberos 5 API Overview:: +* Walkthrough of a sample Kerberos 5 client:: +* Validating a password in a server application:: +* API differences to MIT Kerberos:: +* File formats:: + + +File: heimdal.info, Node: Introduction, Next: What is Kerberos?, Prev: Top, Up: Top + +1 Introduction +************** + +What is Heimdal? +================ + +Heimdal is a free implementation of Kerberos 5. The goals are to: + + * have an implementation that can be freely used by anyone + + * be protocol compatible with existing implementations and, if not in + conflict, with RFC 4120 (and any future updated RFC). RFC 4120 + replaced RFC 1510. + + * be reasonably compatible with the M.I.T Kerberos V5 API + + * have support for Kerberos V5 over GSS-API (RFC1964) + + * include the most important and useful application programs (rsh, + telnet, popper, etc.) + + * include enough backwards compatibility with Kerberos V4 + +Status +====== + +Heimdal has the following features (this does not mean any of this +works): + + * a stub generator and a library to encode/decode/whatever ASN.1/DER + stuff + + * a `libkrb5' library that should be possible to get to work with + simple applications + + * a GSS-API library + + * `kinit', `klist', `kdestroy' + + * `telnet', `telnetd' + + * `rsh', `rshd' + + * `popper', `push' (a movemail equivalent) + + * `ftp', and `ftpd' + + * a library `libkafs' for authenticating to AFS and a program + `afslog' that uses it + + * some simple test programs + + * a KDC that supports most things; optionally, it may also support + Kerberos V4 and kaserver, + + * simple programs for distributing databases between a KDC master and + slaves + + * a password changing daemon `kpasswdd', library functions for + changing passwords and a simple client + + * some kind of administration system + + * Kerberos V4 support in many of the applications. + +Bug reports +=========== + +If you find bugs in this software, make sure it is a genuine bug and not +just a part of the code that isn't implemented. + +Bug reports should be sent to . Please include +information on what machine and operating system (including version) +you are running, what you are trying to do, what happens, what you +think should have happened, an example for us to repeat, the output you +get when trying the example, and a patch for the problem if you have +one. Please make any patches with `diff -u' or `diff -c'. + +Suggestions, comments and other non bug reports are also welcome. + +Mailing list +============ + +There are two mailing lists with talk about Heimdal. + is a low-volume announcement list, while + is for general discussion. Send a message to + to subscribe. + +Heimdal source code, binaries and the manual +============================================ + +The source code for heimdal, links to binaries and the manual (this +document) can be found on our web-page at +`http://www.pdc.kth.se/heimdal/'. + + +File: heimdal.info, Node: What is Kerberos?, Next: Building and Installing, Prev: Introduction, Up: Top + +2 What is Kerberos? +******************* + + Now this Cerberus had three heads of dogs, + the tail of a dragon, and on his back the + heads of all sorts of snakes. + -- Pseudo-Apollodorus Library 2.5.12 + +Kerberos is a system for authenticating users and services on a network. +It is built upon the assumption that the network is "unsafe". For +example, data sent over the network can be eavesdropped and altered, and +addresses can also be faked. Therefore they cannot be used for +authentication purposes. + +Kerberos is a trusted third-party service. That means that there is a +third party (the kerberos server) that is trusted by all the entities on +the network (users and services, usually called "principals"). All +principals share a secret password (or key) with the kerberos server and +this enables principals to verify that the messages from the kerberos +server are authentic. Thus trusting the kerberos server, users and +services can authenticate each other. + +2.1 Basic mechanism +=================== + + *Note* This discussion is about Kerberos version 4, but version 5 + works similarly. + +In Kerberos, principals use "tickets" to prove that they are who they +claim to be. In the following example, A is the initiator of the +authentication exchange, usually a user, and B is the service that A +wishes to use. + +To obtain a ticket for a specific service, A sends a ticket request to +the kerberos server. The request contains A's and B's names (along with +some other fields). The kerberos server checks that both A and B are +valid principals. + +Having verified the validity of the principals, it creates a packet +containing A's and B's names, A's network address (A), the +current time (T), the lifetime of the ticket (LIFE), and a +secret "session key" (K). This packet is encrypted with B's secret +key (K). The actual ticket (T) looks like this: ({A, B, +A, T, LIFE, K}K). + +The reply to A consists of the ticket (T), B's name, the current +time, the lifetime of the ticket, and the session key, all encrypted in +A's secret key ({B, T, LIFE, K, T}K). A decrypts the +reply and retains it for later use. + + +Before sending a message to B, A creates an authenticator consisting of +A's name, A's address, the current time, and a "checksum" chosen by A, +all encrypted with the secret session key ({A, A, T, +CHECKSUM}K). This is sent together with the ticket received from +the kerberos server to B. Upon reception, B decrypts the ticket using +B's secret key. Since the ticket contains the session key that the +authenticator was encrypted with, B can now also decrypt the +authenticator. To verify that A really is A, B now has to compare the +contents of the ticket with that of the authenticator. If everything +matches, B now considers A as properly authenticated. + +2.2 Different attacks +===================== + +Impersonating A +--------------- + +An impostor, C could steal the authenticator and the ticket as it is +transmitted across the network, and use them to impersonate A. The +address in the ticket and the authenticator was added to make it more +difficult to perform this attack. To succeed C will have to either use +the same machine as A or fake the source addresses of the packets. By +including the time stamp in the authenticator, C does not have much +time in which to mount the attack. + +Impersonating B +--------------- + +C can hijack B's network address, and when A sends her credentials, C +just pretend to verify them. C can't be sure that she is talking to A. + +2.3 Defence strategies +====================== + +It would be possible to add a "replay cache" to the server side. The +idea is to save the authenticators sent during the last few minutes, so +that B can detect when someone is trying to retransmit an already used +message. This is somewhat impractical (mostly regarding efficiency), +and is not part of Kerberos 4; MIT Kerberos 5 contains it. + +To authenticate B, A might request that B sends something back that +proves that B has access to the session key. An example of this is the +checksum that A sent as part of the authenticator. One typical +procedure is to add one to the checksum, encrypt it with the session +key and send it back to A. This is called "mutual authentication". + +The session key can also be used to add cryptographic checksums to the +messages sent between A and B (known as "message integrity"). +Encryption can also be added ("message confidentiality"). This is +probably the best approach in all cases. + +2.4 Further reading +=================== + +The original paper on Kerberos from 1988 is `Kerberos: An +Authentication Service for Open Network Systems', by Jennifer Steiner, +Clifford Neuman and Jeffrey I. Schiller. + +A less technical description can be found in `Designing an +Authentication System: a Dialogue in Four Scenes' by Bill Bryant, also +from 1988. + +These documents can be found on our web-page at +`http://www.pdc.kth.se/kth-krb/'. + + +File: heimdal.info, Node: Building and Installing, Next: Setting up a realm, Prev: What is Kerberos?, Up: Top + +3 Building and Installing +************************* + +Heimdal uses GNU Autoconf to configure for specific hosts, and GNU +Automake to manage makefiles. If this is new to you, the short +instruction is to run the `configure' script in the top level +directory, and when that finishes `make'. + +If you want to build the distribution in a different directory from the +source directory, you will need a make that implements VPATH correctly, +such as GNU make. + +You will need to build the distribution: + + * A compiler that supports a "loose" ANSI C mode, such as `gcc'. + + * lex or flex + + * awk + + * yacc or bison + + * a socket library + + * NDBM or Berkeley DB for building the server side. + +When everything is built, you can install by doing `make install'. The +default location for installation is `/usr/heimdal', but this can be +changed by running `configure' with `--prefix=/some/other/place'. + +If you need to change the default behaviour, configure understands the +following options: + +`--without-berkeley-db' + DB is preferred before NDBM, but if you for some reason want to + use NDBM instead, you can use this option. + +`--with-krb4=`dir'' + Gives the location of Kerberos 4 libraries and headers. This + enables Kerberos 4 support in the applications (telnet, rsh, + popper, etc) and the KDC. It is automatically found if present + under `/usr/athena'. If you keep libraries and headers in + different places, you can instead give the path to each with the + `--with-krb4-lib=`dir'', and `--with-krb4-include=`dir'' options. + + You will need a fairly recent version of our Kerberos 4 + distribution for `rshd' and `popper' to support version 4 clients. + +`--enable-dce' + Enables support for getting DCE credentials and tokens. See the + README files in `appl/dceutils' for more information. + +`--disable-otp' + By default some of the application programs will build with + support for one-time passwords (OTP). Use this option to disable + that support. + +`--enable-osfc2' + Enable some C2 support for OSF/Digital Unix/Tru64. Use this + option if you are running your OSF operating system in C2 mode. + +`--with-readline=`dir'' + Gives the path for the GNU Readline library, which will be used in + some programs. If no readline library is found, the (simpler) + editline library will be used instead. + +`--with-hesiod=`dir'' + Enables hesiod support in push. + +`--enable-netinfo' + Add support for using netinfo to lookup configuration information. + Probably only useful (and working) on NextStep/Mac OS X. + +`--without-ipv6' + Disable the IPv6 support. + +`--with-openldap' + Compile Heimdal with support for storing the database in LDAP. + Requires OpenLDAP `http://www.openldap.org'. See + `http://www.padl.com/Research/Heimdal.html' for more information. + +`--enable-bigendian' + +`--enable-littleendian' + Normally, the build process will figure out by itself if the + machine is big or little endian. It might fail in some cases when + cross-compiling. If it does fail to figure it out, use the + relevant of these two options. + +`--with-mips-abi=ABI' + On Irix there are three different ABIs that can be used (`32', + `n32', or `64'). This option allows you to override the automatic + selection. + +`--disable-mmap' + Do not use the mmap system call. Normally, configure detects if + there is a working mmap and it is only used if there is one. Only + try this option if it fails to work anyhow. + + + +File: heimdal.info, Node: Setting up a realm, Next: Applications, Prev: Building and Installing, Up: Top + +4 Setting up a realm +******************** + +A realm is an administrative domain. The name of a Kerberos realm is +usually the Internet domain name in uppercase. Call your realm the same +as your Internet domain name if you do not have strong reasons for not +doing so. It will make life easier for you and everyone else. + +* Menu: + +* Configuration file:: +* Creating the database:: +* Modifying the database:: +* Checking the setup:: +* keytabs:: +* Serving Kerberos 4/524/kaserver:: +* Remote administration:: +* Password changing:: +* Testing clients and servers:: +* Slave Servers:: +* Incremental propagation:: +* Encryption types and salting:: +* Cross realm:: +* Transit policy:: +* Setting up DNS:: +* Using LDAP to store the database:: +* Providing Kerberos credentials to servers and programs:: +* Setting up PK-INIT:: + + +File: heimdal.info, Node: Configuration file, Next: Creating the database, Prev: Setting up a realm, Up: Setting up a realm + +4.1 Configuration file +====================== + +To setup a realm you will first have to create a configuration file: +`/etc/krb5.conf'. The `krb5.conf' file can contain many configuration +options, some of which are described here. + +There is a sample `krb5.conf' supplied with the distribution. + +The configuration file is a hierarchical structure consisting of +sections, each containing a list of bindings (either variable +assignments or subsections). A section starts with `[`section-name']'. +A binding consists of a left hand side, an equal sign (`=') and a right +hand side (the left hand side tag must be separated from the equal sign +with some whitespace). Subsections have a `{' as the first +non-whitespace character after the equal sign. All other bindings are +treated as variable assignments. The value of a variable extends to the +end of the line. + + [section1] + a-subsection = { + var = value1 + other-var = value with {} + sub-sub-section = { + var = 123 + } + } + var = some other value + [section2] + var = yet another value + +In this manual, names of sections and bindings will be given as strings +separated by slashes (`/'). The `other-var' variable will thus be +`section1/a-subsection/other-var'. + +For in-depth information about the contents of the configuration file, +refer to the `krb5.conf' manual page. Some of the more important +sections are briefly described here. + +The `libdefaults' section contains a list of library configuration +parameters, such as the default realm and the timeout for KDC +responses. The `realms' section contains information about specific +realms, such as where they hide their KDC. This section serves the same +purpose as the Kerberos 4 `krb.conf' file, but can contain more +information. Finally the `domain_realm' section contains a list of +mappings from domains to realms, equivalent to the Kerberos 4 +`krb.realms' file. + +To continue with the realm setup, you will have to create a +configuration file, with contents similar to the following. + + [libdefaults] + default_realm = MY.REALM + [realms] + MY.REALM = { + kdc = my.kdc my.slave.kdc + kdc = my.third.kdc + } + [domain_realm] + .my.domain = MY.REALM + +If you use a realm name equal to your domain name, you can omit the +`libdefaults', and `domain_realm', sections. If you have a DNS +SRV-record for your realm, or your Kerberos server has DNS CNAME +`kerberos.my.realm', you can omit the `realms' section too. + + +File: heimdal.info, Node: Creating the database, Next: Modifying the database, Prev: Configuration file, Up: Setting up a realm + +4.2 Creating the database +========================= + +The database library will look for the database in the directory +`@DBDIR@', so you should probably create that directory. Make +sure the directory has restrictive permissions. + + # mkdir @DBDIR@ + +The keys of all the principals are stored in the database. If you +choose to, these can be encrypted with a master key. You do not have to +remember this key (or password), but just to enter it once and it will +be stored in a file (`@DBDIR@/m-key'). If you want to have a +master key, run `kstash' to create this master key: + + # kstash + Master key: + Verifying password - Master key: + +If you want to generate a random master key you can use the -random-key +to kstash. This will make sure you have a good key on which attackers +can't do a dictionary attack. + +If you have a master key, make sure you make a backup of your master +key file; without it backups of the database are of no use. + +To initialise the database use the `kadmin' program, with the `-l' +option (to enable local database mode). First issue a `init MY.REALM' +command. This will create the database and insert default principals +for that realm. You can have more than one realm in one database, so +`init' does not destroy any old database. + +Before creating the database, `init' will ask you some questions about +maximum ticket lifetimes. + +After creating the database you should probably add yourself to it. You +do this with the `add' command. It takes as argument the name of a +principal. The principal should contain a realm, so if you haven't set +up a default realm, you will need to explicitly include the realm. + + # kadmin -l + kadmin> init MY.REALM + Realm max ticket life [unlimited]: + Realm max renewable ticket life [unlimited]: + kadmin> add me + Max ticket life [unlimited]: + Max renewable life [unlimited]: + Attributes []: + Password: + Verifying password - Password: + +Now start the KDC and try getting a ticket. + + # kdc & + # kinit me + me@MY.REALMS's Password: + # klist + Credentials cache: /tmp/krb5cc_0 + Principal: me@MY.REALM + + Issued Expires Principal + Aug 25 07:25:55 Aug 25 17:25:55 krbtgt/MY.REALM@MY.REALM + +If you are curious you can use the `dump' command to list all the +entries in the database. It should look something similar to the +following example (note that the entries here are truncated for +typographical reasons): + + kadmin> dump + me@MY.REALM 1:0:1:0b01d3cb7c293b57:-:0:7:8aec316b9d1629e3baf8 ... + kadmin/admin@MY.REALM 1:0:1:e5c8a2675b37a443:-:0:7:cb913ebf85 ... + krbtgt/MY.REALM@MY.REALM 1:0:1:52b53b61c875ce16:-:0:7:c8943be ... + kadmin/changepw@MY.REALM 1:0:1:f48c8af2b340e9fb:-:0:7:e3e6088 ... + + +File: heimdal.info, Node: Modifying the database, Next: Checking the setup, Prev: Creating the database, Up: Setting up a realm + +4.3 Modifying the database +========================== + +All modifications of principals are done with with kadmin. + +A principal has several attributes and lifetimes associated with it. + +Principals are added, renamed, modified, and deleted with the kadmin +commands `add', `rename', `modify', `delete'. Both interactive editing +and command line flags can be used (use -help to list the available +options). + +There are different kinds of types for the fields in the database; +attributes, absolute time times and relative times. + +4.3.1 Attributes +---------------- + +When doing interactive editing, attributes are listed with `?'. + +The attributes are given in a comma (`,') separated list. Attributes +are removed from the list by prefixing them with `-'. + + kadmin> modify me + Max ticket life [1 day]: + Max renewable life [1 week]: + Principal expiration time [never]: + Password expiration time [never]: + Attributes [disallow-renewable]: requires-pre-auth,-disallow-renewable + kadmin> get me + Principal: me@MY.REALM + [...] + Attributes: requires-pre-auth + +4.3.2 Absolute times +-------------------- + +The format for absolute times are any of the following: + + never + now + YYYY-mm-dd + YYYY-mm-dd HH:MM:SS + +4.3.3 Relative times +-------------------- + +The format for relative times are any of the following combined: + + N year + M month + O day + P hour + Q minute + R second + + +File: heimdal.info, Node: Checking the setup, Next: keytabs, Prev: Modifying the database, Up: Setting up a realm + +4.4 Checking the setup +====================== + +There are two tools that can check the consistency of the Kerberos +configuration file and the Kerberos database. + +The Kerberos configuration file is checked using `verify_krb5_conf'. +The tool checks for common errors, but commonly there are several +uncommon configuration entries that are never added to the tool and +thus generates "unknown entry" warnings. This is usually nothing to +worry about. + +The database check is built into the kadmin tool. It will check for +common configuration error that will cause problems later. Common check +are for existence and flags on important principals. The database check +by run by the following command : + + kadmin check REALM.EXAMPLE.ORG + + +File: heimdal.info, Node: keytabs, Next: Serving Kerberos 4/524/kaserver, Prev: Checking the setup, Up: Setting up a realm + +4.5 keytabs +=========== + +To extract a service ticket from the database and put it in a keytab, +you need to first create the principal in the database with `ank' +(using the `--random-key' flag to get a random key) and then extract it +with `ext_keytab'. + + kadmin> add --random-key host/my.host.name + Max ticket life [unlimited]: + Max renewable life [unlimited]: + Attributes []: + kadmin> ext host/my.host.name + kadmin> exit + # ktutil list + Version Type Principal + 1 des-cbc-md5 host/my.host.name@MY.REALM + 1 des-cbc-md4 host/my.host.name@MY.REALM + 1 des-cbc-crc host/my.host.name@MY.REALM + 1 des3-cbc-sha1 host/my.host.name@MY.REALM + + +File: heimdal.info, Node: Serving Kerberos 4/524/kaserver, Next: Remote administration, Prev: keytabs, Up: Setting up a realm + +4.6 Serving Kerberos 4/524/kaserver +=================================== + +Heimdal can be configured to support 524, Kerberos 4 or kaserver. All +these services are turned off by default. Kerberos 4 is always +supported by the KDC, but the Kerberos 4 client support also depends on +Kerberos 4 support having been included at compile-time, using +`--with-krb4=dir'. + +4.6.1 524 +--------- + +524 is a service that allows the KDC to convert Kerberos 5 tickets to +Kerberos 4 tickets for backward compatibility. See also Using 2b tokens +with AFS in *Note Things in search for a better place::. + +524 can be turned on by adding this to the configuration file + + [kdc] + enable-524 = yes + +4.6.2 Kerberos 4 +---------------- + +Kerberos 4 is the predecessor to to Kerberos 5. It only supports single +DES. You should only enable Kerberos 4 support if you have needs for +compatibility with an installed base of Kerberos 4 clients/servers. + +Kerberos 4 can be turned on by adding this to the configuration file + + [kdc] + enable-kerberos4 = yes + +4.6.3 kaserver +-------------- + +Kaserver is a Kerberos 4 that is used in AFS. The protocol has some +extra features over plain Kerberos 4, but like Kerberos 4, only uses +single DES. + +You should only enable Kaserver support if you have needs for +compatibility with an installed base of AFS machines. + +Kaserver can be turned on by adding this to the configuration file + + [kdc] + enable-kaserver = yes + + +File: heimdal.info, Node: Remote administration, Next: Password changing, Prev: Serving Kerberos 4/524/kaserver, Up: Setting up a realm + +4.7 Remote administration +========================= + +The administration server, `kadmind', can be started by `inetd' (which +isn't recommended) or run as a normal daemon. If you want to start it +from `inetd' you should add a line similar to the one below to your +`/etc/inetd.conf'. + + kerberos-adm stream tcp nowait root /usr/heimdal/libexec/kadmind kadmind + +You might need to add `kerberos-adm' to your `/etc/services' as +`749/tcp'. + +Access to the administration server is controlled by an ACL file, +(default `@DBDIR@/kadmind.acl'.) The file has the following syntax: + principal [priv1,priv2,...] [glob-pattern] + +The matching is from top to bottom for matching principals (and if +given, glob-pattern). When there is a match, the access rights of that +line are applied. + +The privileges you can assign to a principal are: `add', +`change-password' (or `cpw' for short), `delete', `get', `list', and +`modify', or the special privilege `all'. All of these roughly +correspond to the different commands in `kadmin'. + +If a GLOB-PATTERN is given on a line, it restricts the access rights +for the principal to only apply for subjects that match the pattern. +The patterns are of the same type as those used in shell globbing, see +fnmatch(3). + +In the example below `lha/admin' can change every principal in the +database. `jimmy/admin' can only modify principals that belong to the +realm `E.KTH.SE'. `mille/admin' is working at the help desk, so he +should only be able to change the passwords for single component +principals (ordinary users). He will not be able to change any `/admin' +principal. + + lha/admin@E.KTH.SE all + jimmy/admin@E.KTH.SE all *@E.KTH.SE + jimmy/admin@E.KTH.SE all */*@E.KTH.SE + mille/admin@E.KTH.SE change-password *@E.KTH.SE + + +File: heimdal.info, Node: Password changing, Next: Testing clients and servers, Prev: Remote administration, Up: Setting up a realm + +4.8 Password changing +===================== + +To allow users to change their passwords, you should run `kpasswdd'. +It is not run from `inetd'. + +You might need to add `kpasswd' to your `/etc/services' as `464/udp'. + +4.8.1 Password quality assurance +-------------------------------- + +It is important that users have good passwords, both to make it harder +to guess them and to avoid off-line attacks (although +pre-authentication provides some defence against off-line attacks). To +ensure that the users choose good passwords, you can enable password +quality controls in `kpasswdd' and `kadmind'. The controls themselves +are done in a shared library or an external program that is used by +`kpasswdd'. To configure in these controls, add lines similar to the +following to your `/etc/krb5.conf': + + [password_quality] + policies = external-check builtin:minimum-length module:policyname + external_program = /bin/false + policy_libraries = LIBRARY1.SO LIBRARY2.SO + +In `[password_quality]policies' the module name is optional if the +policy name is unique in all modules (members of `policy_libraries'). + +The built-in polices are + + * external-check + + Executes the program specified by + `[password_quality]external_program'. + + A number of key/value pairs are passed as input to the program, + one per line, ending with the string `end'. The key/value lines + are of the form + principal: PRINCIPAL + new-password: PASSWORD + where PASSWORD is the password to check for the previous PRINCIPAL. + + If the external application approves the password, it should return + `APPROVED' on standard out and exit with exit code 0. If it + doesn't approve the password, an one line error message explaining + the problem should be returned on standard error and the + application should exit with exit code 0. In case of a fatal + error, the application should, if possible, print an error message + on standard error and exit with a non-zero error code. + + * minimum-length + + The minimum length password quality check reads the configuration + file stanza `[password_quality]min_length' and requires the + password to be at least this length. + + * character-class + + The character-class password quality check reads the configuration + file stanza `[password_quality]min_classes'. The policy requires + the password to have characters from at least that many character + classes. Default value if not given is 3. + + The four different characters classes are, uppercase, lowercase, + number, special characters. + + +If you want to write your own shared object to check password policies, +see the manual page `kadm5_pwcheck(3)'. + +Code for a password quality checking function that uses the cracklib +library can be found in `lib/kadm5/sample_password_check.c' in the +source code distribution. It requires that the cracklib library be +built with the patch available at +`ftp://ftp.pdc.kth.se/pub/krb/src/cracklib.patch'. + +A sample policy external program is included in +`lib/kadm5/check-cracklib.pl'. + +If no password quality checking function is configured, the only check +performed is that the password is at least six characters long. + +To check the password policy settings, use the command +`password-quality' in `kadmin' program. The password verification is +only performed locally, on the client. It may be convenient to set the +environment variable `KRB5_CONFIG' to point to a test version of +`krb5.conf' while you're testing the `[password_quality]' stanza that +way. + + +File: heimdal.info, Node: Testing clients and servers, Next: Slave Servers, Prev: Password changing, Up: Setting up a realm + +4.9 Testing clients and servers +=============================== + +Now you should be able to run all the clients and servers. Refer to the +appropriate man pages for information on how to use them. + + +File: heimdal.info, Node: Slave Servers, Next: Incremental propagation, Prev: Testing clients and servers, Up: Setting up a realm + +4.10 Slave servers, Incremental propagation, Testing clients and servers, Setting up a realm +============================================================================================ + +It is desirable to have at least one backup (slave) server in case the +master server fails. It is possible to have any number of such slave +servers but more than three usually doesn't buy much more redundancy. + +All Kerberos servers for a realm must have the same database so that +they present the same service to the users. The `hprop' program, +running on the master, will propagate the database to the slaves, +running `hpropd' processes. + +Every slave needs a database directory, the master key (if it was used +for the database) and a keytab with the principal `hprop/HOSTNAME'. +Add the principal with the `ktutil' command and start `hpropd', as +follows: + + slave# ktutil get -p foo/admin hprop/`hostname` + slave# mkdir @DBDIR@ + slave# hpropd + +The master will use the principal `kadmin/hprop' to authenticate to the +slaves. This principal should be added when running `kadmin -l init' +but if you do not have it in your database for whatever reason, please +add it with `kadmin -l add'. + +Then run `hprop' on the master: + + master# hprop slave + +This was just an hands-on example to make sure that everything was +working properly. Doing it manually is of course the wrong way, and to +automate this you will want to start `hpropd' from `inetd' on the +slave(s) and regularly run `hprop' on the master to regularly propagate +the database. Starting the propagation once an hour from `cron' is +probably a good idea. + + +File: heimdal.info, Node: Incremental propagation, Next: Encryption types and salting, Prev: Slave Servers, Up: Setting up a realm + +4.11 Incremental propagation +============================ + +There is also a newer, and still somewhat experimental, mechanism for +doing incremental propagation in Heimdal. Instead of sending the whole +database regularly, it sends the changes as they happen on the master to +the slaves. The master keeps track of all the changes by assigning a +version number to every change to the database. The slaves know which +was the latest version they saw and in this way it can be determined if +they are in sync or not. A log of all the changes is kept on the +master, and when a slave is at an older version than the oldest one in +the log, the whole database has to be sent. + +Protocol-wise, all the slaves connect to the master and as a greeting +tell it the latest version that they have (`IHAVE' message). The +master then responds by sending all the changes between that version and +the current version at the master (a series of `FORYOU' messages) or +the whole database in a `TELLYOUEVERYTHING' message. There is also a +keep-alive protocol that makes sure all slaves are up and running. + +4.11.1 Configuring incremental propagation +------------------------------------------ + +The program that runs on the master is `ipropd-master' and all clients +run `ipropd-slave'. + +Create the file `@DBDIR@/slaves' on the master containing all the +slaves that the database should be propagated to. Each line contains +the full name of the principal (for example +`iprop/hemligare.foo.se@FOO.SE'). + +You should already have `iprop/tcp' defined as 2121, in your +`/etc/services'. Otherwise, or if you need to use a different port for +some peculiar reason, you can use the `--port' option. This is useful +when you have multiple realms to distribute from one server. + +Then you need to create those principals that you added in the +configuration file. Create one `iprop/hostname' for the master and for +every slave. + + master# /usr/heimdal/sbin/ktutil get iprop/`hostname` + +The next step is to start the `ipropd-master' process on the master +server. The `ipropd-master' listens on the UNIX domain socket +`@DBDIR@/signal' to know when changes have been made to the +database so they can be propagated to the slaves. There is also a +safety feature of testing the version number regularly (every 30 +seconds) to see if it has been modified by some means that do not raise +this signal. Then, start `ipropd-slave' on all the slaves: + + master# /usr/heimdal/libexec/ipropd-master & + slave# /usr/heimdal/libexec/ipropd-slave master & + +To manage the iprop log file you should use the `iprop-log' command. +With it you can dump, truncate and replay the logfile. + + +File: heimdal.info, Node: Encryption types and salting, Next: Cross realm, Prev: Incremental propagation, Up: Setting up a realm + +4.12 Encryption types and salting +================================= + +The encryption types that the KDC is going to assign by default is +possible to change. Since the keys used for user authentication is +salted the encryption types are described together with the salt +strings. + +Salting is used to make it harder to pre-calculate all possible keys. +Using a salt increases the search space to make it almost impossible to +pre-calculate all keys. Salting is the process of mixing a public +string (the salt) with the password, then sending it through an +encryption type specific string-to-key function that will output the +fixed size encryption key. + +In Kerberos 5 the salt is determined by the encryption type, except in +some special cases. + +In `des' there is the Kerberos 4 salt (none at all) or the afs-salt +(using the cell (realm in AFS lingo)). + +In `arcfour' (the encryption type that Microsoft Windows 2000 uses) +there is no salt. This is to be compatible with NTLM keys in Windows NT +4. + +`[kadmin]default_keys' in `krb5.conf' controls what salting to use. + +The syntax of `[kadmin]default_keys' is +`[etype:]salt-type[:salt-string]'. `etype' is the encryption type +(des-cbc-crc, arcfour-hmac-md5, aes256-cts-hmac-sha1-96), `salt-type' +is the type of salt (pw-salt or afs3-salt), and the salt-string is the +string that will be used as salt (remember that if the salt is +appended/prepended, the empty salt "" is the same thing as no salt at +all). + +Common types of salting include + + * `v4' (or `des:pw-salt:') + + The Kerberos 4 salting is using no salt at all. Reason there is + colon at the end of the salt string is that it makes the salt the + empty string (same as no salt). + + * `v5' (or `pw-salt') + + `pw-salt' uses the default salt for each encryption type is + specified for. If the encryption type `etype' isn't given, all + default encryption will be used. + + * `afs3-salt' + + `afs3-salt' is the salt that is used with Transarc kaserver. Its + the cell name appended to the password. + + + +File: heimdal.info, Node: Cross realm, Next: Transit policy, Prev: Encryption types and salting, Up: Setting up a realm + +4.13 Cross realm +================ + +Suppose you reside in the realm `MY.REALM', how do you authenticate to +a server in `OTHER.REALM'? Having valid tickets in `MY.REALM' allows +you to communicate with Kerberised services in that realm. However, the +computer in the other realm does not have a secret key shared with the +Kerberos server in your realm. + +It is possible to share keys between two realms that trust each other. +When a client program, such as `telnet' or `ssh', finds that the other +computer is in a different realm, it will try to get a ticket granting +ticket for that other realm, but from the local Kerberos server. With +that ticket granting ticket, it will then obtain service tickets from +the Kerberos server in the other realm. + +For a two way trust between `MY.REALM' and `OTHER.REALM' add the +following principals to each realm. The principals should be +`krbtgt/OTHER.REALM@MY.REALM' and `krbtgt/MY.REALM@OTHER.REALM' in +`MY.REALM', and `krbtgt/MY.REALM@OTHER.REALM' and +`krbtgt/OTHER.REALM@MY.REALM'in `OTHER.REALM'. + +In Kerberos 5 the trust can be configured to be one way. So that users +from `MY.REALM' can authenticate to services in `OTHER.REALM', but not +the opposite. In the example above, the `krbtgt/MY.REALM@OTHER.REALM' +then should be removed. + +The two principals must have the same key, key version number, and the +same set of encryption types. Remember to transfer the two keys in a +safe manner. + + vr$ klist + Credentials cache: FILE:/tmp/krb5cc_913.console + Principal: lha@E.KTH.SE + + Issued Expires Principal + May 3 13:55:52 May 3 23:55:54 krbtgt/E.KTH.SE@E.KTH.SE + + vr$ telnet -l lha hummel.it.su.se + Trying 2001:6b0:5:1095:250:fcff:fe24:dbf... + Connected to hummel.it.su.se. + Escape character is '^]'. + Waiting for encryption to be negotiated... + [ Trying mutual KERBEROS5 (host/hummel.it.su.se@SU.SE)... ] + [ Kerberos V5 accepts you as ``lha@E.KTH.SE'' ] + Encryption negotiated. + Last login: Sat May 3 14:11:47 from vr.l.nxs.se + hummel$ exit + + vr$ klist + Credentials cache: FILE:/tmp/krb5cc_913.console + Principal: lha@E.KTH.SE + + Issued Expires Principal + May 3 13:55:52 May 3 23:55:54 krbtgt/E.KTH.SE@E.KTH.SE + May 3 13:55:56 May 3 23:55:54 krbtgt/SU.SE@E.KTH.SE + May 3 14:10:54 May 3 23:55:54 host/hummel.it.su.se@SU.SE + + +File: heimdal.info, Node: Transit policy, Next: Setting up DNS, Prev: Cross realm, Up: Setting up a realm + +4.14 Transit policy +=================== + +If you want to use cross realm authentication through an intermediate +realm, it must be explicitly allowed by either the KDCs or the server +receiving the request. This is done in `krb5.conf' in the `[capaths]' +section. + +When the ticket transits through a realm to another realm, the +destination realm adds its peer to the "transited-realms" field in the +ticket. The field is unordered, since there is no way to know if know +if one of the transited-realms changed the order of the list. + +The syntax for `[capaths]' section: + + [capaths] + CLIENT-REALM = { + SERVER-REALM = PERMITTED-CROSS-REALMS ... + } + +The realm `STACKEN.KTH.SE' allows clients from `SU.SE' and `DSV.SU.SE' +to cross it. Since `STACKEN.KTH.SE' only has direct cross realm setup +with `KTH.SE', and `DSV.SU.SE' only has direct cross realm setup with +`SU.SE' they need to use both `SU.SE' and `KTH.SE' as transit realms. + + [capaths] + SU.SE = { + STACKEN.KTH.SE = KTH.SE + } + DSV.SU.SE = { + STACKEN.KTH.SE = SU.SE KTH.SE + } + +The order of the `PERMITTED-CROSS-REALMS' is not important when doing +transit cross realm verification. + +However, the order is important when the `[capaths]' section is used to +figure out the intermediate realm to go to when doing multi-realm +transit. When figuring out the next realm, the first realm of the list +of `PERMITTED-CROSS-REALMS' is chosen. This is done in both the client +kerberos library and the KDC. + + +File: heimdal.info, Node: Setting up DNS, Next: Using LDAP to store the database, Prev: Transit policy, Up: Setting up a realm + +4.15 Setting up DNS +=================== + +4.15.1 Using DNS to find KDC +---------------------------- + +If there is information about where to find the KDC or kadmind for a +realm in the `krb5.conf' for a realm, that information will be +preferred, and DNS will not be queried. + +Heimdal will try to use DNS to find the KDCs for a realm. First it will +try to find a `SRV' resource record (RR) for the realm. If no SRV RRs +are found, it will fall back to looking for an `A' RR for a machine +named kerberos.REALM, and then kerberos-1.REALM, etc + +Adding this information to DNS minimises the client configuration (in +the common case, resulting in no configuration needed) and allows the +system administrator to change the number of KDCs and on what machines +they are running without caring about clients. + +The downside of using DNS is that the client might be fooled to use the +wrong server if someone fakes DNS replies/data, but storing the IP +addresses of the KDC on all the clients makes it very hard to change +the infrastructure. + +An example of the configuration for the realm `EXAMPLE.COM': + + + $ORIGIN example.com. + _kerberos._tcp SRV 10 1 88 kerberos.example.com. + _kerberos._udp SRV 10 1 88 kerberos.example.com. + _kerberos._tcp SRV 10 1 88 kerberos-1.example.com. + _kerberos._udp SRV 10 1 88 kerberos-1.example.com. + _kpasswd._udp SRV 10 1 464 kerberos.example.com. + _kerberos-adm._tcp SRV 10 1 749 kerberos.example.com. + +More information about DNS SRV resource records can be found in +RFC-2782 (A DNS RR for specifying the location of services (DNS SRV)). + +4.15.2 Using DNS to map hostname to Kerberos realm +-------------------------------------------------- + +Heimdal also supports a way to lookup a realm from a hostname. This to +minimise configuration needed on clients. Using this has the drawback +that clients can be redirected by an attacker to realms within the same +cross realm trust and made to believe they are talking to the right +server (since Kerberos authentication will succeed). + +An example configuration that informs clients that for the realms +it.example.com and srv.example.com, they should use the realm +EXAMPLE.COM: + + + $ORIGIN example.com. + _kerberos.it TXT "EXAMPLE.COM" + _kerberos.srv TXT "EXAMPLE.COM" + + +File: heimdal.info, Node: Using LDAP to store the database, Next: Providing Kerberos credentials to servers and programs, Prev: Setting up DNS, Up: Setting up a realm + +4.16 Using LDAP to store the database +===================================== + +This document describes how to install the LDAP backend for Heimdal. +Note that before attempting to configure such an installation, you +should be aware of the implications of storing private information +(such as users' keys) in a directory service primarily designed for +public information. Nonetheless, with a suitable authorisation policy, +it is possible to set this up in a secure fashion. A knowledge of LDAP, +Kerberos, and C is necessary to install this backend. The HDB schema +was devised by Leif Johansson. + +Requirements: + + * A current release of Heimdal, configured with + `--with-openldap=/usr/local' (adjust according to where you have + installed OpenLDAP). + + You can verify that you manage to configure LDAP support by running + `kdc --builtin-hdb', and checking that `ldap:' is one entry in the + list. + + Its also possible to configure the ldap backend as a shared module, + see option -hdb-openldap-module to configure. + + * OpenLDAP 2.0.x. Configure OpenLDAP with `--enable-local' to enable + the local transport. (A patch to support SASL EXTERNAL + authentication is necessary in order to use OpenLDAP 2.1.x.) + + * Add the hdb schema to the LDAP server, its included in the + source-tree in `lib/hdb/hdb.schema'. Example from slapd.conf: + + include /usr/local/etc/openldap/schema/hdb.schema + + * Configure the LDAP server ACLs to accept writes from clients over + the local transport. For example: + + access to * + by dn.exact="uid=heimdal,dc=services,dc=example,dc=com" write + ... + + sasl-regexp "uidNumber=0\\\+gidNumber=.*,cn=peercred,cn=external,cn=auth" + "uid=heimdal,dc=services,dc=example,dc=com" + + The sasl-regexp is for mapping between the SASL/EXTERNAL and a + user in a tree. The user that the key is mapped to should be have + a krb5Principal aux object with krb5PrincipalName set so that the + "creator" and "modifier" is right in `kadmin'. + + Another option is to create an admins group and add the dn to that + group. + + Since Heimdal talks to the LDAP server over a UNIX domain socket, + and uses external sasl authentication, its not possible to require + security layer quality (ssf in cyrus-sasl lingo). So that + requirement has to be turned off in OpenLDAP `slapd' configuration + file `slapd.conf'. + + sasl-secprops minssf=0 + + * Start `slapd' with the local listener (as well as the default + TCP/IP listener on port 389) as follows: + + slapd -h "ldapi:/// ldap:///" + + Note: These is a bug in `slapd' where it appears to corrupt the + krb5Key binary attribute on shutdown. This may be related to our + use of the V3 schema definition syntax instead of the old + UMich-style, V2 syntax. + + * You should specify the distinguished name under which your + principals will be stored in `krb5.conf'. Also you need to enter + the path to the kadmin acl file: + + [kdc] + database = { + dbname = ldap:ou=KerberosPrincipals,dc=example,dc=com + hdb-ldap-structural-object = inetOrgPerson + acl_file = /path/to/kadmind.acl + mkey_file = /path/to/mkey + } + + `mkey_file' can be excluded if you feel that you trust your ldap + directory to have the raw keys inside it. The + hdb-ldap-structural-object is not necessary if you do not need + Samba comatibility. + + * Once you have built Heimdal and started the LDAP server, run kadmin + (as usual) to initialise the database. Note that the instructions + for stashing a master key are as per any Heimdal installation. + + kdc# kadmin -l + kadmin> init EXAMPLE.COM + Realm max ticket life [unlimited]: + Realm max renewable ticket life [unlimited]: + kadmin> ank lukeh + Max ticket life [1 day]: + Max renewable life [1 week]: + Principal expiration time [never]: + Password expiration time [never]: + Attributes []: + lukeh@EXAMPLE.COM's Password: + Verifying password - lukeh@EXAMPLE.COM's Password: + kadmin> exit + + Verify that the principal database has indeed been stored in the + directory with the following command: + + kdc# ldapsearch -L -h localhost -D cn=manager \ + -w secret -b ou=KerberosPrincipals,dc=example,dc=com \ + 'objectclass=krb5KDCEntry' + + * Now consider adding indexes to the database to speed up the + access, at least theses should be added to slapd.conf. + + index objectClass eq + index cn eq,sub,pres + index uid eq,sub,pres + index displayName eq,sub,pres + index krb5PrincipalName eq + + +4.16.1 Troubleshooting guide +---------------------------- + +`https://sec.miljovern.no/bin/view/Info/TroubleshootingGuide' + +4.16.2 Using Samba LDAP password database +----------------------------------------- + +The Samba domain and the Kerberos realm can have different names since +arcfour's string to key functions principal/realm independent. So now +will be your first and only chance name your Kerberos realm without +needing to deal with old configuration files. + +First, you should set up Samba and get that working with LDAP backend. + +Now you can proceed as in *Note Using LDAP to store the database::. +Heimdal will pick up the Samba LDAP entries if they are in the same +search space as the Kerberos entries. + + +File: heimdal.info, Node: Providing Kerberos credentials to servers and programs, Next: Setting up PK-INIT, Prev: Using LDAP to store the database, Up: Setting up a realm + +4.17 Providing Kerberos credentials to servers and programs +=========================================================== + +Some services require Kerberos credentials when they start to make +connections to other services or need to use them when they have +started. + +The easiest way to get tickets for a service is to store the key in a +keytab. Both ktutil get and kadmin ext can be used to get a keytab. +ktutil get is better in that way it changes the key/password for the +user. This is also the problem with ktutil. If ktutil is used for the +same service principal on several hosts, they keytab will only be +useful on the last host. In that case, run the extract command on one +host and then securely copy the keytab around to all other hosts that +need it. + + host# ktutil -k /etc/krb5-service.keytab \ + get -p lha/admin@EXAMPLE.ORG service-principal@EXAMPLE.ORG + lha/admin@EXAMPLE.ORG's Password: + +To get a Kerberos credential file for the service, use kinit in the +-keytab mode. This will not ask for a password but instead fetch the +key from the keytab. + + service@host$ kinit --cache=/var/run/service_krb5_cache \ + --keytab=/etc/krb5-service.keytab \ + service-principal@EXAMPLE.ORG + +Long running services might need credentials longer then the expiration +time of the tickets. kinit can run in a mode that refreshes the tickets +before they expire. This is useful for services that write into AFS and +other distributed file systems using Kerberos. To run the long running +script, just append the program and arguments (if any) after the +principal. kinit will stop refreshing credentials and remove the +credentials when the script-to-start-service exits. + + service@host$ kinit --cache=/var/run/service_krb5_cache \ + --keytab=/etc/krb5-service.keytab \ + service-principal@EXAMPLE.ORG \ + script-to-start-service argument1 argument2 + + +File: heimdal.info, Node: Setting up PK-INIT, Prev: Providing Kerberos credentials to servers and programs, Up: Setting up a realm + +4.18 Setting up PK-INIT +======================= + +PK-INIT is levering the existing PKI infrastructure to use certificates +to get the initial ticket, that is usually the krbtgt. + +To use PK-INIT you must first have a PKI, so if you don't have one, now +its time to create it. Note that you should read the whole chapter of +the document to see the requirements on the CA sortware. + +There needs to exist a mapping between the certificate and what +principals that certificate is allowed to use. There are several ways +to do this. The administrator can use a configuration file, storing the +principal in the SubjectAltName extension of the certificate, or store +the mapping in the principals entry in the kerberos database. + +4.19 Certificates +================= + +This section documents the requirements on the KDC and client +certificates and the format used in the id-pkinit-san OtherName +extention. + +4.19.1 KDC certificate +---------------------- + +The certificate for the KDC have serveral requirements. + +First the certificate should have an Extended Key Usage (EKU) +id-pkkdcekuoid (1.3.6.1.5.2.3.5) set. Second there must be a +subjectAltName otherName using oid id-pkinit-san (1.3.6.1.5.2.2) in the +type field and a DER encoded KRB5PrincipalName that matches the name of +the TGS of the target realm. + +Both of these two requirements are not required by the standard to be +checked by the client if it have external information what the +certificate the KDC is supposed to be used. So its in the interst of +minimum amount of configuration on the clients they should be included. + +Remember that if the client would accept any certificate as the KDC's +certificate, the client could be fooled into trusting something that +isn't a KDC and thus expose the user to giving away information (like +password or other private information) that it is supposed to secret. + +Also, if the certificate has a nameConstraints extention with a +Generalname with dNSName or iPAdress it must match the hostname or +adress of the KDC. + +4.19.2 Client certificate +------------------------- + +The client certificate may need to have a EKU id-pkekuoid +(1.3.6.1.5.2.3.4) set depending on the certifiate on the KDC. + +It possible to store the principal (if allowed by the KDC) in the +certificate and thus delegate responsibility to do the mapping between +certificates and principals to the CA. + +4.19.2.1 Using KRB5PrincipalName in id-pkinit-san +................................................. + +OtherName extention in the GeneralName is used to do the mapping +between certifiate and principal in the certifiate or storing the +krbtgt principal in the KDC certificate. + +The principal is stored in a SubjectAltName in the certificate using +OtherName. The oid in the type is id-pkinit-san. + + id-pkinit-san OBJECT IDENTIFIER ::= { iso (1) org (3) dod (6) + internet (1) security (5) kerberosv5 (2) 2 } + +The data part of the OtherName is filled with the following DER encoded +ASN.1 structure: + + KRB5PrincipalName ::= SEQUENCE { + realm [0] Realm, + principalName [1] PrincipalName + } + +where Realm and PrincipalName is defined by the Kerberos ASN.1 +specification. + +4.20 Naming certificate using hx509 +=================================== + +hx509 is the X.509 software used in Heimdal to handle certificates. +hx509 uses different syntaxes to specify the different formats the +certificates are stored in and what formats they exist in. + +There are several formats that can be used, PEM, embedded into PKCS12 +files, embedded into PKCS11 devices and raw DER encoded certificates. +Below is a list of types to use. + +DIR: + DIR is reading all certificates in a directory that is DER or PEM + formatted. + + The main feature of DIR is that the directory is read on demand + when iterating over certificates, that way applictions can for + some cases avoid to store all certificates in memory. It's very + useful for tests that iterate over larger amount of certificates. + + Syntax is: + + DIR:/path/to/der/files + +FILE: + FILE: is used to have the lib pick up a certificate chain and a + private key. The file can be either a PEM (openssl) file or a raw + DER encoded certificate. If it's a PEM file it can contain several + keys and certificates and the code will try to match the private + key and certificate together. + + Its useful to have one PEM file that contains all the trust + anchors. + + Syntax is: + + FILE:certificate.pem,private-key.key,other-cert.pem,.... + +PKCS11: + PKCS11: is used to handle smartcards via PKCS11 drivers, for + example soft-token, opensc, or muscle. The default is to use all + slots on the device/token. + + Syntax is: + + PKCS11:shared-object.so + +PKCS12: + PKCS12: is used to handle PKCS12 files. PKCS12 files commonly have + the extension pfx or p12. + + Syntax is: + + PKCS12:/path/to/file.pfx + + +4.21 Configure the Kerberos software +==================================== + +First configure the client's trust anchors and what parameters to +verify, see subsection below how to do that. Now you can use kinit to +get yourself tickets. One example how that can look like is: + + $ kinit -C FILE:$HOME/.certs/lha.crt,$HOME/.certs/lha.key lha@EXAMPLE.ORG + Enter your private key passphrase: + : lha@nutcracker ; klist + Credentials cache: FILE:/tmp/krb5cc_19100a + Principal: lha@EXAMPLE.ORG + + Issued Expires Principal + Apr 20 02:08:08 Apr 20 12:08:08 krbtgt/EXAMPLE.ORG@EXAMPLE.ORG + +Using PKCS11 it can look like this instead: + + $ kinit -C PKCS11:/tmp/pkcs11/lib/soft-pkcs11.so lha@EXAMPLE.ORG + PIN code for SoftToken (slot): + $ klist + Credentials cache: API:4 + Principal: lha@EXAMPLE.ORG + + Issued Expires Principal + Mar 26 23:40:10 Mar 27 09:40:10 krbtgt/EXAMPLE.ORG@EXAMPLE.ORG + +Write about the kdc. + +4.22 Configure the client +========================= + + [appdefaults] + pkinit_anchors = FILE:/path/to/trust-anchors.pem + + [realms] + EXAMPLE.COM = { + pkinit_require_eku = true + pkinit_require_krbtgt_otherName = true + pkinit_win2k = no + pkinit_win2k_require_binding = yes + } + +4.23 Configure the KDC +====================== + + [kdc] + enable-pkinit = yes + pkinit_identity = FILE:/secure/kdc.crt,/secure/kdc.key + pkinit_anchors = FILE:/path/to/trust-anchors.pem + pkinit_pool = PKCS12:/path/to/useful-intermediate-certs.pfx + pkinit_pool = FILE:/path/to/other-useful-intermediate-certs.pem + pkinit_allow_proxy_certificate = false + pkinit_win2k_require_binding = yes + +4.23.1 Using pki-mapping file +----------------------------- + +Note that the file name is space sensitive. + + # cat @DBDIR@/pki-mapping + # comments starts with # + lha@EXAMPLE.ORG:C=SE,O=Stockholm universitet,CN=Love,UID=lha + lha@EXAMPLE.ORG:CN=Love,UID=lha + +4.23.2 Using the Kerberos database +---------------------------------- + +4.24 Use hxtool to create certificates +====================================== + +4.24.1 Generate certificates +---------------------------- + +First you need to generate a CA certificate, change the -subject to +something appropriate, the CA certificate will be valid for 10 years. + +You need to change -subject in the command below. + + hxtool issue-certificate \ + --self-signed \ + --issue-ca \ + --generate-key=rsa \ + --subject="CN=CA,DC=test,DC=h5l,DC=se" \ + --lifetime=10years \ + --certificate="FILE:ca.pem" + +The KDC needs to have a certificate, so generate a certificate of the +type "pkinit-kdc" and set the PK-INIT specifial SubjectAltName to the +name of the krbtgt of the realm. + +You need to change -subject and -pk-init-principal in the command below. + + hxtool issue-certificate \ + --ca-certificate=FILE:ca.pem \ + --generate-key=rsa \ + --type="pkinit-kdc" \ + --pk-init-principal="krbtgt/TEST.H5L.SE@TEST.H5L.SE" \ + --subject="uid=kdc,DC=test,DC=h5l,DC=se" \ + --certificate="FILE:kdc.pem" + +The users also needs to have a certificate, so generate a certificate +of the type "pkinit-client". The client doesn't need to have the PK-INIT +SubjectAltName set, you can have the Subject DN in the ACL file +(pki-mapping) instead. + +You need to change -subject and -pk-init-principal in the command below. + + hxtool issue-certificate \ + --ca-certificate=FILE:ca.pem \ + --generate-key=rsa \ + --type="pkinit-client" \ + --pk-init-principal="lha@TEST.H5L.SE" \ + --subject="uid=lha,DC=test,DC=h5l,DC=se" \ + --certificate="FILE:user.pem" + +4.24.2 Validate the certificate +------------------------------- + +hxtool also contains a tool that will validate certificates according to +rules from the PKIX document. These checks are not complete, but a good +test to check if you got all of the basic bits right in your +certificates. + + hxtool validate FILE:user.pem + +4.25 Use OpenSSL to create certificates +======================================= + +This section tries to give the CA owners hints how to create +certificates using OpenSSL (or CA software based on OpenSSL). + +4.25.1 Using OpenSSL to create certificates with krb5PrincipalName +------------------------------------------------------------------ + +To make OpenSSL create certificates with krb5PrincipalName use +`openssl.cnf' as described below. To see a complete example of creating +client and KDC certificates, see the test-data generation script +`lib/hx509/data/gen-req.sh' in the source-tree. The certicates it +creates are used to test the PK-INIT functionality in +`tests/kdc/check-kdc.in'. + +To use this example you have to use OpenSSL 0.9.8a or later. + + + [user_certificate] + subjectAltName=otherName:1.3.6.1.5.2.2;SEQUENCE:princ_name + + [princ_name] + realm = EXP:0, GeneralString:MY.REALM + principal_name = EXP:1, SEQUENCE:principal_seq + + [principal_seq] + name_type = EXP:0, INTEGER:1 + name_string = EXP:1, SEQUENCE:principals + + [principals] + princ1 = GeneralString:userid + +Command usage + + openssl x509 -extensions user_certificate + openssl ca -extensions user_certificate + +4.26 Using PK-INIT with Windows +=============================== + +4.26.1 Client configration +-------------------------- + +Clients using a Windows KDC with PK-INIT need configuration since +windows uses pre-standard format and this can't be autodetected. + +The pkinit_win2k_require_binding option requires the reply for the KDC +to be of the new, secure, type that binds the request to reply. Before +clients should fake the reply from the KDC. To use this option you have +to apply a fix from Microsoft. + + [realms] + MY.MS.REALM = { + pkinit_win2k = yes + pkinit_win2k_require_binding = no + } + +4.26.2 Certificates +------------------- + +The client certificates need to have the extended keyusage "Microsoft +Smartcardlogin" (openssl have the oid shortname msSmartcardLogin). + +See Microsoft Knowledge Base Article - 281245 "Guidelines for Enabling +Smart Card Logon with Third-Party Certification Authorities" for a more +extensive description of how set setup an external CA to it includes +all information that will make a Windows KDC happy. + +4.26.3 Configure Windows 2000 CA +-------------------------------- + +To enable Microsoft Smartcardlogin> for certificates in your Windows +2000 CA, you want to look at Microsoft Knowledge Base Article - 313274 +"HOW TO: Configure a Certification Authority to Issue Smart Card +Certificates in Windows". + + +File: heimdal.info, Node: Applications, Next: Things in search for a better place, Prev: Setting up a realm, Up: Top + +5 Applications +************** + +* Menu: + +* Authentication modules:: +* AFS:: + + +File: heimdal.info, Node: Authentication modules, Next: AFS, Prev: Applications, Up: Applications + +5.1 Authentication modules +========================== + +The problem of having different authentication mechanisms has been +recognised by several vendors, and several solutions have appeared. In +most cases these solutions involve some kind of shared modules that are +loaded at run-time. Modules for some of these systems can be found in +`lib/auth'. Presently there are modules for Digital's SIA, and IRIX' +`login' and `xdm' (in `lib/auth/afskauthlib'). + +* Menu: + +* Digital SIA:: +* IRIX:: + + +File: heimdal.info, Node: Digital SIA, Next: IRIX, Prev: Authentication modules, Up: Authentication modules + +5.1.1 Digital SIA +----------------- + +How to install the SIA module depends on which OS version you're +running. Tru64 5.0 has a new command, `siacfg', which makes this +process quite simple. If you have this program, you should just be able +to run: + siacfg -a KRB5 /usr/athena/lib/libsia_krb5.so + +On older versions, or if you want to do it by hand, you have to do the +following (not tested by us on Tru64 5.0): + + * Make sure `libsia_krb5.so' is available in `/usr/athena/lib'. If + `/usr/athena' is not on local disk, you might want to put it in + `/usr/shlib' or someplace else. If you do, you'll have to edit + `krb5_matrix.conf' to reflect the new location (you will also have + to do this if you installed in some other directory than + `/usr/athena'). If you built with shared libraries, you will have + to copy the shared `libkrb.so', `libdes.so', `libkadm.so', and + `libkafs.so' to a place where the loader can find them (such as + `/usr/shlib'). + + * Copy (your possibly edited) `krb5_matrix.conf' to `/etc/sia'. + + * Apply `security.patch' to `/sbin/init.d/security'. + + * Turn on KRB5 security by issuing `rcmgr set SECURITY KRB5' and + `rcmgr set KRB5_MATRIX_CONF krb5_matrix.conf'. + + * Digital thinks you should reboot your machine, but that really + shouldn't be necessary. It's usually sufficient just to run + `/sbin/init.d/security start' (and restart any applications that + use SIA, like `xdm'.) + +Users with local passwords (like `root') should be able to login safely. + +When using Digital's xdm the `KRB5CCNAME' environment variable isn't +passed along as it should (since xdm zaps the environment). Instead you +have to set `KRB5CCNAME' to the correct value in +`/usr/lib/X11/xdm/Xsession'. Add a line similar to + KRB5CCNAME=FILE:/tmp/krb5cc`id -u`_`ps -o ppid= -p $$`; export KRB5CCNAME +If you use CDE, `dtlogin' allows you to specify which additional +environment variables it should export. To add `KRB5CCNAME' to this +list, edit `/usr/dt/config/Xconfig', and look for the definition of +`exportList'. You want to add something like: + Dtlogin.exportList: KRB5CCNAME + +Notes to users with Enhanced security +..................................... + +Digital's `ENHANCED' (C2) security, and Kerberos solve two different +problems. C2 deals with local security, adds better control of who can +do what, auditing, and similar things. Kerberos deals with network +security. + +To make C2 security work with Kerberos you will have to do the +following. + + * Replace all occurrences of `krb5_matrix.conf' with + `krb5+c2_matrix.conf' in the directions above. + + * You must enable "vouching" in the `default' database. This will + make the OSFC2 module trust other SIA modules, so you can login + without giving your C2 password. To do this use `edauth' to edit + the default entry `/usr/tcb/bin/edauth -dd default', and add a + `d_accept_alternate_vouching' capability, if not already present. + + * For each user who does _not_ have a local C2 password, you should + set the password expiration field to zero. You can do this for each + user, or in the `default' table. To do this use `edauth' to set + (or change) the `u_exp' capability to `u_exp#0'. + + * You also need to be aware that the shipped `login', `rcp', and + `rshd', don't do any particular C2 magic (such as checking for + various forms of disabled accounts), so if you rely on those + features, you shouldn't use those programs. If you configure with + `--enable-osfc2', these programs will, however, set the login UID. + Still: use at your own risk. + +At present `su' does not accept the vouching flag, so it will not work +as expected. + +Also, kerberised ftp will not work with C2 passwords. You can solve this +by using both Digital's ftpd and our on different ports. + +*Remember*, if you do these changes you will get a system that most +certainly does _not_ fulfil the requirements of a C2 system. If C2 is +what you want, for instance if someone else is forcing you to use it, +you're out of luck. If you use enhanced security because you want a +system that is more secure than it would otherwise be, you probably got +an even more secure system. Passwords will not be sent in the clear, +for instance. + + +File: heimdal.info, Node: IRIX, Prev: Digital SIA, Up: Authentication modules + +5.1.2 IRIX +---------- + +The IRIX support is a module that is compatible with Transarc's +`afskauthlib.so'. It should work with all programs that use this +library. This should include `login' and `xdm'. + +The interface is not very documented but it seems that you have to copy +`libkafs.so', `libkrb.so', and `libdes.so' to `/usr/lib', or build your +`afskauthlib.so' statically. + +The `afskauthlib.so' itself is able to reside in `/usr/vice/etc', +`/usr/afsws/lib', or the current directory (wherever that is). + +IRIX 6.4 and newer seem to have all programs (including `xdm' and +`login') in the N32 object format, whereas in older versions they were +O32. For it to work, the `afskauthlib.so' library has to be in the same +object format as the program that tries to load it. This might require +that you have to configure and build for O32 in addition to the default +N32. + +Apart from this it should "just work"; there are no configuration files. + +Note that recent Irix 6.5 versions (at least 6.5.22) have PAM, +including a `pam_krb5.so' module. Not all relevant programs use PAM, +though, e.g. `ssh'. In particular, for console graphical login you need +to turn off `visuallogin' and turn on `xdm' with `chkconfig'. + + +File: heimdal.info, Node: AFS, Prev: Authentication modules, Up: Applications + +5.2 AFS +======= + +AFS is a distributed filesystem that uses Kerberos for authentication. + +For more information about AFS see OpenAFS `http://www.openafs.org/' +and Arla `http://www.stacken.kth.se/projekt/arla/'. + +5.2.1 How to get a KeyFile +-------------------------- + +`ktutil -k AFSKEYFILE:KeyFile get afs@MY.REALM' + +or you can extract it with kadmin + + kadmin> ext -k AFSKEYFILE:/usr/afs/etc/KeyFile afs@My.CELL.NAME + +You have to make sure you have a `des-cbc-md5' encryption type since +that is the enctype that will be converted. + +5.2.2 How to convert a srvtab to a KeyFile +------------------------------------------ + +You need a `/usr/vice/etc/ThisCell' containing the cellname of your +AFS-cell. + +`ktutil copy krb4:/root/afs-srvtab AFSKEYFILE:/usr/afs/etc/KeyFile'. + +If keyfile already exists, this will add the new key in afs-srvtab to +KeyFile. + +5.3 Using 2b tokens with AFS +============================ + +5.3.1 What is 2b ? +------------------ + +2b is the name of the proposal that was implemented to give basic +Kerberos 5 support to AFS in rxkad. Its not real Kerberos 5 support +since it still uses fcrypt for data encryption and not Kerberos +encryption types. + +Its only possible (in all cases) to do this for DES encryption types +because only then the token (the AFS equivalent of a ticket) will be +smaller than the maximum size that can fit in the token cache in the +OpenAFS/Transarc client. It is a so tight fit that some extra wrapping +on the ASN1/DER encoding is removed from the Kerberos ticket. + +2b uses a Kerberos 5 EncTicketPart instead of a Kerberos 4 ditto for +the part of the ticket that is encrypted with the service's key. The +client doesn't know what's inside the encrypted data so to the client +it doesn't matter. + +To differentiate between Kerberos 4 tickets and Kerberos 5 tickets, 2b +uses a special kvno, 213 for 2b tokens and 255 for Kerberos 5 tokens. + +Its a requirement that all AFS servers that support 2b also support +native Kerberos 5 in rxkad. + +5.3.2 Configuring a Heimdal kdc to use 2b tokens +------------------------------------------------ + +Support for 2b tokens in the kdc are turned on for specific principals +by adding them to the string list option `[kdc]use_2b' in the kdc's +`krb5.conf' file. + + [kdc] + use_2b = { + afs@SU.SE = yes + afs/it.su.se@SU.SE = yes + } + +5.3.3 Configuring AFS clients for 2b support +-------------------------------------------- + +There is no need to configure AFS clients for 2b support. The only +software that needs to be installed/upgrade is a Kerberos 5 enabled +`afslog'. + + +File: heimdal.info, Node: Things in search for a better place, Next: Kerberos 4 issues, Prev: Applications, Up: Top + +6 Things in search for a better place +************************************* + +6.1 Making things work on Ciscos +================================ + +Modern versions of Cisco IOS has some support for authenticating via +Kerberos 5. This can be used both by having the router get a ticket when +you login (boring), and by using Kerberos authenticated telnet to access +your router (less boring). The following has been tested on IOS +11.2(12), things might be different with other versions. Old versions +are known to have bugs. + +To make this work, you will first have to configure your router to use +Kerberos (this is explained in the documentation). A sample +configuration looks like the following: + + aaa new-model + aaa authentication login default krb5-telnet krb5 enable + aaa authorization exec krb5-instance + kerberos local-realm FOO.SE + kerberos srvtab entry host/router.foo.se 0 891725446 4 1 8 012345678901234567 + kerberos server FOO.SE 10.0.0.1 + kerberos instance map admin 15 + +This tells you (among other things) that when logging in, the router +should try to authenticate with kerberised telnet, and if that fails try +to verify a plain text password via a Kerberos ticket exchange (as +opposed to a local database, RADIUS or something similar), and if that +fails try the local enable password. If you're not careful when you +specify the `login default' authentication mechanism, you might not be +able to login at all. The `instance map' and `authorization exec' lines +says that people with `admin' instances should be given `enabled' shells +when logging in. + +The numbers after the principal on the `srvtab' line are principal type, +time stamp (in seconds since 1970), key version number (4), keytype (1 +== des), key length (always 8 with des), and then the key. + +To make the Heimdal KDC produce tickets that the Cisco can decode you +might have to turn on the `encode_as_rep_as_tgs_rep' flag in the KDC. +You will also have to specify that the router can't handle anything but +`des-cbc-crc'. This can be done with the `del_enctype' command of +`kadmin'. + +This all fine and so, but unless you have an IOS version with encryption +(available only in the U.S) it doesn't really solve any problems. Sure +you don't have to send your password over the wire, but since the telnet +connection isn't protected it's still possible for someone to steal your +session. This won't be fixed until someone adds integrity to the telnet +protocol. + +A working solution would be to hook up a machine with a real operating +system to the console of the Cisco and then use it as a backwards +terminal server. + + +File: heimdal.info, Node: Kerberos 4 issues, Next: Windows 2000 compatability, Prev: Things in search for a better place, Up: Top + +7 Kerberos 4 issues +******************* + +The KDC has built-in version 4 support. It is not enabled by default, +see setup how to set it up. + +The KDC will also have kaserver emulation and be able to handle +AFS-clients that use `klog'. + +* Menu: + +* Principal conversion issues:: +* Converting a version 4 database:: +* kaserver:: + + +File: heimdal.info, Node: Principal conversion issues, Next: Converting a version 4 database, Prev: Kerberos 4 issues, Up: Kerberos 4 issues + +7.1 Principal conversion issues +=============================== + +First, Kerberos 4 and Kerberos 5 principals are different. A version 4 +principal consists of a name, an instance, and a realm. A version 5 +principal has one or more components, and a realm (the terms "name" and +"instance" are still used, for the first and second component, +respectively). Also, in some cases the name of a version 4 principal +differs from the first component of the corresponding version 5 +principal. One notable example is the "host" type principals, where the +version 4 name is `rcmd' (for "remote command"), and the version 5 name +is `host'. For the class of principals that has a hostname as instance, +there is an other major difference, Kerberos 4 uses only the first +component of the hostname, whereas Kerberos 5 uses the fully qualified +hostname. + +Because of this it can be hard or impossible to correctly convert a +version 4 principal to a version 5 principal (1). The biggest problem is +to know if the conversion resulted in a valid principal. To give an +example, suppose you want to convert the principal `rcmd.foo'. + +The `rcmd' name suggests that the instance is a hostname (even if there +are exceptions to this rule). To correctly convert the instance `foo' +to a hostname, you have to know which host it is referring to. You can +to this by either guessing (from the realm) which domain name to +append, or you have to have a list of possible hostnames. In the +simplest cases you can cover most principals with the first rule. If you +have several domains sharing a single realm this will not usually work. +If the exceptions are few you can probably come by with a lookup table +for the exceptions. + +In a complex scenario you will need some kind of host lookup mechanism. +Using DNS for this is tempting, but DNS is error prone, slow and unsafe +(2). + +Fortunately, the KDC has a trump on hand: it can easily tell if a +principal exists in the database. The KDC will use +`krb5_425_conv_principal_ext' to convert principals when handling to +version 4 requests. + +---------- Footnotes ---------- + +(1) the other way is not always trivial either, but usually easier + +(2) at least until secure DNS is commonly available + + +File: heimdal.info, Node: Converting a version 4 database, Next: kaserver, Prev: Principal conversion issues, Up: Kerberos 4 issues + +7.2 Converting a version 4 database +=================================== + +If you want to convert an existing version 4 database, the principal +conversion issue arises too. + +If you decide to convert your database once and for all, you will only +have to do this conversion once. It is also possible to run a version 5 +KDC as a slave to a version 4 KDC. In this case this conversion will +happen every time the database is propagated. When doing this +conversion, there are a few things to look out for. If you have stale +entries in the database, these entries will not be converted. This might +be because these principals are not used anymore, or it might be just +because the principal couldn't be converted. + +You might also see problems with a many-to-one mapping of principals. +For instance, if you are using DNS lookups and you have two principals +`rcmd.foo' and `rcmd.bar', where `foo' is a CNAME for `bar', the +resulting principals will be the same. Since the conversion function +can't tell which is correct, these conflicts will have to be resolved +manually. + +7.2.1 Conversion example +------------------------ + +Given the following set of hosts and services: + + foo.se rcmd + mail.foo.se rcmd, pop + ftp.bar.se rcmd, ftp + +you have a database that consists of the following principals: + +`rcmd.foo', `rcmd.mail', `pop.mail', `rcmd.ftp', and `ftp.ftp'. + +lets say you also got these extra principals: `rcmd.gone', +`rcmd.old-mail', where `gone.foo.se' was a machine that has now passed +away, and `old-mail.foo.se' was an old mail machine that is now a CNAME +for `mail.foo.se'. + +When you convert this database you want the following conversions to be +done: + rcmd.foo host/foo.se + rcmd.mail host/mail.foo.se + pop.mail pop/mail.foo.se + rcmd.ftp host/ftp.bar.se + ftp.ftp ftp/ftp.bar.se + rcmd.gone removed + rcmd.old-mail removed + +A `krb5.conf' that does this looks like: + + [realms] + FOO.SE = { + v4_name_convert = { + host = { + ftp = ftp + pop = pop + rcmd = host + } + } + v4_instance_convert = { + foo = foo.se + ftp = ftp.bar.se + } + default_domain = foo.se + } + +The `v4_name_convert' section says which names should be considered +having an instance consisting of a hostname, and it also says how the +names should be converted (for instance `rcmd' should be converted to +`host'). The `v4_instance_convert' section says how a hostname should +be qualified (this is just a hosts-file in disguise). Host-instances +that aren't covered by `v4_instance_convert' are qualified by appending +the contents of the `default_domain'. + +Actually, this example doesn't work. Or rather, it works to well. Since +it has no way of knowing which hostnames are valid and which are not, it +will happily convert `rcmd.gone' to `host/gone.foo.se'. This isn't a +big problem, but if you have run your kerberos realm for a few years, +chances are big that you have quite a few `junk' principals. + +If you don't want this you can remove the `default_domain' statement, +but then you will have to add entries for _all_ your hosts in the +`v4_instance_convert' section. + +Instead of doing this you can use DNS to convert instances. This is not +a solution without problems, but it is probably easier than adding lots +of static host entries. + +To enable DNS lookup you should turn on `v4_instance_resolve' in the +`[libdefaults]' section. + +7.2.2 Converting a database +--------------------------- + +The database conversion is done with `hprop'. You can run this command +to propagate the database to the machine called `slave-server' (which +should be running a `hpropd'). + + hprop --source=krb4-db --master-key=/.m slave-server + +This command can also be to use for converting the v4 database on the +server: + + hprop -n --source=krb4-db -d /var/kerberos/principal --master-key=/.m | hpropd -n + +7.3 Version 4 Kadmin +==================== + +`kadmind' can act as a version 4 kadmind, and you can do most +operations, but with some restrictions (since the version 4 kadmin +protocol is, lets say, very ad hoc.) One example is that it only passes +des keys when creating principals and changing passwords (modern kpasswd +clients do send the password, so it's possible to to password quality +checks). Because of this you can only create principals with des keys, +and you can't set any flags or do any other fancy stuff. + +To get this to work, you have to add another entry to inetd (since +version 4 uses port 751, not 749). + +_And then there are a many more things you can do; more on this in a +later version of this manual. Until then, UTSL._ + + +File: heimdal.info, Node: kaserver, Prev: Converting a version 4 database, Up: Kerberos 4 issues + +7.4 kaserver +============ + +7.4.1 kaserver emulation +------------------------ + +The Heimdal kdc can emulate a kaserver. The kaserver is a Kerberos 4 +server with pre-authentication using Rx as the on-wire protocol. The kdc +contains a minimalistic Rx implementation. + +There are three parts of the kaserver; KAA (Authentication), KAT (Ticket +Granting), and KAM (Maintenance). The KAA interface and KAT interface +both passes over DES encrypted data-blobs (just like the +Kerberos-protocol) and thus do not need any other protection. The KAM +interface uses `rxkad' (Kerberos authentication layer for Rx) for +security and data protection, and is used for example for changing +passwords. This part is not implemented in the kdc. + +Another difference between the ka-protocol and the Kerberos 4 protocol +is that the pass-phrase is salted with the cellname in the `string to +key' function in the ka-protocol, while in the Kerberos 4 protocol there +is no salting of the password at all. To make sure AFS-compatible keys +are added to each principals when they are created or their password are +changed, `afs3-salt' should be added to `[kadmin]default_keys'. + +7.4.2 Transarc AFS Windows client +--------------------------------- + +The Transarc Windows client uses Kerberos 4 to obtain tokens, and thus +does not need a kaserver. The Windows client assumes that the Kerberos +server is on the same machine as the AFS-database server. If you do not +like to do that you can add a small program that runs on the database +servers that forward all kerberos requests to the real kerberos server. +A program that does this is `krb-forward' +(`ftp://ftp.stacken.kth.se/pub/projekts/krb-forward'). + + +File: heimdal.info, Node: Windows 2000 compatability, Next: Programming with Kerberos, Prev: Kerberos 4 issues, Up: Top + +8 Windows 2000 compatability +**************************** + +Windows 2000 (formerly known as Windows NT 5) from Microsoft implements +Kerberos 5. Their implementation, however, has some quirks, +peculiarities, and bugs. This chapter is a short summary of the things +that we have found out while trying to test Heimdal against Windows +2000. Another big problem with the Kerberos implementation in Windows +2000 is that the available documentation is more focused on getting +things to work rather than how they work, and not that useful in +figuring out how things really work. + +This information should apply to Heimdal 1.0 and Windows 2000 +Professional. It's of course subject to change all the time and mostly +consists of our not so inspired guesses. Hopefully it's still somewhat +useful. + +* Menu: + +* Configuring Windows 2000 to use a Heimdal KDC:: +* Inter-Realm keys (trust) between Windows 2000 and a Heimdal KDC:: +* Create account mappings:: +* Encryption types:: +* Authorisation data:: +* Quirks of Windows 2000 KDC:: +* Useful links when reading about the Windows 2000:: + + +File: heimdal.info, Node: Configuring Windows 2000 to use a Heimdal KDC, Next: Inter-Realm keys (trust) between Windows 2000 and a Heimdal KDC, Prev: Windows 2000 compatability, Up: Windows 2000 compatability + +8.1 Configuring Windows 2000 to use a Heimdal KDC +================================================= + +You need the command line program called `ksetup.exe' which is available +in the file `SUPPORT/TOOLS/SUPPORT.CAB' on the Windows 2000 Professional +CD-ROM. This program is used to configure the Kerberos settings on a +Workstation. + +`Ksetup' store the domain information under the registry key: +`HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\LSA\Kerberos\Domains'. + +Use the `kadmin' program in Heimdal to create a host principal in the +Kerberos realm. + + unix% kadmin + kadmin> ank --password=password host/datan.example.com + +The name `datan.example.com' should be replaced with DNS name of the +workstation. + +You must configure the workstation as a member of a workgroup, as +opposed to a member in an NT domain, and specify the KDC server of the +realm as follows: + C:> ksetup /setdomain EXAMPLE.COM + C:> ksetup /addkdc EXAMPLE.COM kdc.example.com + +Set the machine password, i.e. create the local keytab: + C:> ksetup /SetComputerPassword password + +The password used in `ksetup /setmachpassword' must be the same as the +password used in the `kadmin ank' command. + +The workstation must now be rebooted. + +A mapping between local NT users and Kerberos principals must be +specified. You have two choices. First: + + C:> ksetup /mapuser user@MY.REALM nt_user + +This will map a user to a specific principal; this allows you to have +other usernames in the realm than in your NT user database. (Don't ask +me why on earth you would want that....) + +You can also say: + C:> ksetup /mapuser * * +The Windows machine will now map any user to the corresponding +principal, for example `nisse' to the principal `nisse@MY.REALM'. +(This is most likely what you want.) + + +File: heimdal.info, Node: Inter-Realm keys (trust) between Windows 2000 and a Heimdal KDC, Next: Create account mappings, Prev: Configuring Windows 2000 to use a Heimdal KDC, Up: Windows 2000 compatability + +8.2 Inter-Realm keys (trust) between Windows 2000 and a Heimdal KDC +=================================================================== + +See also the Step-by-Step guide from Microsoft, referenced below. + +Install Windows 2000, and create a new controller (Active Directory +Server) for the domain. + +By default the trust will be non-transitive. This means that only users +directly from the trusted domain may authenticate. This can be changed +to transitive by using the `netdom.exe' tool. `netdom.exe' can also be +used to add the trust between two realms. + +You need to tell Windows 2000 on what hosts to find the KDCs for the +non-Windows realm with `ksetup', see *Note Configuring Windows 2000 to +use a Heimdal KDC::. + +This needs to be done on all computers that want enable cross-realm +login with `Mapped Names'. Then you need to add the inter-realm keys +on the Windows KDC. Start the Domain Tree Management tool (found in +Programs, Administrative tools, Active Directory Domains and Trusts). + +Right click on Properties of your domain, select the Trust tab. Press +Add on the appropriate trust windows and enter domain name and +password. When prompted if this is a non-Windows Kerberos realm, press +OK. + +Do not forget to add trusts in both directions (if that's what you +want). + +If you want to use `netdom.exe' instead of the Domain Tree Management +tool, you do it like this: + + netdom trust NT.REALM.EXAMPLE.COM /Domain:EXAMPLE.COM /add /realm /passwordt:TrustPassword + +You also need to add the inter-realm keys to the Heimdal KDC. Make sure +you have matching encryption types (DES, Arcfour and AES in case of +Longhorn) + +Another issue is salting. Since Windows 2000 does not seem to +understand Kerberos 4 salted hashes you might need to turn off anything +similar to the following if you have it, at least while adding the +principals that are going to share keys with Windows 2000. + + [kadmin] + default_keys = v5 v4 + +So remove v4 from default keys. + +What you probably want to use is this: + + [kadmin] + default_keys = des-cbc-crc:pw-salt arcfour-hmac-md5:pw-salt + +Once that is also done, you can add the required inter-realm keys: + + kadmin add krbtgt/NT.REALM.EXAMPLE.COM@EXAMPLE.COM + kadmin add krbtgt/REALM.EXAMPLE.COM@NT.EXAMPLE.COM + +Use the same passwords for both keys. + +Do not forget to reboot before trying the new realm-trust (after +running `ksetup'). It looks like it might work, but packets are never +sent to the non-Windows KDC. + + +File: heimdal.info, Node: Create account mappings, Next: Encryption types, Prev: Inter-Realm keys (trust) between Windows 2000 and a Heimdal KDC, Up: Windows 2000 compatability + +8.3 Create account mappings +=========================== + +Start the `Active Directory Users and Computers' tool. Select the View +menu, that is in the left corner just below the real menu (or press +Alt-V), and select Advanced Features. Right click on the user that you +are going to do a name mapping for and choose Name mapping. + +Click on the Kerberos Names tab and add a new principal from the +non-Windows domain. + +This adds `authorizationNames' entry to the users LDAP entry to the +Active Directory LDAP catalog. When you create users by script you can +add this entry instead. + + +File: heimdal.info, Node: Encryption types, Next: Authorisation data, Prev: Create account mappings, Up: Windows 2000 compatability + +8.4 Encryption types +==================== + +Windows 2000 supports both the standard DES encryptions (`des-cbc-crc' +and `des-cbc-md5') and its own proprietary encryption that is based on +MD4 and RC4 that is documented in and is supposed to be described in +`draft-brezak-win2k-krb-rc4-hmac-03.txt'. New users will get both MD4 +and DES keys. Users that are converted from a NT4 database, will only +have MD4 passwords and will need a password change to get a DES key. + + +File: heimdal.info, Node: Authorisation data, Next: Quirks of Windows 2000 KDC, Prev: Encryption types, Up: Windows 2000 compatability + +8.5 Authorisation data +====================== + +The Windows 2000 KDC also adds extra authorisation data in tickets. It +is at this point unclear what triggers it to do this. The format of +this data is only available under a "secret" license from Microsoft, +which prohibits you implementing it. + +A simple way of getting hold of the data to be able to understand it +better is described here. + + 1. Find the client example on using the SSPI in the SDK documentation. + + 2. Change "AuthSamp" in the source code to lowercase. + + 3. Build the program. + + 4. Add the "authsamp" principal with a known password to the + database. Make sure it has a DES key. + + 5. Run `ktutil add' to add the key for that principal to a keytab. + + 6. Run `appl/test/nt_gss_server -p 2000 -s authsamp --dump-auth=FILE' + where FILE is an appropriate file. + + 7. It should authenticate and dump for you the authorisation data in + the file. + + 8. The tool `lib/asn1/asn1_print' is somewhat useful for analysing + the data. + + +File: heimdal.info, Node: Quirks of Windows 2000 KDC, Next: Useful links when reading about the Windows 2000, Prev: Authorisation data, Up: Windows 2000 compatability + +8.6 Quirks of Windows 2000 KDC +============================== + +There are some issues with salts and Windows 2000. Using an empty +salt--which is the only one that Kerberos 4 supported, and is therefore +known as a Kerberos 4 compatible salt--does not work, as far as we can +tell from out experiments and users' reports. Therefore, you have to +make sure you keep around keys with all the different types of salts +that are required. Microsoft have fixed this issue post Windows 2003. + +Microsoft seems also to have forgotten to implement the checksum +algorithms `rsa-md4-des' and `rsa-md5-des'. This can make Name mapping +(*note Create account mappings::) fail if a `des-cbc-md5' key is used. +To make the KDC return only `des-cbc-crc' you must delete the +`des-cbc-md5' key from the kdc using the `kadmin del_enctype' command. + + kadmin del_enctype lha des-cbc-md5 + +You should also add the following entries to the `krb5.conf' file: + + [libdefaults] + default_etypes = des-cbc-crc + default_etypes_des = des-cbc-crc + +These configuration options will make sure that no checksums of the +unsupported types are generated. + + +File: heimdal.info, Node: Useful links when reading about the Windows 2000, Prev: Quirks of Windows 2000 KDC, Up: Windows 2000 compatability + +8.7 Useful links when reading about the Windows 2000 +==================================================== + +See also our paper presented at the 2001 Usenix Annual Technical +Conference, available in the proceedings or at +`http://www.usenix.org/publications/library/proceedings/usenix01/freenix01/westerlund.html'. + +There are lots of texts about Kerberos on Microsoft's web site, here is +a short list of the interesting documents that we have managed to find. + + * Step-by-Step Guide to Kerberos 5 (krb5 1.0) Interoperability: + `http://www.microsoft.com/technet/prodtechnol/windows2000serv/howto/kerbstep.mspx'. + Kerberos GSS-API (in Windows-eze SSPI), Windows as a client in a + non-Windows KDC realm, adding unix clients to a Windows 2000 KDC, + and adding cross-realm trust (*note Inter-Realm keys (trust) + between Windows 2000 and a Heimdal KDC::). + + * Windows 2000 Kerberos Authentication: + `www.microsoft.com/technet/prodtechnol/windows2000serv/deploy/confeat/kerberos.mspx'. + White paper that describes how Kerberos is used in Windows 2000. + + * Overview of Kerberos: + `http://support.microsoft.com/support/kb/articles/Q248/7/58.ASP'. + Links to useful other links. + + * Event logging for Kerberos: + `http://support.microsoft.com/support/kb/articles/Q262/1/77.ASP'. + Basically it say that you can add a registry key + `HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Lsa\Kerberos\Parameters\LogLevel' + with value DWORD equal to 1, and then you'll get logging in the + Event Logger. + + +Other useful programs include these: + + * pwdump2 + `http://www.bindview.com/Support/RAZOR/Utilities/Windows/pwdump2_readme.cfm' + + +File: heimdal.info, Node: Programming with Kerberos, Next: Migration, Prev: Windows 2000 compatability, Up: Top + +9 Programming with Kerberos +*************************** + +First you need to know how the Kerberos model works, go read the +introduction text (*note What is Kerberos?::). + +* Menu: + +* Kerberos 5 API Overview:: +* Walkthrough of a sample Kerberos 5 client:: +* Validating a password in a server application:: +* API differences to MIT Kerberos:: +* File formats:: + + +File: heimdal.info, Node: Kerberos 5 API Overview, Next: Walkthrough of a sample Kerberos 5 client, Prev: Programming with Kerberos, Up: Programming with Kerberos + +9.1 Kerberos 5 API Overview +=========================== + +All functions are documented in manual pages. This section tries to +give an overview of the major components used in Kerberos library, and +point to where to look for a specific function. + +9.1.1 Kerberos context +---------------------- + +A kerberos context (`krb5_context') holds all per thread state. All +global variables that are context specific are stored in this +structure, including default encryption types, credential cache (for +example, a ticket file), and default realms. + +See the manual pages for `krb5_context(3)' and `krb5_init_context(3)'. + +9.1.2 Kerberos authentication context +------------------------------------- + +Kerberos authentication context (`krb5_auth_context') holds all context +related to an authenticated connection, in a similar way to the +kerberos context that holds the context for the thread or process. + +The `krb5_auth_context' is used by various functions that are directly +related to authentication between the server/client. Example of data +that this structure contains are various flags, addresses of client and +server, port numbers, keyblocks (and subkeys), sequence numbers, replay +cache, and checksum types. + +See the manual page for `krb5_auth_context(3)'. + +9.1.3 Kerberos principal +------------------------ + +The Kerberos principal is the structure that identifies a user or +service in Kerberos. The structure that holds the principal is the +`krb5_principal'. There are function to extract the realm and elements +of the principal, but most applications have no reason to inspect the +content of the structure. + +The are several ways to create a principal (with different degree of +portability), and one way to free it. + +See manual page for `krb5_principal(3)' for more information about the +functions. + +9.1.4 Credential cache +---------------------- + +A credential cache holds the tickets for a user. A given user can have +several credential caches, one for each realm where the user have the +initial tickets (the first krbtgt). + +The credential cache data can be stored internally in different way, +each of them for different proposes. File credential (FILE) caches and +processes based (KCM) caches are for permanent storage. While memory +caches (MEMORY) are local caches to the local process. + +Caches are opened with `krb5_cc_resolve(3)' or created with +`krb5_cc_gen_unique(3)'. + +If the cache needs to be opened again (using `krb5_cc_resolve(3)') +`krb5_cc_close(3)' will close the handle, but not the remove the cache. +`krb5_cc_destroy(3)' will zero out the cache, remove the cache so it +can no longer be referenced. + +See also manual page for `krb5_ccache(3)' + +9.1.5 Kerberos errors +--------------------- + +Kerberos errors are based on the com_err library. All error codes are +32-bit signed numbers, the first 24 bits define what subsystem the +error originates from, and last 8 bits are 255 error codes within the +library. Each error code have fixed string associated with it. For +example, the error-code -1765328383 have the symbolic name +KRB5KDC_ERR_NAME_EXP, and associated error string "Client's entry in +database has expired". + +This is a great improvement compared to just getting one of the unix +error-codes back. However, Heimdal have an extention to pass back +customised errors messages. Instead of getting "Key table entry not +found", the user might back "failed to find +host/host.example.com@EXAMLE.COM(kvno 3) in keytab /etc/krb5.keytab +(des-cbc-crc)". This improves the chance that the user find the cause +of the error so you should use the customised error message whenever +its available. + +See also manual page for `krb5_get_error_string(3)' and +`krb5_get_err_text(3)'. + +9.1.6 Keytab management +----------------------- + +A keytab is a storage for locally stored keys. Heimdal includes keytab +support for Kerberos 5 keytabs, Kerberos 4 srvtab, AFS-KeyFile's, and +for storing keys in memory. + +Keytabs are used for servers and long-running services. + +See also manual page for `krb5_keytab(3)' + +9.1.7 Kerberos crypto +--------------------- + +Heimdal includes a implementation of the Kerberos crypto framework, all +crypto operations. + +See also manual page for `krb5_crypto_init(3)', `krb5_keyblock(3)', +`krb5_create_checksum(3)', and `krb5_encrypt(3)'. + + +File: heimdal.info, Node: Walkthrough of a sample Kerberos 5 client, Next: Validating a password in a server application, Prev: Kerberos 5 API Overview, Up: Programming with Kerberos + +9.2 Walkthrough of a sample Kerberos 5 client +============================================= + +This example contains parts of a sample TCP Kerberos 5 clients, if you +want a real working client, please look in `appl/test' directory in the +Heimdal distribution. + +All Kerberos error-codes that are returned from kerberos functions in +this program are passed to `krb5_err', that will print a descriptive +text of the error code and exit. Graphical programs can convert +error-code to a human readable error-string with the +`krb5_get_err_text(3)' function. + +Note that you should not use any Kerberos function before +`krb5_init_context()' have completed successfully. That is the reason +`err()' is used when `krb5_init_context()' fails. + +First the client needs to call `krb5_init_context' to initialise the +Kerberos 5 library. This is only needed once per thread in the program. +If the function returns a non-zero value it indicates that either the +Kerberos implementation is failing or its disabled on this host. + + #include + + int + main(int argc, char **argv) + { + krb5_context context; + + if (krb5_context(&context)) + errx (1, "krb5_context"); + +Now the client wants to connect to the host at the other end. The +preferred way of doing this is using `getaddrinfo(3)' (for operating +system that have this function implemented), since getaddrinfo is +neutral to the address type and can use any protocol that is available. + + struct addrinfo *ai, *a; + struct addrinfo hints; + int error; + + memset (&hints, 0, sizeof(hints)); + hints.ai_socktype = SOCK_STREAM; + hints.ai_protocol = IPPROTO_TCP; + + error = getaddrinfo (hostname, "pop3", &hints, &ai); + if (error) + errx (1, "%s: %s", hostname, gai_strerror(error)); + + for (a = ai; a != NULL; a = a->ai_next) { + int s; + + s = socket (a->ai_family, a->ai_socktype, a->ai_protocol); + if (s < 0) + continue; + if (connect (s, a->ai_addr, a->ai_addrlen) < 0) { + warn ("connect(%s)", hostname); + close (s); + continue; + } + freeaddrinfo (ai); + ai = NULL; + } + if (ai) { + freeaddrinfo (ai); + errx ("failed to contact %s", hostname); + } + +Before authenticating, an authentication context needs to be created. +This context keeps all information for one (to be) authenticated +connection (see `krb5_auth_context(3)'). + + status = krb5_auth_con_init (context, &auth_context); + if (status) + krb5_err (context, 1, status, "krb5_auth_con_init"); + +For setting the address in the authentication there is a help function +`krb5_auth_con_setaddrs_from_fd' that does everything that is needed +when given a connected file descriptor to the socket. + + status = krb5_auth_con_setaddrs_from_fd (context, + auth_context, + &sock); + if (status) + krb5_err (context, 1, status, + "krb5_auth_con_setaddrs_from_fd"); + +The next step is to build a server principal for the service we want to +connect to. (See also `krb5_sname_to_principal(3)'.) + + status = krb5_sname_to_principal (context, + hostname, + service, + KRB5_NT_SRV_HST, + &server); + if (status) + krb5_err (context, 1, status, "krb5_sname_to_principal"); + +The client principal is not passed to `krb5_sendauth(3)' function, this +causes the `krb5_sendauth' function to try to figure it out itself. + +The server program is using the function `krb5_recvauth(3)' to receive +the Kerberos 5 authenticator. + +In this case, mutual authentication will be tried. That means that the +server will authenticate to the client. Using mutual authentication is +good since it enables the user to verify that they are talking to the +right server (a server that knows the key). + +If you are using a non-blocking socket you will need to do all work of +`krb5_sendauth' yourself. Basically you need to send over the +authenticator from `krb5_mk_req(3)' and, in case of mutual +authentication, verifying the result from the server with +`krb5_rd_rep(3)'. + + status = krb5_sendauth (context, + &auth_context, + &sock, + VERSION, + NULL, + server, + AP_OPTS_MUTUAL_REQUIRED, + NULL, + NULL, + NULL, + NULL, + NULL, + NULL); + if (status) + krb5_err (context, 1, status, "krb5_sendauth"); + +Once authentication has been performed, it is time to send some data. +First we create a krb5_data structure, then we sign it with +`krb5_mk_safe(3)' using the `auth_context' that contains the +session-key that was exchanged in the +`krb5_sendauth(3)'/`krb5_recvauth(3)' authentication sequence. + + data.data = "hej"; + data.length = 3; + + krb5_data_zero (&packet); + + status = krb5_mk_safe (context, + auth_context, + &data, + &packet, + NULL); + if (status) + krb5_err (context, 1, status, "krb5_mk_safe"); + +And send it over the network. + + len = packet.length; + net_len = htonl(len); + + if (krb5_net_write (context, &sock, &net_len, 4) != 4) + err (1, "krb5_net_write"); + if (krb5_net_write (context, &sock, packet.data, len) != len) + err (1, "krb5_net_write"); + +To send encrypted (and signed) data `krb5_mk_priv(3)' should be used +instead. `krb5_mk_priv(3)' works the same way as `krb5_mk_safe(3)', +with the exception that it encrypts the data in addition to signing it. + + data.data = "hemligt"; + data.length = 7; + + krb5_data_free (&packet); + + status = krb5_mk_priv (context, + auth_context, + &data, + &packet, + NULL); + if (status) + krb5_err (context, 1, status, "krb5_mk_priv"); + +And send it over the network. + + len = packet.length; + net_len = htonl(len); + + if (krb5_net_write (context, &sock, &net_len, 4) != 4) + err (1, "krb5_net_write"); + if (krb5_net_write (context, &sock, packet.data, len) != len) + err (1, "krb5_net_write"); + +The server is using `krb5_rd_safe(3)' and `krb5_rd_priv(3)' to verify +the signature and decrypt the packet. + + +File: heimdal.info, Node: Validating a password in a server application, Next: API differences to MIT Kerberos, Prev: Walkthrough of a sample Kerberos 5 client, Up: Programming with Kerberos + +9.3 Validating a password in an application +=========================================== + +See the manual page for `krb5_verify_user(3)'. + + +File: heimdal.info, Node: API differences to MIT Kerberos, Next: File formats, Prev: Validating a password in a server application, Up: Programming with Kerberos + +9.4 API differences to MIT Kerberos +=================================== + +This section is somewhat disorganised, but so far there is no overall +structure to the differences, though some of the have their root in +that Heimdal uses an ASN.1 compiler and MIT doesn't. + +9.4.1 Principal and realms +-------------------------- + +Heimdal stores the realm as a `krb5_realm', that is a `char *'. MIT +Kerberos uses a `krb5_data' to store a realm. + +In Heimdal `krb5_principal' doesn't contain the component `name_type'; +it's instead stored in component `name.name_type'. To get and set the +nametype in Heimdal, use `krb5_principal_get_type(3)' and +`krb5_principal_set_type(3)'. + +For more information about principal and realms, see +`krb5_principal(3)'. + +9.4.2 Error messages +-------------------- + +To get the error string, Heimdal uses `krb5_get_error_string(3)' or, if +`NULL' is returned, `krb5_get_err_text(3)'. This is to return custom +error messages (like "Can't find host/datan.example.com@EXAMPLE.COM in +/etc/krb5.conf." instead of a "Key table entry not found" that +`error_message(3)' returns. + +Heimdal uses a threadsafe(r) version of the com_err interface; the +global `com_err' table isn't initialised. Then `error_message(3)' +returns quite a boring error string (just the error code itself). + + +File: heimdal.info, Node: File formats, Prev: API differences to MIT Kerberos, Up: Programming with Kerberos + +9.5 File formats +================ + +This section documents the diffrent file formats that are used in +Heimdal and other Kerberos implementations. + +9.5.1 keytab +------------ + +The keytab binary format is not a standard format. The format has +evolved and may continue to. It is however understood by several +Kerberos implementations including Heimdal, MIT, Sun's Java ktab and +are created by the ktpass.exe utility from Windows. So it has +established itself as the defacto format for storing Kerberos keys. + +The following C-like structure definitions illustrate the MIT keytab +file format. All values are in network byte order. All text is ASCII. + + keytab { + uint16_t file_format_version; /* 0x502 */ + keytab_entry entries[*]; + }; + + keytab_entry { + int32_t size; + uint16_t num_components; /* subtract 1 if version 0x501 */ + counted_octet_string realm; + counted_octet_string components[num_components]; + uint32_t name_type; /* not present if version 0x501 */ + uint32_t timestamp; + uint8_t vno8; + keyblock key; + uint32_t vno; /* only present if >= 4 bytes left in entry */ + }; + + counted_octet_string { + uint16_t length; + uint8_t data[length]; + }; + + keyblock { + uint16_t type; + counted_octet_string; + }; + +All numbers are stored in network byteorder (big endian) format. + +The keytab file format begins with the 16 bit file_format_version which +at the time this document was authored is 0x502. The format of older +keytabs is described at the end of this document. + +The file_format_version is immediately followed by an array of +keytab_entry structures which are prefixed with a 32 bit size indicating +the number of bytes that follow in the entry. Note that the size should +be evaluated as signed. This is because a negative value indicates that +the entry is in fact empty (e.g. it has been deleted) and that the +negative value of that negative value (which is of course a positive +value) is the offset to the next keytab_entry. Based on these size +values alone the entire keytab file can be traversed. + +The size is followed by a 16 bit num_components field indicating the +number of counted_octet_string components in the components array. + +The num_components field is followed by a counted_octet_string +representing the realm of the principal. + +A counted_octet_string is simply an array of bytes prefixed with a 16 +bit length. For the realm and name components, the counted_octet_string +bytes are ASCII encoded text with no zero terminator. + +Following the realm is the components array that represents the name of +the principal. The text of these components may be joined with slashs +to construct the typical SPN representation. For example, the service +principal HTTP/www.foo.net@FOO.NET would consist of name components +"HTTP" followed by "www.foo.net". + +Following the components array is the 32 bit name_type (e.g. 1 is +KRB5_NT_PRINCIPAL, 2 is KRB5_NT_SRV_INST, 5 is KRB5_NT_UID, etc). In +practice the name_type is almost certainly 1 meaning KRB5_NT_PRINCIPAL. + +The 32 bit timestamp indicates the time the key was established for that +principal. The value represents the number of seconds since Jan 1, 1970. + +The 8 bit vno8 field is the version number of the key. This value is +overridden by the 32 bit vno field if it is present. The vno8 field is +filled with the lower 8 bits of the 32 bit protocol kvno field. + +The keyblock structure consists of a 16 bit value indicating the +encryption type and is a counted_octet_string containing the key. The +encryption type is the same as the Kerberos standard (e.g. 3 is +des-cbc-md5, 23 is arcfour-hmac-md5, etc). + +The last field of the keytab_entry structure is optional. If the size of +the keytab_entry indicates that there are at least 4 bytes remaining, a +32 bit value representing the key version number is present. This value +supersedes the 8 bit vno8 value preceeding the keyblock. + +Older keytabs with a file_format_version of 0x501 are different in +three ways: + +All integers are in host byte order [1]. + +The num_components field is 1 too large (i.e. after decoding, decrement by 1). + +The 32 bit name_type field is not present. + +[1] The file_format_version field should really be treated as two +separate 8 bit quantities representing the major and minor version +number respectively. + +9.5.2 Heimdal database dump file +-------------------------------- + +Format of the Heimdal text dump file as of Heimdal 0.6.3: + +Each line in the dump file is one entry in the database. + +Each field of a line is separated by one or more spaces, with the +exception of fields consisting of principals containing spaces, where +space can be quoted with \ and \ is quoted by \. + +Fields and their types are: + + Quoted princial (quote character is \) [string] + Keys [keys] + Created by [event] + Modified by [event optional] + Valid start time [time optional] + Valid end time [time optional] + Password end valid time [time optional] + Max lifetime of ticket [time optional] + Max renew time of ticket [integer optional] + Flags [hdb flags] + Generation number [generation optional] + Extensions [extentions optional] + +Fields following these silently are ignored. + +All optional fields will be skipped if they fail to parse (or comprise +the optional field marker of "-", w/o quotes). + +Example: + + fred@EXAMPLE.COM 27:1:16:e8b4c8fc7e60b9e641dcf4cff3f08a701d982a2f89ba373733d26ca59ba6c789666f6b8bfcf169412bb1e5dceb9b33cda29f3412:-:1:3:4498a933881178c744f4232172dcd774c64e81fa6d05ecdf643a7e390624a0ebf3c7407a:-:1:2:b01934b13eb795d76f3a80717d469639b4da0cfb644161340ef44fdeb375e54d684dbb85:-:1:1:ea8e16d8078bf60c781da90f508d4deccba70595258b9d31888d33987cd31af0c9cced2e:- 20020415130120:admin@EXAMPLE.COM 20041221112428:fred@EXAMPLE.COM - - - 86400 604800 126 20020415130120:793707:28 - + +Encoding of types are as follows: + +keys + kvno:[masterkvno:keytype:keydata:salt]{zero or more separated by :} + + kvno is the key version number. + + keydata is hex-encoded + + masterkvno is the kvno of the database master key. If this field + is empty, the kadmin load and merge operations will encrypt the + key data with the master key if there is one. Otherwise the key + data will be imported asis. + + salt is encoded as "-" (no/default salt) or + + salt-type / + salt-type / "string" + salt-type / hex-encoded-data + + keytype is the protocol enctype number; see enum ENCTYPE in + include/krb5_asn1.h for values. + + Example: + 27:1:16:e8b4c8fc7e60b9e641dcf4cff3f08a701d982a2f89ba373733d26ca59ba6c789666f6b8bfcf169412bb1e5dceb9b33cda29f3412:-:1:3:4498a933881178c744f4232172dcd774c64e81fa6d05ecdf643a7e390624a0ebf3c7407a:-:1:2:b01934b13eb795d76f3a80717d469639b4da0cfb644161340ef44fdeb375e54d684dbb85:-:1:1:ea8e16d8078bf60c781da90f508d4deccba70595258b9d31888d33987cd31af0c9cced2e:- + + kvno=27,{key: masterkvno=1,keytype=des3-cbc-sha1,keydata=..., default salt}... + +time + Format of the time is: YYYYmmddHHMMSS, corresponding to strftime + format "%Y%m%d%k%M%S". + + Time is expressed in UTC. + + Time can be optional (using -), when the time 0 is used. + + Example: + + 20041221112428 + +event + time:principal + + time is as given in format time + + principal is a string. Not quoting it may not work in earlier + versions of Heimdal. + + Example: + 20041221112428:bloggs@EXAMPLE.COM + +hdb flags + Integer encoding of HDB flags, see HDBFlags in lib/hdb/hdb.asn1. + Each bit in the integer is the same as the bit in the + specification. + +generation: + time:usec:gen + + usec is a the microsecond, integer. gen is generation number, + integer. + + The generation can be defaulted (using '-') or the empty string + +extensions: + first-hex-encoded-HDB-Extension[:second-...] + + HDB-extension is encoded the DER encoded HDB-Extension from + lib/hdb/hdb.asn1. Consumers HDB extensions should be aware that + unknown entires needs to be preserved even thought the ASN.1 data + content might be unknown. There is a critical flag in the data to + show to the KDC that the entry MUST be understod if the entry is + to be used. + + + +File: heimdal.info, Node: Migration, Next: Acknowledgments, Prev: Programming with Kerberos, Up: Top + +10 Migration +************ + +10.1 General issues +=================== + +When migrating from a Kerberos 4 KDC. + +10.2 Order in what to do things: +================================ + + * Convert the database, check all principals that hprop complains + about. + + `hprop -n --source=| hpropd -n' + + Replace with whatever source you have, like krb4-db or + krb4-dump. + + * Run a Kerberos 5 slave for a while. + + * Figure out if it does everything you want it to. + + Make sure that all things that you use works for you. + + * Let a small number of controlled users use Kerberos 5 tools. + + Find a sample population of your users and check what programs + they use, you can also check the kdc-log to check what ticket are + checked out. + + * Burn the bridge and change the master. + + * Let all users use the Kerberos 5 tools by default. + + * Turn off services that do not need Kerberos 4 authentication. + + Things that might be hard to get away is old programs with support + for Kerberos 4. Example applications are old Eudora installations + using KPOP, and Zephyr. Eudora can use the Kerberos 4 kerberos in + the Heimdal kdc. + + + +File: heimdal.info, Node: Acknowledgments, Prev: Migration, Up: Top + +Appendix A Acknowledgments +************************** + +Eric Young wrote "libdes". Heimdal used to use libdes, without it +kth-krb would never have existed. Since there are no longer any Eric +Young code left in the library, we renamed it to libhcrypto. + +All functions in libhcrypto have been re-implemented or used available +public domain code. The core AES function where written by Vincent +Rijmen, Antoon Bosselaers and Paulo Barreto. The core DES SBOX +transformation was written by Richard Outerbridge. `imath' that is used +for public key crypto support is written by Michael J. Fromberger. + +The University of California at Berkeley initially wrote `telnet', and +`telnetd'. The authentication and encryption code of `telnet' and +`telnetd' was added by David Borman (then of Cray Research, Inc). The +encryption code was removed when this was exported and then added back +by Juha Eskelinen. + +The `popper' was also a Berkeley program initially. + +Some of the functions in `libroken' also come from Berkeley by way of +NetBSD/FreeBSD. + +`editline' was written by Simmule Turner and Rich Salz. Heimdal +contains a modifed copy. + +The `getifaddrs' implementation for Linux was written by Hideaki +YOSHIFUJI for the Usagi project. + +The `pkcs11.h' headerfile was written by the Scute project. + +Bugfixes, documentation, encouragement, and code has been contributed +by: +Alexander Boström + +Andreaw Bartlett + +Björn Sandell + +Brandon S. Allbery KF8NH + +Brian A May + +Chaskiel M Grundman + +Cizzi Storm + +Daniel Kouril + +David Love + +Derrick J Brashear + +Douglas E Engert + +Frank van der Linden + +Jason McIntyre + +Johan Ihrén + +Jun-ichiro itojun Hagino + +Ken Hornstein + +Magnus Ahltorp + +Marc Horowitz + +Mario Strasser + +Mark Eichin + +Mattias Amnefelt + +Michael B Allen + +Michael Fromberger + +Michal Vocu + +Miroslav Ruda + +Petr Holub + +Phil Fisher + +Rafal Malinowski + +Richard Nyberg + +Åke Sandgren + +and we hope that those not mentioned here will forgive us. + +All bugs were introduced by ourselves. + + + +Tag Table: +Node: Top211 +Node: Introduction1916 +Node: What is Kerberos?4724 +Node: Building and Installing9837 +Node: Setting up a realm13472 +Node: Configuration file14394 +Node: Creating the database17177 +Node: Modifying the database20101 +Node: Checking the setup21694 +Node: keytabs22546 +Node: Serving Kerberos 4/524/kaserver23414 +Node: Remote administration24990 +Node: Password changing26920 +Node: Testing clients and servers30618 +Node: Slave Servers30946 +Node: Incremental propagation32701 +Node: Encryption types and salting35491 +Node: Cross realm37649 +Node: Transit policy40194 +Node: Setting up DNS41866 +Node: Using LDAP to store the database44341 +Node: Providing Kerberos credentials to servers and programs50121 +Node: Setting up PK-INIT52216 +Node: Applications63946 +Node: Authentication modules64146 +Node: Digital SIA64740 +Node: IRIX69124 +Node: AFS70414 +Node: Things in search for a better place73058 +Node: Kerberos 4 issues75787 +Node: Principal conversion issues76249 +Ref: Principal conversion issues-Footnote-178480 +Ref: Principal conversion issues-Footnote-278548 +Node: Converting a version 4 database78601 +Node: kaserver83669 +Node: Windows 2000 compatability85440 +Node: Configuring Windows 2000 to use a Heimdal KDC86640 +Node: Inter-Realm keys (trust) between Windows 2000 and a Heimdal KDC88630 +Node: Create account mappings91324 +Node: Encryption types92086 +Node: Authorisation data92691 +Node: Quirks of Windows 2000 KDC93843 +Node: Useful links when reading about the Windows 200095147 +Node: Programming with Kerberos96976 +Node: Kerberos 5 API Overview97452 +Node: Walkthrough of a sample Kerberos 5 client101878 +Node: Validating a password in a server application109666 +Node: API differences to MIT Kerberos110001 +Node: File formats111459 +Node: Migration119941 +Node: Acknowledgments121221 + +End Tag Table diff -U 3 -H -d -r -N -x Makefile.in -x 'config.h.in*' -x 'output*' -x requests -x 'traces*' -x '*.loT' -x aclocal.m4 -x configure -- heimdal-1.0.1/doc/setup.texi heimdal-1.0.1.work/doc/setup.texi --- heimdal-1.0.1/doc/setup.texi 2007-08-09 10:47:03.000000000 +0300 +++ heimdal-1.0.1.work/doc/setup.texi 1970-01-01 02:00:00.000000000 +0200 @@ -1,1455 +0,0 @@ -@c $Id: setup.texi 21298 2007-06-25 14:50:03Z lha $ - -@node Setting up a realm, Applications, Building and Installing, Top - -@chapter Setting up a realm - -A -@cindex realm -realm is an administrative domain. The name of a Kerberos realm is -usually the Internet domain name in uppercase. Call your realm the same -as your Internet domain name if you do not have strong reasons for not -doing so. It will make life easier for you and everyone else. - -@menu -* Configuration file:: -* Creating the database:: -* Modifying the database:: -* Checking the setup:: -* keytabs:: -* Serving Kerberos 4/524/kaserver:: -* Remote administration:: -* Password changing:: -* Testing clients and servers:: -* Slave Servers:: -* Incremental propagation:: -* Encryption types and salting:: -* Cross realm:: -* Transit policy:: -* Setting up DNS:: -* Using LDAP to store the database:: -* Providing Kerberos credentials to servers and programs:: -* Setting up PK-INIT:: -@end menu - -@node Configuration file, Creating the database, Setting up a realm, Setting up a realm -@section Configuration file - -To setup a realm you will first have to create a configuration file: -@file{/etc/krb5.conf}. The @file{krb5.conf} file can contain many -configuration options, some of which are described here. - -There is a sample @file{krb5.conf} supplied with the distribution. - -The configuration file is a hierarchical structure consisting of -sections, each containing a list of bindings (either variable -assignments or subsections). A section starts with -@samp{[@samp{section-name}]}. A binding consists of a left hand side, an equal sign -(@samp{=}) and a right hand side (the left hand side tag must be -separated from the equal sign with some whitespace). Subsections have a -@samp{@{} as the first non-whitespace character after the equal sign. All -other bindings are treated as variable assignments. The value of a -variable extends to the end of the line. - -@example -[section1] - a-subsection = @{ - var = value1 - other-var = value with @{@} - sub-sub-section = @{ - var = 123 - @} - @} - var = some other value -[section2] - var = yet another value -@end example - -In this manual, names of sections and bindings will be given as strings -separated by slashes (@samp{/}). The @samp{other-var} variable will thus -be @samp{section1/a-subsection/other-var}. - -For in-depth information about the contents of the configuration file, refer to -the @file{krb5.conf} manual page. Some of the more important sections -are briefly described here. - -The @samp{libdefaults} section contains a list of library configuration -parameters, such as the default realm and the timeout for KDC -responses. The @samp{realms} section contains information about specific -realms, such as where they hide their KDC@. This section serves the same -purpose as the Kerberos 4 @file{krb.conf} file, but can contain more -information. Finally the @samp{domain_realm} section contains a list of -mappings from domains to realms, equivalent to the Kerberos 4 -@file{krb.realms} file. - -To continue with the realm setup, you will have to create a configuration file, -with contents similar to the following. - -@example -[libdefaults] - default_realm = MY.REALM -[realms] - MY.REALM = @{ - kdc = my.kdc my.slave.kdc - kdc = my.third.kdc - @} -[domain_realm] - .my.domain = MY.REALM - -@end example - -If you use a realm name equal to your domain name, you can omit the -@samp{libdefaults}, and @samp{domain_realm}, sections. If you have a DNS -SRV-record for your realm, or your Kerberos server has DNS CNAME -@samp{kerberos.my.realm}, you can omit the @samp{realms} section too. - -@node Creating the database, Modifying the database, Configuration file, Setting up a realm -@section Creating the database - -The database library will look for the database in the directory -@file{/var/heimdal}, so you should probably create that directory. -Make sure the directory has restrictive permissions. - -@example -# mkdir /var/heimdal -@end example - -The keys of all the principals are stored in the database. If you -choose to, these can be encrypted with a master key. You do not have to -remember this key (or password), but just to enter it once and it will -be stored in a file (@file{/var/heimdal/m-key}). If you want to have a -master key, run @samp{kstash} to create this master key: - -@example -# kstash -Master key: -Verifying password - Master key: -@end example - -If you want to generate a random master key you can use the ---random-key to kstash. This will make sure you have a good key -on which attackers can't do a dictionary attack. - -If you have a master key, make sure you make a backup of your master -key file; without it backups of the database are of no use. - -To initialise the database use the @command{kadmin} program, with the -@samp{-l} option (to enable local database mode). First issue a -@kbd{init MY.REALM} command. This will create the database and insert -default principals for that realm. You can have more than one realm in -one database, so @samp{init} does not destroy any old database. - -Before creating the database, @samp{init} will ask you some questions -about maximum ticket lifetimes. - -After creating the database you should probably add yourself to it. You -do this with the @samp{add} command. It takes as argument the name of a -principal. The principal should contain a realm, so if you haven't set up -a default realm, you will need to explicitly include the realm. - -@example -# kadmin -l -kadmin> init MY.REALM -Realm max ticket life [unlimited]: -Realm max renewable ticket life [unlimited]: -kadmin> add me -Max ticket life [unlimited]: -Max renewable life [unlimited]: -Attributes []: -Password: -Verifying password - Password: -@end example - -Now start the KDC and try getting a ticket. - -@example -# kdc & -# kinit me -me@@MY.REALMS's Password: -# klist -Credentials cache: /tmp/krb5cc_0 - Principal: me@@MY.REALM - - Issued Expires Principal -Aug 25 07:25:55 Aug 25 17:25:55 krbtgt/MY.REALM@@MY.REALM -@end example - -If you are curious you can use the @samp{dump} command to list all the -entries in the database. It should look something similar to the -following example (note that the entries here are truncated for -typographical reasons): - -@smallexample -kadmin> dump -me@@MY.REALM 1:0:1:0b01d3cb7c293b57:-:0:7:8aec316b9d1629e3baf8 ... -kadmin/admin@@MY.REALM 1:0:1:e5c8a2675b37a443:-:0:7:cb913ebf85 ... -krbtgt/MY.REALM@@MY.REALM 1:0:1:52b53b61c875ce16:-:0:7:c8943be ... -kadmin/changepw@@MY.REALM 1:0:1:f48c8af2b340e9fb:-:0:7:e3e6088 ... -@end smallexample - -@node Modifying the database, Checking the setup, Creating the database, Setting up a realm -@section Modifying the database - -All modifications of principals are done with with kadmin. - -A principal has several attributes and lifetimes associated with it. - -Principals are added, renamed, modified, and deleted with the kadmin -commands @samp{add}, @samp{rename}, @samp{modify}, @samp{delete}. -Both interactive editing and command line flags can be used (use --help -to list the available options). - -There are different kinds of types for the fields in the database; -attributes, absolute time times and relative times. - -@subsection Attributes - -When doing interactive editing, attributes are listed with @samp{?}. - -The attributes are given in a comma (@samp{,}) separated list. -Attributes are removed from the list by prefixing them with @samp{-}. - -@smallexample -kadmin> modify me -Max ticket life [1 day]: -Max renewable life [1 week]: -Principal expiration time [never]: -Password expiration time [never]: -Attributes [disallow-renewable]: requires-pre-auth,-disallow-renewable -kadmin> get me - Principal: me@@MY.REALM -[...] - Attributes: requires-pre-auth -@end smallexample - -@subsection Absolute times - -The format for absolute times are any of the following: - -@smallexample -never -now -YYYY-mm-dd -YYYY-mm-dd HH:MM:SS -@end smallexample - - -@subsection Relative times - -The format for relative times are any of the following combined: - -@smallexample -N year -M month -O day -P hour -Q minute -R second -@end smallexample - -@c Describe more of kadmin commands here... - -@node Checking the setup, keytabs, Modifying the database, Setting up a realm -@section Checking the setup - -There are two tools that can check the consistency of the Kerberos -configuration file and the Kerberos database. - -The Kerberos configuration file is checked using -@command{verify_krb5_conf}. The tool checks for common errors, but -commonly there are several uncommon configuration entries that are -never added to the tool and thus generates ``unknown entry'' warnings. -This is usually nothing to worry about. - -The database check is built into the kadmin tool. It will check for -common configuration error that will cause problems later. Common -check are for existence and flags on important principals. The -database check by run by the following command : - -@example -kadmin check REALM.EXAMPLE.ORG -@end example - -@node keytabs, Serving Kerberos 4/524/kaserver, Checking the setup, Setting up a realm -@section keytabs - -To extract a service ticket from the database and put it in a keytab, you -need to first create the principal in the database with @samp{ank} -(using the @kbd{--random-key} flag to get a random key) and then -extract it with @samp{ext_keytab}. - -@example -kadmin> add --random-key host/my.host.name -Max ticket life [unlimited]: -Max renewable life [unlimited]: -Attributes []: -kadmin> ext host/my.host.name -kadmin> exit -# ktutil list -Version Type Principal - 1 des-cbc-md5 host/my.host.name@@MY.REALM - 1 des-cbc-md4 host/my.host.name@@MY.REALM - 1 des-cbc-crc host/my.host.name@@MY.REALM - 1 des3-cbc-sha1 host/my.host.name@@MY.REALM -@end example - -@node Serving Kerberos 4/524/kaserver, Remote administration, keytabs, Setting up a realm -@section Serving Kerberos 4/524/kaserver - -Heimdal can be configured to support 524, Kerberos 4 or kaserver. All -these services are turned off by default. Kerberos 4 is always -supported by the KDC, but the Kerberos 4 client support also depends -on Kerberos 4 support having been included at compile-time, using -@kbd{--with-krb4=dir}. - -@subsection 524 - -524 is a service that allows the KDC to convert Kerberos 5 tickets to -Kerberos 4 tickets for backward compatibility. See also Using 2b -tokens with AFS in @xref{Things in search for a better place}. - -524 can be turned on by adding this to the configuration file - -@example -[kdc] - enable-524 = yes -@end example - -@subsection Kerberos 4 - -Kerberos 4 is the predecessor to to Kerberos 5. It only supports -single DES@. You should only enable Kerberos 4 support if you have -needs for compatibility with an installed base of Kerberos 4 -clients/servers. - -Kerberos 4 can be turned on by adding this to the configuration file - -@example -[kdc] - enable-kerberos4 = yes -@end example - -@subsection kaserver - -Kaserver is a Kerberos 4 that is used in AFS@. The protocol has some -extra features over plain Kerberos 4, but like Kerberos 4, only uses -single DES@. - -You should only enable Kaserver support if you have needs for -compatibility with an installed base of AFS machines. - -Kaserver can be turned on by adding this to the configuration file - -@example -[kdc] - enable-kaserver = yes -@end example - -@node Remote administration, Password changing, Serving Kerberos 4/524/kaserver, Setting up a realm -@section Remote administration - -The administration server, @command{kadmind}, can be started by -@command{inetd} (which isn't recommended) or run as a normal daemon. If you -want to start it from @command{inetd} you should add a line similar to the -one below to your @file{/etc/inetd.conf}. - -@example -kerberos-adm stream tcp nowait root /usr/heimdal/libexec/kadmind kadmind -@end example - -You might need to add @samp{kerberos-adm} to your @file{/etc/services} -as @samp{749/tcp}. - -Access to the administration server is controlled by an ACL file, -(default @file{/var/heimdal/kadmind.acl}.) The file has the following -syntax: -@smallexample -principal [priv1,priv2,...] [glob-pattern] -@end smallexample - -The matching is from top to bottom for matching principals (and if given, -glob-pattern). When there is a match, the access rights of that line are -applied. - -The privileges you can assign to a principal are: @samp{add}, -@samp{change-password} (or @samp{cpw} for short), @samp{delete}, -@samp{get}, @samp{list}, and @samp{modify}, or the special privilege -@samp{all}. All of these roughly correspond to the different commands -in @command{kadmin}. - -If a @var{glob-pattern} is given on a line, it restricts the access -rights for the principal to only apply for subjects that match the -pattern. The patterns are of the same type as those used in shell -globbing, see @url{none,,fnmatch(3)}. - -In the example below @samp{lha/admin} can change every principal in the -database. @samp{jimmy/admin} can only modify principals that belong to -the realm @samp{E.KTH.SE}. @samp{mille/admin} is working at the -help desk, so he should only be able to change the passwords for single -component principals (ordinary users). He will not be able to change any -@samp{/admin} principal. - -@example -lha/admin@@E.KTH.SE all -jimmy/admin@@E.KTH.SE all *@@E.KTH.SE -jimmy/admin@@E.KTH.SE all */*@@E.KTH.SE -mille/admin@@E.KTH.SE change-password *@@E.KTH.SE -@end example - -@node Password changing, Testing clients and servers, Remote administration, Setting up a realm -@section Password changing - -To allow users to change their passwords, you should run @command{kpasswdd}. -It is not run from @command{inetd}. - -You might need to add @samp{kpasswd} to your @file{/etc/services} as -@samp{464/udp}. - -@subsection Password quality assurance - -It is important that users have good passwords, both to make it harder -to guess them and to avoid off-line attacks (although -pre-authentication provides some defence against off-line attacks). -To ensure that the users choose good passwords, you can enable -password quality controls in @command{kpasswdd} and @command{kadmind}. -The controls themselves are done in a shared library or an external -program that is used by @command{kpasswdd}. To configure in these -controls, add lines similar to the following to your -@file{/etc/krb5.conf}: - -@example -[password_quality] - policies = external-check builtin:minimum-length module:policyname - external_program = /bin/false - policy_libraries = @var{library1.so} @var{library2.so} -@end example - -In @samp{[password_quality]policies} the module name is optional if -the policy name is unique in all modules (members of -@samp{policy_libraries}). - -The built-in polices are - -@itemize @bullet - -@item external-check - -Executes the program specified by @samp{[password_quality]external_program}. - -A number of key/value pairs are passed as input to the program, one per -line, ending with the string @samp{end}. The key/value lines are of -the form -@example -principal: @var{principal} -new-password: @var{password} -@end example -where @var{password} is the password to check for the previous -@var{principal}. - -If the external application approves the password, it should return -@samp{APPROVED} on standard out and exit with exit code 0. If it -doesn't approve the password, an one line error message explaining the -problem should be returned on standard error and the application -should exit with exit code 0. In case of a fatal error, the -application should, if possible, print an error message on standard -error and exit with a non-zero error code. - -@item minimum-length - -The minimum length password quality check reads the configuration file -stanza @samp{[password_quality]min_length} and requires the password -to be at least this length. - -@item character-class - -The character-class password quality check reads the configuration -file stanza @samp{[password_quality]min_classes}. The policy requires -the password to have characters from at least that many character -classes. Default value if not given is 3. - -The four different characters classes are, uppercase, lowercase, -number, special characters. - -@end itemize - -If you want to write your own shared object to check password -policies, see the manual page @manpage{kadm5_pwcheck,3}. - -Code for a password quality checking function that uses the cracklib -library can be found in @file{lib/kadm5/sample_password_check.c} in -the source code distribution. It requires that the cracklib library -be built with the patch available at -@url{ftp://ftp.pdc.kth.se/pub/krb/src/cracklib.patch}. - -A sample policy external program is included in -@file{lib/kadm5/check-cracklib.pl}. - -If no password quality checking function is configured, the only check -performed is that the password is at least six characters long. - -To check the password policy settings, use the command -@command{password-quality} in @command{kadmin} program. The password -verification is only performed locally, on the client. It may be -convenient to set the environment variable @samp{KRB5_CONFIG} to point -to a test version of @file{krb5.conf} while you're testing the -@samp{[password_quality]} stanza that way. - -@node Testing clients and servers, Slave Servers, Password changing, Setting up a realm -@section Testing clients and servers - -Now you should be able to run all the clients and servers. Refer to the -appropriate man pages for information on how to use them. - -@node Slave Servers, Incremental propagation, Testing clients and servers, Setting up a realm -@section Slave servers, Incremental propagation, Testing clients and servers, Setting up a realm - -It is desirable to have at least one backup (slave) server in case the -master server fails. It is possible to have any number of such slave -servers but more than three usually doesn't buy much more redundancy. - -All Kerberos servers for a realm must have the same database so that -they present the same service to the users. The -@pindex hprop -@command{hprop} program, running on the master, will propagate the database -to the slaves, running -@pindex hpropd -@command{hpropd} processes. - -Every slave needs a database directory, the master key (if it was used -for the database) and a keytab with the principal -@samp{hprop/@var{hostname}}. Add the principal with the -@pindex ktutil -@command{ktutil} command and start -@pindex hpropd -@command{hpropd}, as follows: - -@example -slave# ktutil get -p foo/admin hprop/`hostname` -slave# mkdir /var/heimdal -slave# hpropd -@end example - -The master will use the principal @samp{kadmin/hprop} to authenticate to -the slaves. This principal should be added when running @kbd{kadmin -l -init} but if you do not have it in your database for whatever reason, -please add it with @kbd{kadmin -l add}. - -Then run -@pindex hprop -@code{hprop} on the master: - -@example -master# hprop slave -@end example - -This was just an hands-on example to make sure that everything was -working properly. Doing it manually is of course the wrong way, and to -automate this you will want to start -@pindex hpropd -@command{hpropd} from @command{inetd} on the slave(s) and regularly run -@pindex hprop -@command{hprop} on the master to regularly propagate the database. -Starting the propagation once an hour from @command{cron} is probably a -good idea. - -@node Incremental propagation, Encryption types and salting, Slave Servers, Setting up a realm -@section Incremental propagation - -There is also a newer, and still somewhat experimental, mechanism for -doing incremental propagation in Heimdal. Instead of sending the whole -database regularly, it sends the changes as they happen on the master to -the slaves. The master keeps track of all the changes by assigning a -version number to every change to the database. The slaves know which -was the latest version they saw and in this way it can be determined if -they are in sync or not. A log of all the changes is kept on the master, -and when a slave is at an older version than the oldest one in the -log, the whole database has to be sent. - -Protocol-wise, all the slaves connect to the master and as a greeting -tell it the latest version that they have (@samp{IHAVE} message). The -master then responds by sending all the changes between that version and -the current version at the master (a series of @samp{FORYOU} messages) -or the whole database in a @samp{TELLYOUEVERYTHING} message. There is -also a keep-alive protocol that makes sure all slaves are up and running. - -@subsection Configuring incremental propagation - -The program that runs on the master is @command{ipropd-master} and all -clients run @command{ipropd-slave}. - -Create the file @file{/var/heimdal/slaves} on the master containing all -the slaves that the database should be propagated to. Each line contains -the full name of the principal (for example -@samp{iprop/hemligare.foo.se@@FOO.SE}). - -You should already have @samp{iprop/tcp} defined as 2121, in your -@file{/etc/services}. Otherwise, or if you need to use a different port -for some peculiar reason, you can use the @kbd{--port} option. This is -useful when you have multiple realms to distribute from one server. - -Then you need to create those principals that you added in the -configuration file. Create one @samp{iprop/hostname} for the master and -for every slave. - - -@example -master# /usr/heimdal/sbin/ktutil get iprop/`hostname` -@end example - -The next step is to start the @command{ipropd-master} process on the master -server. The @command{ipropd-master} listens on the UNIX domain socket -@file{/var/heimdal/signal} to know when changes have been made to the -database so they can be propagated to the slaves. There is also a -safety feature of testing the version number regularly (every 30 -seconds) to see if it has been modified by some means that do not raise -this signal. Then, start @command{ipropd-slave} on all the slaves: - -@example -master# /usr/heimdal/libexec/ipropd-master & -slave# /usr/heimdal/libexec/ipropd-slave master & -@end example - -To manage the iprop log file you should use the @command{iprop-log} -command. With it you can dump, truncate and replay the logfile. - -@node Encryption types and salting, Cross realm, Incremental propagation, Setting up a realm -@section Encryption types and salting -@cindex Salting -@cindex Encryption types - -The encryption types that the KDC is going to assign by default is -possible to change. Since the keys used for user authentication is -salted the encryption types are described together with the salt -strings. - -Salting is used to make it harder to pre-calculate all possible -keys. Using a salt increases the search space to make it almost -impossible to pre-calculate all keys. Salting is the process of mixing a -public string (the salt) with the password, then sending it through an -encryption type specific string-to-key function that will output the -fixed size encryption key. - -In Kerberos 5 the salt is determined by the encryption type, except in -some special cases. - -In @code{des} there is the Kerberos 4 salt -(none at all) or the afs-salt (using the cell (realm in -AFS lingo)). - -In @code{arcfour} (the encryption type that Microsoft Windows 2000 uses) -there is no salt. This is to be compatible with NTLM keys in Windows -NT 4. - -@code{[kadmin]default_keys} in @file{krb5.conf} controls -what salting to use. - -The syntax of @code{[kadmin]default_keys} is -@samp{[etype:]salt-type[:salt-string]}. @samp{etype} is the encryption -type (des-cbc-crc, arcfour-hmac-md5, aes256-cts-hmac-sha1-96), -@code{salt-type} is the type of salt (pw-salt or afs3-salt), and the -salt-string is the string that will be used as salt (remember that if -the salt is appended/prepended, the empty salt "" is the same thing as -no salt at all). - -Common types of salting include - -@itemize @bullet -@item @code{v4} (or @code{des:pw-salt:}) - -The Kerberos 4 salting is using no salt at all. Reason there is colon -at the end of the salt string is that it makes the salt the empty -string (same as no salt). - -@item @code{v5} (or @code{pw-salt}) - -@code{pw-salt} uses the default salt for each encryption type is -specified for. If the encryption type @samp{etype} isn't given, all -default encryption will be used. - -@item @code{afs3-salt} - -@code{afs3-salt} is the salt that is used with Transarc kaserver. Its -the cell name appended to the password. - -@end itemize - -@node Cross realm, Transit policy, Encryption types and salting, Setting up a realm -@section Cross realm -@cindex Cross realm - -Suppose you reside in the realm @samp{MY.REALM}, how do you -authenticate to a server in @samp{OTHER.REALM}? Having valid tickets in -@samp{MY.REALM} allows you to communicate with Kerberised services in that -realm. However, the computer in the other realm does not have a secret -key shared with the Kerberos server in your realm. - -It is possible to share keys between two realms that trust each -other. When a client program, such as @command{telnet} or @command{ssh}, -finds that the other computer is in a different realm, it will try to -get a ticket granting ticket for that other realm, but from the local -Kerberos server. With that ticket granting ticket, it will then obtain -service tickets from the Kerberos server in the other realm. - -For a two way trust between @samp{MY.REALM} and @samp{OTHER.REALM} -add the following principals to each realm. The principals should be -@samp{krbtgt/OTHER.REALM@@MY.REALM} and -@samp{krbtgt/MY.REALM@@OTHER.REALM} in @samp{MY.REALM}, and -@samp{krbtgt/MY.REALM@@OTHER.REALM} and -@samp{krbtgt/OTHER.REALM@@MY.REALM}in @samp{OTHER.REALM}. - -In Kerberos 5 the trust can be configured to be one way. So that -users from @samp{MY.REALM} can authenticate to services in -@samp{OTHER.REALM}, but not the opposite. In the example above, the -@samp{krbtgt/MY.REALM@@OTHER.REALM} then should be removed. - -The two principals must have the same key, key version number, and the -same set of encryption types. Remember to transfer the two keys in a -safe manner. - -@example -vr$ klist -Credentials cache: FILE:/tmp/krb5cc_913.console - Principal: lha@@E.KTH.SE - - Issued Expires Principal -May 3 13:55:52 May 3 23:55:54 krbtgt/E.KTH.SE@@E.KTH.SE - -vr$ telnet -l lha hummel.it.su.se -Trying 2001:6b0:5:1095:250:fcff:fe24:dbf... -Connected to hummel.it.su.se. -Escape character is '^]'. -Waiting for encryption to be negotiated... -[ Trying mutual KERBEROS5 (host/hummel.it.su.se@@SU.SE)... ] -[ Kerberos V5 accepts you as ``lha@@E.KTH.SE'' ] -Encryption negotiated. -Last login: Sat May 3 14:11:47 from vr.l.nxs.se -hummel$ exit - -vr$ klist -Credentials cache: FILE:/tmp/krb5cc_913.console - Principal: lha@@E.KTH.SE - - Issued Expires Principal -May 3 13:55:52 May 3 23:55:54 krbtgt/E.KTH.SE@@E.KTH.SE -May 3 13:55:56 May 3 23:55:54 krbtgt/SU.SE@@E.KTH.SE -May 3 14:10:54 May 3 23:55:54 host/hummel.it.su.se@@SU.SE - -@end example - -@node Transit policy, Setting up DNS, Cross realm, Setting up a realm -@section Transit policy -@cindex Transit policy - -If you want to use cross realm authentication through an intermediate -realm, it must be explicitly allowed by either the KDCs or the server -receiving the request. This is done in @file{krb5.conf} in the -@code{[capaths]} section. - -When the ticket transits through a realm to another realm, the -destination realm adds its peer to the "transited-realms" field in the -ticket. The field is unordered, since there is no way to know if -know if one of the transited-realms changed the order of the list. - -The syntax for @code{[capaths]} section: - -@example -[capaths] - CLIENT-REALM = @{ - SERVER-REALM = PERMITTED-CROSS-REALMS ... - @} -@end example - -The realm @code{STACKEN.KTH.SE} allows clients from @code{SU.SE} and -@code{DSV.SU.SE} to cross it. Since @code{STACKEN.KTH.SE} only has -direct cross realm setup with @code{KTH.SE}, and @code{DSV.SU.SE} only -has direct cross realm setup with @code{SU.SE} they need to use both -@code{SU.SE} and @code{KTH.SE} as transit realms. - -@example -[capaths] - SU.SE = @{ - STACKEN.KTH.SE = KTH.SE - @} - DSV.SU.SE = @{ - STACKEN.KTH.SE = SU.SE KTH.SE - @} - -@end example - -The order of the @code{PERMITTED-CROSS-REALMS} is not important when -doing transit cross realm verification. - -However, the order is important when the @code{[capaths]} section is used -to figure out the intermediate realm to go to when doing multi-realm -transit. When figuring out the next realm, the first realm of the list -of @code{PERMITTED-CROSS-REALMS} is chosen. This is done in both the -client kerberos library and the KDC. - -@c To test the cross realm configuration, use: -@c kmumble transit-check client server transit-realms ... - -@node Setting up DNS, Using LDAP to store the database, Transit policy, Setting up a realm -@section Setting up DNS -@cindex Setting up DNS - -@subsection Using DNS to find KDC - -If there is information about where to find the KDC or kadmind for a -realm in the @file{krb5.conf} for a realm, that information will be -preferred, and DNS will not be queried. - -Heimdal will try to use DNS to find the KDCs for a realm. First it -will try to find a @code{SRV} resource record (RR) for the realm. If no -SRV RRs are found, it will fall back to looking for an @code{A} RR for -a machine named kerberos.REALM, and then kerberos-1.REALM, etc - -Adding this information to DNS minimises the client configuration (in -the common case, resulting in no configuration needed) and allows the -system administrator to change the number of KDCs and on what machines -they are running without caring about clients. - -The downside of using DNS is that the client might be fooled to use the -wrong server if someone fakes DNS replies/data, but storing the IP -addresses of the KDC on all the clients makes it very hard to change -the infrastructure. - -An example of the configuration for the realm @code{EXAMPLE.COM}: - -@example - -$ORIGIN example.com. -_kerberos._tcp SRV 10 1 88 kerberos.example.com. -_kerberos._udp SRV 10 1 88 kerberos.example.com. -_kerberos._tcp SRV 10 1 88 kerberos-1.example.com. -_kerberos._udp SRV 10 1 88 kerberos-1.example.com. -_kpasswd._udp SRV 10 1 464 kerberos.example.com. -_kerberos-adm._tcp SRV 10 1 749 kerberos.example.com. - -@end example - -More information about DNS SRV resource records can be found in -RFC-2782 (A DNS RR for specifying the location of services (DNS SRV)). - -@subsection Using DNS to map hostname to Kerberos realm - -Heimdal also supports a way to lookup a realm from a hostname. This to -minimise configuration needed on clients. Using this has the drawback -that clients can be redirected by an attacker to realms within the -same cross realm trust and made to believe they are talking to the -right server (since Kerberos authentication will succeed). - -An example configuration that informs clients that for the realms -it.example.com and srv.example.com, they should use the realm -EXAMPLE.COM: - -@example - -$ORIGIN example.com. -_kerberos.it TXT "EXAMPLE.COM" -_kerberos.srv TXT "EXAMPLE.COM" - -@end example - -@node Using LDAP to store the database, Providing Kerberos credentials to servers and programs, Setting up DNS, Setting up a realm -@section Using LDAP to store the database -@cindex Using the LDAP backend - -This document describes how to install the LDAP backend for -Heimdal. Note that before attempting to configure such an -installation, you should be aware of the implications of storing -private information (such as users' keys) in a directory service -primarily designed for public information. Nonetheless, with a -suitable authorisation policy, it is possible to set this up in a -secure fashion. A knowledge of LDAP, Kerberos, and C is necessary to -install this backend. The HDB schema was devised by Leif Johansson. - -Requirements: - -@itemize @bullet - -@item -A current release of Heimdal, configured with -@code{--with-openldap=/usr/local} (adjust according to where you have -installed OpenLDAP). - -You can verify that you manage to configure LDAP support by running -@file{kdc --builtin-hdb}, and checking that @samp{ldap:} is one entry -in the list. - -Its also possible to configure the ldap backend as a shared module, -see option --hdb-openldap-module to configure. - -@item -OpenLDAP 2.0.x. Configure OpenLDAP with @kbd{--enable-local} to enable the -local transport. (A patch to support SASL EXTERNAL authentication is -necessary in order to use OpenLDAP 2.1.x.) - -@item -Add the hdb schema to the LDAP server, its included in the source-tree -in @file{lib/hdb/hdb.schema}. Example from slapd.conf: - -@example -include /usr/local/etc/openldap/schema/hdb.schema -@end example - -@item -Configure the LDAP server ACLs to accept writes from clients over the -local transport. For example: - -@example -access to * - by dn.exact="uid=heimdal,dc=services,dc=example,dc=com" write - ... - -sasl-regexp "uidNumber=0\\\+gidNumber=.*,cn=peercred,cn=external,cn=auth" - "uid=heimdal,dc=services,dc=example,dc=com" - -@end example - -The sasl-regexp is for mapping between the SASL/EXTERNAL and a user in -a tree. The user that the key is mapped to should be have a -krb5Principal aux object with krb5PrincipalName set so that the -``creator'' and ``modifier'' is right in @file{kadmin}. - -Another option is to create an admins group and add the dn to that -group. - -Since Heimdal talks to the LDAP server over a UNIX domain socket, and -uses external sasl authentication, its not possible to require -security layer quality (ssf in cyrus-sasl lingo). So that requirement -has to be turned off in OpenLDAP @command{slapd} configuration file -@file{slapd.conf}. - -@example -sasl-secprops minssf=0 -@end example - -@item - -Start @command{slapd} with the local listener (as well as the default TCP/IP -listener on port 389) as follows: - -@example - slapd -h "ldapi:/// ldap:///" -@end example - -Note: These is a bug in @command{slapd} where it appears to corrupt the krb5Key -binary attribute on shutdown. This may be related to our use of the V3 -schema definition syntax instead of the old UMich-style, V2 syntax. - -@item -You should specify the distinguished name under which your -principals will be stored in @file{krb5.conf}. Also you need to -enter the path to the kadmin acl file: - - -@example -[kdc] - database = @{ - dbname = ldap:ou=KerberosPrincipals,dc=example,dc=com - hdb-ldap-structural-object = inetOrgPerson - acl_file = /path/to/kadmind.acl - mkey_file = /path/to/mkey - @} -@end example - -@samp{mkey_file} can be excluded if you feel that you trust your ldap -directory to have the raw keys inside it. The -hdb-ldap-structural-object is not necessary if you do not need Samba -comatibility. - - - -@item -Once you have built Heimdal and started the LDAP server, run kadmin -(as usual) to initialise the database. Note that the instructions for -stashing a master key are as per any Heimdal installation. - -@example -kdc# kadmin -l -kadmin> init EXAMPLE.COM -Realm max ticket life [unlimited]: -Realm max renewable ticket life [unlimited]: -kadmin> ank lukeh -Max ticket life [1 day]: -Max renewable life [1 week]: -Principal expiration time [never]: -Password expiration time [never]: -Attributes []: -lukeh@@EXAMPLE.COM's Password: -Verifying password - lukeh@@EXAMPLE.COM's Password: -kadmin> exit -@end example - -Verify that the principal database has indeed been stored in the -directory with the following command: - -@example -kdc# ldapsearch -L -h localhost -D cn=manager \ - -w secret -b ou=KerberosPrincipals,dc=example,dc=com \ - 'objectclass=krb5KDCEntry' -@end example - -@item -Now consider adding indexes to the database to speed up the access, at -least theses should be added to slapd.conf. - -@example -index objectClass eq -index cn eq,sub,pres -index uid eq,sub,pres -index displayName eq,sub,pres -index krb5PrincipalName eq -@end example - -@end itemize - -@subsection Troubleshooting guide - -@url{https://sec.miljovern.no/bin/view/Info/TroubleshootingGuide} - - -@subsection Using Samba LDAP password database -@cindex Samba - -@c @node Using Samba LDAP password database, Providing Kerberos credentials to servers and programs, Using LDAP to store the database, Setting up a realm -@c @section Using Samba LDAP password database - -The Samba domain and the Kerberos realm can have different names since -arcfour's string to key functions principal/realm independent. So now -will be your first and only chance name your Kerberos realm without -needing to deal with old configuration files. - -First, you should set up Samba and get that working with LDAP backend. - -Now you can proceed as in @xref{Using LDAP to store the database}. -Heimdal will pick up the Samba LDAP entries if they are in the same -search space as the Kerberos entries. - -@node Providing Kerberos credentials to servers and programs, Setting up PK-INIT, Using LDAP to store the database, Setting up a realm -@section Providing Kerberos credentials to servers and programs - -Some services require Kerberos credentials when they start to make -connections to other services or need to use them when they have started. - -The easiest way to get tickets for a service is to store the key in a -keytab. Both ktutil get and kadmin ext can be used to get a -keytab. ktutil get is better in that way it changes the key/password -for the user. This is also the problem with ktutil. If ktutil is used -for the same service principal on several hosts, they keytab will only -be useful on the last host. In that case, run the extract command on -one host and then securely copy the keytab around to all other hosts -that need it. - -@example -host# ktutil -k /etc/krb5-service.keytab \ - get -p lha/admin@@EXAMPLE.ORG service-principal@@EXAMPLE.ORG -lha/admin@@EXAMPLE.ORG's Password: -@end example - -To get a Kerberos credential file for the service, use kinit in the ---keytab mode. This will not ask for a password but instead fetch the -key from the keytab. - -@example -service@@host$ kinit --cache=/var/run/service_krb5_cache \ - --keytab=/etc/krb5-service.keytab \ - service-principal@@EXAMPLE.ORG -@end example - -Long running services might need credentials longer then the -expiration time of the tickets. kinit can run in a mode that refreshes -the tickets before they expire. This is useful for services that write -into AFS and other distributed file systems using Kerberos. To run the -long running script, just append the program and arguments (if any) -after the principal. kinit will stop refreshing credentials and remove -the credentials when the script-to-start-service exits. - -@example -service@@host$ kinit --cache=/var/run/service_krb5_cache \ - --keytab=/etc/krb5-service.keytab \ - service-principal@@EXAMPLE.ORG \ - script-to-start-service argument1 argument2 -@end example - - -@node Setting up PK-INIT, , Providing Kerberos credentials to servers and programs, Setting up a realm -@section Setting up PK-INIT - -PK-INIT is levering the existing PKI infrastructure to use -certificates to get the initial ticket, that is usually the krbtgt. - -To use PK-INIT you must first have a PKI, so if you don't have one, -now its time to create it. Note that you should read the whole chapter -of the document to see the requirements on the CA sortware. - -There needs to exist a mapping between the certificate and what -principals that certificate is allowed to use. There are several ways -to do this. The administrator can use a configuration file, storing -the principal in the SubjectAltName extension of the certificate, or store the -mapping in the principals entry in the kerberos database. - -@section Certificates - -This section documents the requirements on the KDC and client -certificates and the format used in the id-pkinit-san OtherName -extention. - -@subsection KDC certificate - -The certificate for the KDC have serveral requirements. - -First the certificate should have an Extended Key Usage (EKU) -id-pkkdcekuoid (1.3.6.1.5.2.3.5) set. Second there must be a -subjectAltName otherName using oid id-pkinit-san (1.3.6.1.5.2.2) in -the type field and a DER encoded KRB5PrincipalName that matches the -name of the TGS of the target realm. - -Both of these two requirements are not required by the standard to be -checked by the client if it have external information what the -certificate the KDC is supposed to be used. So its in the interst of -minimum amount of configuration on the clients they should be included. - -Remember that if the client would accept any certificate as the KDC's -certificate, the client could be fooled into trusting something that -isn't a KDC and thus expose the user to giving away information (like -password or other private information) that it is supposed to secret. - -Also, if the certificate has a nameConstraints extention with a -Generalname with dNSName or iPAdress it must match the hostname or -adress of the KDC. - -@subsection Client certificate - -The client certificate may need to have a EKU id-pkekuoid -(1.3.6.1.5.2.3.4) set depending on the certifiate on the KDC. - -It possible to store the principal (if allowed by the KDC) in the -certificate and thus delegate responsibility to do the mapping between -certificates and principals to the CA. - -@subsubsection Using KRB5PrincipalName in id-pkinit-san - -OtherName extention in the GeneralName is used to do the -mapping between certifiate and principal in the certifiate or storing -the krbtgt principal in the KDC certificate. - -The principal is stored in a SubjectAltName in the certificate using -OtherName. The oid in the type is id-pkinit-san. - -@example -id-pkinit-san OBJECT IDENTIFIER ::= @{ iso (1) org (3) dod (6) -internet (1) security (5) kerberosv5 (2) 2 @} -@end example - -The data part of the OtherName is filled with the following DER -encoded ASN.1 structure: - -@example -KRB5PrincipalName ::= SEQUENCE @{ - realm [0] Realm, - principalName [1] PrincipalName -@} -@end example - -where Realm and PrincipalName is defined by the Kerberos ASN.1 specification. - -@section Naming certificate using hx509 - -hx509 is the X.509 software used in Heimdal to handle -certificates. hx509 uses different syntaxes to specify the different -formats the certificates are stored in and what formats they exist in. - -There are several formats that can be used, PEM, embedded into PKCS12 -files, embedded into PKCS11 devices and raw DER encoded certificates. -Below is a list of types to use. - - -@table @asis - -@item DIR: - -DIR is reading all certificates in a directory that is DER or PEM -formatted. - -The main feature of DIR is that the directory is read on demand when -iterating over certificates, that way applictions can for some cases -avoid to store all certificates in memory. It's very useful for tests -that iterate over larger amount of certificates. - -Syntax is: - -@example -DIR:/path/to/der/files -@end example - -@item FILE: - -FILE: is used to have the lib pick up a certificate chain and a -private key. The file can be either a PEM (openssl) file or a raw DER -encoded certificate. If it's a PEM file it can contain several keys and -certificates and the code will try to match the private key and -certificate together. - -Its useful to have one PEM file that contains all the trust anchors. - -Syntax is: - -@example -FILE:certificate.pem,private-key.key,other-cert.pem,.... -@end example - -@item PKCS11: - -PKCS11: is used to handle smartcards via PKCS11 drivers, for example -soft-token, opensc, or muscle. The default is to use all slots on the -device/token. - -Syntax is: - -@example -PKCS11:shared-object.so -@end example - -@item PKCS12: - -PKCS12: is used to handle PKCS12 files. PKCS12 files commonly have the -extension pfx or p12. - -Syntax is: - -@example -PKCS12:/path/to/file.pfx -@end example - -@end table - -@section Configure the Kerberos software - -First configure the client's trust anchors and what parameters to -verify, see subsection below how to do that. Now you can use kinit to -get yourself tickets. One example how that can look like is: - -@example -$ kinit -C FILE:$HOME/.certs/lha.crt,$HOME/.certs/lha.key lha@@EXAMPLE.ORG -Enter your private key passphrase: -: lha@@nutcracker ; klist -Credentials cache: FILE:/tmp/krb5cc_19100a - Principal: lha@@EXAMPLE.ORG - - Issued Expires Principal -Apr 20 02:08:08 Apr 20 12:08:08 krbtgt/EXAMPLE.ORG@@EXAMPLE.ORG -@end example - -Using PKCS11 it can look like this instead: - -@example -$ kinit -C PKCS11:/tmp/pkcs11/lib/soft-pkcs11.so lha@@EXAMPLE.ORG -PIN code for SoftToken (slot): -$ klist -Credentials cache: API:4 - Principal: lha@@EXAMPLE.ORG - - Issued Expires Principal -Mar 26 23:40:10 Mar 27 09:40:10 krbtgt/EXAMPLE.ORG@@EXAMPLE.ORG -@end example - - -Write about the kdc. - -@section Configure the client - -@example -[appdefaults] - pkinit_anchors = FILE:/path/to/trust-anchors.pem - -[realms] - EXAMPLE.COM = @{ - pkinit_require_eku = true - pkinit_require_krbtgt_otherName = true - pkinit_win2k = no - pkinit_win2k_require_binding = yes - @} - -@end example - -@section Configure the KDC - -@example -[kdc] - enable-pkinit = yes - pkinit_identity = FILE:/secure/kdc.crt,/secure/kdc.key - pkinit_anchors = FILE:/path/to/trust-anchors.pem - pkinit_pool = PKCS12:/path/to/useful-intermediate-certs.pfx - pkinit_pool = FILE:/path/to/other-useful-intermediate-certs.pem - pkinit_allow_proxy_certificate = false - pkinit_win2k_require_binding = yes -@end example - -@subsection Using pki-mapping file - -Note that the file name is space sensitive. - -@example -# cat /var/heimdal/pki-mapping -# comments starts with # -lha@@EXAMPLE.ORG:C=SE,O=Stockholm universitet,CN=Love,UID=lha -lha@@EXAMPLE.ORG:CN=Love,UID=lha -@end example - -@subsection Using the Kerberos database - -@section Use hxtool to create certificates - -@subsection Generate certificates - -First you need to generate a CA certificate, change the --subject to -something appropriate, the CA certificate will be valid for 10 years. - -You need to change --subject in the command below. - -@example -hxtool issue-certificate \ - --self-signed \ - --issue-ca \ - --generate-key=rsa \ - --subject="CN=CA,DC=test,DC=h5l,DC=se" \ - --lifetime=10years \ - --certificate="FILE:ca.pem" -@end example - -The KDC needs to have a certificate, so generate a certificate of the -type ``pkinit-kdc'' and set the PK-INIT specifial SubjectAltName to the -name of the krbtgt of the realm. - -You need to change --subject and --pk-init-principal in the command below. - -@example -hxtool issue-certificate \ - --ca-certificate=FILE:ca.pem \ - --generate-key=rsa \ - --type="pkinit-kdc" \ - --pk-init-principal="krbtgt/TEST.H5L.SE@@TEST.H5L.SE" \ - --subject="uid=kdc,DC=test,DC=h5l,DC=se" \ - --certificate="FILE:kdc.pem" -@end example - -The users also needs to have a certificate, so generate a certificate -of the type ``pkinit-client''. The client doesn't need to have the PK-INIT -SubjectAltName set, you can have the Subject DN in the ACL file -(pki-mapping) instead. - -You need to change --subject and --pk-init-principal in the command below. - -@example -hxtool issue-certificate \ - --ca-certificate=FILE:ca.pem \ - --generate-key=rsa \ - --type="pkinit-client" \ - --pk-init-principal="lha@@TEST.H5L.SE" \ - --subject="uid=lha,DC=test,DC=h5l,DC=se" \ - --certificate="FILE:user.pem" -@end example - -@subsection Validate the certificate - -hxtool also contains a tool that will validate certificates according to -rules from the PKIX document. These checks are not complete, but a good test -to check if you got all of the basic bits right in your certificates. - -@example -hxtool validate FILE:user.pem -@end example - -@section Use OpenSSL to create certificates - -This section tries to give the CA owners hints how to create -certificates using OpenSSL (or CA software based on OpenSSL). - -@subsection Using OpenSSL to create certificates with krb5PrincipalName - -To make OpenSSL create certificates with krb5PrincipalName use -@file{openssl.cnf} as described below. To see a complete example of -creating client and KDC certificates, see the test-data generation -script @file{lib/hx509/data/gen-req.sh} in the source-tree. The -certicates it creates are used to test the PK-INIT functionality in -@file{tests/kdc/check-kdc.in}. - -To use this example you have to use OpenSSL 0.9.8a or later. - -@example - -[user_certificate] -subjectAltName=otherName:1.3.6.1.5.2.2;SEQUENCE:princ_name - -[princ_name] -realm = EXP:0, GeneralString:MY.REALM -principal_name = EXP:1, SEQUENCE:principal_seq - -[principal_seq] -name_type = EXP:0, INTEGER:1 -name_string = EXP:1, SEQUENCE:principals - -[principals] -princ1 = GeneralString:userid - -@end example - -Command usage - -@example -openssl x509 -extensions user_certificate -openssl ca -extensions user_certificate -@end example - - -@c --- ms certificate -@c -@c [ new_oids ] -@c msCertificateTemplateName = 1.3.6.1.4.1.311.20.2 -@c -@c -@c [ req_smartcard ] -@c keyUsage = digitalSignature, keyEncipherment -@c extendedKeyUsage = msSmartcardLogin, clientAuth -@c msCertificateTemplateName = ASN1:BMP:SmartcardLogon -@c subjectAltName = otherName:msUPN;UTF8:lukeh@dsg.padl.com -@c #subjectAltName = email:copy - - -@section Using PK-INIT with Windows - -@subsection Client configration - -Clients using a Windows KDC with PK-INIT need configuration since -windows uses pre-standard format and this can't be autodetected. - -The pkinit_win2k_require_binding option requires the reply for the KDC -to be of the new, secure, type that binds the request to reply. Before -clients should fake the reply from the KDC. To use this option you -have to apply a fix from Microsoft. - -@example -[realms] - MY.MS.REALM = @{ - pkinit_win2k = yes - pkinit_win2k_require_binding = no - @} -@end example - -@subsection Certificates - -The client certificates need to have the extended keyusage ``Microsoft -Smartcardlogin'' (openssl have the oid shortname msSmartcardLogin). - -See Microsoft Knowledge Base Article - 281245 ``Guidelines for Enabling -Smart Card Logon with Third-Party Certification Authorities'' for a -more extensive description of how set setup an external CA to it -includes all information that will make a Windows KDC happy. - -@subsection Configure Windows 2000 CA - -To enable Microsoft Smartcardlogin> for certificates in your Windows -2000 CA, you want to look at Microsoft Knowledge Base Article - -313274 ``HOW TO: Configure a Certification Authority to Issue -Smart Card Certificates in Windows''. diff -U 3 -H -d -r -N -x Makefile.in -x 'config.h.in*' -x 'output*' -x requests -x 'traces*' -x '*.loT' -x aclocal.m4 -x configure -- heimdal-1.0.1/doc/setup.texi.in heimdal-1.0.1.work/doc/setup.texi.in --- heimdal-1.0.1/doc/setup.texi.in 1970-01-01 02:00:00.000000000 +0200 +++ heimdal-1.0.1.work/doc/setup.texi.in 2007-12-05 23:00:39.000000000 +0200 @@ -0,0 +1,1455 @@ +@c $Id: setup.texi 21298 2007-06-25 14:50:03Z lha $ + +@node Setting up a realm, Applications, Building and Installing, Top + +@chapter Setting up a realm + +A +@cindex realm +realm is an administrative domain. The name of a Kerberos realm is +usually the Internet domain name in uppercase. Call your realm the same +as your Internet domain name if you do not have strong reasons for not +doing so. It will make life easier for you and everyone else. + +@menu +* Configuration file:: +* Creating the database:: +* Modifying the database:: +* Checking the setup:: +* keytabs:: +* Serving Kerberos 4/524/kaserver:: +* Remote administration:: +* Password changing:: +* Testing clients and servers:: +* Slave Servers:: +* Incremental propagation:: +* Encryption types and salting:: +* Cross realm:: +* Transit policy:: +* Setting up DNS:: +* Using LDAP to store the database:: +* Providing Kerberos credentials to servers and programs:: +* Setting up PK-INIT:: +@end menu + +@node Configuration file, Creating the database, Setting up a realm, Setting up a realm +@section Configuration file + +To setup a realm you will first have to create a configuration file: +@file{/etc/krb5.conf}. The @file{krb5.conf} file can contain many +configuration options, some of which are described here. + +There is a sample @file{krb5.conf} supplied with the distribution. + +The configuration file is a hierarchical structure consisting of +sections, each containing a list of bindings (either variable +assignments or subsections). A section starts with +@samp{[@samp{section-name}]}. A binding consists of a left hand side, an equal sign +(@samp{=}) and a right hand side (the left hand side tag must be +separated from the equal sign with some whitespace). Subsections have a +@samp{@{} as the first non-whitespace character after the equal sign. All +other bindings are treated as variable assignments. The value of a +variable extends to the end of the line. + +@example +[section1] + a-subsection = @{ + var = value1 + other-var = value with @{@} + sub-sub-section = @{ + var = 123 + @} + @} + var = some other value +[section2] + var = yet another value +@end example + +In this manual, names of sections and bindings will be given as strings +separated by slashes (@samp{/}). The @samp{other-var} variable will thus +be @samp{section1/a-subsection/other-var}. + +For in-depth information about the contents of the configuration file, refer to +the @file{krb5.conf} manual page. Some of the more important sections +are briefly described here. + +The @samp{libdefaults} section contains a list of library configuration +parameters, such as the default realm and the timeout for KDC +responses. The @samp{realms} section contains information about specific +realms, such as where they hide their KDC@. This section serves the same +purpose as the Kerberos 4 @file{krb.conf} file, but can contain more +information. Finally the @samp{domain_realm} section contains a list of +mappings from domains to realms, equivalent to the Kerberos 4 +@file{krb.realms} file. + +To continue with the realm setup, you will have to create a configuration file, +with contents similar to the following. + +@example +[libdefaults] + default_realm = MY.REALM +[realms] + MY.REALM = @{ + kdc = my.kdc my.slave.kdc + kdc = my.third.kdc + @} +[domain_realm] + .my.domain = MY.REALM + +@end example + +If you use a realm name equal to your domain name, you can omit the +@samp{libdefaults}, and @samp{domain_realm}, sections. If you have a DNS +SRV-record for your realm, or your Kerberos server has DNS CNAME +@samp{kerberos.my.realm}, you can omit the @samp{realms} section too. + +@node Creating the database, Modifying the database, Configuration file, Setting up a realm +@section Creating the database + +The database library will look for the database in the directory +@file{@DBDIR@}, so you should probably create that directory. +Make sure the directory has restrictive permissions. + +@example +# mkdir @DBDIR@ +@end example + +The keys of all the principals are stored in the database. If you +choose to, these can be encrypted with a master key. You do not have to +remember this key (or password), but just to enter it once and it will +be stored in a file (@file{@DBDIR@/m-key}). If you want to have a +master key, run @samp{kstash} to create this master key: + +@example +# kstash +Master key: +Verifying password - Master key: +@end example + +If you want to generate a random master key you can use the +--random-key to kstash. This will make sure you have a good key +on which attackers can't do a dictionary attack. + +If you have a master key, make sure you make a backup of your master +key file; without it backups of the database are of no use. + +To initialise the database use the @command{kadmin} program, with the +@samp{-l} option (to enable local database mode). First issue a +@kbd{init MY.REALM} command. This will create the database and insert +default principals for that realm. You can have more than one realm in +one database, so @samp{init} does not destroy any old database. + +Before creating the database, @samp{init} will ask you some questions +about maximum ticket lifetimes. + +After creating the database you should probably add yourself to it. You +do this with the @samp{add} command. It takes as argument the name of a +principal. The principal should contain a realm, so if you haven't set up +a default realm, you will need to explicitly include the realm. + +@example +# kadmin -l +kadmin> init MY.REALM +Realm max ticket life [unlimited]: +Realm max renewable ticket life [unlimited]: +kadmin> add me +Max ticket life [unlimited]: +Max renewable life [unlimited]: +Attributes []: +Password: +Verifying password - Password: +@end example + +Now start the KDC and try getting a ticket. + +@example +# kdc & +# kinit me +me@@MY.REALMS's Password: +# klist +Credentials cache: /tmp/krb5cc_0 + Principal: me@@MY.REALM + + Issued Expires Principal +Aug 25 07:25:55 Aug 25 17:25:55 krbtgt/MY.REALM@@MY.REALM +@end example + +If you are curious you can use the @samp{dump} command to list all the +entries in the database. It should look something similar to the +following example (note that the entries here are truncated for +typographical reasons): + +@smallexample +kadmin> dump +me@@MY.REALM 1:0:1:0b01d3cb7c293b57:-:0:7:8aec316b9d1629e3baf8 ... +kadmin/admin@@MY.REALM 1:0:1:e5c8a2675b37a443:-:0:7:cb913ebf85 ... +krbtgt/MY.REALM@@MY.REALM 1:0:1:52b53b61c875ce16:-:0:7:c8943be ... +kadmin/changepw@@MY.REALM 1:0:1:f48c8af2b340e9fb:-:0:7:e3e6088 ... +@end smallexample + +@node Modifying the database, Checking the setup, Creating the database, Setting up a realm +@section Modifying the database + +All modifications of principals are done with with kadmin. + +A principal has several attributes and lifetimes associated with it. + +Principals are added, renamed, modified, and deleted with the kadmin +commands @samp{add}, @samp{rename}, @samp{modify}, @samp{delete}. +Both interactive editing and command line flags can be used (use --help +to list the available options). + +There are different kinds of types for the fields in the database; +attributes, absolute time times and relative times. + +@subsection Attributes + +When doing interactive editing, attributes are listed with @samp{?}. + +The attributes are given in a comma (@samp{,}) separated list. +Attributes are removed from the list by prefixing them with @samp{-}. + +@smallexample +kadmin> modify me +Max ticket life [1 day]: +Max renewable life [1 week]: +Principal expiration time [never]: +Password expiration time [never]: +Attributes [disallow-renewable]: requires-pre-auth,-disallow-renewable +kadmin> get me + Principal: me@@MY.REALM +[...] + Attributes: requires-pre-auth +@end smallexample + +@subsection Absolute times + +The format for absolute times are any of the following: + +@smallexample +never +now +YYYY-mm-dd +YYYY-mm-dd HH:MM:SS +@end smallexample + + +@subsection Relative times + +The format for relative times are any of the following combined: + +@smallexample +N year +M month +O day +P hour +Q minute +R second +@end smallexample + +@c Describe more of kadmin commands here... + +@node Checking the setup, keytabs, Modifying the database, Setting up a realm +@section Checking the setup + +There are two tools that can check the consistency of the Kerberos +configuration file and the Kerberos database. + +The Kerberos configuration file is checked using +@command{verify_krb5_conf}. The tool checks for common errors, but +commonly there are several uncommon configuration entries that are +never added to the tool and thus generates ``unknown entry'' warnings. +This is usually nothing to worry about. + +The database check is built into the kadmin tool. It will check for +common configuration error that will cause problems later. Common +check are for existence and flags on important principals. The +database check by run by the following command : + +@example +kadmin check REALM.EXAMPLE.ORG +@end example + +@node keytabs, Serving Kerberos 4/524/kaserver, Checking the setup, Setting up a realm +@section keytabs + +To extract a service ticket from the database and put it in a keytab, you +need to first create the principal in the database with @samp{ank} +(using the @kbd{--random-key} flag to get a random key) and then +extract it with @samp{ext_keytab}. + +@example +kadmin> add --random-key host/my.host.name +Max ticket life [unlimited]: +Max renewable life [unlimited]: +Attributes []: +kadmin> ext host/my.host.name +kadmin> exit +# ktutil list +Version Type Principal + 1 des-cbc-md5 host/my.host.name@@MY.REALM + 1 des-cbc-md4 host/my.host.name@@MY.REALM + 1 des-cbc-crc host/my.host.name@@MY.REALM + 1 des3-cbc-sha1 host/my.host.name@@MY.REALM +@end example + +@node Serving Kerberos 4/524/kaserver, Remote administration, keytabs, Setting up a realm +@section Serving Kerberos 4/524/kaserver + +Heimdal can be configured to support 524, Kerberos 4 or kaserver. All +these services are turned off by default. Kerberos 4 is always +supported by the KDC, but the Kerberos 4 client support also depends +on Kerberos 4 support having been included at compile-time, using +@kbd{--with-krb4=dir}. + +@subsection 524 + +524 is a service that allows the KDC to convert Kerberos 5 tickets to +Kerberos 4 tickets for backward compatibility. See also Using 2b +tokens with AFS in @xref{Things in search for a better place}. + +524 can be turned on by adding this to the configuration file + +@example +[kdc] + enable-524 = yes +@end example + +@subsection Kerberos 4 + +Kerberos 4 is the predecessor to to Kerberos 5. It only supports +single DES@. You should only enable Kerberos 4 support if you have +needs for compatibility with an installed base of Kerberos 4 +clients/servers. + +Kerberos 4 can be turned on by adding this to the configuration file + +@example +[kdc] + enable-kerberos4 = yes +@end example + +@subsection kaserver + +Kaserver is a Kerberos 4 that is used in AFS@. The protocol has some +extra features over plain Kerberos 4, but like Kerberos 4, only uses +single DES@. + +You should only enable Kaserver support if you have needs for +compatibility with an installed base of AFS machines. + +Kaserver can be turned on by adding this to the configuration file + +@example +[kdc] + enable-kaserver = yes +@end example + +@node Remote administration, Password changing, Serving Kerberos 4/524/kaserver, Setting up a realm +@section Remote administration + +The administration server, @command{kadmind}, can be started by +@command{inetd} (which isn't recommended) or run as a normal daemon. If you +want to start it from @command{inetd} you should add a line similar to the +one below to your @file{/etc/inetd.conf}. + +@example +kerberos-adm stream tcp nowait root /usr/heimdal/libexec/kadmind kadmind +@end example + +You might need to add @samp{kerberos-adm} to your @file{/etc/services} +as @samp{749/tcp}. + +Access to the administration server is controlled by an ACL file, +(default @file{@DBDIR@/kadmind.acl}.) The file has the following +syntax: +@smallexample +principal [priv1,priv2,...] [glob-pattern] +@end smallexample + +The matching is from top to bottom for matching principals (and if given, +glob-pattern). When there is a match, the access rights of that line are +applied. + +The privileges you can assign to a principal are: @samp{add}, +@samp{change-password} (or @samp{cpw} for short), @samp{delete}, +@samp{get}, @samp{list}, and @samp{modify}, or the special privilege +@samp{all}. All of these roughly correspond to the different commands +in @command{kadmin}. + +If a @var{glob-pattern} is given on a line, it restricts the access +rights for the principal to only apply for subjects that match the +pattern. The patterns are of the same type as those used in shell +globbing, see @url{none,,fnmatch(3)}. + +In the example below @samp{lha/admin} can change every principal in the +database. @samp{jimmy/admin} can only modify principals that belong to +the realm @samp{E.KTH.SE}. @samp{mille/admin} is working at the +help desk, so he should only be able to change the passwords for single +component principals (ordinary users). He will not be able to change any +@samp{/admin} principal. + +@example +lha/admin@@E.KTH.SE all +jimmy/admin@@E.KTH.SE all *@@E.KTH.SE +jimmy/admin@@E.KTH.SE all */*@@E.KTH.SE +mille/admin@@E.KTH.SE change-password *@@E.KTH.SE +@end example + +@node Password changing, Testing clients and servers, Remote administration, Setting up a realm +@section Password changing + +To allow users to change their passwords, you should run @command{kpasswdd}. +It is not run from @command{inetd}. + +You might need to add @samp{kpasswd} to your @file{/etc/services} as +@samp{464/udp}. + +@subsection Password quality assurance + +It is important that users have good passwords, both to make it harder +to guess them and to avoid off-line attacks (although +pre-authentication provides some defence against off-line attacks). +To ensure that the users choose good passwords, you can enable +password quality controls in @command{kpasswdd} and @command{kadmind}. +The controls themselves are done in a shared library or an external +program that is used by @command{kpasswdd}. To configure in these +controls, add lines similar to the following to your +@file{/etc/krb5.conf}: + +@example +[password_quality] + policies = external-check builtin:minimum-length module:policyname + external_program = /bin/false + policy_libraries = @var{library1.so} @var{library2.so} +@end example + +In @samp{[password_quality]policies} the module name is optional if +the policy name is unique in all modules (members of +@samp{policy_libraries}). + +The built-in polices are + +@itemize @bullet + +@item external-check + +Executes the program specified by @samp{[password_quality]external_program}. + +A number of key/value pairs are passed as input to the program, one per +line, ending with the string @samp{end}. The key/value lines are of +the form +@example +principal: @var{principal} +new-password: @var{password} +@end example +where @var{password} is the password to check for the previous +@var{principal}. + +If the external application approves the password, it should return +@samp{APPROVED} on standard out and exit with exit code 0. If it +doesn't approve the password, an one line error message explaining the +problem should be returned on standard error and the application +should exit with exit code 0. In case of a fatal error, the +application should, if possible, print an error message on standard +error and exit with a non-zero error code. + +@item minimum-length + +The minimum length password quality check reads the configuration file +stanza @samp{[password_quality]min_length} and requires the password +to be at least this length. + +@item character-class + +The character-class password quality check reads the configuration +file stanza @samp{[password_quality]min_classes}. The policy requires +the password to have characters from at least that many character +classes. Default value if not given is 3. + +The four different characters classes are, uppercase, lowercase, +number, special characters. + +@end itemize + +If you want to write your own shared object to check password +policies, see the manual page @manpage{kadm5_pwcheck,3}. + +Code for a password quality checking function that uses the cracklib +library can be found in @file{lib/kadm5/sample_password_check.c} in +the source code distribution. It requires that the cracklib library +be built with the patch available at +@url{ftp://ftp.pdc.kth.se/pub/krb/src/cracklib.patch}. + +A sample policy external program is included in +@file{lib/kadm5/check-cracklib.pl}. + +If no password quality checking function is configured, the only check +performed is that the password is at least six characters long. + +To check the password policy settings, use the command +@command{password-quality} in @command{kadmin} program. The password +verification is only performed locally, on the client. It may be +convenient to set the environment variable @samp{KRB5_CONFIG} to point +to a test version of @file{krb5.conf} while you're testing the +@samp{[password_quality]} stanza that way. + +@node Testing clients and servers, Slave Servers, Password changing, Setting up a realm +@section Testing clients and servers + +Now you should be able to run all the clients and servers. Refer to the +appropriate man pages for information on how to use them. + +@node Slave Servers, Incremental propagation, Testing clients and servers, Setting up a realm +@section Slave servers, Incremental propagation, Testing clients and servers, Setting up a realm + +It is desirable to have at least one backup (slave) server in case the +master server fails. It is possible to have any number of such slave +servers but more than three usually doesn't buy much more redundancy. + +All Kerberos servers for a realm must have the same database so that +they present the same service to the users. The +@pindex hprop +@command{hprop} program, running on the master, will propagate the database +to the slaves, running +@pindex hpropd +@command{hpropd} processes. + +Every slave needs a database directory, the master key (if it was used +for the database) and a keytab with the principal +@samp{hprop/@var{hostname}}. Add the principal with the +@pindex ktutil +@command{ktutil} command and start +@pindex hpropd +@command{hpropd}, as follows: + +@example +slave# ktutil get -p foo/admin hprop/`hostname` +slave# mkdir @DBDIR@ +slave# hpropd +@end example + +The master will use the principal @samp{kadmin/hprop} to authenticate to +the slaves. This principal should be added when running @kbd{kadmin -l +init} but if you do not have it in your database for whatever reason, +please add it with @kbd{kadmin -l add}. + +Then run +@pindex hprop +@code{hprop} on the master: + +@example +master# hprop slave +@end example + +This was just an hands-on example to make sure that everything was +working properly. Doing it manually is of course the wrong way, and to +automate this you will want to start +@pindex hpropd +@command{hpropd} from @command{inetd} on the slave(s) and regularly run +@pindex hprop +@command{hprop} on the master to regularly propagate the database. +Starting the propagation once an hour from @command{cron} is probably a +good idea. + +@node Incremental propagation, Encryption types and salting, Slave Servers, Setting up a realm +@section Incremental propagation + +There is also a newer, and still somewhat experimental, mechanism for +doing incremental propagation in Heimdal. Instead of sending the whole +database regularly, it sends the changes as they happen on the master to +the slaves. The master keeps track of all the changes by assigning a +version number to every change to the database. The slaves know which +was the latest version they saw and in this way it can be determined if +they are in sync or not. A log of all the changes is kept on the master, +and when a slave is at an older version than the oldest one in the +log, the whole database has to be sent. + +Protocol-wise, all the slaves connect to the master and as a greeting +tell it the latest version that they have (@samp{IHAVE} message). The +master then responds by sending all the changes between that version and +the current version at the master (a series of @samp{FORYOU} messages) +or the whole database in a @samp{TELLYOUEVERYTHING} message. There is +also a keep-alive protocol that makes sure all slaves are up and running. + +@subsection Configuring incremental propagation + +The program that runs on the master is @command{ipropd-master} and all +clients run @command{ipropd-slave}. + +Create the file @file{@DBDIR@/slaves} on the master containing all +the slaves that the database should be propagated to. Each line contains +the full name of the principal (for example +@samp{iprop/hemligare.foo.se@@FOO.SE}). + +You should already have @samp{iprop/tcp} defined as 2121, in your +@file{/etc/services}. Otherwise, or if you need to use a different port +for some peculiar reason, you can use the @kbd{--port} option. This is +useful when you have multiple realms to distribute from one server. + +Then you need to create those principals that you added in the +configuration file. Create one @samp{iprop/hostname} for the master and +for every slave. + + +@example +master# /usr/heimdal/sbin/ktutil get iprop/`hostname` +@end example + +The next step is to start the @command{ipropd-master} process on the master +server. The @command{ipropd-master} listens on the UNIX domain socket +@file{@DBDIR@/signal} to know when changes have been made to the +database so they can be propagated to the slaves. There is also a +safety feature of testing the version number regularly (every 30 +seconds) to see if it has been modified by some means that do not raise +this signal. Then, start @command{ipropd-slave} on all the slaves: + +@example +master# /usr/heimdal/libexec/ipropd-master & +slave# /usr/heimdal/libexec/ipropd-slave master & +@end example + +To manage the iprop log file you should use the @command{iprop-log} +command. With it you can dump, truncate and replay the logfile. + +@node Encryption types and salting, Cross realm, Incremental propagation, Setting up a realm +@section Encryption types and salting +@cindex Salting +@cindex Encryption types + +The encryption types that the KDC is going to assign by default is +possible to change. Since the keys used for user authentication is +salted the encryption types are described together with the salt +strings. + +Salting is used to make it harder to pre-calculate all possible +keys. Using a salt increases the search space to make it almost +impossible to pre-calculate all keys. Salting is the process of mixing a +public string (the salt) with the password, then sending it through an +encryption type specific string-to-key function that will output the +fixed size encryption key. + +In Kerberos 5 the salt is determined by the encryption type, except in +some special cases. + +In @code{des} there is the Kerberos 4 salt +(none at all) or the afs-salt (using the cell (realm in +AFS lingo)). + +In @code{arcfour} (the encryption type that Microsoft Windows 2000 uses) +there is no salt. This is to be compatible with NTLM keys in Windows +NT 4. + +@code{[kadmin]default_keys} in @file{krb5.conf} controls +what salting to use. + +The syntax of @code{[kadmin]default_keys} is +@samp{[etype:]salt-type[:salt-string]}. @samp{etype} is the encryption +type (des-cbc-crc, arcfour-hmac-md5, aes256-cts-hmac-sha1-96), +@code{salt-type} is the type of salt (pw-salt or afs3-salt), and the +salt-string is the string that will be used as salt (remember that if +the salt is appended/prepended, the empty salt "" is the same thing as +no salt at all). + +Common types of salting include + +@itemize @bullet +@item @code{v4} (or @code{des:pw-salt:}) + +The Kerberos 4 salting is using no salt at all. Reason there is colon +at the end of the salt string is that it makes the salt the empty +string (same as no salt). + +@item @code{v5} (or @code{pw-salt}) + +@code{pw-salt} uses the default salt for each encryption type is +specified for. If the encryption type @samp{etype} isn't given, all +default encryption will be used. + +@item @code{afs3-salt} + +@code{afs3-salt} is the salt that is used with Transarc kaserver. Its +the cell name appended to the password. + +@end itemize + +@node Cross realm, Transit policy, Encryption types and salting, Setting up a realm +@section Cross realm +@cindex Cross realm + +Suppose you reside in the realm @samp{MY.REALM}, how do you +authenticate to a server in @samp{OTHER.REALM}? Having valid tickets in +@samp{MY.REALM} allows you to communicate with Kerberised services in that +realm. However, the computer in the other realm does not have a secret +key shared with the Kerberos server in your realm. + +It is possible to share keys between two realms that trust each +other. When a client program, such as @command{telnet} or @command{ssh}, +finds that the other computer is in a different realm, it will try to +get a ticket granting ticket for that other realm, but from the local +Kerberos server. With that ticket granting ticket, it will then obtain +service tickets from the Kerberos server in the other realm. + +For a two way trust between @samp{MY.REALM} and @samp{OTHER.REALM} +add the following principals to each realm. The principals should be +@samp{krbtgt/OTHER.REALM@@MY.REALM} and +@samp{krbtgt/MY.REALM@@OTHER.REALM} in @samp{MY.REALM}, and +@samp{krbtgt/MY.REALM@@OTHER.REALM} and +@samp{krbtgt/OTHER.REALM@@MY.REALM}in @samp{OTHER.REALM}. + +In Kerberos 5 the trust can be configured to be one way. So that +users from @samp{MY.REALM} can authenticate to services in +@samp{OTHER.REALM}, but not the opposite. In the example above, the +@samp{krbtgt/MY.REALM@@OTHER.REALM} then should be removed. + +The two principals must have the same key, key version number, and the +same set of encryption types. Remember to transfer the two keys in a +safe manner. + +@example +vr$ klist +Credentials cache: FILE:/tmp/krb5cc_913.console + Principal: lha@@E.KTH.SE + + Issued Expires Principal +May 3 13:55:52 May 3 23:55:54 krbtgt/E.KTH.SE@@E.KTH.SE + +vr$ telnet -l lha hummel.it.su.se +Trying 2001:6b0:5:1095:250:fcff:fe24:dbf... +Connected to hummel.it.su.se. +Escape character is '^]'. +Waiting for encryption to be negotiated... +[ Trying mutual KERBEROS5 (host/hummel.it.su.se@@SU.SE)... ] +[ Kerberos V5 accepts you as ``lha@@E.KTH.SE'' ] +Encryption negotiated. +Last login: Sat May 3 14:11:47 from vr.l.nxs.se +hummel$ exit + +vr$ klist +Credentials cache: FILE:/tmp/krb5cc_913.console + Principal: lha@@E.KTH.SE + + Issued Expires Principal +May 3 13:55:52 May 3 23:55:54 krbtgt/E.KTH.SE@@E.KTH.SE +May 3 13:55:56 May 3 23:55:54 krbtgt/SU.SE@@E.KTH.SE +May 3 14:10:54 May 3 23:55:54 host/hummel.it.su.se@@SU.SE + +@end example + +@node Transit policy, Setting up DNS, Cross realm, Setting up a realm +@section Transit policy +@cindex Transit policy + +If you want to use cross realm authentication through an intermediate +realm, it must be explicitly allowed by either the KDCs or the server +receiving the request. This is done in @file{krb5.conf} in the +@code{[capaths]} section. + +When the ticket transits through a realm to another realm, the +destination realm adds its peer to the "transited-realms" field in the +ticket. The field is unordered, since there is no way to know if +know if one of the transited-realms changed the order of the list. + +The syntax for @code{[capaths]} section: + +@example +[capaths] + CLIENT-REALM = @{ + SERVER-REALM = PERMITTED-CROSS-REALMS ... + @} +@end example + +The realm @code{STACKEN.KTH.SE} allows clients from @code{SU.SE} and +@code{DSV.SU.SE} to cross it. Since @code{STACKEN.KTH.SE} only has +direct cross realm setup with @code{KTH.SE}, and @code{DSV.SU.SE} only +has direct cross realm setup with @code{SU.SE} they need to use both +@code{SU.SE} and @code{KTH.SE} as transit realms. + +@example +[capaths] + SU.SE = @{ + STACKEN.KTH.SE = KTH.SE + @} + DSV.SU.SE = @{ + STACKEN.KTH.SE = SU.SE KTH.SE + @} + +@end example + +The order of the @code{PERMITTED-CROSS-REALMS} is not important when +doing transit cross realm verification. + +However, the order is important when the @code{[capaths]} section is used +to figure out the intermediate realm to go to when doing multi-realm +transit. When figuring out the next realm, the first realm of the list +of @code{PERMITTED-CROSS-REALMS} is chosen. This is done in both the +client kerberos library and the KDC. + +@c To test the cross realm configuration, use: +@c kmumble transit-check client server transit-realms ... + +@node Setting up DNS, Using LDAP to store the database, Transit policy, Setting up a realm +@section Setting up DNS +@cindex Setting up DNS + +@subsection Using DNS to find KDC + +If there is information about where to find the KDC or kadmind for a +realm in the @file{krb5.conf} for a realm, that information will be +preferred, and DNS will not be queried. + +Heimdal will try to use DNS to find the KDCs for a realm. First it +will try to find a @code{SRV} resource record (RR) for the realm. If no +SRV RRs are found, it will fall back to looking for an @code{A} RR for +a machine named kerberos.REALM, and then kerberos-1.REALM, etc + +Adding this information to DNS minimises the client configuration (in +the common case, resulting in no configuration needed) and allows the +system administrator to change the number of KDCs and on what machines +they are running without caring about clients. + +The downside of using DNS is that the client might be fooled to use the +wrong server if someone fakes DNS replies/data, but storing the IP +addresses of the KDC on all the clients makes it very hard to change +the infrastructure. + +An example of the configuration for the realm @code{EXAMPLE.COM}: + +@example + +$ORIGIN example.com. +_kerberos._tcp SRV 10 1 88 kerberos.example.com. +_kerberos._udp SRV 10 1 88 kerberos.example.com. +_kerberos._tcp SRV 10 1 88 kerberos-1.example.com. +_kerberos._udp SRV 10 1 88 kerberos-1.example.com. +_kpasswd._udp SRV 10 1 464 kerberos.example.com. +_kerberos-adm._tcp SRV 10 1 749 kerberos.example.com. + +@end example + +More information about DNS SRV resource records can be found in +RFC-2782 (A DNS RR for specifying the location of services (DNS SRV)). + +@subsection Using DNS to map hostname to Kerberos realm + +Heimdal also supports a way to lookup a realm from a hostname. This to +minimise configuration needed on clients. Using this has the drawback +that clients can be redirected by an attacker to realms within the +same cross realm trust and made to believe they are talking to the +right server (since Kerberos authentication will succeed). + +An example configuration that informs clients that for the realms +it.example.com and srv.example.com, they should use the realm +EXAMPLE.COM: + +@example + +$ORIGIN example.com. +_kerberos.it TXT "EXAMPLE.COM" +_kerberos.srv TXT "EXAMPLE.COM" + +@end example + +@node Using LDAP to store the database, Providing Kerberos credentials to servers and programs, Setting up DNS, Setting up a realm +@section Using LDAP to store the database +@cindex Using the LDAP backend + +This document describes how to install the LDAP backend for +Heimdal. Note that before attempting to configure such an +installation, you should be aware of the implications of storing +private information (such as users' keys) in a directory service +primarily designed for public information. Nonetheless, with a +suitable authorisation policy, it is possible to set this up in a +secure fashion. A knowledge of LDAP, Kerberos, and C is necessary to +install this backend. The HDB schema was devised by Leif Johansson. + +Requirements: + +@itemize @bullet + +@item +A current release of Heimdal, configured with +@code{--with-openldap=/usr/local} (adjust according to where you have +installed OpenLDAP). + +You can verify that you manage to configure LDAP support by running +@file{kdc --builtin-hdb}, and checking that @samp{ldap:} is one entry +in the list. + +Its also possible to configure the ldap backend as a shared module, +see option --hdb-openldap-module to configure. + +@item +OpenLDAP 2.0.x. Configure OpenLDAP with @kbd{--enable-local} to enable the +local transport. (A patch to support SASL EXTERNAL authentication is +necessary in order to use OpenLDAP 2.1.x.) + +@item +Add the hdb schema to the LDAP server, its included in the source-tree +in @file{lib/hdb/hdb.schema}. Example from slapd.conf: + +@example +include /usr/local/etc/openldap/schema/hdb.schema +@end example + +@item +Configure the LDAP server ACLs to accept writes from clients over the +local transport. For example: + +@example +access to * + by dn.exact="uid=heimdal,dc=services,dc=example,dc=com" write + ... + +sasl-regexp "uidNumber=0\\\+gidNumber=.*,cn=peercred,cn=external,cn=auth" + "uid=heimdal,dc=services,dc=example,dc=com" + +@end example + +The sasl-regexp is for mapping between the SASL/EXTERNAL and a user in +a tree. The user that the key is mapped to should be have a +krb5Principal aux object with krb5PrincipalName set so that the +``creator'' and ``modifier'' is right in @file{kadmin}. + +Another option is to create an admins group and add the dn to that +group. + +Since Heimdal talks to the LDAP server over a UNIX domain socket, and +uses external sasl authentication, its not possible to require +security layer quality (ssf in cyrus-sasl lingo). So that requirement +has to be turned off in OpenLDAP @command{slapd} configuration file +@file{slapd.conf}. + +@example +sasl-secprops minssf=0 +@end example + +@item + +Start @command{slapd} with the local listener (as well as the default TCP/IP +listener on port 389) as follows: + +@example + slapd -h "ldapi:/// ldap:///" +@end example + +Note: These is a bug in @command{slapd} where it appears to corrupt the krb5Key +binary attribute on shutdown. This may be related to our use of the V3 +schema definition syntax instead of the old UMich-style, V2 syntax. + +@item +You should specify the distinguished name under which your +principals will be stored in @file{krb5.conf}. Also you need to +enter the path to the kadmin acl file: + + +@example +[kdc] + database = @{ + dbname = ldap:ou=KerberosPrincipals,dc=example,dc=com + hdb-ldap-structural-object = inetOrgPerson + acl_file = /path/to/kadmind.acl + mkey_file = /path/to/mkey + @} +@end example + +@samp{mkey_file} can be excluded if you feel that you trust your ldap +directory to have the raw keys inside it. The +hdb-ldap-structural-object is not necessary if you do not need Samba +comatibility. + + + +@item +Once you have built Heimdal and started the LDAP server, run kadmin +(as usual) to initialise the database. Note that the instructions for +stashing a master key are as per any Heimdal installation. + +@example +kdc# kadmin -l +kadmin> init EXAMPLE.COM +Realm max ticket life [unlimited]: +Realm max renewable ticket life [unlimited]: +kadmin> ank lukeh +Max ticket life [1 day]: +Max renewable life [1 week]: +Principal expiration time [never]: +Password expiration time [never]: +Attributes []: +lukeh@@EXAMPLE.COM's Password: +Verifying password - lukeh@@EXAMPLE.COM's Password: +kadmin> exit +@end example + +Verify that the principal database has indeed been stored in the +directory with the following command: + +@example +kdc# ldapsearch -L -h localhost -D cn=manager \ + -w secret -b ou=KerberosPrincipals,dc=example,dc=com \ + 'objectclass=krb5KDCEntry' +@end example + +@item +Now consider adding indexes to the database to speed up the access, at +least theses should be added to slapd.conf. + +@example +index objectClass eq +index cn eq,sub,pres +index uid eq,sub,pres +index displayName eq,sub,pres +index krb5PrincipalName eq +@end example + +@end itemize + +@subsection Troubleshooting guide + +@url{https://sec.miljovern.no/bin/view/Info/TroubleshootingGuide} + + +@subsection Using Samba LDAP password database +@cindex Samba + +@c @node Using Samba LDAP password database, Providing Kerberos credentials to servers and programs, Using LDAP to store the database, Setting up a realm +@c @section Using Samba LDAP password database + +The Samba domain and the Kerberos realm can have different names since +arcfour's string to key functions principal/realm independent. So now +will be your first and only chance name your Kerberos realm without +needing to deal with old configuration files. + +First, you should set up Samba and get that working with LDAP backend. + +Now you can proceed as in @xref{Using LDAP to store the database}. +Heimdal will pick up the Samba LDAP entries if they are in the same +search space as the Kerberos entries. + +@node Providing Kerberos credentials to servers and programs, Setting up PK-INIT, Using LDAP to store the database, Setting up a realm +@section Providing Kerberos credentials to servers and programs + +Some services require Kerberos credentials when they start to make +connections to other services or need to use them when they have started. + +The easiest way to get tickets for a service is to store the key in a +keytab. Both ktutil get and kadmin ext can be used to get a +keytab. ktutil get is better in that way it changes the key/password +for the user. This is also the problem with ktutil. If ktutil is used +for the same service principal on several hosts, they keytab will only +be useful on the last host. In that case, run the extract command on +one host and then securely copy the keytab around to all other hosts +that need it. + +@example +host# ktutil -k /etc/krb5-service.keytab \ + get -p lha/admin@@EXAMPLE.ORG service-principal@@EXAMPLE.ORG +lha/admin@@EXAMPLE.ORG's Password: +@end example + +To get a Kerberos credential file for the service, use kinit in the +--keytab mode. This will not ask for a password but instead fetch the +key from the keytab. + +@example +service@@host$ kinit --cache=/var/run/service_krb5_cache \ + --keytab=/etc/krb5-service.keytab \ + service-principal@@EXAMPLE.ORG +@end example + +Long running services might need credentials longer then the +expiration time of the tickets. kinit can run in a mode that refreshes +the tickets before they expire. This is useful for services that write +into AFS and other distributed file systems using Kerberos. To run the +long running script, just append the program and arguments (if any) +after the principal. kinit will stop refreshing credentials and remove +the credentials when the script-to-start-service exits. + +@example +service@@host$ kinit --cache=/var/run/service_krb5_cache \ + --keytab=/etc/krb5-service.keytab \ + service-principal@@EXAMPLE.ORG \ + script-to-start-service argument1 argument2 +@end example + + +@node Setting up PK-INIT, , Providing Kerberos credentials to servers and programs, Setting up a realm +@section Setting up PK-INIT + +PK-INIT is levering the existing PKI infrastructure to use +certificates to get the initial ticket, that is usually the krbtgt. + +To use PK-INIT you must first have a PKI, so if you don't have one, +now its time to create it. Note that you should read the whole chapter +of the document to see the requirements on the CA sortware. + +There needs to exist a mapping between the certificate and what +principals that certificate is allowed to use. There are several ways +to do this. The administrator can use a configuration file, storing +the principal in the SubjectAltName extension of the certificate, or store the +mapping in the principals entry in the kerberos database. + +@section Certificates + +This section documents the requirements on the KDC and client +certificates and the format used in the id-pkinit-san OtherName +extention. + +@subsection KDC certificate + +The certificate for the KDC have serveral requirements. + +First the certificate should have an Extended Key Usage (EKU) +id-pkkdcekuoid (1.3.6.1.5.2.3.5) set. Second there must be a +subjectAltName otherName using oid id-pkinit-san (1.3.6.1.5.2.2) in +the type field and a DER encoded KRB5PrincipalName that matches the +name of the TGS of the target realm. + +Both of these two requirements are not required by the standard to be +checked by the client if it have external information what the +certificate the KDC is supposed to be used. So its in the interst of +minimum amount of configuration on the clients they should be included. + +Remember that if the client would accept any certificate as the KDC's +certificate, the client could be fooled into trusting something that +isn't a KDC and thus expose the user to giving away information (like +password or other private information) that it is supposed to secret. + +Also, if the certificate has a nameConstraints extention with a +Generalname with dNSName or iPAdress it must match the hostname or +adress of the KDC. + +@subsection Client certificate + +The client certificate may need to have a EKU id-pkekuoid +(1.3.6.1.5.2.3.4) set depending on the certifiate on the KDC. + +It possible to store the principal (if allowed by the KDC) in the +certificate and thus delegate responsibility to do the mapping between +certificates and principals to the CA. + +@subsubsection Using KRB5PrincipalName in id-pkinit-san + +OtherName extention in the GeneralName is used to do the +mapping between certifiate and principal in the certifiate or storing +the krbtgt principal in the KDC certificate. + +The principal is stored in a SubjectAltName in the certificate using +OtherName. The oid in the type is id-pkinit-san. + +@example +id-pkinit-san OBJECT IDENTIFIER ::= @{ iso (1) org (3) dod (6) +internet (1) security (5) kerberosv5 (2) 2 @} +@end example + +The data part of the OtherName is filled with the following DER +encoded ASN.1 structure: + +@example +KRB5PrincipalName ::= SEQUENCE @{ + realm [0] Realm, + principalName [1] PrincipalName +@} +@end example + +where Realm and PrincipalName is defined by the Kerberos ASN.1 specification. + +@section Naming certificate using hx509 + +hx509 is the X.509 software used in Heimdal to handle +certificates. hx509 uses different syntaxes to specify the different +formats the certificates are stored in and what formats they exist in. + +There are several formats that can be used, PEM, embedded into PKCS12 +files, embedded into PKCS11 devices and raw DER encoded certificates. +Below is a list of types to use. + + +@table @asis + +@item DIR: + +DIR is reading all certificates in a directory that is DER or PEM +formatted. + +The main feature of DIR is that the directory is read on demand when +iterating over certificates, that way applictions can for some cases +avoid to store all certificates in memory. It's very useful for tests +that iterate over larger amount of certificates. + +Syntax is: + +@example +DIR:/path/to/der/files +@end example + +@item FILE: + +FILE: is used to have the lib pick up a certificate chain and a +private key. The file can be either a PEM (openssl) file or a raw DER +encoded certificate. If it's a PEM file it can contain several keys and +certificates and the code will try to match the private key and +certificate together. + +Its useful to have one PEM file that contains all the trust anchors. + +Syntax is: + +@example +FILE:certificate.pem,private-key.key,other-cert.pem,.... +@end example + +@item PKCS11: + +PKCS11: is used to handle smartcards via PKCS11 drivers, for example +soft-token, opensc, or muscle. The default is to use all slots on the +device/token. + +Syntax is: + +@example +PKCS11:shared-object.so +@end example + +@item PKCS12: + +PKCS12: is used to handle PKCS12 files. PKCS12 files commonly have the +extension pfx or p12. + +Syntax is: + +@example +PKCS12:/path/to/file.pfx +@end example + +@end table + +@section Configure the Kerberos software + +First configure the client's trust anchors and what parameters to +verify, see subsection below how to do that. Now you can use kinit to +get yourself tickets. One example how that can look like is: + +@example +$ kinit -C FILE:$HOME/.certs/lha.crt,$HOME/.certs/lha.key lha@@EXAMPLE.ORG +Enter your private key passphrase: +: lha@@nutcracker ; klist +Credentials cache: FILE:/tmp/krb5cc_19100a + Principal: lha@@EXAMPLE.ORG + + Issued Expires Principal +Apr 20 02:08:08 Apr 20 12:08:08 krbtgt/EXAMPLE.ORG@@EXAMPLE.ORG +@end example + +Using PKCS11 it can look like this instead: + +@example +$ kinit -C PKCS11:/tmp/pkcs11/lib/soft-pkcs11.so lha@@EXAMPLE.ORG +PIN code for SoftToken (slot): +$ klist +Credentials cache: API:4 + Principal: lha@@EXAMPLE.ORG + + Issued Expires Principal +Mar 26 23:40:10 Mar 27 09:40:10 krbtgt/EXAMPLE.ORG@@EXAMPLE.ORG +@end example + + +Write about the kdc. + +@section Configure the client + +@example +[appdefaults] + pkinit_anchors = FILE:/path/to/trust-anchors.pem + +[realms] + EXAMPLE.COM = @{ + pkinit_require_eku = true + pkinit_require_krbtgt_otherName = true + pkinit_win2k = no + pkinit_win2k_require_binding = yes + @} + +@end example + +@section Configure the KDC + +@example +[kdc] + enable-pkinit = yes + pkinit_identity = FILE:/secure/kdc.crt,/secure/kdc.key + pkinit_anchors = FILE:/path/to/trust-anchors.pem + pkinit_pool = PKCS12:/path/to/useful-intermediate-certs.pfx + pkinit_pool = FILE:/path/to/other-useful-intermediate-certs.pem + pkinit_allow_proxy_certificate = false + pkinit_win2k_require_binding = yes +@end example + +@subsection Using pki-mapping file + +Note that the file name is space sensitive. + +@example +# cat @DBDIR@/pki-mapping +# comments starts with # +lha@@EXAMPLE.ORG:C=SE,O=Stockholm universitet,CN=Love,UID=lha +lha@@EXAMPLE.ORG:CN=Love,UID=lha +@end example + +@subsection Using the Kerberos database + +@section Use hxtool to create certificates + +@subsection Generate certificates + +First you need to generate a CA certificate, change the --subject to +something appropriate, the CA certificate will be valid for 10 years. + +You need to change --subject in the command below. + +@example +hxtool issue-certificate \ + --self-signed \ + --issue-ca \ + --generate-key=rsa \ + --subject="CN=CA,DC=test,DC=h5l,DC=se" \ + --lifetime=10years \ + --certificate="FILE:ca.pem" +@end example + +The KDC needs to have a certificate, so generate a certificate of the +type ``pkinit-kdc'' and set the PK-INIT specifial SubjectAltName to the +name of the krbtgt of the realm. + +You need to change --subject and --pk-init-principal in the command below. + +@example +hxtool issue-certificate \ + --ca-certificate=FILE:ca.pem \ + --generate-key=rsa \ + --type="pkinit-kdc" \ + --pk-init-principal="krbtgt/TEST.H5L.SE@@TEST.H5L.SE" \ + --subject="uid=kdc,DC=test,DC=h5l,DC=se" \ + --certificate="FILE:kdc.pem" +@end example + +The users also needs to have a certificate, so generate a certificate +of the type ``pkinit-client''. The client doesn't need to have the PK-INIT +SubjectAltName set, you can have the Subject DN in the ACL file +(pki-mapping) instead. + +You need to change --subject and --pk-init-principal in the command below. + +@example +hxtool issue-certificate \ + --ca-certificate=FILE:ca.pem \ + --generate-key=rsa \ + --type="pkinit-client" \ + --pk-init-principal="lha@@TEST.H5L.SE" \ + --subject="uid=lha,DC=test,DC=h5l,DC=se" \ + --certificate="FILE:user.pem" +@end example + +@subsection Validate the certificate + +hxtool also contains a tool that will validate certificates according to +rules from the PKIX document. These checks are not complete, but a good test +to check if you got all of the basic bits right in your certificates. + +@example +hxtool validate FILE:user.pem +@end example + +@section Use OpenSSL to create certificates + +This section tries to give the CA owners hints how to create +certificates using OpenSSL (or CA software based on OpenSSL). + +@subsection Using OpenSSL to create certificates with krb5PrincipalName + +To make OpenSSL create certificates with krb5PrincipalName use +@file{openssl.cnf} as described below. To see a complete example of +creating client and KDC certificates, see the test-data generation +script @file{lib/hx509/data/gen-req.sh} in the source-tree. The +certicates it creates are used to test the PK-INIT functionality in +@file{tests/kdc/check-kdc.in}. + +To use this example you have to use OpenSSL 0.9.8a or later. + +@example + +[user_certificate] +subjectAltName=otherName:1.3.6.1.5.2.2;SEQUENCE:princ_name + +[princ_name] +realm = EXP:0, GeneralString:MY.REALM +principal_name = EXP:1, SEQUENCE:principal_seq + +[principal_seq] +name_type = EXP:0, INTEGER:1 +name_string = EXP:1, SEQUENCE:principals + +[principals] +princ1 = GeneralString:userid + +@end example + +Command usage + +@example +openssl x509 -extensions user_certificate +openssl ca -extensions user_certificate +@end example + + +@c --- ms certificate +@c +@c [ new_oids ] +@c msCertificateTemplateName = 1.3.6.1.4.1.311.20.2 +@c +@c +@c [ req_smartcard ] +@c keyUsage = digitalSignature, keyEncipherment +@c extendedKeyUsage = msSmartcardLogin, clientAuth +@c msCertificateTemplateName = ASN1:BMP:SmartcardLogon +@c subjectAltName = otherName:msUPN;UTF8:lukeh@dsg.padl.com +@c #subjectAltName = email:copy + + +@section Using PK-INIT with Windows + +@subsection Client configration + +Clients using a Windows KDC with PK-INIT need configuration since +windows uses pre-standard format and this can't be autodetected. + +The pkinit_win2k_require_binding option requires the reply for the KDC +to be of the new, secure, type that binds the request to reply. Before +clients should fake the reply from the KDC. To use this option you +have to apply a fix from Microsoft. + +@example +[realms] + MY.MS.REALM = @{ + pkinit_win2k = yes + pkinit_win2k_require_binding = no + @} +@end example + +@subsection Certificates + +The client certificates need to have the extended keyusage ``Microsoft +Smartcardlogin'' (openssl have the oid shortname msSmartcardLogin). + +See Microsoft Knowledge Base Article - 281245 ``Guidelines for Enabling +Smart Card Logon with Third-Party Certification Authorities'' for a +more extensive description of how set setup an external CA to it +includes all information that will make a Windows KDC happy. + +@subsection Configure Windows 2000 CA + +To enable Microsoft Smartcardlogin> for certificates in your Windows +2000 CA, you want to look at Microsoft Knowledge Base Article - +313274 ``HOW TO: Configure a Certification Authority to Issue +Smart Card Certificates in Windows''. diff -U 3 -H -d -r -N -x Makefile.in -x 'config.h.in*' -x 'output*' -x requests -x 'traces*' -x '*.loT' -x aclocal.m4 -x configure -- heimdal-1.0.1/kdc/kstash.8 heimdal-1.0.1.work/kdc/kstash.8 --- heimdal-1.0.1/kdc/kstash.8 2007-08-09 10:47:23.000000000 +0300 +++ heimdal-1.0.1.work/kdc/kstash.8 1970-01-01 02:00:00.000000000 +0200 @@ -1,104 +0,0 @@ -.\" Copyright (c) 1997 - 2004 Kungliga Tekniska Högskolan -.\" (Royal Institute of Technology, Stockholm, Sweden). -.\" All rights reserved. -.\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: -.\" -.\" 1. Redistributions of source code must retain the above copyright -.\" notice, this list of conditions and the following disclaimer. -.\" -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice, this list of conditions and the following disclaimer in the -.\" documentation and/or other materials provided with the distribution. -.\" -.\" 3. Neither the name of the Institute nor the names of its contributors -.\" may be used to endorse or promote products derived from this software -.\" without specific prior written permission. -.\" -.\" THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND -.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -.\" ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE -.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS -.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT -.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY -.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF -.\" SUCH DAMAGE. -.\" -.\" $Id: kstash.8 20316 2007-04-11 11:53:20Z lha $ -.\" -.Dd April 10, 2007 -.Dt KSTASH 8 -.Os HEIMDAL -.Sh NAME -.Nm kstash -.Nd "store the KDC master password in a file" -.Sh SYNOPSIS -.Nm -.Bk -words -.Oo Fl e Ar string \*(Ba Xo -.Fl -enctype= Ns Ar string -.Xc -.Oc -.Oo Fl k Ar file \*(Ba Xo -.Fl -key-file= Ns Ar file -.Xc -.Oc -.Op Fl -convert-file -.Op Fl -random-key -.Op Fl -master-key-fd= Ns Ar fd -.Op Fl -random-key -.Op Fl h | Fl -help -.Op Fl -version -.Ek -.Sh DESCRIPTION -.Nm -reads the Kerberos master key and stores it in a file that will be -used by the KDC. -.Pp -Supported options: -.Bl -tag -width Ds -.It Xo -.Fl e Ar string , -.Fl -enctype= Ns Ar string -.Xc -the encryption type to use, defaults to DES3-CBC-SHA1. -.It Xo -.Fl k Ar file , -.Fl -key-file= Ns Ar file -.Xc -the name of the master key file. -.It Xo -.Fl -convert-file -.Xc -don't ask for a new master key, just read an old master key file, and -write it back in the new keyfile format. -.It Xo -.Fl -random-key -.Xc -generate a random master key. -.It Xo -.Fl -master-key-fd= Ns Ar fd -.Xc -filedescriptor to read passphrase from, if not specified the -passphrase will be read from the terminal. -.El -.\".Sh ENVIRONMENT -.Sh FILES -.Pa /var/heimdal/m-key -is the default keyfile if no other keyfile is specified. -The format of a Heimdal master key is the same as a keytab, so -.Nm ktutil -list can be used to list the content of the file. -.\".Sh EXAMPLES -.\".Sh DIAGNOSTICS -.Sh SEE ALSO -.Xr kdc 8 -.\".Sh STANDARDS -.\".Sh HISTORY -.\".Sh AUTHORS -.\".Sh BUGS diff -U 3 -H -d -r -N -x Makefile.in -x 'config.h.in*' -x 'output*' -x requests -x 'traces*' -x '*.loT' -x aclocal.m4 -x configure -- heimdal-1.0.1/kdc/kstash.8.in heimdal-1.0.1.work/kdc/kstash.8.in --- heimdal-1.0.1/kdc/kstash.8.in 1970-01-01 02:00:00.000000000 +0200 +++ heimdal-1.0.1.work/kdc/kstash.8.in 2007-12-05 23:15:31.000000000 +0200 @@ -0,0 +1,104 @@ +.\" Copyright (c) 1997 - 2004 Kungliga Tekniska Högskolan +.\" (Royal Institute of Technology, Stockholm, Sweden). +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" 3. Neither the name of the Institute nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $Id: kstash.8 20316 2007-04-11 11:53:20Z lha $ +.\" +.Dd April 10, 2007 +.Dt KSTASH 8 +.Os HEIMDAL +.Sh NAME +.Nm kstash +.Nd "store the KDC master password in a file" +.Sh SYNOPSIS +.Nm +.Bk -words +.Oo Fl e Ar string \*(Ba Xo +.Fl -enctype= Ns Ar string +.Xc +.Oc +.Oo Fl k Ar file \*(Ba Xo +.Fl -key-file= Ns Ar file +.Xc +.Oc +.Op Fl -convert-file +.Op Fl -random-key +.Op Fl -master-key-fd= Ns Ar fd +.Op Fl -random-key +.Op Fl h | Fl -help +.Op Fl -version +.Ek +.Sh DESCRIPTION +.Nm +reads the Kerberos master key and stores it in a file that will be +used by the KDC. +.Pp +Supported options: +.Bl -tag -width Ds +.It Xo +.Fl e Ar string , +.Fl -enctype= Ns Ar string +.Xc +the encryption type to use, defaults to DES3-CBC-SHA1. +.It Xo +.Fl k Ar file , +.Fl -key-file= Ns Ar file +.Xc +the name of the master key file. +.It Xo +.Fl -convert-file +.Xc +don't ask for a new master key, just read an old master key file, and +write it back in the new keyfile format. +.It Xo +.Fl -random-key +.Xc +generate a random master key. +.It Xo +.Fl -master-key-fd= Ns Ar fd +.Xc +filedescriptor to read passphrase from, if not specified the +passphrase will be read from the terminal. +.El +.\".Sh ENVIRONMENT +.Sh FILES +.Pa @DBDIR@/m-key +is the default keyfile if no other keyfile is specified. +The format of a Heimdal master key is the same as a keytab, so +.Nm ktutil +list can be used to list the content of the file. +.\".Sh EXAMPLES +.\".Sh DIAGNOSTICS +.Sh SEE ALSO +.Xr kdc 8 +.\".Sh STANDARDS +.\".Sh HISTORY +.\".Sh AUTHORS +.\".Sh BUGS diff -U 3 -H -d -r -N -x Makefile.in -x 'config.h.in*' -x 'output*' -x requests -x 'traces*' -x '*.loT' -x aclocal.m4 -x configure -- heimdal-1.0.1/lib/hdb/Makefile.am heimdal-1.0.1.work/lib/hdb/Makefile.am --- heimdal-1.0.1/lib/hdb/Makefile.am 2007-08-09 10:47:06.000000000 +0300 +++ heimdal-1.0.1.work/lib/hdb/Makefile.am 2007-12-05 23:18:08.000000000 +0200 @@ -2,7 +2,7 @@ include $(top_srcdir)/Makefile.am.common -AM_CPPFLAGS += -I../asn1 -I$(srcdir)/../asn1 $(INCLUDE_hcrypto) +AM_CPPFLAGS += -I../asn1 -I$(srcdir)/../asn1 $(INCLUDE_hcrypto) -DDBDIR=$(DBDIR) BUILT_SOURCES = \ $(gen_files_hdb:.x=.c) \ diff -U 3 -H -d -r -N -x Makefile.in -x 'config.h.in*' -x 'output*' -x requests -x 'traces*' -x '*.loT' -x aclocal.m4 -x configure -- heimdal-1.0.1/lib/hdb/hdb.h heimdal-1.0.1.work/lib/hdb/hdb.h --- heimdal-1.0.1/lib/hdb/hdb.h 2007-08-09 10:47:05.000000000 +0300 +++ heimdal-1.0.1.work/lib/hdb/hdb.h 2007-12-05 23:17:38.000000000 +0200 @@ -135,7 +135,7 @@ krb5_error_code (*create)(krb5_context, HDB **, const char *filename); }; -#define HDB_DB_DIR "/var/heimdal" +#define HDB_DB_DIR "DBDIR" #define HDB_DEFAULT_DB HDB_DB_DIR "/heimdal" #define HDB_DB_FORMAT_ENTRY "hdb/db-format" diff -U 3 -H -d -r -N -x Makefile.in -x 'config.h.in*' -x 'output*' -x requests -x 'traces*' -x '*.loT' -x aclocal.m4 -x configure -- heimdal-1.0.1/lib/krb5/kcm.h heimdal-1.0.1.work/lib/krb5/kcm.h --- heimdal-1.0.1/lib/krb5/kcm.h 2007-08-09 10:47:13.000000000 +0300 +++ heimdal-1.0.1.work/lib/krb5/kcm.h 2007-12-05 23:55:45.000000000 +0200 @@ -62,8 +62,8 @@ KCM_OP_MAX } kcm_operation; -#define _PATH_KCM_SOCKET "/var/run/.kcm_socket" -#define _PATH_KCM_DOOR "/var/run/.kcm_door" +#define _PATH_KCM_SOCKET LOCALSTATEDIR "/run/.kcm_socket" +#define _PATH_KCM_DOOR LOCALSTATEDIR "/run/.kcm_door" #endif /* __KCM_H__ */ diff -U 3 -H -d -r -N -x Makefile.in -x 'config.h.in*' -x 'output*' -x requests -x 'traces*' -x '*.loT' -x aclocal.m4 -x configure -- heimdal-1.0.1/lib/krb5/krb5.conf.5 heimdal-1.0.1.work/lib/krb5/krb5.conf.5 --- heimdal-1.0.1/lib/krb5/krb5.conf.5 2007-08-09 10:47:13.000000000 +0300 +++ heimdal-1.0.1.work/lib/krb5/krb5.conf.5 1970-01-01 02:00:00.000000000 +0200 @@ -1,530 +0,0 @@ -.\" Copyright (c) 1999 - 2005 Kungliga Tekniska Högskolan -.\" (Royal Institute of Technology, Stockholm, Sweden). -.\" All rights reserved. -.\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: -.\" -.\" 1. Redistributions of source code must retain the above copyright -.\" notice, this list of conditions and the following disclaimer. -.\" -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice, this list of conditions and the following disclaimer in the -.\" documentation and/or other materials provided with the distribution. -.\" -.\" 3. Neither the name of the Institute nor the names of its contributors -.\" may be used to endorse or promote products derived from this software -.\" without specific prior written permission. -.\" -.\" THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND -.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -.\" ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE -.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS -.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT -.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY -.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF -.\" SUCH DAMAGE. -.\" -.\" $Id: krb5.conf.5 15514 2005-06-23 18:43:34Z lha $ -.\" -.Dd May 4, 2005 -.Dt KRB5.CONF 5 -.Os HEIMDAL -.Sh NAME -.Nm krb5.conf -.Nd configuration file for Kerberos 5 -.Sh SYNOPSIS -.In krb5.h -.Sh DESCRIPTION -The -.Nm -file specifies several configuration parameters for the Kerberos 5 -library, as well as for some programs. -.Pp -The file consists of one or more sections, containing a number of -bindings. -The value of each binding can be either a string or a list of other -bindings. -The grammar looks like: -.Bd -literal -offset indent -file: - /* empty */ - sections - -sections: - section sections - section - -section: - '[' section_name ']' bindings - -section_name: - STRING - -bindings: - binding bindings - binding - -binding: - name '=' STRING - name '=' '{' bindings '}' - -name: - STRING - -.Ed -.Li STRINGs -consists of one or more non-whitespace characters. -.Pp -STRINGs that are specified later in this man-page uses the following -notation. -.Bl -tag -width "xxx" -offset indent -.It boolean -values can be either yes/true or no/false. -.It time -values can be a list of year, month, day, hour, min, second. -Example: 1 month 2 days 30 min. -If no unit is given, seconds is assumed. -.It etypes -valid encryption types are: des-cbc-crc, des-cbc-md4, des-cbc-md5, -des3-cbc-sha1, arcfour-hmac-md5, aes128-cts-hmac-sha1-96, and -aes256-cts-hmac-sha1-96 . -.It address -an address can be either a IPv4 or a IPv6 address. -.El -.Pp -Currently recognised sections and bindings are: -.Bl -tag -width "xxx" -offset indent -.It Li [appdefaults] -Specifies the default values to be used for Kerberos applications. -You can specify defaults per application, realm, or a combination of -these. -The preference order is: -.Bl -enum -compact -.It -.Va application Va realm Va option -.It -.Va application Va option -.It -.Va realm Va option -.It -.Va option -.El -.Pp -The supported options are: -.Bl -tag -width "xxx" -offset indent -.It Li forwardable = Va boolean -When obtaining initial credentials, make the credentials forwardable. -.It Li proxiable = Va boolean -When obtaining initial credentials, make the credentials proxiable. -.It Li no-addresses = Va boolean -When obtaining initial credentials, request them for an empty set of -addresses, making the tickets valid from any address. -.It Li ticket_lifetime = Va time -Default ticket lifetime. -.It Li renew_lifetime = Va time -Default renewable ticket lifetime. -.It Li encrypt = Va boolean -Use encryption, when available. -.It Li forward = Va boolean -Forward credentials to remote host (for -.Xr rsh 1 , -.Xr telnet 1 , -etc). -.El -.It Li [libdefaults] -.Bl -tag -width "xxx" -offset indent -.It Li default_realm = Va REALM -Default realm to use, this is also known as your -.Dq local realm . -The default is the result of -.Fn krb5_get_host_realm "local hostname" . -.It Li clockskew = Va time -Maximum time differential (in seconds) allowed when comparing -times. -Default is 300 seconds (five minutes). -.It Li kdc_timeout = Va time -Maximum time to wait for a reply from the kdc, default is 3 seconds. -.It Li v4_name_convert -.It Li v4_instance_resolve -These are described in the -.Xr krb5_425_conv_principal 3 -manual page. -.It Li capath = { -.Bl -tag -width "xxx" -offset indent -.It Va destination-realm Li = Va next-hop-realm -.It ... -.It Li } -.El -This is deprecated, see the -.Li capaths -section below. -.It Li default_cc_name = Va ccname -the default credentials cache name. -The string can contain variables that are expanded on runtime. -Only support variable now is -.Li %{uid} -that expands to the current user id. -.It Li default_etypes = Va etypes ... -A list of default encryption types to use. -.It Li default_etypes_des = Va etypes ... -A list of default encryption types to use when requesting a DES credential. -.It Li default_keytab_name = Va keytab -The keytab to use if no other is specified, default is -.Dq FILE:/etc/krb5.keytab . -.It Li dns_lookup_kdc = Va boolean -Use DNS SRV records to lookup KDC services location. -.It Li dns_lookup_realm = Va boolean -Use DNS TXT records to lookup domain to realm mappings. -.It Li kdc_timesync = Va boolean -Try to keep track of the time differential between the local machine -and the KDC, and then compensate for that when issuing requests. -.It Li max_retries = Va number -The max number of times to try to contact each KDC. -.It Li large_msg_size = Va number -The threshold where protocols with tiny maximum message sizes are not -considered usable to send messages to the KDC. -.It Li ticket_lifetime = Va time -Default ticket lifetime. -.It Li renew_lifetime = Va time -Default renewable ticket lifetime. -.It Li forwardable = Va boolean -When obtaining initial credentials, make the credentials forwardable. -This option is also valid in the [realms] section. -.It Li proxiable = Va boolean -When obtaining initial credentials, make the credentials proxiable. -This option is also valid in the [realms] section. -.It Li verify_ap_req_nofail = Va boolean -If enabled, failure to verify credentials against a local key is a -fatal error. -The application has to be able to read the corresponding service key -for this to work. -Some applications, like -.Xr su 1 , -enable this option unconditionally. -.It Li warn_pwexpire = Va time -How soon to warn for expiring password. -Default is seven days. -.It Li http_proxy = Va proxy-spec -A HTTP-proxy to use when talking to the KDC via HTTP. -.It Li dns_proxy = Va proxy-spec -Enable using DNS via HTTP. -.It Li extra_addresses = Va address ... -A list of addresses to get tickets for along with all local addresses. -.It Li time_format = Va string -How to print time strings in logs, this string is passed to -.Xr strftime 3 . -.It Li date_format = Va string -How to print date strings in logs, this string is passed to -.Xr strftime 3 . -.It Li log_utc = Va boolean -Write log-entries using UTC instead of your local time zone. -.It Li scan_interfaces = Va boolean -Scan all network interfaces for addresses, as opposed to simply using -the address associated with the system's host name. -.It Li fcache_version = Va int -Use file credential cache format version specified. -.It Li krb4_get_tickets = Va boolean -Also get Kerberos 4 tickets in -.Nm kinit , -.Nm login , -and other programs. -This option is also valid in the [realms] section. -.It Li fcc-mit-ticketflags = Va boolean -Use MIT compatible format for file credential cache. -It's the field ticketflags that is stored in reverse bit order for -older than Heimdal 0.7. -Setting this flag to -.Dv TRUE -make it store the MIT way, this is default for Heimdal 0.7. -.El -.It Li [domain_realm] -This is a list of mappings from DNS domain to Kerberos realm. -Each binding in this section looks like: -.Pp -.Dl domain = realm -.Pp -The domain can be either a full name of a host or a trailing -component, in the latter case the domain-string should start with a -period. -The trailing component only matches hosts that are in the same domain, ie -.Dq .example.com -matches -.Dq foo.example.com , -but not -.Dq foo.test.example.com . -.Pp -The realm may be the token `dns_locate', in which case the actual -realm will be determined using DNS (independently of the setting -of the `dns_lookup_realm' option). -.It Li [realms] -.Bl -tag -width "xxx" -offset indent -.It Va REALM Li = { -.Bl -tag -width "xxx" -offset indent -.It Li kdc = Va [service/]host[:port] -Specifies a list of kdcs for this realm. -If the optional -.Va port -is absent, the -default value for the -.Dq kerberos/udp -.Dq kerberos/tcp , -and -.Dq http/tcp -port (depending on service) will be used. -The kdcs will be used in the order that they are specified. -.Pp -The optional -.Va service -specifies over what medium the kdc should be -contacted. -Possible services are -.Dq udp , -.Dq tcp , -and -.Dq http . -Http can also be written as -.Dq http:// . -Default service is -.Dq udp -and -.Dq tcp . -.It Li admin_server = Va host[:port] -Specifies the admin server for this realm, where all the modifications -to the database are performed. -.It Li kpasswd_server = Va host[:port] -Points to the server where all the password changes are performed. -If there is no such entry, the kpasswd port on the admin_server host -will be tried. -.It Li krb524_server = Va host[:port] -Points to the server that does 524 conversions. -If it is not mentioned, the krb524 port on the kdcs will be tried. -.It Li v4_instance_convert -.It Li v4_name_convert -.It Li default_domain -See -.Xr krb5_425_conv_principal 3 . -.It Li tgs_require_subkey -a boolan variable that defaults to false. -Old DCE secd (pre 1.1) might need this to be true. -.El -.It Li } -.El -.It Li [capaths] -.Bl -tag -width "xxx" -offset indent -.It Va client-realm Li = { -.Bl -tag -width "xxx" -offset indent -.It Va server-realm Li = Va hop-realm ... -This serves two purposes. First the first listed -.Va hop-realm -tells a client which realm it should contact in order to ultimately -obtain credentials for a service in the -.Va server-realm . -Secondly, it tells the KDC (and other servers) which realms are -allowed in a multi-hop traversal from -.Va client-realm -to -.Va server-realm . -Except for the client case, the order of the realms are not important. -.El -.It Va } -.El -.It Li [logging] -.Bl -tag -width "xxx" -offset indent -.It Va entity Li = Va destination -Specifies that -.Va entity -should use the specified -.Li destination -for logging. -See the -.Xr krb5_openlog 3 -manual page for a list of defined destinations. -.El -.It Li [kdc] -.Bl -tag -width "xxx" -offset indent -.It Li database Li = { -.Bl -tag -width "xxx" -offset indent -.It Li dbname Li = Va DATABASENAME -Use this database for this realm. -See the info documetation how to configure diffrent database backends. -.It Li realm Li = Va REALM -Specifies the realm that will be stored in this database. -It realm isn't set, it will used as the default database, there can -only be one entry that doesn't have a -.Li realm -stanza. -.It Li mkey_file Li = Pa FILENAME -Use this keytab file for the master key of this database. -If not specified -.Va DATABASENAME Ns .mkey -will be used. -.It Li acl_file Li = PA FILENAME -Use this file for the ACL list of this database. -.It Li log_file Li = Pa FILENAME -Use this file as the log of changes performed to the database. -This file is used by -.Nm ipropd-master -for propagating changes to slaves. -.El -.It Li } -.It Li max-request = Va SIZE -Maximum size of a kdc request. -.It Li require-preauth = Va BOOL -If set pre-authentication is required. -Since krb4 requests are not pre-authenticated they will be rejected. -.It Li ports = Va "list of ports" -List of ports the kdc should listen to. -.It Li addresses = Va "list of interfaces" -List of addresses the kdc should bind to. -.It Li enable-kerberos4 = Va BOOL -Turn on Kerberos 4 support. -.It Li v4-realm = Va REALM -To what realm v4 requests should be mapped. -.It Li enable-524 = Va BOOL -Should the Kerberos 524 converting facility be turned on. -Default is the same as -.Va enable-kerberos4 . -.It Li enable-http = Va BOOL -Should the kdc answer kdc-requests over http. -.It Li enable-kaserver = Va BOOL -If this kdc should emulate the AFS kaserver. -.It Li check-ticket-addresses = Va BOOL -Verify the addresses in the tickets used in tgs requests. -.\" XXX -.It Li allow-null-ticket-addresses = Va BOOL -Allow address-less tickets. -.\" XXX -.It Li allow-anonymous = Va BOOL -If the kdc is allowed to hand out anonymous tickets. -.It Li encode_as_rep_as_tgs_rep = Va BOOL -Encode as-rep as tgs-rep tobe compatible with mistakes older DCE secd did. -.\" XXX -.It Li kdc_warn_pwexpire = Va TIME -The time before expiration that the user should be warned that her -password is about to expire. -.It Li logging = Va Logging -What type of logging the kdc should use, see also [logging]/kdc. -.It Li use_2b = { -.Bl -tag -width "xxx" -offset indent -.It Va principal Li = Va BOOL -boolean value if the 524 daemon should return AFS 2b tokens for -.Fa principal . -.It ... -.El -.It Li } -.It Li hdb-ldap-structural-object Va structural object -If the LDAP backend is used for storing principals, this is the -structural object that will be used when creating and when reading -objects. -The default value is account . -.It Li hdb-ldap-create-base Va creation dn -is the dn that will be appended to the principal when creating entries. -Default value is the search dn. -.El -.It Li [kadmin] -.Bl -tag -width "xxx" -offset indent -.It Li require-preauth = Va BOOL -If pre-authentication is required to talk to the kadmin server. -.It Li password_lifetime = Va time -If a principal already have its password set for expiration, this is -the time it will be valid for after a change. -.It Li default_keys = Va keytypes... -For each entry in -.Va default_keys -try to parse it as a sequence of -.Va etype:salttype:salt -syntax of this if something like: -.Pp -[(des|des3|etype):](pw-salt|afs3-salt)[:string] -.Pp -If -.Ar etype -is omitted it means everything, and if string is omitted it means the -default salt string (for that principal and encryption type). -Additional special values of keytypes are: -.Bl -tag -width "xxx" -offset indent -.It Li v5 -The Kerberos 5 salt -.Va pw-salt -.It Li v4 -The Kerberos 4 salt -.Va des:pw-salt: -.El -.It Li use_v4_salt = Va BOOL -When true, this is the same as -.Pp -.Va default_keys = Va des3:pw-salt Va v4 -.Pp -and is only left for backwards compatibility. -.El -.It Li [password-quality] -Check the Password quality assurance in the info documentation for -more information. -.Bl -tag -width "xxx" -offset indent -.It Li check_library = Va library-name -Library name that contains the password check_function -.It Li check_function = Va function-name -Function name for checking passwords in check_library -.It Li policy_libraries = Va library1 ... libraryN -List of libraries that can do password policy checks -.It Li policies = Va policy1 ... policyN -List of policy names to apply to the password. Builtin policies are -among other minimum-length, character-class, external-check. -.El -.El -.Sh ENVIRONMENT -.Ev KRB5_CONFIG -points to the configuration file to read. -.Sh FILES -.Bl -tag -width "/etc/krb5.conf" -.It Pa /etc/krb5.conf -configuration file for Kerberos 5. -.El -.Sh EXAMPLES -.Bd -literal -offset indent -[libdefaults] - default_realm = FOO.SE -[domain_realm] - .foo.se = FOO.SE - .bar.se = FOO.SE -[realms] - FOO.SE = { - kdc = kerberos.foo.se - v4_name_convert = { - rcmd = host - } - v4_instance_convert = { - xyz = xyz.bar.se - } - default_domain = foo.se - } -[logging] - kdc = FILE:/var/heimdal/kdc.log - kdc = SYSLOG:INFO - default = SYSLOG:INFO:USER -.Ed -.Sh DIAGNOSTICS -Since -.Nm -is read and parsed by the krb5 library, there is not a lot of -opportunities for programs to report parsing errors in any useful -format. -To help overcome this problem, there is a program -.Nm verify_krb5_conf -that reads -.Nm -and tries to emit useful diagnostics from parsing errors. -Note that this program does not have any way of knowing what options -are actually used and thus cannot warn about unknown or misspelled -ones. -.Sh SEE ALSO -.Xr kinit 1 , -.Xr krb5_425_conv_principal 3 , -.Xr krb5_openlog 3 , -.Xr strftime 3 , -.Xr verify_krb5_conf 8 diff -U 3 -H -d -r -N -x Makefile.in -x 'config.h.in*' -x 'output*' -x requests -x 'traces*' -x '*.loT' -x aclocal.m4 -x configure -- heimdal-1.0.1/lib/krb5/krb5.conf.5.in heimdal-1.0.1.work/lib/krb5/krb5.conf.5.in --- heimdal-1.0.1/lib/krb5/krb5.conf.5.in 1970-01-01 02:00:00.000000000 +0200 +++ heimdal-1.0.1.work/lib/krb5/krb5.conf.5.in 2007-12-05 23:04:27.000000000 +0200 @@ -0,0 +1,530 @@ +.\" Copyright (c) 1999 - 2005 Kungliga Tekniska Högskolan +.\" (Royal Institute of Technology, Stockholm, Sweden). +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" 3. Neither the name of the Institute nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $Id: krb5.conf.5 15514 2005-06-23 18:43:34Z lha $ +.\" +.Dd May 4, 2005 +.Dt KRB5.CONF 5 +.Os HEIMDAL +.Sh NAME +.Nm krb5.conf +.Nd configuration file for Kerberos 5 +.Sh SYNOPSIS +.In krb5.h +.Sh DESCRIPTION +The +.Nm +file specifies several configuration parameters for the Kerberos 5 +library, as well as for some programs. +.Pp +The file consists of one or more sections, containing a number of +bindings. +The value of each binding can be either a string or a list of other +bindings. +The grammar looks like: +.Bd -literal -offset indent +file: + /* empty */ + sections + +sections: + section sections + section + +section: + '[' section_name ']' bindings + +section_name: + STRING + +bindings: + binding bindings + binding + +binding: + name '=' STRING + name '=' '{' bindings '}' + +name: + STRING + +.Ed +.Li STRINGs +consists of one or more non-whitespace characters. +.Pp +STRINGs that are specified later in this man-page uses the following +notation. +.Bl -tag -width "xxx" -offset indent +.It boolean +values can be either yes/true or no/false. +.It time +values can be a list of year, month, day, hour, min, second. +Example: 1 month 2 days 30 min. +If no unit is given, seconds is assumed. +.It etypes +valid encryption types are: des-cbc-crc, des-cbc-md4, des-cbc-md5, +des3-cbc-sha1, arcfour-hmac-md5, aes128-cts-hmac-sha1-96, and +aes256-cts-hmac-sha1-96 . +.It address +an address can be either a IPv4 or a IPv6 address. +.El +.Pp +Currently recognised sections and bindings are: +.Bl -tag -width "xxx" -offset indent +.It Li [appdefaults] +Specifies the default values to be used for Kerberos applications. +You can specify defaults per application, realm, or a combination of +these. +The preference order is: +.Bl -enum -compact +.It +.Va application Va realm Va option +.It +.Va application Va option +.It +.Va realm Va option +.It +.Va option +.El +.Pp +The supported options are: +.Bl -tag -width "xxx" -offset indent +.It Li forwardable = Va boolean +When obtaining initial credentials, make the credentials forwardable. +.It Li proxiable = Va boolean +When obtaining initial credentials, make the credentials proxiable. +.It Li no-addresses = Va boolean +When obtaining initial credentials, request them for an empty set of +addresses, making the tickets valid from any address. +.It Li ticket_lifetime = Va time +Default ticket lifetime. +.It Li renew_lifetime = Va time +Default renewable ticket lifetime. +.It Li encrypt = Va boolean +Use encryption, when available. +.It Li forward = Va boolean +Forward credentials to remote host (for +.Xr rsh 1 , +.Xr telnet 1 , +etc). +.El +.It Li [libdefaults] +.Bl -tag -width "xxx" -offset indent +.It Li default_realm = Va REALM +Default realm to use, this is also known as your +.Dq local realm . +The default is the result of +.Fn krb5_get_host_realm "local hostname" . +.It Li clockskew = Va time +Maximum time differential (in seconds) allowed when comparing +times. +Default is 300 seconds (five minutes). +.It Li kdc_timeout = Va time +Maximum time to wait for a reply from the kdc, default is 3 seconds. +.It Li v4_name_convert +.It Li v4_instance_resolve +These are described in the +.Xr krb5_425_conv_principal 3 +manual page. +.It Li capath = { +.Bl -tag -width "xxx" -offset indent +.It Va destination-realm Li = Va next-hop-realm +.It ... +.It Li } +.El +This is deprecated, see the +.Li capaths +section below. +.It Li default_cc_name = Va ccname +the default credentials cache name. +The string can contain variables that are expanded on runtime. +Only support variable now is +.Li %{uid} +that expands to the current user id. +.It Li default_etypes = Va etypes ... +A list of default encryption types to use. +.It Li default_etypes_des = Va etypes ... +A list of default encryption types to use when requesting a DES credential. +.It Li default_keytab_name = Va keytab +The keytab to use if no other is specified, default is +.Dq FILE:/etc/krb5.keytab . +.It Li dns_lookup_kdc = Va boolean +Use DNS SRV records to lookup KDC services location. +.It Li dns_lookup_realm = Va boolean +Use DNS TXT records to lookup domain to realm mappings. +.It Li kdc_timesync = Va boolean +Try to keep track of the time differential between the local machine +and the KDC, and then compensate for that when issuing requests. +.It Li max_retries = Va number +The max number of times to try to contact each KDC. +.It Li large_msg_size = Va number +The threshold where protocols with tiny maximum message sizes are not +considered usable to send messages to the KDC. +.It Li ticket_lifetime = Va time +Default ticket lifetime. +.It Li renew_lifetime = Va time +Default renewable ticket lifetime. +.It Li forwardable = Va boolean +When obtaining initial credentials, make the credentials forwardable. +This option is also valid in the [realms] section. +.It Li proxiable = Va boolean +When obtaining initial credentials, make the credentials proxiable. +This option is also valid in the [realms] section. +.It Li verify_ap_req_nofail = Va boolean +If enabled, failure to verify credentials against a local key is a +fatal error. +The application has to be able to read the corresponding service key +for this to work. +Some applications, like +.Xr su 1 , +enable this option unconditionally. +.It Li warn_pwexpire = Va time +How soon to warn for expiring password. +Default is seven days. +.It Li http_proxy = Va proxy-spec +A HTTP-proxy to use when talking to the KDC via HTTP. +.It Li dns_proxy = Va proxy-spec +Enable using DNS via HTTP. +.It Li extra_addresses = Va address ... +A list of addresses to get tickets for along with all local addresses. +.It Li time_format = Va string +How to print time strings in logs, this string is passed to +.Xr strftime 3 . +.It Li date_format = Va string +How to print date strings in logs, this string is passed to +.Xr strftime 3 . +.It Li log_utc = Va boolean +Write log-entries using UTC instead of your local time zone. +.It Li scan_interfaces = Va boolean +Scan all network interfaces for addresses, as opposed to simply using +the address associated with the system's host name. +.It Li fcache_version = Va int +Use file credential cache format version specified. +.It Li krb4_get_tickets = Va boolean +Also get Kerberos 4 tickets in +.Nm kinit , +.Nm login , +and other programs. +This option is also valid in the [realms] section. +.It Li fcc-mit-ticketflags = Va boolean +Use MIT compatible format for file credential cache. +It's the field ticketflags that is stored in reverse bit order for +older than Heimdal 0.7. +Setting this flag to +.Dv TRUE +make it store the MIT way, this is default for Heimdal 0.7. +.El +.It Li [domain_realm] +This is a list of mappings from DNS domain to Kerberos realm. +Each binding in this section looks like: +.Pp +.Dl domain = realm +.Pp +The domain can be either a full name of a host or a trailing +component, in the latter case the domain-string should start with a +period. +The trailing component only matches hosts that are in the same domain, ie +.Dq .example.com +matches +.Dq foo.example.com , +but not +.Dq foo.test.example.com . +.Pp +The realm may be the token `dns_locate', in which case the actual +realm will be determined using DNS (independently of the setting +of the `dns_lookup_realm' option). +.It Li [realms] +.Bl -tag -width "xxx" -offset indent +.It Va REALM Li = { +.Bl -tag -width "xxx" -offset indent +.It Li kdc = Va [service/]host[:port] +Specifies a list of kdcs for this realm. +If the optional +.Va port +is absent, the +default value for the +.Dq kerberos/udp +.Dq kerberos/tcp , +and +.Dq http/tcp +port (depending on service) will be used. +The kdcs will be used in the order that they are specified. +.Pp +The optional +.Va service +specifies over what medium the kdc should be +contacted. +Possible services are +.Dq udp , +.Dq tcp , +and +.Dq http . +Http can also be written as +.Dq http:// . +Default service is +.Dq udp +and +.Dq tcp . +.It Li admin_server = Va host[:port] +Specifies the admin server for this realm, where all the modifications +to the database are performed. +.It Li kpasswd_server = Va host[:port] +Points to the server where all the password changes are performed. +If there is no such entry, the kpasswd port on the admin_server host +will be tried. +.It Li krb524_server = Va host[:port] +Points to the server that does 524 conversions. +If it is not mentioned, the krb524 port on the kdcs will be tried. +.It Li v4_instance_convert +.It Li v4_name_convert +.It Li default_domain +See +.Xr krb5_425_conv_principal 3 . +.It Li tgs_require_subkey +a boolan variable that defaults to false. +Old DCE secd (pre 1.1) might need this to be true. +.El +.It Li } +.El +.It Li [capaths] +.Bl -tag -width "xxx" -offset indent +.It Va client-realm Li = { +.Bl -tag -width "xxx" -offset indent +.It Va server-realm Li = Va hop-realm ... +This serves two purposes. First the first listed +.Va hop-realm +tells a client which realm it should contact in order to ultimately +obtain credentials for a service in the +.Va server-realm . +Secondly, it tells the KDC (and other servers) which realms are +allowed in a multi-hop traversal from +.Va client-realm +to +.Va server-realm . +Except for the client case, the order of the realms are not important. +.El +.It Va } +.El +.It Li [logging] +.Bl -tag -width "xxx" -offset indent +.It Va entity Li = Va destination +Specifies that +.Va entity +should use the specified +.Li destination +for logging. +See the +.Xr krb5_openlog 3 +manual page for a list of defined destinations. +.El +.It Li [kdc] +.Bl -tag -width "xxx" -offset indent +.It Li database Li = { +.Bl -tag -width "xxx" -offset indent +.It Li dbname Li = Va DATABASENAME +Use this database for this realm. +See the info documetation how to configure diffrent database backends. +.It Li realm Li = Va REALM +Specifies the realm that will be stored in this database. +It realm isn't set, it will used as the default database, there can +only be one entry that doesn't have a +.Li realm +stanza. +.It Li mkey_file Li = Pa FILENAME +Use this keytab file for the master key of this database. +If not specified +.Va DATABASENAME Ns .mkey +will be used. +.It Li acl_file Li = PA FILENAME +Use this file for the ACL list of this database. +.It Li log_file Li = Pa FILENAME +Use this file as the log of changes performed to the database. +This file is used by +.Nm ipropd-master +for propagating changes to slaves. +.El +.It Li } +.It Li max-request = Va SIZE +Maximum size of a kdc request. +.It Li require-preauth = Va BOOL +If set pre-authentication is required. +Since krb4 requests are not pre-authenticated they will be rejected. +.It Li ports = Va "list of ports" +List of ports the kdc should listen to. +.It Li addresses = Va "list of interfaces" +List of addresses the kdc should bind to. +.It Li enable-kerberos4 = Va BOOL +Turn on Kerberos 4 support. +.It Li v4-realm = Va REALM +To what realm v4 requests should be mapped. +.It Li enable-524 = Va BOOL +Should the Kerberos 524 converting facility be turned on. +Default is the same as +.Va enable-kerberos4 . +.It Li enable-http = Va BOOL +Should the kdc answer kdc-requests over http. +.It Li enable-kaserver = Va BOOL +If this kdc should emulate the AFS kaserver. +.It Li check-ticket-addresses = Va BOOL +Verify the addresses in the tickets used in tgs requests. +.\" XXX +.It Li allow-null-ticket-addresses = Va BOOL +Allow address-less tickets. +.\" XXX +.It Li allow-anonymous = Va BOOL +If the kdc is allowed to hand out anonymous tickets. +.It Li encode_as_rep_as_tgs_rep = Va BOOL +Encode as-rep as tgs-rep tobe compatible with mistakes older DCE secd did. +.\" XXX +.It Li kdc_warn_pwexpire = Va TIME +The time before expiration that the user should be warned that her +password is about to expire. +.It Li logging = Va Logging +What type of logging the kdc should use, see also [logging]/kdc. +.It Li use_2b = { +.Bl -tag -width "xxx" -offset indent +.It Va principal Li = Va BOOL +boolean value if the 524 daemon should return AFS 2b tokens for +.Fa principal . +.It ... +.El +.It Li } +.It Li hdb-ldap-structural-object Va structural object +If the LDAP backend is used for storing principals, this is the +structural object that will be used when creating and when reading +objects. +The default value is account . +.It Li hdb-ldap-create-base Va creation dn +is the dn that will be appended to the principal when creating entries. +Default value is the search dn. +.El +.It Li [kadmin] +.Bl -tag -width "xxx" -offset indent +.It Li require-preauth = Va BOOL +If pre-authentication is required to talk to the kadmin server. +.It Li password_lifetime = Va time +If a principal already have its password set for expiration, this is +the time it will be valid for after a change. +.It Li default_keys = Va keytypes... +For each entry in +.Va default_keys +try to parse it as a sequence of +.Va etype:salttype:salt +syntax of this if something like: +.Pp +[(des|des3|etype):](pw-salt|afs3-salt)[:string] +.Pp +If +.Ar etype +is omitted it means everything, and if string is omitted it means the +default salt string (for that principal and encryption type). +Additional special values of keytypes are: +.Bl -tag -width "xxx" -offset indent +.It Li v5 +The Kerberos 5 salt +.Va pw-salt +.It Li v4 +The Kerberos 4 salt +.Va des:pw-salt: +.El +.It Li use_v4_salt = Va BOOL +When true, this is the same as +.Pp +.Va default_keys = Va des3:pw-salt Va v4 +.Pp +and is only left for backwards compatibility. +.El +.It Li [password-quality] +Check the Password quality assurance in the info documentation for +more information. +.Bl -tag -width "xxx" -offset indent +.It Li check_library = Va library-name +Library name that contains the password check_function +.It Li check_function = Va function-name +Function name for checking passwords in check_library +.It Li policy_libraries = Va library1 ... libraryN +List of libraries that can do password policy checks +.It Li policies = Va policy1 ... policyN +List of policy names to apply to the password. Builtin policies are +among other minimum-length, character-class, external-check. +.El +.El +.Sh ENVIRONMENT +.Ev KRB5_CONFIG +points to the configuration file to read. +.Sh FILES +.Bl -tag -width "/etc/krb5.conf" +.It Pa /etc/krb5.conf +configuration file for Kerberos 5. +.El +.Sh EXAMPLES +.Bd -literal -offset indent +[libdefaults] + default_realm = FOO.SE +[domain_realm] + .foo.se = FOO.SE + .bar.se = FOO.SE +[realms] + FOO.SE = { + kdc = kerberos.foo.se + v4_name_convert = { + rcmd = host + } + v4_instance_convert = { + xyz = xyz.bar.se + } + default_domain = foo.se + } +[logging] + kdc = FILE:@DBDIR@/kdc.log + kdc = SYSLOG:INFO + default = SYSLOG:INFO:USER +.Ed +.Sh DIAGNOSTICS +Since +.Nm +is read and parsed by the krb5 library, there is not a lot of +opportunities for programs to report parsing errors in any useful +format. +To help overcome this problem, there is a program +.Nm verify_krb5_conf +that reads +.Nm +and tries to emit useful diagnostics from parsing errors. +Note that this program does not have any way of knowing what options +are actually used and thus cannot warn about unknown or misspelled +ones. +.Sh SEE ALSO +.Xr kinit 1 , +.Xr krb5_425_conv_principal 3 , +.Xr krb5_openlog 3 , +.Xr strftime 3 , +.Xr verify_krb5_conf 8 diff -U 3 -H -d -r -N -x Makefile.in -x 'config.h.in*' -x 'output*' -x requests -x 'traces*' -x '*.loT' -x aclocal.m4 -x configure -- heimdal-1.0.1/lib/krb5/replay.c heimdal-1.0.1.work/lib/krb5/replay.c --- heimdal-1.0.1/lib/krb5/replay.c 2007-08-09 10:47:16.000000000 +0300 +++ heimdal-1.0.1.work/lib/krb5/replay.c 2007-12-05 23:55:47.000000000 +0200 @@ -100,7 +100,7 @@ const char* KRB5_LIB_FUNCTION krb5_rc_default_name(krb5_context context) { - return "FILE:/var/run/default_rcache"; + return "FILE:" LOCALSTATEDIR "/run/default_rcache"; } const char* KRB5_LIB_FUNCTION diff -U 3 -H -d -r -N -x Makefile.in -x 'config.h.in*' -x 'output*' -x requests -x 'traces*' -x '*.loT' -x aclocal.m4 -x configure -- heimdal-1.0.1/lib/roken/roken-common.h heimdal-1.0.1.work/lib/roken/roken-common.h --- heimdal-1.0.1/lib/roken/roken-common.h 2007-08-09 10:47:19.000000000 +0300 +++ heimdal-1.0.1.work/lib/roken/roken-common.h 2007-12-05 23:56:07.000000000 +0200 @@ -133,7 +133,7 @@ #endif #ifndef _PATH_VARRUN -#define _PATH_VARRUN "/var/run/" +#define _PATH_VARRUN LOCALSTATEDIR "/run/" #endif #ifndef _PATH_BSHELL