[capaths]
---------

In order to perform direct (non-hierarchical) cross-realm
authentication, a database is needed to construct the authentication
paths between the realms.  This section defines that database.

A client will use this section to find the authentication path between
its realm and the realm of the server.  The server will use this section
to verify the authentication path used by the client, by checking the
transited field of the received ticket.

There is a tag for each participating realm, and each tag has subtags
for each of the realms.  The value of the subtags is an intermediate
realm which may participate in the cross-realm authentication.  The
subtags may be repeated if there is more then one intermediate realm.  A
value of "."  means that the two realms share keys directly, and no
intermediate realms should be allowd to participate.

There are n**2 possible entries in this table, but only those entries
which will be needed on the client or the server need to be present.
The client needs a tag for its local realm, with subtags for all the
realms of servers it will need to authenticate with.  A server needs a
tag for each realm of the clients it will serve.

For example, ANL.GOV, PNL.GOV, and NERSC.GOV all wish to use the ES.NET
realm as an intermediate realm.  ANL has a sub realm of TEST.ANL.GOV
which will authenticate with NERSC.GOV but not PNL.GOV.  The [capaths]
section for ANL.GOV systems would look like this:

     [capaths]
         ANL.GOV = {
             TEST.ANL.GOV = .
             PNL.GOV = ES.NET
             NERSC.GOV = ES.NET
             ES.NET = .
         }
         TEST.ANL.GOV = {
             ANL.GOV = .
         }
         PNL.GOV = {
             ANL.GOV = ES.NET
         }
         NERSC.GOV = {
             ANL.GOV = ES.NET
         }
         ES.NET = {
             ANL.GOV = .
         }

The [capaths] section of the configuration file used on NERSC.GOV
systems would look like this:

     [capaths]
         NERSC.GOV = {
             ANL.GOV = ES.NET
             TEST.ANL.GOV = ES.NET
             TEST.ANL.GOV = ANL.GOV
             PNL.GOV = ES.NET
             ES.NET = .
         }
         ANL.GOV = {
             NERSC.GOV = ES.NET
         }
         PNL.GOV = {
             NERSC.GOV = ES.NET
         }
         ES.NET = {
             NERSC.GOV = .
         }
         TEST.ANL.GOV = {
             NERSC.GOV = ANL.GOV
             NERSC.GOV = ES.NET
         }

In the above examples, the ordering is not important, except when the
same subtag name is used more then once.  The client will use this to
determine the path.  (It is not important to the server, since the
transited field is not sorted.)

This feature is not currently supported by DCE.  DCE security servers
can be used with Kerberized clients and servers, but versions prior to
DCE 1.1 did not fill in the transited field, and should be used with
caution.

Sample krb5.conf File
---------------------

Here is an example of a generic `krb5.conf' file:

     [libdefaults]
         default_realm = ATHENA.MIT.EDU
         default_tkt_enctypes = des3-hmac-sha1 des-cbc-crc
         default_tgs_enctypes = des3-hmac-sha1 des-cbc-crc
         dns_lookup_kdc = true
         dns_lookup_realm = false

     [realms]
         ATHENA.MIT.EDU = {
             kdc = kerberos.mit.edu
             kdc = kerberos-1.mit.edu
             kdc = kerberos-2.mit.edu:750
             admin_server = kerberos.mit.edu
             master_kdc = kerberos.mit.edu
             default_domain = mit.edu
         }
         EXAMPLE.COM = {
             kdc = kerberos.example.com
             kdc = kerberos-1.example.com
             admin_server = kerberos.example.com
         }

     [domain_realm]
         .mit.edu = ATHENA.MIT.EDU
         mit.edu = ATHENA.MIT.EDU

     [capaths]
         ATHENA.MIT.EDU = {
         	EXAMPLE.COM = .
         }
         EXAMPLE.COM = {
         	ATHENA.MIT.EDU = .
         }

     [logging]
         kdc = SYSLOG:INFO
         admin_server = FILE=/var/kadm5.log

kdc.conf
========

The `kdc.conf' file contains KDC configuration information, including
defaults used when issuing Kerberos tickets.  Normally, you should
install your `kdc.conf' file in the directory `/usr/local/var/krb5kdc'.
You can override the default location by setting the environment
variable `KRB5_KDC_PROFILE'.

The `kdc.conf' file is set up in the same format as the `krb5.conf'
file.  (see krb5.conf.)  The `kdc.conf' file may contain any or all
of the following three sections:

kdcdefaults
     Contains default values for overall behavior of the KDC.

realms
     Contains subsections keyed by Kerberos realm names.  Each
     subsection describes realm-specific information, including where
     to find the Kerberos servers for that realm.

logging
     Contains relations which determine how Kerberos programs are to
     perform logging.

[kdcdefaults]
-------------

The following relation is defined in the [kdcdefaults] section:

kdc_ports
     This relation lists the ports on which the Kerberos server should
     listen for UDP requests by default.  This list is a comma separated
     list of integers.  If this relation is not specified, the
     compiled-in default is 88,750, the first being the assigned
     Kerberos port and the second which was used by Kerberos V4.

kdc_tcp_ports
     This relation lists the ports on which the Kerberos server should
     listen for TCP connections by default.  This list is a comma
     separated list of integers.  If this relation is not specified,
     the compiled-in default is not to listen for TCP connections at
     all.

     If you wish to change this (which we do not recommend, because the
     current implementation has little protection against
     denial-of-service attacks), the standard port number assigned for
     Kerberos TCP traffic is port 88.

v4_mode
     This string specifies how the KDC should respond to Kerberos 4
     packets.  The possible values are none, disable, full, and
     nopreauth.  The default value is none.

[realms]
--------

Each tag in the [realms] section of the file names a Kerberos realm.
The value of the tag is a subsection where the relations in that
subsection define KDC parameters for that particular realm.

For each realm, the following tags may be specified in the [realms]
subsection:

acl_file
     (String.)  Location of the access control list (acl) file that
     kadmin uses to determine which principals are allowed which
     permissions on the database.  The default is
     `/usr/local/var/krb5kdc/kadm5.acl'.

admin_keytab
     (String.)  Location of the keytab file that the legacy
     administration daemons `kadmind4' and `v5passwdd' use to
     authenticate to the database.  The default is
     `/usr/local/var/krb5kdc/kadm5.keytab'.

database_name
     (String.)  Location of the Kerberos database for this realm.  The
     default is
     `/usr/local/var/krb5kdc/principal'.

default_principal_expiration
     (Absolute time string.)  Specifies the default expiration date of
     principals created in this realm.  The default value for this tag
     is 0.

default_principal_flags
     (Flag string.)  Specifies the default attributes of principals
     created in this realm.  The format for this string is a
     comma-separated list of flags, with '+' before each flag that
     should be enabled and '-' before each flag that should be
     disabled.   The default is postdateable, forwardable, tgt-based,
     renewable, proxiable, dup-skey, allow-tickets, and service
     enabled..

     There are a number of possible flags:

    postdateable
          Enabling this flag allows the principal to obtain
          postdateable tickets.

    forwardable
          Enabling this flag allows the principal to obtain forwardable
          tickets.

    tgt-based
          Enabling this flag allows a principal to obtain tickets based
          on a ticket-granting-ticket, rather than repeating the
          authentication process that was used to obtain the TGT.

    renewable
          Enabling this flag allows the principal to obtain renewable
          tickets.

    proxiable
          Enabling this flag allows the principal to obtain proxy
          tickets.

    dup-skey
          Enabling this flag allows the principal to obtain a session
          key for another user, permitting user-to-user authentication
          for this principal.

    allow-tickets
          Enabling this flag means that the KDC will issue tickets for
          this principal.  Disabling this flag essentially deactivates
          the principal within this realm.

    preauth
          If this flag is enabled on a client principal, then that
          principal is required to preauthenticate to the KDC before
          receiving any tickets.  On a service principal, enabling this
          flag means that service tickets for this principal will only
          be issued to clients with a TGT that has the preauthenticated
          ticket set.

    hwauth
          If this flag is enabled, then the principal is required to
          preauthenticate using a hardware device before receiving any
          tickets.

    pwchange
          Enabling this flag forces a password change for this
          principal.

    service
          Enabling this flag allows the the KDC to issue service
          tickets for this principal.

    pwservice
          If this flag is enabled, it marks this principal as a
          password change service.  This should only be used in special
          cases, for example, if a user's password has expired, then
          the user has to get tickets for that principal without going
          through the normal password authentication in order to be
          able to change the password.

dict_file
     (String.)  Location of the dictionary file containing strings that
     are not allowed as passwords.  If none is specified or if there is
     no policy assigned to the principal, no dictionary checks of
     passwords will be performed.

kadmind_port
     (Port number.)  Specifies the port on which the kadmind daemon is
     to listen for this realm.  The assigned port for kadmind is
     749.

kpasswd_port
     (Port number.)  Specifies the port on which the kpasswd daemon is
     to listen for this realm.  The default is 464.

key_stash_file
     (String.)  Specifies the location where the master key has been
     stored (via `kdb5_util stash').  The default is
     `/usr/local/var/krb5kdc/.k5.REALM', where REALM is the Kerberos
     realm.

kdc_ports
     (String.)  Specifies the list of ports that the KDC is to listen to
     for UDP requests for this realm.  By default, the value of
     kdc_ports as specified in the [kdcdefaults] section is used.

kdc_tcp_ports
     (String.)  Specifies the list of ports that the KDC is to listen to
     for TCP requests for this realm.  By default, the value of
     kdc_tcp_ports as specified in the [kdcdefaults] section is used.

master_key_name
     (String.)  Specifies the name of the principal associated with the
     master key.  The default is K/M.

master_key_type
     (Key type string.)  Specifies the master key's key type.  The
     default value for this is des3-cbc-sha1.  For a list of all
     possible values, see Supported Encryption Types.

max_life
     (Delta time string.)  Specifes the maximum time period for which a
     ticket may be valid in this realm.  The default value is
     10 hours.

max_renewable_life
     (Delta time string.)  Specifies the maximum time period during
     which a valid ticket may be renewed in this realm.  The default
     value is 0.

supported_enctypes
     List of key:salt strings.  Specifies the default key/salt
     combinations of principals for this realm.  Any principals created
     through `kadmin' will have keys of these types.  The default value
     for this tag is des3-hmac-sha1:normal des-cbc-crc:normal. For
     lists of possible values, see Supported Encryption Types
     and Salts.

reject_bad_transit
     A boolean value (`true', `false').  If set to `true', the KDC will
     check the list of transited realms for cross-realm tickets against
     the transit path computed from the realm names and the `capaths'
     section of its `krb5.conf' file; if the path in the ticket to be
     issued contains any realms not in the computed path, the ticket
     will not be issued, and an error will be returned to the client
     instead.  If this value is set to `false', such tickets will be
     issued anyways, and it will be left up to the application server to
     validate the realm transit path.

     If the `disable-transited-check' flag is set in the incoming
     request, this check is not performed at all.  Having the
     `reject_bad_transit' option will cause such ticket requests to be
     rejected always.

     This transit path checking and config file option currently apply
     only to TGS requests.

     Earlier versions of the MIT release (before 1.2.3) had bugs in the
     application server support such that the server-side checks may
     not be performed correctly.  We recommend turning this option on,
     unless you know that all application servers in this realm have
     been updated to fixed versions of the software, and for whatever
     reason, you don't want the KDC to do the validation.

     This is a per-realm option so that multiple-realm KDCs may control
     it separately for each realm, in case (for example) one realm has
     had the software on its application servers updated but another
     has not.

     This option defaults to `true'.

Sample kdc.conf File
--------------------

Here's an example of a `kdc.conf' file:

     [kdcdefaults]
         kdc_ports = 88

     [realms]
         ATHENA.MIT.EDU = {
             kadmind_port = 749
             max_life = 12h 0m 0s
             max_renewable_life = 7d 0h 0m 0s
             master_key_type = des3-hmac-sha1
             supported_enctypes = des3-hmac-sha1:normal des-cbc-crc:normal des-cbc-crc:v4
         }

     [logging]
         kdc = FILE:/usr/local/var/krb5kdc/kdc.log
         admin_server = FILE:/usr/local/var/krb5kdc/kadmin.log

Using DNS
*********

Mapping Hostnames onto Kerberos Realms
======================================

Mapping hostnames onto Kerberos realms is done in one of two ways.

The first mechanism, which has been in use for years in MIT-based
Kerberos distributions, works through a set of rules in the `krb5.conf'
configuration file.  (see krb5.conf.)  You can specify mappings for
an entire domain or subdomain, and/or on a hostname-by-hostname basis.
Since greater specificity takes precedence, you would do this by
specifying the mappings for a given domain or subdomain and listing the
exceptions.

The second mechanism works by looking up the information in special
`TXT' records in the Domain Name Service.  This is currently not used
by default because security holes could result if the DNS TXT records
were spoofed.  If this mechanism is enabled on the client, it will try
to look up a `TXT' record for the DNS name formed by putting the prefix
`_kerberos' in front of the hostname in question.  If that record is
not found, it will try using `_kerberos' and the host's domain name,
then its parent domain, and so forth.  So for the hostname
BOSTON.ENGINEERING.FOOBAR.COM, the names looked up would be:

     _kerberos.boston.engineering.foobar.com
     _kerberos.engineering.foobar.com
     _kerberos.foobar.com
     _kerberos.com

The value of the first TXT record found is taken as the realm name.
(Obviously, this doesn't work all that well if a host and a subdomain
have the same name, and different realms.  For example, if all the hosts
in the ENGINEERING.FOOBAR.COM domain are in the ENGINEERING.FOOBAR.COM
realm, but a host named ENGINEERING.FOOBAR.COM is for some reason in
another realm.  In that case, you would set up TXT records for all
hosts, rather than relying on the fallback to the domain name.)

Even if you do not choose to use this mechanism within your site, you
may wish to set it up anyway, for use when interacting with other sites.

Hostnames for KDCs
==================

MIT recommends that your KDCs have a predefined set of CNAME records
(DNS hostname aliases), such as `kerberos' for the master KDC and
`kerberos-1', `kerberos-2', ... for the slave KDCs.  This way, if you
need to swap a machine, you only need to change a DNS entry, rather
than having to change hostnames.

A new mechanism for locating KDCs of a realm through DNS has been added
to the MIT Kerberos V5 distribution.  A relatively new record type
called `SRV' has been added to DNS.  Looked up by a service name and a
domain name, these records indicate the hostname and port number to
contact for that service, optionally with weighting and prioritization.
(See RFC 2782 if you want more information.  You can follow the
example below for straightforward cases.)

The use with Kerberos is fairly straightforward.  The domain name used
in the SRV record name is the domain-style Kerberos realm name.  (It is
possible to have Kerberos realm names that are not DNS-style names, but
we don't recommend it for Internet use, and our code does not support it
well.)  Several different Kerberos-related service names are used:

`_kerberos._udp'
     This is for contacting any KDC by UDP.  This entry will be used
     the most often.  Normally you should list port 88 on each of your
     KDCs.

`_kerberos._tcp'
     This is for contacting any KDC by TCP.  The MIT KDC by default
     will not listen on any TCP ports, so unless you've changed the
     configuration or you're running another KDC implementation, you
     should leave this unspecified.  If you do enable TCP support,
     normally you should use port 88.

`_kerberos-master._udp'
     This entry should refer to those KDCs, if any, that will
     immediately see password changes to the Kerberos database.  This
     entry is used only in one case, when the user is logging in and
     the password appears to be incorrect; the master KDC is then
     contacted, and the same password used to try to decrypt the
     response, in case the user's password had recently been changed
     and the first KDC contacted hadn't been updated.  Only if that
     fails is an "incorrect password" error given.

     If you have only one KDC, or for whatever reason there is no
     accessible KDC that would get database changes faster than the
     others, you do not need to define this entry.

`_kerberos-adm._tcp'
     This should list port 749 on your master KDC.  Support for it is
     not complete at this time, but it will eventually be used by the
     `kadmin' program and related utilities.  For now, you will also
     need the `admin_server' entry in `krb5.conf'.  (see krb5.conf.)

`_kpasswd._udp'
     This should list port 464 on your master KDC.  It is used when a
     user changes her password.

`_kerberos-iv._udp'
     This should refer to your KDCs that serve Kerberos version 4
     requests, if you have Kerberos v4 enabled.

Be aware, however, that the DNS SRV specification requires that the
hostnames listed be the canonical names, not aliases.  So, for example,
you might include the following records in your (BIND-style) zone file:

     $ORIGIN foobar.com.
     _kerberos               TXT       "FOOBAR.COM"
     kerberos                CNAME     daisy
     kerberos-1              CNAME     use-the-force-luke
     kerberos-2              CNAME     bunny-rabbit
     _kerberos._udp          SRV       0 0 88 daisy
                             SRV       0 0 88 use-the-force-luke
                             SRV       0 0 88 bunny-rabbit
     _kerberos-master._udp   SRV       0 0 88 daisy
     _kerberos-adm._tcp      SRV       0 0 749 daisy
     _kpasswd._udp           SRV       0 0 464 daisy

As with the DNS-based mechanism for determining the Kerberos realm of a
host, we recommend distributing the information this way for use by
other sites that may want to interact with yours using Kerberos, even if
you don't immediately make use of it within your own site.  If you
anticipate installing a very large number of machines on which it will
be hard to update the Kerberos configuration files, you may wish to do
all of your Kerberos service lookups via DNS and not put the information
(except for `admin_server' as noted above) in future versions of your
`krb5.conf' files at all.  Eventually, we hope to phase out the listing
of server hostnames in the client-side configuration files; making
preparations now will make the transition easier in the future.

Administrating the Kerberos Database
************************************

Your Kerberos database contains all of your realm's Kerberos principals,
their passwords, and other administrative information about each
principal.  For the most part, you will use the `kdb5_util' program to
manipulate the Kerberos database as a whole, and the `kadmin' program
to make changes to the entries in the database.  (One notable exception
is that users will use the `kpasswd' program to change their own
passwords.)  The `kadmin' program has its own command-line interface,
to which you type the database administrating commands.

`Kdb5_util' provides a means to create, delete, load, or dump a
Kerberos database.  It also includes a command to stash a copy of the
master database key in a file on a KDC, so that the KDC can authenticate
itself to the `kadmind' and `krb5kdc' daemons at boot time.

`Kadmin' provides for the maintenance of Kerberos principals, KADM5
policies, and service key tables (keytabs).  It exists as both a
Kerberos client, `kadmin', using Kerberos authentication and an RPC, to
operate securely from anywhere on the network, and as a local client,
`kadmin.local', intended to run directly on the KDC without Kerberos
authentication.  Other than the fact that the remote client uses
Kerberos to authenticate the person using it, the functionalities of
the two versions are identical.  The local version is necessary to
enable you to set up enough of the database to be able to use the remote
version.  It replaces the now obsolete `kdb5_edit' (except for database
dump and load, which are provided by `kdb5_util').

The remote version authenticates to the KADM5 server using the service
principal `kadmin/admin'.  If the credentials cache contains a ticket
for the `kadmin/admin' principal, and the `-c ccache' option is
specified, that ticket is used to authenticate to KADM5.  Otherwise,
the `-p' and `-k' options are used to specify the client Kerberos
principal name used to authenticate.  Once kadmin has determined the
principal name, it requests a `kadmin/admin' Kerberos service ticket
from the KDC, and uses that service ticket to authenticate to KADM5.

Kadmin Options
==============

You can invoke `kadmin' or `kadmin.local' with any of the following
options:

-r REALM
     Use REALM as the default Kerberos realm for the database.

-p principal
     Use the Kerberos principal principal to authenticate to Kerberos.
     If this option is not given, `kadmin' will append `admin' to
     either the primary principal name, the environment variable USER,
     or to the username obtained from `getpwuid', in order of
     preference.

-q query
     Pass query directly to `kadmin'.  This is useful for writing
     scripts that pass specific queries to `kadmin'.

     You can invoke `kadmin' with any of the following options:

-k [-t keytab]
     Use the keytab keytab to decrypt the KDC response instead of
     prompting for a password on the TTY.  In this case, the principal
     will be `host/hostname'.  If -t is not used to specify a keytab,
     then the default keytab will be used.

-c credentials cache
     Use credentials_cache as the credentials cache.  The credentials
     cache should contain a service ticket for the `kadmin/admin'
     service, which can be acquired with the `kinit' program.  If this
     option is not specified, `kadmin' requests a new service ticket
     from the KDC, and stores it in its own temporary ccache.

-w password
     Use password as the password instead of prompting for one on the
     TTY.  Note:  placing the password for a Kerberos principal with
     administration access into a shell script can be dangerous if
     unauthorized users gain read access to the script.

-s admin_server[:port]
     Specifies the admin server that kadmin should contact.

     You can invoke `kadmin.local' with an of the follwing options:

-d_ dbname
     Specifies the name of the Kerberos database.

-e "enctypes ..."
     Sets the list of cryptosystem and salt types to be used for any new
     keys created.  See Supported Encryption Types and
     Salts for available types.

-m
     Do not authenticate using a keytab.  This option will cause kadmin
     to prompt for the master database password.

Date Format
===========

Many of the `kadmin' commands take a duration or time as an argument.
The date can appear in a wide variety of formats, such as:

     "15 minutes"
     "7 days"
     "1 month"
     "2 hours"
     "400000 seconds"
     "next year"
     "this Monday"
     "next Monday"
     yesterday
     tomorrow
     now
     "second Monday"
     fortnight
     "3/31/1992 10:00:07 PST"
     "January 23, 2007 10:05pm"
     "22:00 GMT"

Note that if the date specification contains spaces, you must enclose it
in double quotes.  Note also that you cannot use a number without a
unit.  (I.e., ""60 seconds"" is correct, but "60" is incorrect.)  All
keywords are case-insensitive.  The following is a list of all of the
allowable keywords.

Months
     january, jan, february, feb, march, mar, april, apr, may, june,
     jun, july, jul, august, aug, september, sep, sept, october, oct,
     november, nov, december, dec

Days
     sunday, sun, monday, mon, tuesday, tues, tue, wednesday, wednes,
     wed, thursday, thurs, thur, thu, friday, fri, saturday, sat

Units
     year, month, fortnight, week, day, hour, minute, min, second, sec

Relative
     tomorrow, yesterday, today, now, last, this, next, first, second,
     third, fourth, fifth, sixth, seventh, eighth, ninth, tenth,
     eleventh, twelfth, ago

Time Zones
     `kadmin' recognizes abbreviations for most of the world's time
     zones.  A complete listing appears in kadmin Time Zones.

12-hour Time Delimiters
     am, pm

Principals
==========

Each entry in the Kerberos database contains a Kerberos principal
(see Definitions) and the attributes and policies associated with
that principal.

Retrieving Information About a Principal
----------------------------------------

Attributes
..........

To retrieve a listing of the attributes and/or policies associated with
a principal, use the `kadmin' `get_principal' command, which requires
the "inquire" administrative privilege.  The syntax is:

     get_principal principal

The `get_principal' command has the alias `getprinc'.

For example, suppose you wanted to view the attributes of the principal
`jennifer/root@ATHENA.MIT.EDU'.    You would type:

     shell% kadmin
     kadmin: getprinc jennifer/root
     Principal: jennifer/root@ATHENA.MIT.EDU
     Expiration date: [never]
     Last password change: Mon Jan 31 02:06:40 EDT 2002
     Password Expiration date: [none]
     Maximum ticket life: 0 days 10:00:00
     Maximum renewable life: 7 days 00:00:00
     Last modified: Wed Jul 24 14:46:25 EDT 2002 (joeadmin/admin@ATHENA.MIT.EDU)
     Last successful authentication: Mon Jul 29 18:20:17 EDT 2002
     Last failed authentication: Mon Jul 29 18:18:54 EDT 2002
     Failed password attempts: 3
     Number of keys: 2
     Key: vno 2, Triple DES cbc mode with HMAC/sha1, no salt
     Key: vno 2, DES cbc mode with CRC-32, no salt
     Attributes: DISALLOW_FORWARDABLE, DISALLOW_PROXIABLE
     Policy: [none]
     kadmin:

The `get_principal' command has a `-terse' option, which lists the
fields as a quoted, tab-separated string.  For example:

     kadmin: getprinc -terse jennifer/root
     jennifer/root@ATHENA.MIT.EDU	0	1027458564
     0	36000	 (joeadmin/admin@ATHENA.MIT.EDU
     1027536385	18	2	0	[none]	604800	1027980137
     1027980054	3	2	1	2	16	0	1
     2	1	0
     kadmin:

Retrieving a List of Principals
...............................

To generate a listing of principals, use the `kadmin' `list_principals'
command, which requires the "list" privilege.  The syntax is:

     list_principals [expression]

where expression is a shell-style glob expression that can contain the
characters `*', `?', `[', and `]'.  All policy names matching the
expression are displayed.  The `list_principals' command has the
aliases `listprincs', `get_principals', and `getprincs'.  For example:

     kadmin: listprincs test*
     test3@ATHENA.MIT.EDU
     test2@ATHENA.MIT.EDU
     test1@ATHENA.MIT.EDU
     testuser@ATHENA.MIT.EDU
     kadmin:

If no expression is provided, all principals are printed.

Privileges
----------

Administrative privileges for the Kerberos database are stored in the
file `kadm5.acl'.

The format of the file is:

     Kerberos_principal      permissions     [target_principal]	[restrictions]

The Kerberos principal (and optional target principal) can include the
"*" wildcard, so if you want any principal with the instance "admin" to
have full permissions on the database, you could use the principal
"`*/admin@REALM'" where "REALM" is your Kerberos realm.
`target_principal' can also include backreferences to
`Kerberos_principal', in which "*number" matches the component number
in the `Kerberos_principal'.

Note:  a common use of an admin instance is so you can grant separate
permissions (such as administrator access to the Kerberos database) to
a separate Kerberos principal.  For example, the user `joeadmin' might
have a principal for his administrative use, called `joeadmin/admin'.
This way, `joeadmin' would obtain `joeadmin/admin' tickets only when he
actually needs to use those permissions.

The permissions are represented by single letters; UPPER-CASE letters
represent negative permissions.  The permissions are:

a
     allows the addition of principals or policies in the database.

A
     disallows the addition of principals or policies in the database.

d
     allows the deletion of principals or policies in the database.

D
     disallows the deletion of principals or policies in the database.

m
     allows the modification of principals or policies in the database.

M
     disallows the modification of principals or policies in the
     database.

c
     allows the changing of passwords for principals in the database.

C
     disallows the changing of passwords for principals in the database.

i
     allows inquiries to the database.

I
     disallows inquiries to the database.

l
     allows the listing of principals or policies in the database.

L
     disallows the listing of principals or policies in the database.

s
     allows the explicit setting of the key for a principal

S
     disallows the explicit setting of the key for a principal

*
     All privileges (admcil).

x
     All privileges (admcil); identical to "*".

The restrictions are a string of flags.  Allowed restrictions are:

[+ -]flagname
     flag is forced to indicated value.  The permissible flags are the
     same as the `+' and `-' flags for the `kadmin addprinc' and
     `modprinc' commands.

-clearpolicy
     policy is forced to clear

-policy pol
     policy is forced to be pol

expire time
pwexpire time
maxlife time
maxrenewlife time
     associated value will be forced to MIN(time, requested value)

The above flags act as restrictions on any add or modify operation
which is allowed due to that ACL line.

Here is an example of a `kadm5.acl' file.  Note that order is
important; permissions are determined by the first matching entry.

     */admin@ATHENA.MIT.EDU  *
     joeadmin@ATHENA.MIT.EDU  ADMCIL
     joeadmin/*@ATHENA.MIT.EDU il */root@ATHENA.MIT.EDU
     *@ATHENA.MIT.EDU cil *1/admin@ATHENA.MIT.EDU
     */*@ATHENA.MIT.EDU  i
     */admin@EXAMPLE.COM * -maxlife 9h -postdateable

In the above file, any principal in the ATHENA.MIT.EDU realm with an
`admin' instance has all administrative privileges.  The user `joeadmin'
has all permissions with his `admin' instance,
`joeadmin/admin@ATHENA.MIT.EDU' (matches the first line).  He has no
permissions at all with his `null' instance, `joeadmin@ATHENA.MIT.EDU'
(matches the second line).  His root instance has inquire and list
permissions with any other principal that has the instance `root'.  Any
principal in ATHENA.MIT.EDU can inquire, list, or change the password of
their `admin' instance, but not any other `admin' instance.  Any
principal in the realm `ATHENA.MIT.EDU' (except for
`joeadmin@ATHENA.MIT.EDU', as mentioned above) has inquire privileges.
Finally, any principal with an admin instance in EXAMPLE.COM has all
permissions, but any principal that they create or modify will not be
able to get postdateable tickets or tickets with a life of longer than
9 hours.

Adding or Modifying Principals
------------------------------

To add a principal to the database, use the kadmin `add_principal'
command, which requires the "add" administrative privilege.  This
function creates the new principal, prompting twice for a password, and,
if neither the -policy nor -clearpolicy options are specified and the
policy "default" exists, assigns it that policy.  The syntax is:

     kadmin: add_principal [options] principal

To modify attributes of a principal, use the kadmin `modify_principal'
command, which requires the "modify" administrative privilege.  The
syntax is:

     kadmin: modify_principal [options] principal

`add_principal' has the aliases `addprinc' and `ank'(1).
`modify_principal' has the alias `modprinc'.

The `add_principal' and `modify_principal' commands take the following
switches:

-expire date
     Sets the expiration date of the principal to date.

-pwexpire date
     Sets the expiration date of the password to date.

-maxlife maxlife
     Sets the maximum ticket life of the principal to maxlife.

-maxrenewlife maxrenewlife
     Sets the maximum renewable life of tickets for the principal to
     maxrenewlife.

-kvno number
     Explicity sets the key version number to number.  MIT does not
     recommend doing this unless there is a specific reason.

-policy policy
     Sets the policy used by this principal.  (see Policies.)  With
     `modify_principal', the current policy assigned to the principal is
     set or changed.  With `add_principal', if this option is not
     supplied, the -clearpolicy is not specified, and the policy
     "default" exists, that policy is assigned.  If a principal is
     created with no policy, `kadmin' will print a warning message.

-clearpolicy
     For `modify_principal', removes the current policy from a
     principal.  For `add_principal', suppresses the automatic
     assignment of the policy "default".

{-|+}allow_postdated
     The "-allow_postdated" option prohibits this principal from
     obtaining postdated tickets.  "+allow_postdated" clears this flag.
     In effect, "-allow_postdated" sets the
     KRB5_KDB_DISALLOW_POSTDATED flag on the principal in the database.

{-|+}allow_forwardable
     The "-allow_forwardable" option prohibits this principal from
     obtaining forwardable tickets.  "+allow_forwardable" clears this
     flag.  In effect, "-allow_forwardable" sets the
     KRB5_KDB_DISALLOW_FORWARDABLE flag on the principal in the
     database.

{-|+}allow_renewable
     The "-allow_renewable" option prohibits this principal from
     obtaining renewable tickets.  "+allow_renewable" clears this flag.
     In effect, "-allow_renewable" sets the
     KRB5_KDB_DISALLOW_RENEWABLE flag on the principal in the database.

{-|+}allow_proxiable
     The "-allow_proxiable" option prohibits this principal from
     obtaining proxiable tickets.  "+allow_proxiable" clears this flag.
     In effect, "-allow_proxiable" sets the
     KRB5_KDB_DISALLOW_PROXIABLE flag. on the principal in the database.

{-|+}allow_dup_skey
     The "-allow_dup_skey" option disables user-to-user authentication
     for this principal by prohibiting this principal from obtaining a
     session key for another user.  "+allow_dup_skey" clears this flag.
     In effect, "-allow_dup_skey" sets the
     KRB5_KDB_DISALLOW_DUP_SKEY flag on the principal in the database.

{-|+}requires_preauth
     The "+requires_preauth" option requires this principal to
     preauthenticate before being allowed to kinit.  -requires_preauth
     clears this flag.  In effect, +requires_preauth sets the
     KRB5_KDB_REQUIRES_PRE_AUTH flag on the principal in the database.

{-|+}requires_hwauth
     The "+requires_hwauth" flag requires the principal to
     preauthenticate using a hardware device before being allowed to
     kinit.  "-requires_hwauth" clears this flag.  In effect,
     "+requires_hwauth" sets the KRB5_KDB_REQUIRES_HW_AUTH flag on the
     principal in the database.

{-|+}allow_svr
     The "-allow_svr" flag prohibits the issuance of service tickets for
     this principal.  "+allow_svr" clears this flag.  In effect,
     "-allow_svr" sets the
     KRB5_KDB_DISALLOW_SVR flag on the principal in the database.

{-|+}allow_tgs_req
     The "-allow_tgs_req" option specifies that a Ticket-Granting
     Service (TGS) request for a service ticket for this principal is
     not permitted.  You will probably never need to use this option.
     "+allow_tgs_req" clears this flag.  The default is
     "+allow_tgs_req".  In effect, "-allow_tgs_req" sets the
     KRB5_KDB_DISALLOW_TGT_BASED flag on the principal in the database.

{-|+}allow_tix
     The "-allow_tix" option forbids the issuance of any tickets for
     this principal.  "+allow_tix" clears this flag.  The default is
     "+allow_tix".  In effect, "-allow_tix" sets the
     KRB5_KDB_DISALLOW_ALL_TIX flag on the principal in the database.

{-|+}needchange
     The "+needchange" option sets a flag in attributes field to force a
     password change; "-needchange" clears it.  The default is
     "-needchange".  In effect, "+needchange" sets the
     KRB5_KDB_REQUIRES_PWCHANGE flag on the principal in the database.

{-|+}password_changing_service
     The "+password_changing_service" option sets a flag in the
     attributes field marking this principal as a password change
     service. (Again, you will probably never need to use this option.)
     "-password_changing_service" clears the flag.  The default is
     "-password_changing_service".  In effect, the
     "+password_changing_service" option sets the
     KRB5_KDB_PWCHANGE_SERVICE flag on the principal in the database.

-randkey
     Sets the key for the principal to a random value (`add_principal'
     only).  MIT recommends using this option for host keys.

-pw password
     Sets the key of the principal to the specified string and does not
     prompt for a password (`add_principal' only).  MIT does not
     recommend using this option.

-e enc:salt...
     Uses the specified list of enctype-salttype pairs for setting the
     key of the principal.  The quotes are necessary if there are
     multiple enctype-salttype pairs.  This will not function against
     kadmin daemons earlier than krb5-1.2.  See Supported Encryption Types
     and Salts for available types.

If you want to just use the default values, all you need to do is:

     kadmin: addprinc jennifer
     WARNING: no policy specified for "jennifer@ATHENA.MIT.EDU";
     defaulting to no policy.
     Enter password for principal jennifer@ATHENA.MIT.EDU:  <= Type the password.
     Re-enter password for principal jennifer@ATHENA.MIT.EDU:  <=Type it again.
     Principal "jennifer@ATHENA.MIT.EDU" created.
     kadmin:

If, on the other hand, you want to set up an account that expires on
January 1, 2000, that uses a policy called "stduser", with a temporary
password (which you want the user to change immediately), you would type
the following.  (Note:  each line beginning with => is a continuation
of the previous line.)

     kadmin: addprinc david -expire "1/1/2000 12:01am EST" -policy stduser
     =>  +needchange
     Enter password for principal david@ATHENA.MIT.EDU:  <= Type the password.
     Re-enter password for principal
     david@ATHENA.MIT.EDU:  <= Type it again.
     Principal "david@ATHENA.MIT.EDU" created.
     kadmin:

If you will need cross-realm authentication, you need to add principals
for the other realm's TGT to each realm.  For example, if you need to
do cross-realm authentication between the realms ATHENA.MIT.EDU and
EXAMPLE.COM, you would need to add the principals
`krbtgt/EXAMPLE.COM@ATHENA.MIT.EDU' and
`krbtgt/ATHENA.MIT.EDU@EXAMPLE.COM' to both databases.  You need to be
sure the passwords and the key version numbers (kvno) are the same in
both databases.  This may require explicitly setting the kvno with the
`-kvno' option.  See Cross-realm Authentication for more
details.

---------- Footnotes ----------

(1) `ank' was the short form of the equivalent command using the
deprecated `kadmin5' database administrative tool.  It has been kept

Deleting Principals
-------------------

To delete a principal, use the kadmin `delete_principal' command, which
requires the "delete" administrative privilege.  The syntax is:

     delete_principal [-force] principal

`delete_principal' has the alias `delprinc'.  The `-force' option
causes `delete_principal' not to ask if you're sure.  For example:

     kadmin: delprinc jennifer
     Are you sure you want to delete the principal
     "jennifer@ATHENA.MIT.EDU"? (yes/no): yes
     Principal "jennifer@ATHENA.MIT.EDU" deleted.
     Make sure that you have removed this principal from
     all ACLs before reusing.
     kadmin:

Changing Passwords
------------------

To change a principal's password use the kadmin `change_password'
command, which requires the "modify" administrative privilege (unless
the principal is changing his/her own password).  The syntax is:

     change_password [options] principal

The `change_password' option has the alias `cpw'.  `change_password'
takes the following options:

-randkey
     Sets the key of the principal to a random value.

-pw password
     Sets the password to the string password.  MIT does not recommend
     using this option.

-e "enc:salt..."
     Uses the specified list of enctype-salttype pairs for setting the
     key of the principal.  The quotes are necessary if there are
     multiple enctype-salttype pairs.  This will not function against
     kadmin daemons earlier than krb5-1.2.  See Supported Encryption Types
     and Salts for possible values.

-keepold
     Keeps the previous kvno's keys around.  There is no easy way to
     delete the old keys, and this flag is usually not necessary except
     perhaps for TGS keys.  Don't use this flag unless you know what
     you're doing.

For example:

     kadmin: cpw david
     Enter password for principal david@ATHENA.MIT.EDU:  <= Type the new password.
     Re-enter password for principal david@ATHENA.MIT.EDU:  <= Type it again.
     Password for david@ATHENA.MIT.EDU changed.
     kadmin:

Note that `change_password' will not let you change the password to one
that is in the principal's password history.

Policies
========

A policy is a set of rules governing passwords.  Policies can dictate
minimum and maximum password lifetimes, minimum number of characters and
character classes a password must contain, and the number of old
passwords kept in the database.

Retrieving Policies
-------------------

To retrieve a policy, use the kadmin `get_policy' command, which
requires the "inquire" administrative privilege.  The syntax is:

     get_policy [-terse] policy

The `get_policy' command has the alias `getpol'.  For example:

     kadmin: get_policy admin
     Policy: admin
     Maximum password life: 180 days 00:00:00
     Minimum password life: 00:00:00
     Minimum password length: 6
     Minimum number of password character classes: 2
     Number of old keys kept: 5
     Reference count: 17
     kadmin:

The "reference count" is the number of principals using that policy.

The `get_policy' command has a `-terse' option, which lists each field
as a quoted, tab-separated string.  For example:

     kadmin: get_policy -terse admin
     admin   15552000        0       6       2       5       17
     kadmin:

Retrieving the List of Policies
-------------------------------

You can retrieve the list of policies with the kadmin `list_policies'
command, which requires the "list" privilege.  The syntax is:

     list_policies [expression]

where expression is a shell-style glob expression that can contain the
characters *, ?, and [].  All policy names matching the expression are
displayed.  The `list_policies' command has the aliases `listpols',
`get_policies', and `getpols'.  For example:

     kadmin:  listpols
     test-pol
     dict-only
     once-a-min
     test-pol-nopw

     kadmin:  listpols t*
     test-pol
     test-pol-nopw
     kadmin:

Adding or Modifying Policies
----------------------------

To add a new policy, use the kadmin `add_policy' command, which
requires the "add" administrative privilege.  The syntax is:

     add_policy [options] policy_name

To modify attributes of a principal, use the kadmin `modify_policy'
command, which requires the "modify" administrative privilege.  The
syntax is:

     modify_policy [options] policy_name

`add_policy' has the alias `addpol'.  `modify_poilcy' has the alias
`modpol'.

The `add_policy' and `modify_policy' commands take the following
switches:

-maxlife time
     Sets the maximum lifetime of a password to time.

-minlife time
     Sets the minimum lifetime of a password to time.

-minlength length
     Sets the minimum length of a password to length characters.

-minclasses number
     Requires at least number of character classes in a password.

-history number
     Sets the number of past keys kept for a principal to number.