heimdal: Vendor import f62e2f278vendor/heimdal/7.8.0-2023-06-10-f62e2f278vendor/heimdal

Heimdal 7.8.0 does not support OpenSSL 3.0. 7.9.0 will but it hasn't
been released yet. We are importing f62e2f278 for its OpenSSL 3.0
support.

1 files changed, 170 insertions, 33 deletions

diff --git a/doc/setup.texi b/doc/setup.texi
index 4caf752fc873..1df24d12c651 100644
--- a/doc/setup.texi
+++ b/doc/setup.texi
@@ -6,15 +6,19 @@
 
 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
+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::
@@ -40,7 +44,8 @@ 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.
+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
@@ -52,7 +57,14 @@ separated from the equal sign with some whitespace). Subsections have a
 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
@@ -77,11 +89,9 @@ 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.
+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.
@@ -101,25 +111,52 @@ with contents similar to the following.
 
 @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.
+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
-If you want to use a different configuration file then the default you
-can point a file with the environment variable @samp{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 database library 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.
+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
@@ -128,8 +165,8 @@ Make sure the directory has restrictive permissions.
 
 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 build time
-from one of lmdb, db3, or db1.
+(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.
@@ -166,6 +203,11 @@ 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
@@ -220,7 +262,7 @@ 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
+@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.
@@ -282,7 +324,101 @@ R second
 
 @c Describe more of kadmin commands here...
 
-@node Checking the setup, keytabs, Modifying the database, Setting up a realm
+@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
@@ -463,6 +599,17 @@ 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
@@ -650,10 +797,6 @@ 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.
@@ -672,12 +815,6 @@ 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
@@ -1747,7 +1884,7 @@ Certificates in Windows''.
 @section Debugging Kerberos problems
 
 To debug Kerberos client and server problems you can enable debug
-traceing by adding the following to @file{/etc/krb5,conf}. Note that the
+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