From a460911b032ce4f19dec8f836f8c20629b108917 Mon Sep 17 00:00:00 2001 From: Nicolas Williams Date: Wed, 16 Mar 2022 17:50:23 -0500 Subject: [PATCH] doc: Document namespaces and synthetic principals --- doc/setup.texi | 90 +++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 71 insertions(+), 19 deletions(-) diff --git a/doc/setup.texi b/doc/setup.texi index 8600d3471..16be95da9 100644 --- a/doc/setup.texi +++ b/doc/setup.texi @@ -6,15 +6,17 @@ 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:: * Checking the setup:: * keytabs:: * Remote administration:: @@ -40,7 +42,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 @@ -106,14 +109,17 @@ 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 @@ -122,15 +128,16 @@ env KRB5_CONFIG=$HOME/etc/krb5.conf kinit user@@REALM @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 only configures additional plugin mechanisms: Kerberos, NTLM -and SPNEGO are built in to the Heimdal GSS-API library. +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 @@ -139,8 +146,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. @@ -177,6 +184,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 @@ -231,7 +243,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. @@ -293,7 +305,47 @@ 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 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