This is Info file krb5-admin.info, produced by Makeinfo version 1.68
from the input file admin.texinfo.


File: krb5-admin.info,  Node: Top,  Next: Copyright,  Prev: (dir),  Up: (dir)

This document describes how to administrate a Kerberos V5 installation.

* Menu:

* Copyright::
* Introduction::
* How Kerberos Works::
* Configuration Files::
* Administrating Kerberos Database Entries::
* Application Servers::
* Backups of Secure Hosts::
* Bug Reporting::
* Appendix::


File: krb5-admin.info,  Node: Copyright,  Next: Introduction,  Prev: Top,  Up: Top

Copyright
*********

Copyright (C) 1985-2001 by the Massachusetts Institute of Technology.

     Export of software employing encryption from the United States of
     America may require a specific license from the United States
     Government.  It is the responsibility of any person or organization
     contemplating export to obtain such a license before exporting.

WITHIN THAT CONSTRAINT, permission to use, copy, modify, and distribute
this software and its documentation for any purpose and without fee is
hereby granted, provided that the above copyright notice appear in all
copies and that both that copyright notice and this permission notice
appear in supporting documentation, and that the name of M.I.T. not be
used in advertising or publicity pertaining to distribution of the
software without specific, written prior permission.  Furthermore if you
modify this software you must label your software as modified software
and not distribute it in such a fashion that it might be confused with
the original MIT software.  M.I.T. makes no representations about the
suitability of this software for any purpose.  It is provided "as is"
without express or implied warranty.

The following copyright and permission notice applies to the OpenVision
Kerberos Administration system located in kadmin/create, kadmin/dbutil,
kadmin/passwd, kadmin/server, lib/kadm5, and portions of lib/rpc:

     Copyright, OpenVision Technologies, Inc., 1996, All Rights Reserved

     WARNING:  Retrieving the OpenVision Kerberos Administration system
     source code, as described below, indicates your acceptance of the
     following terms.  If you do not agree to the following terms, do
     not retrieve the OpenVision Kerberos administration system.

     You may freely use and distribute the Source Code and Object Code
     compiled from it, with or without modification, but this Source
     Code is provided to you "AS IS" EXCLUSIVE OF ANY WARRANTY,
     INCLUDING, WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY
     OR FITNESS FOR A PARTICULAR PURPOSE, OR ANY OTHER WARRANTY,
     WHETHER EXPRESS OR IMPLIED.  IN NO EVENT WILL OPENVISION HAVE ANY
     LIABILITY FOR ANY LOST PROFITS, LOSS OF DATA OR COSTS OF
     PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES, OR FOR ANY SPECIAL,
     INDIRECT, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THIS AGREEMENT,
     INCLUDING, WITHOUT LIMITATION, THOSE RESULTING FROM THE USE OF THE
     SOURCE CODE, OR THE FAILURE OF THE SOURCE CODE TO PERFORM, OR FOR
     ANY OTHER REASON.

     OpenVision retains all copyrights in the donated Source Code.
     OpenVision also retains copyright to derivative works of the
     Source Code, whether created by OpenVision or by a third party.
     The OpenVision copyright notice must be preserved if derivative
     works are made based on the donated Source Code.

     OpenVision Technologies, Inc. has donated this Kerberos
     Administration system to MIT for inclusion in the standard
     Kerberos 5 distribution.  This donation underscores our commitment
     to continuing Kerberos technology development and our gratitude
     for the valuable work which has been performed by MIT and the
     Kerberos community.

Kerberos V5 includes documentation and software developed at the
University of California at Berkeley, which includes this copyright
notice:

Copyright (C) 1983 Regents of the University of California.
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:
  1. Redistributions of source code must retain the above copyright
     notice, this list of conditions and the following disclaimer.

  2. Redistributions in binary form must reproduce the above copyright
     notice, this list of conditions and the following disclaimer in the
     documentation and/or other materials provided with the
     distribution.

  3. All advertising materials mentioning features or use of this
     software must display the following acknowledgement:
          This product includes software developed by the University of
          California, Berkeley and its contributors.

  4. Neither the name of the University nor the names of its
     contributors may be used to endorse or promote products derived
     from this software without specific prior written permission.

Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notices and this permission notice are
preserved on all copies.

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided also that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions.


File: krb5-admin.info,  Node: Introduction,  Next: How Kerberos Works,  Prev: Copyright,  Up: Top

Introduction
************

* Menu:

* Why Should I use Kerberos?::
* Documentation for Kerberos V5::
* Overview of This Guide::


File: krb5-admin.info,  Node: Why Should I use Kerberos?,  Next: Documentation for Kerberos V5,  Prev: Introduction,  Up: Introduction

Why Should I use Kerberos?
==========================

Since Kerberos negotiates authenticated, and optionally encrypted,
communications between two points anywhere on the internet, it provides
a layer of security that is not dependent on which side of a firewall
either client is on.  Since studies have shown that half of the computer
security breaches in industry happen from inside firewalls, Kerberos V5
from MIT will play a vital role in the security of your network.


File: krb5-admin.info,  Node: Documentation for Kerberos V5,  Next: Overview of This Guide,  Prev: Why Should I use Kerberos?,  Up: Introduction

Documentation for Kerberos V5
=============================

This document is one piece of the document set for Kerberos V5.  The
documents, and their intended audiences, are:

   * Kerberos V5 Installation Guide:  a concise guide for installing
     Kerberos V5.  Kerberos administrators (particularly whoever will be
     making site-wide decisions about the installation) and the system
     administrators who will be installing the software should read this
     guide.

   * Kerberos V5 System Administrator's Guide:  a sysadmin's guide to
     administering a Kerberos installation.  The System Administrator's
     Guide describes the administration software and suggests policies
     and procedures for administering a Kerberos installation.  Anyone
     who will have administrative access to your Kerberos database
     should read this guide.

   * Kerberos V5 UNIX User's Guide:  a guide to using the Kerberos UNIX
     client programs.  All users on UNIX systems should read this guide,
     particularly the "Tutorial" section.


File: krb5-admin.info,  Node: Overview of This Guide,  Prev: Documentation for Kerberos V5,  Up: Introduction

Overview of This Guide
======================

The next chapter describes how Kerberos works.

Chapter three describes administration of the principals in the Kerberos
database.

Chapter four describes administrative programs for manipulating the
Kerberos database as a whole.

Chapter five describes issues to consider when adding an application
server to the database.

Chapter six describes our problem reporting system.

The appendices include sample configuration files, the list of Kerberos
error messages, and a complete list of the time zones understood by
`kadmin'.


File: krb5-admin.info,  Node: How Kerberos Works,  Next: Configuration Files,  Prev: Introduction,  Up: Top

How Kerberos Works
******************

This section provides a simplified description of a general user's
interaction with the Kerberos system.  This interaction happens
transparently--users don't need to know and probably don't care about
what's going on--but Kerberos administrators might find a schematic
description of the process useful.  This description glosses over a lot
of details; for more information, see Kerberos: An Authentication
Service for Open Network Systems, a paper presented at Winter USENIX
1988, in Dallas, Texas.  This paper can be retreived by FTP from
`athena-dist.mit.edu', in the location:
`/pub/ATHENA/kerberos/doc/USENIX.ps'.

* Menu:

* Network Services and Their Client Programs::
* Kerberos Tickets::
* The Kerberos Database::
* Kerberos Realms::
* The Ticket-Granting Ticket::
* Network Services and the Master Database::
* The User/Kerberos Interaction::
* Definitions::


File: krb5-admin.info,  Node: Network Services and Their Client Programs,  Next: Kerberos Tickets,  Prev: How Kerberos Works,  Up: How Kerberos Works

Network Services and Their Client Programs
==========================================

In an environment that provides network services, you use "client"
programs to request "services" from "server" programs that are
somewhere on the network.  Suppose you have logged in to a workstation
and you want to `rlogin' to a typical UNIX host.  You use the local
`rlogin' client program to contact the remote machine's `rlogind'
daemon.


File: krb5-admin.info,  Node: Kerberos Tickets,  Next: The Kerberos Database,  Prev: Network Services and Their Client Programs,  Up: How Kerberos Works

Kerberos Tickets
================

Under Kerberos, the `klogind' daemon allows you to login to a remote
machine if you can provide `klogind' a Kerberos ticket which proves
your identity.  In addition to the ticket, you must also have
possession of the corresponding ticket session key. The combination of
a ticket and the ticket's session key is known as a credential.

Typically, a client program automatically obtains credentials
identifying the person using the client program.  The credentials are
obtained from a Kerberos server that resides somewhere on the network.
A Kerberos server maintains a database of user, server, and password
information.


File: krb5-admin.info,  Node: The Kerberos Database,  Next: Kerberos Realms,  Prev: Kerberos Tickets,  Up: How Kerberos Works

The Kerberos Database
=====================

Kerberos will give you credentials only if you have an entry in the
Kerberos server's "Kerberos database".  Your database entry includes
your Kerberos "principal" (an identifying string, which is often just
your username), and your Kerberos password.  Every Kerberos user must
have an entry in this database.


File: krb5-admin.info,  Node: Kerberos Realms,  Next: The Ticket-Granting Ticket,  Prev: The Kerberos Database,  Up: How Kerberos Works

Kerberos Realms
===============

Each administrative domain will have its own Kerberos database, which
contains information about the users and services for that particular
site or administrative domain.  This administrative domain is the
"Kerberos realm".

Each Kerberos realm will have at least one Kerberos server, where the
master Kerberos database for that site or administrative domain is
stored.  A Kerberos realm may also have one or more "slave servers",
which have read-only copies of the Kerberos database that are
periodically propagated from the master server.  For more details on how
this is done, see the "Set Up the Slave KDCs for Database Propagation"
and "Propagate the Database to Each Slave KDC" sections of the Kerberos
V5 Installation Guide.


File: krb5-admin.info,  Node: The Ticket-Granting Ticket,  Next: Network Services and the Master Database,  Prev: Kerberos Realms,  Up: How Kerberos Works

The Ticket-Granting Ticket
==========================

The `kinit' command prompts for your password.  If you enter it
successfully, you will obtain a "ticket-granting ticket" and a "ticket
session key" which gives you the right to use the ticket.  This
combination of the ticket and its associated key is known as your
"credentials".  As illustrated below, client programs use your
ticket-granting ticket credentials in order to obtain client-specific
credentials as needed.

Your credentials are stored in a "credentials cache", which is often
just a file in `/tmp'.  The credentials cache is also called the
"ticket file", especially in Kerberos V4 documentation.  Note, however,
that a credentials cache does not have to be stored in a file.


File: krb5-admin.info,  Node: Network Services and the Master Database,  Next: The User/Kerberos Interaction,  Prev: The Ticket-Granting Ticket,  Up: How Kerberos Works

Network Services and the Master Database
========================================

The master database also contains entries for all network services that
require Kerberos authentication.  Suppose that your site has a machine,
`laughter.mit.edu', that requires Kerberos authentication from anyone
who wants to `rlogin' to it.  The host's Kerberos realm is
`ATHENA.MIT.EDU'.

This service must be registered in the Kerberos database, using the
proper service name, which in this case is the "principal":

     host/laughter.mit.edu@ATHENA.MIT.EDU

The `/' character separates the Kerberos "primary" (in this case,
`host') from the "instance" (in this case, `laughter.mit.edu'); the `@'
character separates the realm name (in this case, `ATHENA.MIT.EDU')
from the rest of the principal.  The primary, `host', denotes the name
or type of the service that is being offered:  generic host-level
access to the machine.  The instance, `laughter.mit.edu', names the
specific machine that is offering this service.  There will generally be
many different machines, each offering one particular type of service,
and the instance serves to give each one of these servers a different
Kerberos principal.

* Menu:

* The Keytab File::


File: krb5-admin.info,  Node: The Keytab File,  Prev: Network Services and the Master Database,  Up: Network Services and the Master Database

The Keytab File
---------------

For each service, there must also be a "service key" known only by
Kerberos and the service.  On the Kerberos server, the service key is
stored in the Kerberos database.

On the server host, these service keys are stored in "key tables",
which are files known as "keytabs".(1)  For example, the service keys
used by services that run as root are usually stored in the keytab file
`/etc/krb5.keytab'.  N.B.: This service key is the equivalent of the
service's password, and must be kept secure.  Data which is meant to be
read only by the service is encrypted using this key.

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

(1) Keytabs were called "srvtabs" in Kerberos V4.


File: krb5-admin.info,  Node: The User/Kerberos Interaction,  Next: Definitions,  Prev: Network Services and the Master Database,  Up: How Kerberos Works

The User/Kerberos Interaction
=============================

Suppose that you walk up to a host intending to login to it, and then
`rlogin' to the machine `laughter'.  Here's what happens:

  1. You login to the workstation and use the `kinit' command to get a
     ticket-granting ticket.  This command prompts you for your Kerberos
     password.  (On systems running the Kerberos V5 `login' program,
     this may be done as part of the login process, not requiring the
     user to run a separate program.)

       A. The `kinit' command sends your request to the Kerberos master
          server machine.  The server software looks for your principal
          name's entry in the Kerberos database.

       B. If this entry exists, the Kerberos server creates and returns
          a ticket-granting ticket and the key which allows you to use
          it, encrypted by your password.  If `kinit' can decrypt the
          Kerberos reply using the password you provide, it stores this
          ticket in a credentials cache on your local machine for later
          use.  The name of the credentials cache can be specified in
          the `KRB5CCNAME' environment variable.  If this variable is
          not set, the name of the file will be `/tmp/krb5cc_<uid>',
          where <uid> is your UNIX user-id, represented in decimal
          format.

  2. Now you use the `rlogin' client to access the machine `laughter'.

          host% rlogin laughter

       A. The `rlogin' client checks your ticket file to see if you
          have a ticket for the `host' service for `laughter'.  You
          don't, so `rlogin' uses the credential cache's
          ticket-granting ticket to make a request to the master
          server's ticket-granting service.

       B. This ticket-granting service receives the request for a
          ticket for `host/laughter.mit.edu', and looks in the master
          database for an entry for `host/laughter.mit.edu'.  If the
          entry exists, the ticket-granting service issues you a ticket
          for that service.  That ticket is also cached in your
          credentials cache.

       C. The `rlogin' client now sends that ticket to the `laughter'
          `klogind' service program.  The service program checks the
          ticket by using its own service key.  If the ticket is valid,
          it now knows your identity.  If you are allowed to login to
          `laughter' (because your username matches one in /etc/passwd,
          or your Kerberos principal is in the appropriate `.k5login'
          file), `klogind' will let you login.


File: krb5-admin.info,  Node: Definitions,  Prev: The User/Kerberos Interaction,  Up: How Kerberos Works

Definitions
===========

Following are definitions of some of the Kerberos terminology.

client
     an entity that can obtain a ticket.  This entity is usually either
     a user or a host.

host
     a computer that can be accessed over a network.

Kerberos
     in Greek mythology, the three-headed dog that guards the entrance
     to the underworld.  In the computing world, Kerberos is a network
     security package that was developed at MIT.

KDC
     Key Distribution Center.  A machine that issues Kerberos tickets.

keytab
     a key table file containing one or more keys.  A host or service
     uses a "keytab" file in much the same way as a user uses his/her
     password.

principal
     a string that names a specific entity to which a set of
     credentials may be assigned.  It generally has three parts:

    primary
          the first part of a Kerberos principal.  In the case of a
          user, it is the username.  In the case of a service, it is
          the name of the service.

    instance
          the second part of a Kerberos principal.  It gives
          information that qualifies the primary.  The instance may be
          null.  In the case of a user, the instance is often used to
          describe the intended use of the corresponding credentials.
          In the case of a host, the instance is the fully qualified
          hostname.

    realm
          the logical network served by a single Kerberos database and
          a set of Key Distribution Centers.  By convention, realm
          names are generally all uppercase letters, to differentiate
          the realm from the internet domain.

     The typical format of a typical Kerberos principal is
     primary/instance@REALM.

service
     any program or computer you access over a network.  Examples of
     services include "host" (a host, e.g., when you use `telnet' and
     `rsh'), "ftp" (FTP), "krbtgt" (authentication; cf. ticket-granting
     ticket), and "pop" (email).

ticket
     a temporary set of electronic credentials that verify the identity
     of a client for a particular service.

TGT
     Ticket-Granting Ticket.  A special Kerberos ticket that permits the
     client to obtain additional Kerberos tickets within the same
     Kerberos realm.


File: krb5-admin.info,  Node: Configuration Files,  Next: Administrating Kerberos Database Entries,  Prev: How Kerberos Works,  Up: Top

Configuration Files
*******************

* Menu:

* krb5.conf::
* kdc.conf::


File: krb5-admin.info,  Node: krb5.conf,  Next: kdc.conf,  Prev: Configuration Files,  Up: Configuration Files

krb5.conf
=========

The `krb5.conf' file contains Kerberos configuration information,
including the locations of KDCs and admin servers for the Kerberos
realms of interest, defaults for the current realm and for Kerberos
applications, and mappings of hostnames onto Kerberos realms.  Normally,
you should install your `krb5.conf' file in the directory `/etc'.  You
can override the default location by setting the environment variable
`KRB5_CONFIG'.

The `krb5.conf' file is set up in the style of a Windows INI file.
Sections are headed by the section name, in square brackets.  Each
section may contain zero or more relations, of the form:

     foo = bar

or

     fubar = {
             foo = bar
             baz = quux
     }

The `krb5.conf' file may contain any or all of the following seven
sections:

libdefaults
     Contains default values used by the Kerberos V5 library.

appdefaults
     Contains default values used by Kerberos V5 applications.

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

domain_realm
     Contains relations which map domain names and subdomains onto
     Kerberos realm names.  This is used by programs to determine what
     realm a host should be in, given its fully qualified domain name.

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

capaths
     Contains the authentication paths used with direct
     (nonhierarchical) cross-realm authentication.  Entries in this
     section are used by the client to determine the intermediate
     realms which may be used in cross-realm authentication.  It is
     also used by the end-service when checking the transited field for
     trusted intermediate realms.

kdc
     For a KDC, may contain the location of the kdc.conf file.

* Menu:

* libdefaults::
* appdefaults::
* realms (krb5.conf)::
* domain_realm::
* logging::
* capaths::
* Sample krb5.conf File::


File: krb5-admin.info,  Node: libdefaults,  Next: appdefaults,  Prev: krb5.conf,  Up: krb5.conf

[libdefaults]
-------------

The `libdefaults' section may contain any of the following relations:

default_realm
     Identifies the default Kerberos realm for the client.  Set its
     value to your Kerberos realm.

default_tgs_enctypes
     Identifies the supported list of session key encryption types that
     should be returned by the KDC.  The list may be delimited with
     commas or whitespace.  Currently, the supported encryption types
     are "des3-hmac-sha1" and "des-cbc-crc".  Support for other
     encryption types is planned in the future.

default_tkt_enctypes
     Identifies the supported list of session key encryption types that
     should be requested by the client.  The format is the same as for
     *default_tkt_enctypes*.  Again, the only supported encryption
     types are "des3-hmac-sha1" and "des-cbc-crc".

clockskew
     Sets the maximum allowable amount of clockskew in seconds that the
     library  will tolerate before assuming that a Kerberos message is
     invalid.  The default value is 300 seconds, or five minutes.

checksum_type
     Used for compatability with DCE security servers which do not
     support the default CKSUMTYPE_RSA_MD5 used by this version of
     Kerberos.  A value of 1 indicates the default checksum type.  Use
     a value of 2 to use the CKSUMTYPE_RSA_MD4 instead.  This applies
     to DCE 1.1 and earlier.

ccache_type
     Use this parameter on systems which are DCE clients, to specify
     the type of cache to be created by kinit, or when forwarded
     tickets are received.  DCE and Kerberos can share the cache, but
     some versions of DCE do not support the default cache as created
     by this version of Kerberos.  Use a value of 1 on DCE 1.0.3a
     systems, and a value of 2 on DCE 1.1 systems.

dns_lookup_kdc
     Indicate whether DNS SRV records should be used to locate the KDCs
     and other servers for a realm, if they are not listed in the
     information for the realm.  (Note that the `admin_server' entry
     must be in the file, because the DNS implementation for it is
     incomplete.)

     Enabling this option does open up a type of denial-of-service
     attack, if someone spoofs the DNS records and redirects you to
     another server.  However, it's no worse than a denial of service,
     because that fake KDC will be unable to decode anything you send
     it (besides the initial ticket request, which has no encrypted
     data), and anything the fake KDC sends will not be trusted without
     verification using some secret that it won't know.

     If this option is not specified but `dns_fallback' is, that value
     will be used instead.  If neither option is specified, the behavior
     depends on configure-time options; if none were given, the default
     is to enable this option.  If the DNS support is not compiled in,
     this entry has no effect.

dns_lookup_realm
     Indicate whether DNS TXT records should be used to determine the
     Kerberos realm of a host.

     Enabling this option may permit a redirection attack, where
     spoofed DNS replies persuade a client to authenticate to the wrong
     realm, when talking to the wrong host (either by spoofing yet more
     DNS records or by intercepting the net traffic).  Depending on how
     the client software manages hostnames, however, it could already
     be vulnerable to such attacks.  We are looking at possible ways to
     minimize or eliminate this exposure.  For now, we encourage more
     adventurous sites to try using Secure DNS.

     If this option is not specified but `dns_fallback' is, that value
     will be used instead.  If neither option is specified, the behavior
     depends on configure-time options; if none were given, the default
     is to disable this option.  If the DNS support is not compiled in,
     this entry has no effect.

dns_fallback
     General flag controlling the use of DNS for Kerberos information.
     If both of the preceding options are specified, this option has no
     effect.


File: krb5-admin.info,  Node: appdefaults,  Next: realms (krb5.conf),  Prev: libdefaults,  Up: krb5.conf

[appdefaults]
-------------

Each tag in the [appdefaults] section names a Kerberos V5 application.
The value of the tag is a subsection with relations that define the
default behaviors for that application.

For example:

     [appdefaults]
         kinit = {
             forwardable = true
         }
         telnet = {
             forward = true
             encrypt = true
             autologin = true
         }

The list of specifiable options for each application may be found in
that application's man pages.  The application defaults specified here
are overridden by those specified in the [realms] section.


File: krb5-admin.info,  Node: realms (krb5.conf),  Next: domain_realm,  Prev: appdefaults,  Up: krb5.conf

[realms]
--------

Each tag in the [realms] section of the file is the name of a Kerberos
realm.  The value of the tag is a subsection with relations that define
the properties of that particular realm.  For each realm, the following
tags may be specified in the realm's subsection:

kdc
     The name of a host running a KDC for that realm.  An optional port
     number (separated from the hostname by a colon) may be included.

admin_server
     Identifies the host where the administration server is running.
     Typically, this is the master Kerberos server.

application defaults
     Application defaults that are specific to a particular realm may be
     specified within that realm's tag.  Realm-specific application
     defaults override the global defaults specified in the
     [appdefaults] section.


File: krb5-admin.info,  Node: domain_realm,  Next: logging,  Prev: realms (krb5.conf),  Up: krb5.conf

[domain_realm]
--------------

The [domain_realm] section provides a translation from a domain name or
hostname to a Kerberos realm name.  The tag name can be a host name, or
a domain name, where domain names are indicated by a prefix of a period
(`.').  The value of the relation is the Kerberos realm name for that
particular host or domain.  Host names and domain names should be in
lower case.

If no translation entry applies, the host's realm is considered to be
the hostname's domain portion converted to upper case.  For example, the
following [domain_realm] section:

     [domain_realm]
         .mit.edu = ATHENA.MIT.EDU
         mit.edu = ATHENA.MIT.EDU
         crash.mit.edu = TEST.ATHENA.MIT.EDU
         fubar.org = FUBAR.ORG

maps crash.mit.edu into the TEST.ATHENA.MIT.EDU realm.  All other hosts
in the mit.edu domain will map by default to the ATHENA.MIT.EDU realm,
and all hosts in the fubar.org domain will map by default into the
FUBAR.ORG realm.  Note the entries for the hosts mit.edu and
fubar.org.  Without these entries, these hosts would be mapped into the
Kerberos realms `EDU' and `ORG', respectively.


File: krb5-admin.info,  Node: logging,  Next: capaths,  Prev: domain_realm,  Up: krb5.conf

[logging]
---------

The [logging] section indicates how a particular entity is to perform
its logging.  The relations in this section assign one or more values to
the entity name.  Currently, the following entities are used:

admin_server
     These entries specify how the administrative server is to perform
     its logging.

default
     These entries specify how to perform logging in the absence of
     explicit specifications otherwise.

Values are of the following forms:

FILE=<filename>
FILE:<filename>
     This value causes the entity's logging messages to go to the
     specified file.  If the `=' form is used, the file is overwritten.
     If the `:' form is used, the file is appended to.

STDERR
     This value causes the entity's logging messages to go to its
     standard error stream.

CONSOLE
     This value causes the entity's logging messages to go to the
     console, if the system supports it.

DEVICE=<devicename>
     This causes the entity's logging messages to go to the specified
     device.

SYSLOG[:<severity>[:<facility>]]
     This causes the entity's logging messages to go to the system log.

     The "severity" argument specifies the default severity of system
     log messages.  This may be any of the following severities
     supported by the `syslog(3)' call, minus the LOG_ prefix:
     LOG_EMERG, LOG_ALERT, LOG_CRIT, LOG_ERR, LOG_WARNING, LOG_NOTICE,
     LOG_INFO, and LOG_DEBUG.  For example, a value of `CRIT' would
     specify LOG_CRIT severity.

     The facility argument specifies the facility under which the
     messages are logged.  This may be any of the following facilities
     supported by the syslog(3) call minus the LOG_ prefix:  LOG_KERN,
     LOG_USER, LOG_MAIL, LOG_DAEMON, LOG_AUTH, LOG_LPR, LOG_NEWS,
     LOG_UUCP, LOG_CRON, and LOG_LOCAL0 through LOG_LOCAL7.

     If no severity is specified, the default is ERR.  If no facility is
     specified, the default is AUTH.

In the following example, the logging messages from the KDC will go to
the console and to the system log under the facility LOG_DAEMON with
default severity of LOG_INFO; and the logging messages from the
administrative server will be appended to the file /var/adm/kadmin.log
and sent to the device /dev/tty04.

     [logging]
         kdc = CONSOLE
         kdc = SYSLOG:INFO:DAEMON
         admin_server = FILE:/var/adm/kadmin.log
         admin_server = DEVICE=/dev/tty04


File: krb5-admin.info,  Node: capaths,  Next: Sample krb5.conf File,  Prev: logging,  Up: krb5.conf

[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 be 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 [capath]
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 [capath] 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
determing 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.


File: krb5-admin.info,  Node: Sample krb5.conf File,  Prev: capaths,  Up: krb5.conf

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

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

     [libdefaults]
         ticket_lifetime = 600
         default_realm = ATHENA.MIT.EDU
         default_tkt_enctypes = des3-hmac-sha1 des-cbc-crc
         default_tgs_enctypes = des3-hmac-sha1 des-cbc-crc
     
     [realms]
         ATHENA.MIT.EDU = {
             kdc = kerberos.mit.edu
             kdc = kerberos-1.mit.edu
             kdc = kerberos-2.mit.edu
             admin_server = kerberos.mit.edu
             default_domain = mit.edu
         }
         FUBAR.ORG = {
             kdc = kerberos.fubar.org
             kdc = kerberos-1.fubar.org
             admin_server = kerberos.fubar.org
         }
     
     [domain_realm]
         .mit.edu = ATHENA.MIT.EDU
         mit.edu = ATHENA.MIT.EDU


File: krb5-admin.info,  Node: kdc.conf,  Prev: krb5.conf,  Up: Configuration Files

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.  (*Note 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.

* Menu:

* kdcdefaults::
* realms (kdc.conf)::
* Sample kdc.conf File::


File: krb5-admin.info,  Node: kdcdefaults,  Next: realms (kdc.conf),  Prev: kdc.conf,  Up: kdc.conf

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

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

kdc_ports
     This relation lists the ports on which the Kerberos server should
     listen by default.  This list is a comma separated list of
     integers.  If this relation is not specified, the compiled-in
     default is usually port 88 (the assigned Kerberos port) and port
     750 (the port used by Kerberos V4).


File: krb5-admin.info,  Node: realms (kdc.conf),  Next: Sample kdc.conf File,  Prev: kdcdefaults,  Up: kdc.conf

[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 kadmin uses 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.

default_principal_flags
     (Flag string.)  Specifies the default attributes of principals
     created in this realm.

dict_file
     (String.)  Location of the dictionary file containing strings that
     are not allowed as passwords.  The default is
     `/usr/local/var/krb5kdc/kadm5.dict'.

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

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 this realm.  By default, the value of kdc_ports as
     specified in the [kdcdefaults] section is used.

master_key_name
     (String.)  Specifies the name of the master key.

master_key_type
     (Key type string.)  Specifies the master key's key type.  Either
     "des3-hmac-sha1" or "des-cbc-crc" may be used at this time.

max_life
     (Delta time string.)  Specifes the maximum time period for which a
     ticket may be valid in this realm.

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

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.  If you do not yet
     wish to enable triple-DES support, you should set this tag to
     `des-cbc-crc:normal des-cbc-crc:v4'; otherwise, put
     `des3-hmac-sha1:normal' at the beginning of the list.

kdc_supported_enctypes
     List of key:salt strings.  Specifies the permitted key/salt
     combinations of principals for this realm.  You should set this
     tag to `des3-hmac-sha1:normal des-cbc-crc:normal des-cbc-crc:v4'.

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'.


File: krb5-admin.info,  Node: Sample kdc.conf File,  Prev: realms (kdc.conf),  Up: kdc.conf

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 = 10h 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
             kdc_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


File: krb5-admin.info,  Node: Administrating Kerberos Database Entries,  Next: Application Servers,  Prev: Configuration Files,  Up: Top

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.

* Menu:

* Kadmin Options::
* Date Format::
* Principals::
* Policies::
* Dumping a Kerberos Database to a File::
* Restoring a Kerberos Database from a Dump File::
* Creating a Stash File::
* Creating and Destroying a Kerberos Database::


File: krb5-admin.info,  Node: Kadmin Options,  Next: Date Format,  Prev: Administrating Kerberos Database Entries,  Up: Administrating Kerberos Database Entries

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

You can invoke `kadmin' 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 grom `getpwuid', in order of
     preference.

-k 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'.

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

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

-e "enctypes ..."
     (For `kadmin.local' only.)  Sets the list of cryptosystem and salt
     types to be used for any new keys created.  Available types
     include `des3-cbc-sha1:normal', `des-cbc-crc:normal', and
     `des-cbc-crc:v4'.


File: krb5-admin.info,  Node: Date Format,  Next: Principals,  Prev: Kadmin Options,  Up: Administrating Kerberos Database Entries

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"

Two-digit years are allowed in places, but the use of this form is not
recommended.

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, sept, sep, 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, 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 *Note kadmin Time Zones::.

12-hour Time Delimiters
     am, pm


File: krb5-admin.info,  Node: Principals,  Next: Policies,  Prev: Date Format,  Up: Administrating Kerberos Database Entries

Principals
==========

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

* Menu:

* Retrieving Information About a Principal::
* Privileges::
* Adding or Modifying Principals::
* Deleting Principals::
* Changing Passwords::


File: krb5-admin.info,  Node: Retrieving Information About a Principal,  Next: Privileges,  Prev: Principals,  Up: Principals

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

* Menu:

* Attributes::
* Retrieving a List of Principals::

