oysteikt/heimdal
0
0
Fork 0
Code Issues 5 Pull Requests Releases Activity

doc: Document namespaces and synthetic principals

Browse Source
This commit is contained in:
Nicolas Williams
2022-03-16 17:50:23 -05:00
parent 0878a568f9
commit a460911b03
1 changed files with 71 additions and 19 deletions
Download Patch File Download Diff File Expand all files Collapse all files

90
doc/setup.texi
View File

@@ -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