diff options
Diffstat (limited to 'third_party/heimdal/doc/setup.texi')
| -rw-r--r-- | third_party/heimdal/doc/setup.texi | 1897 |
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 + + + + |