Adding upstream version 2:4.20.0+dfsg.upstream/2%4.20.0+dfsg

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 1897 insertions, 0 deletions

diff --git a/third_party/heimdal/doc/setup.texi b/third_party/heimdal/doc/setup.texi
new file mode 100644
index 0000000..1df24d1
--- /dev/null
+++ b/third_party/heimdal/doc/setup.texi
@@ -0,0 +1,1897 @@
+@c $Id$
+
+@node Setting up a realm, Applications, Building and Installing, Top
+
+@chapter Setting up a realm
+
+A
+@cindex realm
+realm is an administrative domain containing any number of Kerberos
+principals and namespaces.  The name of a Kerberos realm is
+usually a domain name in uppercase.  Call your realm the same
+as your site's 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::
+* Using namespaces and synthetic principals to keep the database small::
+* Using hard aliases for realm migration::
+* Using soft aliases for configuring referrals::
+* Checking the setup::
+* keytabs::
+* Remote administration::
+* Password changing::
+* Testing clients and servers::
+* Slave Servers::
+* Incremental propagation::
+* Encryption types and salting::
+* Credential cache server - KCM::
+* Cross realm::
+* Transit policy::
+* Setting up DNS::
+* Using LDAP to store the database::
+* Providing Kerberos credentials to servers and programs::
+* Setting up PK-INIT::
+* Debugging Kerberos problems::
+@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, and
+a page for it in section 5 of the system manual.
+
+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.
+
+Configuration files can also include other files, or all files in a
+directory.  Use absolute paths in include directives.  When including a
+directoty, only files whose names consist of alphanumeric, hyphen, or
+underscore characters are allowed, though they may end in '.conf'.
+
+@example
+include /some/config/file
+includedir /some/config/directory
+[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@.
+Finally the @samp{domain_realm} section contains a list of
+mappings from domains to realms.
+
+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
+                kdc = 130.237.237.17
+                kdc = [2001:6b0:1:ea::100]:88
+        @}
+[domain_realm]
+        .my.domain = MY.REALM
+
+@end example
+
+When realm names correspond to domain names, one can avoid having to
+configure @samp{domain_realm} mappings, and one can avoid having to
+configure a @samp{default_realm} in the @samp{libdefaults} section.
+DNS SRV resource records can be used for KDC discovery, obviating the
+need list KDCs in the @samp{realms} section of the @samp{krb5.conf}
+file.
+
+@cindex KRB5_CONFIG
+The Heimdal libraries and commands (and the MIT ones too), support the
+use of the environment variable @samp{KRB5_CONFIG} for using an
+alternative configuration.
+
+@example
+env KRB5_CONFIG=$HOME/etc/krb5.conf kinit user@@REALM
+@end example
+
+@cindex KRB5CCNAME
+The Heimdal libraries and commands (and the MIT ones too), support the
+use of the environment variable @samp{KRB5CCNAME} for specifying a
+credentials cache to use.  See the @manpage{kinit,1} for details.
+
+@cindex KRB5_KTNAME
+The Heimdal libraries and commands (and the MIT ones too), support the
+use of the environment variable @samp{KRB5_KTNAME} for specifying a
+keytab file to use for server operations.  See the @manpage{kinit,1} for
+details.
+
+@cindex KRB5_CLIENT_KTNAME
+The Heimdal libraries and commands (and the MIT ones too), support the
+use of the environment variable @samp{KRB5_CLIENT_KTNAME} for specifying
+a keytab file to use for client operations.  See the @manpage{kinit,1}
+for details.
+
+@cindex GSS_MECH_CONFIG
+The GSS-API mechanism configuration file can also be changed from the
+default with the enviornment variable @samp{GSS_MECH_CONFIG}. Note that
+this file can only configure additional plugin mechanisms: Kerberos,
+NTLM and SPNEGO are built in to the Heimdal GSS-API library.
+
+@node Creating the database, Modifying the database, Configuration file, Setting up a realm
+@section Creating the database
+
+The Heimdal database library, @code{libhdb}, will look for the
+database in the directory @file{@value{dbdir}}, so you should probably
+create that directory.  Make sure the directory has restrictive
+permissions.
+
+@example
+# mkdir /var/heimdal
+# chmod og-rwx /var/heimdal
+@end example
+
+Heimdal supports various database backends: lmdb (LMDB), db3 (Berkeley
+DB 3.x, 4.x, or 5.x), db1 (Berkeley DB 2.x), sqlite (SQLite3), and ldap
+(LDAP).  The default is @value{dbtype}, and is selected at configure
+time from one of lmdb, db3, or db1.
+
+These defaults can be overriden in the 'database' key in the @samp{kdc}
+section of the configuration.
+
+@example
+[kdc]
+        database = @{
+                dbname = lmdb:/path/to/db-file
+                realm = REALM
+                acl_file = /path/to/kadmind.acl
+                mkey_file = /path/to/mkey
+                log_file = /path/to/iprop-log-file
+        @}
+@end example
+
+To use LDAP, see @xref{Using LDAP to store the database}.
+
+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
+@kbd{--random-key} flag 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.
+
+Note that encryption of the keys in the database is only useful when
+the database is stored on external storage media that is easy to
+steal. Thus for the most part there is no need to encrypt the keys in
+the database.
+
+To initialise the database use the @command{kadmin} program, with the
+@kbd{-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, Using namespaces and synthetic principals to keep the database small, 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 Using namespaces and synthetic principals to keep the database small, Checking the setup, Modifying the database, Setting up a realm
+@section Using namespaces and synthetic principals to keep the database small
+
+Keeping a Kerberos database small is useful for several reasons:
+
+@itemize @bullet
+@item to avoid low write transaction rates
+@item to avoid replication latency
+@item to keep re-keying costs down
+@end itemize
+
+To avoid needing database entries for client principals, configure and
+enable PKINIT and synthetic principals. Alternatively, configure and
+enable the use of GSS-API pre-authentication, though this is currently
+experimental.
+
+With synthetic client principals enabled, client principals will be
+deemed to exist if they can pre-authenticate using a method that
+yields an authenticated principal name, and if the client principal
+does not already exist.
+
+To lock out or disable a specific synthetic client principal, create
+it in the database with the desired attributes.
+
+To avoid needing database entries for host-based service principals,
+create virtual host-based service principal namespaces using the
+@command{add_ns} sub-command of the @command{kadmin} command. Virtual
+host-based service principals will exist for every possible hostname
+under a containing namespace, with keys derived from the namespace's
+based keys and the current key rotation period. The long-term keys of
+virtual host-based service principals rotate on a hard schedule as
+configured for their namespaces, so hosts and applications using them
+must keep re-fetching their @samp{keytabs}. See the manual pages for
+@file{krb5.conf}, @command{kadmin}, and @command{httpkadmind} for more
+details.
+
+Using these features one can end up with a database that contains just
+@code{krbtgt} principals, principals for locked users, and principals
+that are neither @code{krbtgt}, user, nor host-based services.
+
+@node Using hard aliases for realm migration, Using soft aliases for configuring referrals, Using namespaces and synthetic principals to keep the database small, Setting up a realm
+@section Using hard aliases for realm migration
+
+The Heimdal @command{kadmin} command can be used to add aliases to
+principal entries in the Heimdal database.  Aliases of principals of
+the form @samp{WELLKNOWN/REFERRALS/TARGET} or
+@samp{WELLKNOWN/REFERRALS/TARGET/anything} are "soft" aliases.
+Aliases of principals of other forms are "hard" aliases.
+
+When a client makes a request for a principal's alias, and it does not
+use the KDC request "canonicalize" option flag, the Heimdal KDC will
+treat the alias as a distinct principal that happens to share
+attributes and long-term symmetric keys and salts with the principal
+it is an alias of.
+
+This is useful for, for example, ensuring that host-based principals
+can be referred to by any aliases.
+
+This can also be very useful for renaming realms: add new
+@code{krbtgt} principals for the new realms, then add aliases to
+existing principals in their new realms. For example, a user with a
+principal @code{joe@@A} can be given an alias of
+@code{joes@@B}, and
+then they can @code{kinit joes@@B} and get Kerberos tickets for
+@code{joes@@B}. Similarly, a service principal such as
+@code{HTTP/foo.bar.baz.example@@BAZ.EXAMPLE} can be given an alias such as
+@code{HTTP/foo.bar.baz.example@@BAR.BAZ.EXAMPLE}, or even
+@code{HTTP/foobar.new-domain.example@@NEW-DOMAIN.EXAMPLE}, and
+requesting tickets with those aliases as the service names will work.
+
+@node Using soft aliases for configuring referrals, Checking the setup, Using hard aliases for realm migration, Setting up a realm
+@section Using soft aliases for configuring referrals
+
+Soft aliases, which are aliases of principals of the form
+@code{WELLKNOWN/REFERRALS/TARGET} or
+@code{WELLKNOWN/REFERRALS/TARGET/anything}, are used to generate
+referrals to other realms. Specifically, the realm of a soft alias'
+canonical name is the realm to issue referrals to.
+
+Soft aliases can be used to configure individual referrals, but also
+of entire namespaces of hostnames. To configure the issuance of
+referrals for entire namespaces, make a soft alias of the form
+@code{WELLKNOWN/HOSTBASED-NAMESPACE/service/namespace-fqdn@@REALM} to
+have the TGS for that @samp{REALM} issue referrals for all principals
+of the form @code{service/hostname@@REALM} where the hostname component
+is a sub-domain of the namespace component of the alias name.
+
+For example, a soft alias name
+@code{WELLKNOWN/HOSTBASED-NAMESPACE/host/cloud.bar.example@@BAR.EXAMPLE}
+to a realm @samp{B} will cause the KDC to issue referrals to @samp{B}
+for any principals such as
+@samp{host/foo.cloud.bar.example@@BAR.EXAMPLE}, and
+@samp{host/baz.cloud.bar.example@@BAR.EXAMPLE}, and so on.
+
+@node Checking the setup, keytabs, Using namespaces and synthetic principals to keep the database small, 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 -l check REALM.EXAMPLE.ORG
+@end example
+
+@node keytabs, Remote administration, 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{add}
+(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 Remote administration, Password changing, keytabs, 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}.  If your realm is not setup to use DNS, you might also
+need to add a @samp{kpasswd_server} entry to the realm configuration
+in @file{/etc/krb5.conf} on client machines:
+
+@example
+[realms]
+        MY.REALM = @{
+                kdc = my.kdc my.slave.kdc
+                kpasswd_server = my.kdc
+        @}
+@end example
+
+@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 modulename: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}).  All built-in policies can be qualified with
+a module name of @samp{builtin} to unambiguously specify the built-in
+policy and not a policy by the same name from a loaded module.
+
+The built-in policies 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.
+
+@item enforce_on_admin_set
+
+The enforce_on_admin_set check subjects administrative password updates to the
+password policy. An administrative password update is a create principal or
+change password request via @command{kadmind}, or a set password request via
+@command{kpasswdd}. (A set password request is one where the authenticating
+principal differs from the principal whose password is being changed.) Password
+policies are always ignored if the authenticating principal is the kadmin
+service itself, for example when running @command{kadmin} in local mode. The
+default value for enforce_on_admin_set if not given is true.
+
+@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{verify-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 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.
+
+In addition on listening on the network to get connection from new
+slaves, the ipropd-master also listens on a status unix
+socket. kadmind and kpasswdd both open that socket when a transation
+is done and written a notification to the socket. That cause
+ipropd-master to check for new version in the log file. As a fallback in
+case a notification is lost by the unix socket, the log file is
+checked after 30 seconds of no event.
+
+@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
+
+@example
+slave# /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.
+
+@subsection Status of iprop master and slave
+
+Both the master and slave provides status of the world as they see it.
+
+The master write outs the current status of the slaves, last seen and
+their version number in @file{/var/heimdal/slaves-stats}.
+
+The slave write out the current status in @file{/var/heimdal/ipropd-slave-status}.
+
+These locations can be changed with command line options, and in the
+case of @command{ipropd_master}, the configuration file.
+
+@node Encryption types and salting, Credential cache server - KCM, 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{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{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. It's
+the cell name appended to the password.
+
+@end itemize
+
+@node Credential cache server - KCM, Cross realm, Encryption types and salting, Setting up a realm
+@section Credential cache server - KCM
+@cindex KCM
+@cindex Credential cache server
+
+When KCM running is easy for users to switch between different
+kerberos principals using @file{kswitch} or built in support in
+application, like OpenSSH's GSSAPIClientIdentity.
+
+Other advantages are that there is the long term credentials are not
+written to disk and on reboot the credential is removed when kcm
+process stopps running.
+
+Configure the system startup script to start the kcm process,
+@file{/usr/heimdal/libexec/kcm} and then configure the system to use kcm in @file{krb5.conf}.
+
+@example
+[libdefaults]
+	default_cc_type = KCM
+@end example
+
+Now when you run @command{kinit} it doesn't overwrite your existing
+credentials but rather just add them to the set of
+credentials. @command{klist -l} lists the credentials and the star
+marks the default credential.
+
+@example
+$ kinit lha@@KTH.SE
+lha@@KTH.SE's Password: 
+$ klist -l
+  Name         Cache name               Expires         
+lha@@KTH.SE   0                        Nov 22 23:09:40   *
+lha@@SU.SE    Initial default ccache   Nov 22 14:14:24   
+@end example
+
+When switching between credentials you can use @command{kswitch}.
+
+@example
+$ kswitch -i
+     Principal
+1    lha@@KTH.SE
+2    lha@@SU.SE
+Select number: 2
+@end example
+
+After switching, a new set of credentials are used as default.
+
+@example
+$ klist -l
+  Name         Cache name               Expires         
+lha@@SU.SE    Initial default ccache   Nov 22 14:14:24   *
+lha@@KTH.SE   0                        Nov 22 23:09:40   
+@end example
+
+Som applications, like openssh with Simon Wilkinsons patch applied,
+support specifiying that credential to use.  The example below will
+login to the host computer.kth.se using lha@@KTH.SE (not the current
+default credential).
+
+@example
+$ ssh \
+   -o GSSAPIAuthentication=yes \
+   -o GSSAPIKeyExchange=yes \
+   -o GSSAPIClientIdentity=lha@@KTH.SE \
+   computer.kth.se
+@end example
+
+
+
+@node Cross realm, Transit policy, Credential cache server - KCM, 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
+
+Under some circumstances, you may not wish to set up direct
+cross-realm trust with every realm to which you wish to authenticate
+or from which you wish to accept authentications. Kerberos supports
+multi-hop cross-realm trust where a client principal in realm A
+authenticates to a service in realm C through a realm B with which
+both A and C have cross-realm trust relationships. In this situation,
+A and C need not set up cross-realm principals between each other.
+
+If you want to use cross-realm authentication through an intermediate
+realm, it must be explicitly allowed by either the KDCs for the realm
+to which the client is authenticating (in this case, realm C), or the
+server receiving the request. This is done in @file{krb5.conf} in the
+@code{[capaths]} section.
+
+In addition, the client in realm A need to be configured to know how
+to reach realm C via realm B. This can be done either on the client or
+via KDC configuration in the KDC for realm A.
+
+@subsection Allowing cross-realm transits
+
+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. For the
+authentication to be accepted by the final destination realm, all of
+the transited realms must be listed as trusted in the @code{[capaths]}
+configuration, either in the KDC for the destination realm or on the
+server receiving the authentication.
+
+The syntax for @code{[capaths]} section is:
+
+@example
+[capaths]
+        CLIENT-REALM = @{
+                SERVER-REALM = PERMITTED-CROSS-REALMS ...
+        @}
+@end example
+
+In the following example, the realm @code{STACKEN.KTH.SE} only has
+direct cross-realm set up with @code{KTH.SE}.  @code{KTH.SE} has
+direct cross-realm set up with @code{STACKEN.KTH.SE} and @code{SU.SE}.
+@code{DSV.SU.SE} only has direct cross-realm set up with @code{SU.SE}.
+The goal is to allow principals in the @code{DSV.SU.SE} or
+@code{SU.SE} realms to authenticate to services in
+@code{STACKEN.KTH.SE}.  This is done with the following
+@code{[capaths]} entry on either the server accepting authentication
+or on the KDC for @code{STACKEN.KTH.SE}.
+
+@example
+[capaths]
+	SU.SE = @{
+                    STACKEN.KTH.SE = KTH.SE
+	@}
+	DSV.SU.SE = @{
+                    STACKEN.KTH.SE = SU.SE KTH.SE
+	@}
+@end example
+
+The first entry allows cross-realm authentication from clients in
+@code{SU.SE} transiting through @code{KTH.SE} to
+@code{STACKEN.KTH.SE}.  The second entry allows cross-realm
+authentication from clients in @code{DSV.SU.SE} transiting through
+both @code{SU.SE} and @code{KTH.SE} to @code{STACKEN.KTH.SE}.
+
+Be careful of which realm goes where; it's easy to put realms in the
+wrong place.  The block is tagged with the client realm (the realm of
+the principal authenticating), and the realm before the equal sign is
+the final destination realm: the realm to which the client is
+authenticating.  After the equal sign go all the realms that the
+client transits through.
+
+The order of the @code{PERMITTED-CROSS-REALMS} is not important when
+doing transit cross realm verification.
+
+@subsection Configuring client cross-realm transits
+
+The @code{[capaths]} section is also used for another purpose: to tell
+clients which realm to transit through to reach a realm with which
+their local realm does not have cross-realm trust.  This can be done
+by either putting a @code{[capaths]} entry in the configuration of the
+client or by putting the entry in the configuration of the KDC for the
+client's local realm.  In the latter case, the KDC will then hand back
+a referral to the client when the client requests a cross-realm ticket
+to the destination realm, telling the client to try to go through an
+intermediate realm.
+
+For client configuration, the order of @code{PERMITTED-CROSS-REALMS}
+is significant, since only the first realm in this section (after the
+equal sign) is used by the client.
+
+For example, again consider the @code{[capaths]} entry above for the
+case of a client in the @code{SU.SE} realm, and assume that the client
+or the @code{SU.SE} KDC has that @code{[capaths]} entry.  If the
+client attempts to authenticate to a service in the
+@code{STACKEN.KTH.SE} realm, that entry says to first authenticate
+cross-realm to the @code{KTH.SE} realm (the first realm listed in the
+@code{PERMITTED-CROSS-REALMS} section), and then from there to
+@code{STACKEN.KTH.SE}.
+
+Each entry in @code{[capaths]} can only give the next hop, since only
+the first realm in @code{PERMITTED-CROSS-REALMS} is used.  If, for
+instance, a client in @code{DSV.SU.SE} had a @code{[capaths]}
+configuration as above but without the first block for @code{SU.SE},
+they would not be able to reach @code{STACKEN.KTH.SE}.  They would get
+as far as @code{SU.SE} based on the @code{DSV.SU.SE} entry in
+@code{[capaths]} and then attempt to go directly from there to
+@code{STACKEN.KTH.SE} and get stuck (unless, of course, the
+@code{SU.SE} KDC had the additional entry required to tell the client
+to go through @code{KTH.SE}).
+
+@subsection Active Directory forest example
+
+One common place where a @code{[capaths]} configuration is desirable
+is with Windows Active Directory forests.  One common Active Directory
+configuration is to have one top-level Active Directory realm but then
+divide systems, services, and users into child realms (perhaps based
+on organizational unit).  One generally establishes cross-realm trust
+only with the top-level realm, and then uses transit policy to permit
+authentications to and from the child realms.
+
+For example, suppose an organization has a Heimdal realm
+@code{EXAMPLE.COM}, a Windows Active Directory realm
+@code{WIN.EXAMPLE.COM}, and then child Active Directory realms
+@code{ENGR.WIN.EXAMPLE.COM} and @code{SALES.WIN.EXAMPLE.COM}.  The
+goal is to allow users in any of these realms to authenticate to
+services in any of these realms.  The @code{EXAMPLE.COM} KDC (and
+possibly client) configuration should therefore contain a
+@code{[capaths]} section as follows:
+
+@example
+[capaths]
+	ENGR.WIN.EXAMPLE.COM = @{
+		EXAMPLE.COM = WIN.EXAMPLE.COM
+	@}
+	SALES.WIN.EXAMPLE.COM = @{
+		EXAMPLE.COM = WIN.EXAMPLE.COM
+	@}
+	EXAMPLE.COM = @{
+		ENGR.WIN.EXAMPLE.COM = WIN.EXAMPLE.COM
+		SALES.WIN.EXAMPLE.COM = WIN.EXAMPLE.COM
+	@}
+@end example
+
+The first two blocks allow clients in the @code{ENGR.WIN.EXAMPLE.COM}
+and @code{SALES.WIN.EXAMPLE.COM} realms to authenticate to services in
+the @code{EXAMPLE.COM} realm.  The third block tells the client (or
+tells the KDC to tell the client via referrals) to transit through
+@code{WIN.EXAMPLE.COM} to reach these realms.  Both sides of the
+configuration are needed for bi-directional transited cross-realm
+authentication.
+
+@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.
+
+This assumes, OpenLDAP 2.3 or later.
+
+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
+Optionally configure OpenLDAP with @kbd{--enable-local} to enable the
+local transport.
+
+@item
+Add the hdb schema to the LDAP server, it's 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. For
+example:
+
+@example
+access to *
+        by dn.exact="uid=heimdal,dc=services,dc=example,dc=com" write
+        ...
+
+authz-regexp "gidNumber=.*\\\+uidNumber=0,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.
+
+If a non-local LDAP connection is used, the authz-regexp is not
+needed as Heimdal will bind to LDAP over the network using
+provided credentials.
+
+Since Heimdal talks to the LDAP server over a UNIX domain socket when
+configured for ldapi:///, and uses external sasl authentication, it's
+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]
+	# Optional configuration
+	hdb-ldap-structural-object = inetOrgPerson
+	hdb-ldap-url = ldapi:/// (default), ldap://hostname or ldaps://hostname
+	hdb-ldap-secret-file = /path/to/file/containing/ldap/credentials
+	hdb-ldap-start-tls = false
+
+        database = @{
+                dbname = ldap:ou=KerberosPrincipals,dc=example,dc=com
+                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.
+
+If connecting to a server over a non-local transport, the @samp{hdb-ldap-url}
+and @samp{hdb-ldap-secret-file} options must be provided. The
+@samp{hdb-ldap-secret-file} must contain the bind credentials:
+
+@example
+[kdc]
+	hdb-ldap-bind-dn = uid=heimdal,dc=services,dc=example,dc=com
+	hdb-ldap-bind-password = secretBindPassword
+@end example
+
+The @samp{hdb-ldap-secret-file} and should be protected with appropriate
+file permissions
+
+@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> add 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 smbk5pwd overlay
+
+The smbk5pwd overlay, updates the krb5Key and krb5KeyVersionNumber
+appropriately when it receives an LDAP Password change Extended
+Operation:
+
+@url{http://www.openldap.org/devel/cvsweb.cgi/contrib/slapd-modules/smbk5pwd/README?hideattic=1&sortbydate=0}
+
+@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
+@kbd{--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, Debugging Kerberos problems, Providing Kerberos credentials to servers and programs, Setting up a realm
+@section Setting up PK-INIT
+
+PK-INIT leverages an existing PKI (public key infrastructure), using
+certificates to get the initial ticket (usually the krbtgt
+ticket-granting ticket).
+
+To use PK-INIT you must first have a PKI. If you don't have one, it is
+time to create it. You should first read the whole current chapter of
+the document to see the requirements imposed on the CA software.
+
+A mapping between the PKI certificate and what principals that
+certificate is allowed to use must exist. There are several ways to do
+this. The administrator can use a configuration file, store the
+principal in the SubjectAltName extension of the certificate, or store
+the mapping in the principals entry in the kerberos database.
+
+@section Certificates
+
+This and following subsection documents the requirements on the KDC
+and client certificates and the format used in the id-pkinit-san
+OtherName extension.
+
+On how to create certificates, you should read @ref{Use OpenSSL to
+create certificates}.
+
+@subsection KDC certificate
+
+The certificate for the KDC has several 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.  Also, if the certificate has a
+nameConstraints extension with a Generalname with dNSName or iPAdress,
+it must match the hostname or adress of the KDC.
+
+The client is not required by the standard to check the server
+certificate for this information if the client has external
+information confirming which certificate the KDC is supposed to be
+using. However, adding this information to the KDC certificate removes
+the need to specially configure the client to recognize the KDC
+certificate.
+
+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
+a password or other private information) that it is supposed to keep
+secret.
+
+@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 configuration 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.
+
+This behavior is controlled by KDC configuration option:
+
+@example
+[kdc]
+	pkinit_principal_in_certificate = yes
+@end example
+
+@subsubsection Using KRB5PrincipalName in id-pkinit-san
+
+The OtherName extension in the GeneralName is used to do the mapping
+between certificate and principal.  For the KDC certificate, this
+stores the krbtgt principal name for that KDC.  For the client
+certificate, this stores the principal for which that certificate is
+allowed to get tickets.
+
+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 supports several different syntaxes for specifying
+certificate files or formats. Several formats may be used:  PEM,
+certificates embedded in PKCS#12 files, certificates embedded in
+PKCS#11 devices, and raw DER encoded certificates.
+
+Those formats may be specified as follows:
+
+@table @asis
+
+@item DIR:
+
+DIR specifies a directory which contains certificates in the DER or
+PEM format.
+
+The main feature of DIR is that the directory is read on demand when
+iterating over certificates. This allows applications, in some
+situations, to avoid having to store all certificates in memory.  It's
+very useful for tests that iterate over large numbers of certificates.
+
+The syntax is:
+
+@example
+DIR:/path/to/der/files
+@end example
+
+@item FILE:
+
+FILE: specifies a file that contains a certificate or 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. Multiple files may be specified, separated by
+commas.
+
+It's useful to have one PEM file that contains all the trust anchors.
+
+The syntax is:
+
+@example
+FILE:certificate.pem,private-key.key,other-cert.pem,....
+@end example
+
+@item PKCS11:
+
+PKCS11: is used to handle smartcards via PKCS#11 drivers, such as
+soft-token, opensc, or muscle. The argument specifies a shared object
+that implements the PKCS#11 API. The default is to use all slots on
+the device/token.
+
+The syntax is:
+
+@example
+PKCS11:shared-object.so
+@end example
+
+@item PKCS12:
+
+PKCS12: is used to handle PKCS#12 files. PKCS#12 files commonly have
+the extension pfx or p12.
+
+The 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 the subsections below for how to do that. Then, you can
+use kinit to get yourself tickets. For example:
+
+@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 PKCS#11 it can look like this instead:
+
+@example
+$ kinit -C PKCS11:/usr/heimdal/lib/hx509.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
+
+@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
+
+Configuration options for the KDC.
+
+@table @asis
+@item enable-pkinit = bool
+
+Enable PKINIT for this KDC.
+
+@item pkinit_identity = string
+
+Identity that the KDC will use when talking to clients. Mandatory.
+
+@item pkinit_anchors = string
+
+Trust anchors that the KDC will use when evaluating the trust of the
+client certificate. Mandatory.
+
+@item pkinit_pool = strings ...
+
+Extra certificate the KDC will use when building trust chains if it
+can't find enough certificates in the request from the client.
+
+@item pkinit_allow_proxy_certificate = bool
+
+Allow clients to use proxy certificates. The root certificate
+of the client's End Entity certificate is used for authorisation.
+
+@item pkinit_win2k_require_binding = bool
+
+Require windows clients up be upgrade to not allow cut and paste
+attack on encrypted data, applies to Windows XP and windows 2000
+servers.
+
+@item pkinit_principal_in_certificate = bool
+
+Enable the KDC to use id-pkinit-san to determine to determine the
+mapping between a certificate and principal.
+
+@end table
+
+@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 = no
+	pkinit_win2k_require_binding = yes
+	pkinit_principal_in_certificate = no
+@end example
+
+@subsection Using pki-mapping file
+
+Note that the file contents are 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
+
+You can also store the subject of the certificate in the principal
+entry in the kerberos database.
+
+@example
+kadmin modify --pkinit-acl="CN=baz,DC=test,DC=h5l,DC=se" user@@REALM
+@end example
+
+@section Use hxtool to create certificates
+
+@subsection Generate certificates
+
+First, you need to generate a CA certificate. This example creates a
+CA certificate that will be valid for 10 years.
+
+You need to change --subject in the command below to something
+appropriate for your site.
+
+@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 to something appropriate for your site.
+
+@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 certificates. For your first client,
+generate a certificate of 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 to something appropriate for your site. You can omit
+--pk-init-principal if you're going to use the ACL file instead.
+
+@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
+they provide a good test of whether 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
+@anchor{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 an
+@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 could 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 has 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 so that it
+includes all the information required to 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''.
+
+@node Debugging Kerberos problems, , Setting up PK-INIT, Setting up a realm
+@section Debugging Kerberos problems
+
+To debug Kerberos client and server problems you can enable debug
+tracing by adding the following to @file{/etc/krb5.conf}. Note that the
+trace logging is sparse at the moment, but will continue to improve.
+
+@example
+[logging]
+        libkrb5 = 0-/SYSLOG:
+@end example
+
+
+
+