--- /dev/null
+# -*- coding: utf-8 -*-
+#
+# MIT Kerberos documentation build configuration file, created by
+# sphinx-quickstart on Wed Oct 13 09:14:03 2010.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#sys.path.insert(0, os.path.abspath('.'))
+
+# -- General configuration -----------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be extensions
+# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+#extensions = ['sphinx.ext.autodoc', 'sphinxcontrib.doxylink']
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode']
+
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The encoding of source files.
+#source_encoding = 'utf-8-sig'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'MIT Kerberos'
+copyright = u'2011, MIT'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = '0.0.1'
+# The full version, including alpha/beta/rc tags.
+release = '0.0.1'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#language = None
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+#today_fmt = '%B %d, %Y'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = []
+
+# The reST default role (used for this markup: `text`) to use for all documents.
+#default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# A list of ignored prefixes for module index sorting.
+#modindex_common_prefix = []
+
+
+# -- Options for HTML output ---------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages. See the documentation for
+# a list of builtin themes.
+# html_theme = 'default'
+html_theme = 'sphinxdoc'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further. For a list of options available for each theme, see the
+# documentation.
+#html_theme_options = {}
+
+# Add any paths that contain custom themes here, relative to this directory.
+#html_theme_path = []
+
+# The name for this set of Sphinx documents. If None, it defaults to
+# "<project> v<release> documentation".
+#html_title = None
+
+# A shorter title for the navigation bar. Default is the same as html_title.
+#html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+html_logo = "./dogkeys.jpg"
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+#html_favicon = None
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+#html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+#html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+
+# If false, no module index is generated.
+#html_domain_indices = True
+
+# If false, no index is generated.
+#html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+html_split_index = True
+
+# If true, links to the reST sources are added to the pages.
+#html_show_sourcelink = True
+
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
+#html_show_sphinx = True
+
+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
+#html_show_copyright = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it. The value of this option must be the
+# base URL from which the finished HTML is served.
+#html_use_opensearch = ''
+
+# This is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = None
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'MIT Kerberos'
+
+pointsize = '10pt'
+
+# -- Options for LaTeX output --------------------------------------------------
+
+# The paper size ('letter' or 'a4').
+#latex_paper_size = 'letter'
+
+# The font size ('10pt', '11pt' or '12pt').
+#latex_font_size = '10pt'
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, documentclass [howto/manual]).
+latex_documents = [
+ ('index', 'MIT Kerberos.tex', u'MIT Kerberos Documentation',
+ u'MIT', 'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+#latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+#latex_use_parts = False
+
+# If true, show page references after internal links.
+#latex_show_pagerefs = False
+
+# If true, show URL addresses after external links.
+#latex_show_urls = False
+
+# Additional stuff for the LaTeX preamble.
+#latex_preamble = ''
+
+# Documents to append as an appendix to all manuals.
+#latex_appendices = []
+
+# If false, no module index is generated.
+#latex_domain_indices = True
+
+
+# -- Options for manual page output --------------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+ ('index', 'krbdoc', u'MIT Kerberos Documentation',
+ [u'MIT'], 1)
+]
--- /dev/null
+MIT Kerberos Documentation.
+===================================
+
+Contents
+=========
+
+.. toctree::
+ :maxdepth: 1
+
+ mitK5features.rst
+ krb_appldev/index.rst
+ krb_admins/index.rst
+ krb_users/index.rst
+ relay/index.rst
+
+
+Feedback
+========
+
+Please, provide your feedback or suggest a new topic at krb5-bugs@mit.edu?subject=Documentation___main
+
+..
+
+
+Version
+=======
+
+.. _reference:
+
+:Release: |version|
+
+:Date: |today|
--- /dev/null
+Advanced topics
+============================
+
+
+Contents:
+---------
+
+.. toctree::
+ :maxdepth: 1
+
+ ldapbackend.rst
+ plugins.rst
+
+
+
+Topics in TODO list:
+---------------------
+
+ Choosing backend: LDAP vs DB2
+ Validating Kerberos tickets
+ Cross-realm interaction with AD
+ Replication
+ Performance tuning tips
+ Error log messages
+
+------------------
+
+Feedback:
+
+Please, provide your feedback on this document at krb5-bugs@mit.edu?subject=Documentation___admin_advanced
--- /dev/null
+.. _ldap_be_ubuntu:
+
+LDAP backend on Ubuntu 10.4 (lucid)
+====================================
+
+Setting up Kerberos v1.9 with LDAP backend on Ubuntu 10.4 (lucid Lynx)
+
+Prerequisites:
+--------------
+
+Install the following packages: *slapd, ldap-utils* and *libldap2-dev*
+
+You can install the necessary packages with these commands::
+
+ sudo apt-get install slapd
+ sudo apt-get install ldap-utils
+ sudo apt-get install libldap2-dev
+
+Extend the user schema using schemas from standart OpenLDAP distribution: *cosine, mics, nis, inetcomperson* ::
+
+ ldapadd -Y EXTERNAL -H ldapi:/// -f /etc/ldap/schema/cosine.ldif
+ ldapadd -Y EXTERNAL -H ldapi:/// -f /etc/ldap/schema/mics.ldif
+ ldapadd -Y EXTERNAL -H ldapi:/// -f /etc/ldap/schema/nis.ldif
+ ldapadd -Y EXTERNAL -H ldapi:/// -f /etc/ldap/schema/inetcomperson.ldif
+
+Building Kerberos from source:
+------------------------------
+
+::
+
+ util/reconf
+ ./configure –with-ldap
+ make
+ sudo make install
+
+.. note:: in some environments one may need to suppress *rpath* linker option: *./configure –with-ldap –disable-rpath*
+
+Setting up Kerberos:
+--------------------------------
+
+Configuration:
+~~~~~~~~~~~~~~
+
+Update Kerberos configuration files with the backend information:
+
+krb5.conf::
+
+ [realms]
+ EXAMPLE.COM = {
+ database_module = LDAP
+ }
+
+ [dbdefaults]
+ ldap_kerberos_container_dn = "cn=krbContainer,dc=example,dc=com"
+
+ [dbmodules]
+ LDAP = {
+ db_library = kldap
+ ldap_kerberos_container_dn = "cn=krbContainer,dc=example,dc=com"
+ ldap_kdc_dn = cn=admin,dc=example,dc=com
+ ldap_kadmind_dn = cn=admin,dc=example,dc=com
+ ldap_service_password_file = /tmp/krb5kdc/admin.stash
+ ldap_servers = ldapi:///
+ }
+
+
+kdc.conf::
+
+ [realms]
+ EXAMPLE.COM = {
+ acl_file = /tmp/kadm5.acl
+
+
+kadm5.acl::
+
+ # See Kerberos V5 Installation Guide for detail of ACL setup and configuration
+ */admin *
+
+Setup run-time environment to point to the Kerberos configuration files::
+
+ export KRB5_CONFIG=/tmp/krb5.conf
+ export KRB5_KDC_PROFILE=/tmp/kdc.conf
+
+
+Schema:
+~~~~~~~
+
+From the source tree copy *src/plugins/kdb/ldap/libkdb_ldap/kerberos.schema* into */etc/ldap/schema*
+
+Warning:: it should be done after slapd is installed to avoid problems with slapd installation
+
+To convert *kerberos.schema* to run-time configuration (cn=config) do the folowing:
+
+#. create temporary file /tmp/schema_convert.conf with the following content::
+
+ include /etc/ldap/schema/kerberos.schema
+
+#. Create temporary directory */tmp/krb5_ldif*
+
+#. Run::
+
+ slaptest -f /tmp/schema_convert.conf -F /tmp/krb5_ldif
+
+ It should result into a new file */tmp/krb5_ldif/cn=config/cn=schema/cn={0}kerberos.ldif*
+
+#. Edit /tmp/krb5_ldif/cn=config/cn=schema/cn={0}kerberos.ldif by replacing lines::
+
+ dn: cn={0}kerberos
+ cn: {0}kerberos
+
+ with
+
+ dn: cn=kerberos,cn=schema,cn=config
+ cn: kerberos
+
+ Also, remove following attribute-value pairs::
+
+ structuralObjectClass: olcSchemaConfig
+ entryUUID: ...
+ creatorsName: cn=config
+ createTimestamp: ...
+ entryCSN: ...
+ modifiersName: cn=config
+ modifyTimestamp: ...
+
+#. Load the new schema with ldapadd (with the proper authentication)::
+
+ ldapadd -Y EXTERNAL -H ldapi:/// -f /tmp/krb5_ldif/cn=config/cn=schema/cn={0}kerberos.ldif
+
+ which should result into *adding new entry "cn=kerberos,cn=schema,cn=config"* message
+
+
+Create Kerberos database:
+-------------------------
+
+Using LDAP administrator credentials, create Kerberos database and stash::
+
+ kdb5_ldap_util -D cn=admin,dc=example,dc=com -H ldapi:/// create
+
+
+Stash the password::
+
+ kdb5_ldap_util -D cn=admin,dc=example,dc=com -H ldapi:/// stashsrvpw cn=admin,dc=example,dc=com
+
+
+Start kdc::
+
+ krb5kdc
+
+
+To destroy database run::
+
+ kdb5_ldap_util -D cn=admin,dc=example,dc=com -H ldapi:/// destroy -f
+
+
+Useful references:
+-------------------
+
+* `Kerberos and LDAP <https://help.ubuntu.com/10.04/serverguide/C/kerberos-ldap.html>`_
+
+------------------
+
+Feedback:
+
+Please, provide your feedback on this document at krb5-bugs@mit.edu?subject=Documentation___ldap_be_ubuntu
+
+
--- /dev/null
+How to create and add plugins
+===================================
+
+Initial reference: <http://k5wiki.kerberos.org/wiki/Projects/Plugin_support_improvements>_
+
+..
+
+------------------
+
+Feedback:
+
+Please, provide your feedback on this document at krb5-bugs@mit.edu?subject=Documentation___plugins
--- /dev/null
+Clock Skew
+============
+
+In order to prevent intruders from resetting their system clocks in order to continue to use expired tickets, Kerberos V5 is set up to reject ticket requests from any host whose clock is not within the specified maximum clock skew of the KDC (as specified in the kdc.conf file). Similarly, hosts are configured to reject responses from any KDC whose clock is not within the specified maximum clock skew of the host (as specified in the krb5.conf file). The default value for maximum clock skew is 300 seconds, or five minutes. MIT suggests that you add a line to client machines' /etc/rc files to synchronize the machine's clock to your KDC at boot time. On UNIX hosts, assuming you had a kdc called kerberos in your realm, this would be::
+
+ gettime -s kerberos
+
+
+If the host is not likely to be rebooted frequently, you may also want to set up a cron job that adjusts the time on a regular basis.
+
+----------------------
+
+Feedback:
+
+Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___appl_servers
+
--- /dev/null
+Configuring your firewall to work with Kerberos V5
+=====================================================
+
+If you need off-site users to be able to get Kerberos tickets in your realm, they must be able to get to your KDC. This requires either that you have a slave KDC outside your firewall, or you configure your firewall to allow UDP requests into at least one of your KDCs, on whichever port the KDC is running. (The default is port 88; other ports may be specified in the KDC's kdc.conf file.) Similarly, if you need off-site users to be able to change their passwords in your realm, they must be able to get to your Kerberos admin server. The default port for the admin server is 749.
+
+If your on-site users inside your firewall will need to get to KDCs in other realms, you will also need to configure your firewall to allow outgoing TCP and UDP requests to port 88. Additionally, if they will need to get to any Kerberos V4 KDCs, you may also need to allow TCP and UDP requests to port 750. If your on-site users inside your firewall will need to get to Kerberos admin servers in other realms, you will also need to allow outgoing TCP and UDP requests to port 749.
+
+If any of your KDCs are outside your firewall, you will need to allow *kprop* requests to get through to the remote KDC.
+*kprop* uses the *krb5_prop* service on port 754 (tcp).
+
+If you need your off-site users to have access to machines inside your firewall, you need to allow TCP connections from their off-site hosts on the appropriate ports for the programs they will be using. The following lines from */etc/services* show the default port numbers for the Kerberos V5 programs::
+
+ ftp 21/tcp # Kerberos ftp and telnet use the
+ telnet 23/tcp # default ports
+ kerberos 88/udp kdc # Kerberos V5 KDC
+ kerberos 88/tcp kdc # Kerberos V5 KDC
+ klogin 543/tcp # Kerberos authenticated rlogin
+ kshell 544/tcp cmd # and remote shell
+ kerberos-adm 749/tcp # Kerberos 5 admin/changepw
+ kerberos-adm 749/udp # Kerberos 5 admin/changepw
+ krb5_prop 754/tcp # Kerberos slave propagation
+ eklogin 2105/tcp # Kerberos auth. & encrypted rlogin
+
+
+By default, Kerberos V5 telnet and ftp use the same ports as the standard telnet and ftp programs, so if you already allow telnet and ftp connections through your firewall, the Kerberos V5 versions will get through as well. If you do not already allow telnet and ftp connections through your firewall, but need your users to be able to use Kerberos V5 telnet and ftp, you can either allow ftp and telnet connections on the standard ports, or switch these programs to non-default port numbers and allow ftp and telnet connections on those ports to get through. Kerberos V5 rlogin uses the *klogin* service, which by default uses port 543. Encrypted Kerberos V5 rlogin uses the *eklogin* service, which by default uses port 2105. Kerberos V5 rsh uses the kshell service, which by default uses port 544. However, the server must be able to make a TCP connection from the kshell port to an arbitrary port on the client, so if your users are to be able to use rsh from outside your firewall, the server they connect to must be able to send outgoing packets to arbitrary port numbers. Similarly, if your users need to run rsh from inside your firewall to hosts outside your firewall, the outside server needs to be able to connect to an arbitrary port on the machine inside your firewall. Because Kerberos V5 rcp uses rsh, the same issues apply. If you need to use rsh (or rcp) through your firewall and are concerned with the security implications of allowing connections to arbitrary ports, MIT suggests that you have rules that specifically name these applications and, if possible, list the allowed hosts.
+
+The book UNIX System Security, by David Curry, is a good starting point for learning to configure firewalls.
+
+----------------------
+
+Feedback:
+
+Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___appl_servers
+
--- /dev/null
+Getting DNS information correct
+===================================
+
+Several aspects of Kerberos rely on name service. In order for Kerberos to provide its high level of security, it is less forgiving of name service problems than some other parts of your network. It is important that your Domain Name System (DNS) entries and your hosts have the correct information.
+
+Each host's canonical name must be the fully-qualified host name (including the domain), and each host's IP address must reverse-resolve to the canonical name.
+
+Other than the localhost entry, make all entries in each machine's /etc/hosts file in the following form::
+
+ IP address fully-qualified hostname aliases
+
+
+Here is a sample */etc/hosts* file::
+
+ # this is a comment
+ 127.0.0.1 localhost localhost@mit.edu
+ 10.0.0.6 daffodil.mit.edu trillium wake-robin
+
+
+Additionally, on Solaris machines, you need to be sure the "hosts" entry in the file */etc/nsswitch.conf* includes the source "dns" as well as "file".
+
+Finally, each host's keytab file must include a host/key pair for the host's canonical name. You can list the keys in a keytab file by issuing the command *klist -k*. For example::
+
+ viola# klist -k
+ Keytab name: /etc/krb5.keytab
+ KVNO Principal
+ ---- ------------------------------------------------------------
+ 1 host/daffodil.mit.edu@ATHENA.MIT.EDU
+
+
+If you telnet to the host with a fresh credentials cache (ticket file), and then *klist*, the host's service principal should be::
+
+ host/fully-qualified-hostname@REALM_NAME.
+
+----------------------
+
+Feedback:
+
+Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___appl_servers
+
--- /dev/null
+Application servers
+==========================
+
+If you need to install the Kerberos V5 programs on an application server, please refer to the Kerberos V5 Installation Guide. Once you have installed the software, you need to add that host to the Kerberos database (see :ref:`add_mod_princs_label`), and generate a keytab for that host, that contains the host's key. You also need to make sure the host's clock is within your maximum clock skew of the KDCs.
+
+
+.. toctree::
+ :maxdepth: 2
+
+ keytabs.rst
+ clock_skew.rst
+ dns_info.rst
+ conf_firewall.rst
+
+----------------------
+
+Feedback:
+
+Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___appl_servers
+
--- /dev/null
+Keytabs
+==============
+
+A keytab is a host's copy of its own keylist, which is analogous to a user's password. An application server that needs to authenticate itself to the KDC has to have a keytab that contains its own principal and key. Just as it is important for users to protect their passwords, it is equally important for hosts to protect their keytabs. You should always store keytab files on local disk, and make them readable only by root, and you should never send a keytab file over a network in the clear. Ideally, you should run the kadmin command to extract a keytab on the host on which the keytab is to reside.
+
+
+.. _add_princ_kt:
+
+Adding Principals to Keytabs
+----------------------------------
+
+To generate a keytab, or to add a principal to an existing keytab, use the **ktadd** command from kadmin, which requires the "inquire" administrative privilege. (If you use the -glob princ_exp option, it also requires the "list" administrative privilege.) The syntax is::
+
+ ktadd [-k[eytab] keytab] [-q] [-e key:salt_list] [principal | -glob princ_exp] [...]
+
+
+The *ktadd* command takes the following switches
+
+============================================= =================================================================
+-k[eytab] *keytab* Use keytab as the keytab file. Otherwise, *ktadd* will use the default keytab file (*/etc/krb5.keytab*).
+-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 :ref:`senct_label` and :ref:`salts_label` for all possible values.
+-q Run in quiet mode. This causes *ktadd* to display less verbose information.
+principal | -glob *principal expression* Add principal, or all principals matching principal expression to the keytab. The rules for principal expression are the same as for the kadmin list_principals (see :ref:`get_list_princs`) command.
+============================================= =================================================================
+
+Here is a sample session, using configuration files that enable only *des-cbc-crc* encryption. (The line beginning with => is a continuation of the previous line.)::
+
+ kadmin: ktadd host/daffodil.mit.edu@ATHENA.MIT.EDU
+ kadmin: Entry for principal host/daffodil.mit.edu@ATHENA.MIT.EDU with
+ kvno 2, encryption type DES-CBC-CRC added to keytab
+ WRFILE:/etc/krb5.keytab.
+ kadmin:
+
+
+ kadmin: ktadd -k /usr/local/var/krb5kdc/kadmind.keytab
+ => kadmin/admin kadmin/changepw
+ kadmin: Entry for principal kadmin/admin@ATHENA.MIT.EDU with
+ kvno 3, encryption type DES-CBC-CRC added to keytab
+ WRFILE:/usr/local/var/krb5kdc/kadmind.keytab.
+ kadmin:
+
+
+Removing Principals from Keytabs
+---------------------------------
+
+To remove a principal from an existing keytab, use the kadmin **ktremove** command. The syntax is::
+
+ ktremove [-k[eytab] keytab] [-q] principal [kvno | all | old]
+
+
+The *ktremove* command takes the following switches
+
+
+====================== ====================================
+-k[eytab] *keytab* Use keytab as the keytab file. Otherwise, *ktremove* will use the default keytab file (*/etc/krb5.keytab*).
+-q Run in quiet mode. This causes *ktremove* to display less verbose information.
+*principal* The principal to remove from the keytab. (Required.)
+*kvno* Remove all entries for the specified principal whose Key Version Numbers match *kvno*.
+all Remove all entries for the specified principal
+old Remove all entries for the specified principal *except those with the highest kvno*.
+====================== ====================================
+
+For example::
+
+ kadmin: ktremove -k /usr/local/var/krb5kdc/kadmind.keytab kadmin/admin
+ kadmin: Entry for principal kadmin/admin with kvno 3 removed
+ from keytab WRFILE:/usr/local/var/krb5kdc/kadmind.keytab.
+ kadmin:
+
+----------------------
+
+Feedback:
+
+Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___appl_servers
+
--- /dev/null
+Backups of secure hosts
+===========================
+
+.. note:: This document was copied from **Kerberos V5 System Administrator's Guide** with minor changes. Currently it is under review. Please, send your feedback, corrections and additions to krb5-bugs@mit.edu. Your contribution is greatly appreciated.
+
+When you back up a secure host, you should exclude the host's keytab file from the backup. If someone obtained a copy of the keytab from a backup, that person could make any host masquerade as the host whose keytab was compromised. This could be particularly dangerous if the compromised keytab was from one of your KDCs. If the machine has a disk crash and the keytab file is lost, it is easy to generate another keytab file. (See :ref:`add_princ_kt`.) If you are unable to exclude particular files from backups, you should ensure that the backups are kept as secure as the host's root password.
+
+
+Backing up the Kerberos database
+--------------------------------------
+
+As with any file, it is possible that your Kerberos database could become corrupted. If this happens on one of the slave KDCs, you might never notice, since the next automatic propagation of the database would install a fresh copy. However, if it happens to the master KDC, the corrupted database would be propagated to all of the slaves during the next propagation. For this reason, MIT recommends that you back up your Kerberos database regularly. Because the master KDC is continuously dumping the database to a file in order to propagate it to the slave KDCs, it is a simple matter to have a cron job periodically copy the dump file to a secure machine elsewhere on your network. (Of course, it is important to make the host where these backups are stored as secure as your KDCs, and to encrypt its transmission across your network.) Then if your database becomes corrupted, you can load the most recent dump onto the master KDC. (See :ref:`restore_from_dump`.)
+
+-----------------------------------
+
+Feedback:
+
+Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___backup_secure_hosts
+
--- /dev/null
+.. _senct_label:
+
+Supported Encryption Types
+===============================
+
+
+Any tag in the configuration files which requires a list of encryption types can be set to some combination of the following strings. Encryption types marked as "weak" are available for compatibility but not recommended for use.
+
+==================================================== =========================================================
+des-cbc-crc DES cbc mode with CRC-32 (weak)
+des-cbc-md4 DES cbc mode with RSA-MD4 (weak)
+des-cbc-md5 DES cbc mode with RSA-MD5 (weak)
+des-cbc-raw DES cbc mode raw (weak)
+des3-cbc-raw Triple DES cbc mode raw (weak)
+des3-cbc-sha1 des3-hmac-sha1 des3-cbc-sha1-kd Triple DES cbc mode with HMAC/sha1
+des-hmac-sha1 DES with HMAC/sha1 (weak)
+aes256-cts-hmac-sha1-96 aes256-cts AES-256 CTS mode with 96-bit SHA-1 HMAC
+aes128-cts-hmac-sha1-96 aes128-cts AES-128 CTS mode with 96-bit SHA-1 HMAC
+arcfour-hmac rc4-hmac arcfour-hmac-md5 RC4 with HMAC/MD5
+arcfour-hmac-exp rc4-hmac-exp arcfour-hmac-md5-exp Exportable RC4 with HMAC/MD5 (weak)
+des The DES family: des-cbc-crc, des-cbc-md5, and des-cbc-md4 (weak)
+des3 The triple DES family: des3-cbc-sha1
+aes The AES family: aes256-cts-hmac-sha1-96 and aes128-cts-hmac-sha1-96
+rc4 The RC4 family: arcfour-hmac
+==================================================== =========================================================
+
+The string **DEFAULT** can be used to refer to the default set of types for the variable in question. Types or families can be removed from the current list by prefixing them with a minus sign ("-"). Types or families can be prefixed with a plus sign ("+") for symmetry; it has the same meaning as just listing the type or family. For example, **"DEFAULT -des"** would be the default set of encryption types with DES types removed, and **"des3 DEFAULT"** would be the default set of encryption types with triple DES types moved to the front.
+
+While *aes128-cts* and *aes256-cts* are supported for all Kerberos operations, they are not supported by older versions of our GSSAPI implementation (krb5-1.3.1 and earlier).
+
+By default, AES is enabled in 1.9 release. Sites wishing to use AES encryption types on their KDCs need to be careful not to give GSSAPI services AES keys if the servers have not been updated. If older GSSAPI services are given AES keys, then services may fail when clients supporting AES for GSSAPI are used. Sites may wish to use AES for user keys and for the ticket granting ticket key, although doing so requires specifying what encryption types are used as each principal is created.
+
+If all GSSAPI-based services have been updated before or with the KDC, this is not an issue.
+
+--------------
+
+Feedback:
+
+Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___conf_files
+
+
--- /dev/null
+Configuration Files
+=========================
+
+.. note:: This document was copied from **Kerberos V5 System Administrator's Guide** with minor changes. Currently it is under review. Please, send your feedback, corrections and additions to krb5-bugs@mit.edu. Your contribution is greatly appreciated.
+
+
+.. toctree::
+ :maxdepth: 2
+
+ enc_types.rst
+ salts.rst
+ krb5_conf.rst
+ kdc_conf.rst
+
+--------------
+
+Feedback:
+
+Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___conf_files
+
+
+
--- /dev/null
+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*.
+
+Structure
+--------------
+
+The kdc.conf file is set up in the same format as the :ref:`krb5_conf_label` file. 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.
+================== ================================
+
+Sections
+-------------
+
+
+.. _kdcdefaults:
+
+**[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.
+restrict_anonymous_to_tgt
+ This flag determines the default value of restrict_anonymous_to_tgt for realms. The default value is false.
+
+.. _realms:
+
+**[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*.
+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:ref:`senct_label`.
+max_life
+ (Delta time string.) Specifes the maximum time period for which a ticket may be valid in this realm. The default value is 24 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 aes256-cts-hmac-sha1-96:normal aes128-cts-hmac-sha1-96:normal des3-cbc-sha1:normal arcfour-hmac-md5:normal. For lists of possible values, see :ref:`senct_label` and :ref:`salts_label`
+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.
+restrict_anonymous_to_tgt
+ A boolean value (true, false). If set to true, the KDC will reject ticket requests from anonymous principals to service principals other than the realm's ticket-granting service. This option allows anonymous PKINIT to be enabled for use as FAST armor tickets without allowing anonymous authentication to services. By default, the value of restrict_anonymous_to_tgt as specified in the [kdcdefaults] section is used.
+
+
+.. _logging:
+
+**[logging]**
+
+See *[logging]* section in :ref:`krb5_conf_label`
+
+
+PKINIT options
+---------------
+
+.. note:: The following are pkinit-specific options. Note that these values may be specified in [kdcdefaults] as global defaults, or within a realm-specific subsection of [realms]. Also note that a realm-specific value over-rides, does not add to, a generic [kdcdefaults] specification. The search order is:
+
+ 1. realm-specific subsection of realms_
+
+ [realms]
+ EXAMPLE.COM = {
+ pkinit_anchors = FILE\:/usr/local/example.com.crt
+
+ }
+
+
+ 2. generic value in the kdcdefaults_ section.
+
+ [kdcdefaults]
+ pkinit_anchors = DIR\:/usr/local/generic_trusted_cas/
+
+
+
+For information about the syntax of some of these options, see See pkinit identity syntax.
+
+pkinit_identity
+ Specifies the location of the KDC's X.509 identity information. This option is required if pkinit is to be supported by the KDC.
+pkinit_anchors
+ Specifies the location of trusted anchor (root) certificates which the KDC trusts to sign client certificates. This option is required if pkinit is to be supported by the KDC. This option may be specified multiple times.
+pkinit_pool
+ Specifies the location of intermediate certificates which may be used by the KDC to complete the trust chain between a client's certificate and a trusted anchor. This option may be specified multiple times.
+pkinit_revoke
+ Specifies the location of Certificate Revocation List (CRL) information to be used by the KDC when verifying the validity of client certificates. This option may be specified multiple times.
+pkinit_require_crl_checking
+ The default certificate verification process will always check the available revocation information to see if a certificate has been revoked. If a match is found for the certificate in a CRL, verification fails. If the certificate being verified is not listed in a CRL, or there is no CRL present for its issuing CA, and pkinit_require_crl_checking is false, then verification succeeds.
+
+ However, if pkinit_require_crl_checking is true and there is no CRL information available for the issuing CA, then verification fails.
+
+ pkinit_require_crl_checking should be set to true if the policy is such that up-to-date CRLs must be present for every CA.
+pkinit_dh_min_bits
+ Specifies the minimum number of bits the KDC is willing to accept for a client's Diffie-Hellman key. The default is 2048.
+pkinit_allow_upn
+ Specifies that the KDC is willing to accept client certificates with the Microsoft UserPrincipalName (UPN) Subject Alternative Name (SAN). This means the KDC accepts the binding of the UPN in the certificate to the Kerberos principal name.
+
+ The default is *false*.
+
+ Without this option, the KDC will only accept certificates with the *id-pkinit-san* as defined in :rfc:`4556`. There is currently no option to disable SAN checking in the KDC.
+pkinit_eku_checking
+ This option specifies what Extended Key Usage (EKU) values the KDC is willing to accept in client certificates. The values recognized in the kdc.conf file are:
+
+ *kpClientAuth*
+ This is the default value and specifies that client certificates must have the id-pkinit-KPClientAuth EKU as defined in :rfc:`4556`.
+ *scLogin*
+ If scLogin is specified, client certificates with the Microsoft Smart Card Login EKU (id-ms-kp-sc-logon) will be accepted.
+ *none*
+ If none is specified, then client certificates will not be checked to verify they have an acceptable EKU. The use of this option is not recommended.
+
+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
+
+--------------
+
+Feedback:
+
+Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___conf_files
+
+
--- /dev/null
+.. _krb5_conf_label:
+
+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.
+
+Structure
+---------
+
+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
+ }
+
+
+Placing a '\*' at the end of a line indicates that this is the *final* value for the tag. This means that neither the remainder of this configuration file nor any other configuration file will be checked for any other values for this tag.
+
+For example, if you have the following lines::
+
+ foo = bar*
+ foo = baz
+
+
+then the second value of *foo* (baz) would never be read.
+
+The krb5.conf file can include other files using either of the following directives at the beginning of a line::
+
+ include FILENAME
+ includedir DIRNAME
+
+
+*FILENAME* or *DIRNAME* should be an absolute path. The named file or directory must exist and be readable. Including a directory includes all files within the directory whose names consist solely of alphanumeric characters, dashes, or underscores. Included profile files are syntactically independent of their parents, so each included file must begin with a section header.
+
+The krb5.conf file may contain any or all of the following sections:
+
+============== =======================================================
+libdefaults_ Contains default values used by the Kerberos V5 library.
+login_ Contains default values used by the Kerberos V5 login program.
+appdefaults_ Contains default values that can be 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.
+plugins_ Contains tags to register dynamic plugin modules and to turn modules on and off.
+============== =======================================================
+
+Sections
+----------
+
+
+.. _libdefaults:
+
+**[libdefaults]**
+
+The libdefaults section may contain any of the following relations:
+
+default_keytab_name
+ This relation specifies the default keytab name to be used by application servers such as telnetd and rlogind. The default is */etc/krb5.keytab*.
+default_realm
+ Identifies the default Kerberos realm for the client. Set its value to your Kerberos realm. If this is not specified and the TXT record lookup is enabled (see :ref:`udns_label`), then that information will be used to determine the default realm. If this tag is not set in this configuration file and there is no DNS information found, then an error will be returned.
+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. Kerberos supports many different encryption types, and support for more is planned in the future. (see :ref:`senct_label` for a list of the accepted values for this tag). The default value is aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 des3-cbc-sha1 arcfour-hmac-md5 des-cbc-crc des-cbc-md5 des-cbc-md4.
+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_tgs_enctypes. The default value for this tag is aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 des3-cbc-sha1 arcfour-hmac-md5 des-cbc-crc des-cbc-md5 des-cbc-md4.
+permitted_enctypes
+ Identifies all encryption types that are permitted for use in session key encryption. The default value for this tag is aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 des3-cbc-sha1 arcfour-hmac-md5 des-cbc-crc des-cbc-md5 des-cbc-md4.
+allow_weak_crypto
+ If this is set to 0 (for false), then weak encryption types will be filtered out of the previous three lists (as noted in :ref:`senct_label`). The default value for this tag is false, which may cause authentication failures in existing Kerberos infrastructures that do not support strong crypto. Users in affected environments should set this tag to true until their infrastructure adopts stronger ciphers.
+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.
+k5login_authoritative
+ If the value of this relation is true (the default), principals must be listed in a local user's k5login file to be granted login access, if a k5login file exists. If the value of this relation is false, a principal may still be granted login access through other mechanisms even if a k5login file exists but does not list the principal.
+k5login_directory
+ If set, the library will look for a local user's k5login file within the named directory, with a filename corresponding to the local username. If not set, the library will look for k5login files in the user's home directory, with the filename .k5login. For security reasons, k5login files must be owned by the local user or by root.
+kdc_timesync
+ If this is set to 1 (for true), then client machines will compute the difference between their time and the time returned by the KDC in the timestamps in the tickets and use this value to correct for an inaccurate system clock. This corrective factor is only used by the Kerberos library. The default is 1.
+
+| kdc_req_checksum_type
+| ap_req_checksum_type
+| safe_checksum_type
+
+ An integer which specifies the type of checksum to use. Used for compatability with DCE security servers which do not support the default RSA MD5 used by this version of Kerberos. The kdc_req_checksum_type is only used for DES keys. The ap_req_checksum_type defaults to the preferred checksum for the encryption type being used if unset. If set, then the selected checksum is used regardless of the type of key being used. The possible values and their meanings are as follows.
+
+ 1
+ CRC32
+ 2
+ RSA MD4
+ 3
+ RSA MD4 DES
+ 4
+ DES CBC
+ 7
+ RSA MD5
+ 8
+ RSA MD5 DES
+ 9
+ NIST SHA
+ 12
+ HMAC SHA1 DES3
+ -138
+ Microsoft MD5 HMAC checksum type
+
+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. The default value is 4.
+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.
+extra_addresses
+ This allows a computer to use multiple local addresses, in order to allow Kerberos to work in a network that uses NATs. The addresses should be in a comma-separated list.
+udp_preference_limit
+ When sending a message to the KDC, the library will try using TCP before UDP if the size of the message is above udp_preference_list. If the message is smaller than udp_preference_list, then UDP will be tried before TCP. Regardless of the size, both protocols will be tried if the first attempt fails.
+verify_ap_req_nofail
+ If this flag is set, then an attempt to get initial credentials will fail if the client machine does not have a keytab. The default for the flag is not set.
+ticket_lifetime
+ The value of this tag is the default lifetime for initial tickets. The default value for the tag is 1 day.
+renew_lifetime
+ The value of this tag is the default renewable lifetime for initial tickets. The default value for the tag is 0.
+noaddresses
+ Setting this flag causes the initial Kerberos ticket to be addressless. The default for the flag is set.
+forwardable
+ If this flag is set, initial tickets by default will be forwardable. The default value for this flag is not set.
+proxiable
+ If this flag is set, initial tickets by default will be proxiable. The default value for this flag is not set.
+rdns
+ If set to false, prevent the use of reverse DNS resolution when translating hostnames into service principal names. Defaults to true. Setting this flag to false is more secure, but may force users to exclusively use fully qualified domain names when authenticating to services.
+
+
+.. _appdefaults:
+
+**[appdefaults]**
+
+Each tag in the [appdefaults] section names a Kerberos V5 application or an option that is used by some Kerberos V5 application[s]. The value of the tag defines the default behaviors for that application.
+
+For example::
+
+ [appdefaults]
+ telnet = {
+ ATHENA.MIT.EDU = {
+ option1 = false
+ }
+ }
+ telnet = {
+ option1 = true
+ option2 = true
+ }
+ ATHENA.MIT.EDU = {
+ option2 = false
+ }
+ option2 = true
+
+
+The above four ways of specifying the value of an option are shown in order of decreasing precedence. In this example, if telnet is running in the realm EXAMPLE.COM, it should, by default, have option1 and option2 set to true. However, a telnet program in the realm ATHENA.MIT.EDU should have option1 set to false and option2 set to true. Any other programs in ATHENA.MIT.EDU should have option2 set to false by default. Any programs running in other realms should have option2 set to 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.
+
+.. _login:
+
+**[login]**
+
+Each tag in the [login] section of the file is an option for *login.krb5*. This section may contain any of the following relations:
+
+krb5_get_tickets
+ Indicate whether or not to use a user's password to get V5 tickets. The default value is *true*.
+krb_run_aklog
+ Indicate whether or not to run aklog. The default value is *false*.
+aklog_path
+ Indicate where to find aklog. The default value is *$(prefix)/bin/aklog*.
+accept_passwd
+ A true value will cause login not to accept plaintext passwords. The default value is false. This is not yet implemented.
+
+.. _realms:
+
+**[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 or address of a host running a KDC for that realm. An optional port number, separated from the hostname by a colon, may be included. If the name or address contains colons (for example, if it is an IPv6 address), enclose it in square brackets to distinguish the colon from a port separator. For your computer to be able to communicate with the KDC for each realm, this tag must be given a value in each realm subsection in the configuration file, or there must be DNS SRV records specifying the KDCs (see :ref:`udns_label`).
+master_kdc
+ Identifies the master KDC(s). Currently, this tag is used in only one case: If an attempt to get credentials fails because of an invalid password, the client software will attempt to contact the master KDC, in case the user's password has just been changed, and the updated database has not been propagated to the slave servers yet.
+database_module
+ This relation indicates the name of the configuration section under [dbmodules] for database specific parameters used by the loadable database library.
+admin_server
+ Identifies the host where the administration server is running. Typically, this is the master Kerberos server. This tag must be given a value in order to communicate with the kadmin server for the realm.
+default_domain
+ This tag is used for Kerberos 4 compatibility. Kerberos 4 does not require the entire hostname of a server to be in its principal like Kerberos 5 does. This tag provides the domain name needed to produce a full hostname when translating V4 principal names into V5 principal names. All servers in this realm are assumed to be in the domain given as the value of this tag
+v4_instance_convert
+ This subsection allows the administrator to configure exceptions to the default_domain mapping rule. It contains V4 instances (the tag name) which should be translated to some specific hostname (the tag value) as the second component in a Kerberos V5 principal name.
+v4_realm
+ This relation is used by the krb524 library routines when converting a V5 principal name to a V4 principal name. It is used when the V4 realm name and the V5 realm name are not the same, but still share the same principal names and passwords. The tag value is the Kerberos V4 realm name.
+auth_to_local_names
+ This subsection allows you to set explicit mappings from principal names to local user names. The tag is the mapping name, and the value is the corresponding local user name.
+auth_to_local
+ This tag allows you to set a general rule for mapping principal names to local user names. It will be used if there is not an explicit mapping for the principal name that is being translated. The possible values are:
+
+
+ DB:filename
+ The principal will be looked up in the database filename. Support for this is not currently compiled in by default.
+ RULE:exp
+ The local name will be formulated from exp.
+
+ The format for exp is [n:string](regexp)s/pattern/replacement/g. The integer n indicates how many components the target principal should have. If this matches, then a string will be formed from string, substituting the realm of the principal for $0 and the n'th component of the principal for $n (e.g. if the principal was johndoe/admin then [2:$2$1foo] would result in the string "adminjohndoefoo"). If this string matches regexp, then the s//[g] substitution command will be run over the string. The optional g will cause the substitution to be global over the string, instead of replacing only the first match in the string.
+
+ DEFAULT
+ The principal name will be used as the local user name. If the principal has more than one component or is not in the default realm, this rule is not applicable and the conversion will fail.
+
+ For example::
+
+ [realms]
+ ATHENA.MIT.EDU = {
+ auth_to_local = RULE:[2:$1](johndoe)s/^.*$/guest/
+ auth_to_local = RULE:[2:$1;$2](^.*;admin$)s/;admin$//
+ auth_to_local = RULE:[2:$2](^.*;root)s/^.*$/root/
+ auto_to_local = DEFAULT
+ }
+
+
+ would result in any principal without *root* or *admin* as the second component to be translated with the default rule. A principal with a second component of *admin* will become its first component. *root* will be used as the local name for any principal with a second component of *root*. The exception to these two rules are any principals johndoe/\*, which will always get the local name *guest*.
+
+.. _domain_realm:
+
+**[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
+ example.com = EXAMPLE.COM
+
+
+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 example.com domain will map by default into the EXAMPLE.COM realm. Note the entries for the hosts *mit.edu* and *example.com*. Without these entries, these hosts would be mapped into the Kerberos realms EDU and ORG, respectively.
+
+.. _logging:
+
+**[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:
+
+kdc
+ These entries specify how the KDC is to perform its logging.
+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
+
+
+.. _capaths:
+
+**[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 allowed 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.
+
+.. _dbdefaults:
+
+**[dbdefaults]**
+
+The [dbdefaults] section provides default values for the database specific parameters. It can also specify the configuration section under dbmodules_ section for database specific parameters used by the database library.
+
+The following tags are used in this section:
+
+database_module
+ This relation indicates the name of the configuration section under the dbmodules_ for database specific parameters used by the loadable database library.
+ldap_kerberos_container_dn
+ This LDAP specific tag indicates the DN of the container object where the realm objects will be located. This value is used if the container object is not mentioned in the configuration section under dbmodules_.
+ldap_kdc_dn
+ This LDAP specific tag indicates the default bind DN for the KDC server. The KDC server does a login to the directory as this object. This object should have the rights to read the Kerberos data in the LDAP database. This value is used if the bind DN for the KDC is not mentioned in the configuration section under dbmodules_.
+ldap_kadmind_dn
+ This LDAP specific tag indicates the default bind DN for the Administration server. The administration server does a login to the directory as this object. This object should have the rights to read and write the Kerberos data in the LDAP database. This value is used if the bind DN for the Administration server is not mentioned in the configuration section under dbmodules_.
+ldap_service_password_file
+ This LDAP specific tag indicates the file containing the stashed passwords (created by kdb5_ldap_util stashsrvpw) for the objects used by the Kerberos servers to bind to the LDAP server. This file must be kept secure. This value is used if no service password file is mentioned in the configuration section under dbmodules_.
+ldap_server
+ This LDAP specific tag indicates the list of LDAP servers that the Kerberos servers can connect to. The list of LDAP servers is whitespace-separated. The LDAP server is specified by a LDAP URI. This value is used if no LDAP servers are mentioned in the configuration section under dbmodules_. It is recommended to use the *ldapi://* or *ldaps://* interface and not to use *ldap://* interface.
+ldap_conns_per_server
+ This LDAP specific tag indicates the number of connections to be maintained per LDAP server. This value is used if the number of connections per LDAP server are not mentioned in the configuration section under dbmodules_. The default value is 5.
+
+.. _dbmodules:
+
+**[dbmodules]**
+
+Contains database specific parameters used by the database library. Each tag in the [dbmodules] section of the file names a configuration section for database specific parameters that can be referred to by a realm. The value of the tag is a subsection where the relations in that subsection define the database specific parameters.
+
+For each section, the following tags may be specified in the subsection:
+
+db_library
+ This tag indicates the name of the loadable database library. The value should be db2 for DB2 database and kldap for LDAP database.
+database_name
+ This DB2-specific tag indicates the location of the database in the filesystem. The default is */usr/local/var/krb5kdc/principal*.
+disable_last_success
+ If set to *true*, suppresses KDC updates to the *"Last successful authentication"* field of principal entries requiring preauthentication. Setting this flag may improve performance. (Principal entries which do not require preauthentication never update the "Last successful authentication" field.)
+disable_lockout
+ If set to *true*, suppresses KDC updates to the *"Last failed authentication"* and *"Failed password attempts"* fields of principal entries requiring preauthentication. Setting this flag may improve performance, but also disables account lockout.
+ldap_kerberos_container_dn
+ This LDAP specific tag indicates the DN of the container object where the realm objects will be located.
+ldap_kdc_dn
+ This LDAP specific tag indicates the default bind DN for the KDC server. The KDC server does a login to the directory as this object. This object should have the rights to read the Kerberos data in the LDAP database.
+ldap_kadmind_dn
+ This LDAP specific tag indicates the default bind DN for the Administration server. The administration server does a login to the directory as this object. This object should have the rights to read and write the Kerberos data in the LDAP database.
+ldap_service_password_file
+ This LDAP specific tag indicates the file containing the stashed passwords (created by *kdb5_ldap_util stashsrvpw*) for the objects used by the Kerberos servers to bind to the LDAP server. This file must be kept secure.
+ldap_server
+ This LDAP specific tag indicates the list of LDAP servers that the Kerberos servers can connect to. The list of LDAP servers is whitespace-separated. The LDAP server is specified by a LDAP URI. It is recommended to use *ldapi://* or *ldaps://* interface to connect to the LDAP server.
+ldap_conns_per_server
+ This LDAP specific tags indicates the number of connections to be maintained per LDAP server.
+
+.. _plugins:
+
+Plugins
+--------
+
+ * pwqual interface
+ * kadm5_hook interface
+
+Tags in the **[plugins]** section can be used to register dynamic plugin modules and to turn modules on and off. Not every krb5 pluggable interface uses the [plugins] section; the ones that do are documented here.
+
+Each pluggable interface corresponds to a subsection of [plugins]. All subsections support the same tags:
+
+module
+ This tag may have multiple values. Each value is a string of the form "modulename:pathname", which causes the shared object located at pathname to be registered as a dynamic module named modulename for the pluggable interface. If pathname is not an absolute path, it will be treated as relative to the "krb5/plugins" subdirectory of the krb5 library directory.
+enable_only
+ This tag may have multiple values. If there are values for this tag, then only the named modules will be enabled for the pluggable interface.
+disable
+ This tag may have multiple values. If there are values for this tag, then the named modules will be disabled for the pluggable interface.
+
+The following subsections are currently supported within the [plugins] section:
+
+..
+
+pwqual interface
+~~~~~~~~~~~~~~~~~~~~~~~
+
+The **pwqual** subsection controls modules for the password quality interface, which is used to reject weak passwords when passwords are changed. In addition to any registered dynamic modules, the following built-in modules exist (and may be disabled with the disable tag):
+
+dict
+ Checks against the realm dictionary file
+empty
+ Rejects empty passwords
+hesiod
+ Checks against user information stored in Hesiod (only if Kerberos was built with Hesiod support)
+princ
+ Checks against components of the principal name
+
+kadm5_hook interface
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+The kadm5_hook interface provides plugins with information on principal creation, modification, password changes and deletion. This interface can be used to write a plugin to synchronize MIT Kerberos with another database such as Active Directory. No plugins are built in for this interface.
+
+PKINIT options
+-----------------
+
+ * pkinit identity syntax
+ * pkinit krb5.conf options
+
+.. note:: The following are pkinit-specific options. Note that these values may be specified in *[libdefaults]* as global defaults, or within a realm-specific subsection of *[libdefaults]*, or may be specified as realm-specific values in the *[realms]* section. Also note that a realm-specific value over-rides, does not add to, a generic *[libdefaults]* specification. The search order is:
+
+ 1. realm-specific subsection of [libdefaults]
+
+ [libdefaults]
+ EXAMPLE.COM = {
+ pkinit_anchors = FILE\:/usr/local/example.com.crt
+
+ }
+
+
+ 2. realm-specific value in the [realms] section,
+
+ [realms]
+ OTHERREALM.ORG = {
+ pkinit_anchors = FILE\:/usr/local/otherrealm.org.crt
+
+ }
+
+
+ 3. generic value in the [libdefaults] section.
+
+ [libdefaults]
+ pkinit_anchors = DIR\:/usr/local/generic_trusted_cas/
+
+
+
+Specifying pkinit identity information
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The syntax for specifying Public Key identity, trust, and revocation information for pkinit is as follows:
+
+
+FILE\:file-name\[,key-file-name]
+ This option has context-specific behavior.
+
+ | pkinit_identity
+ | pkinit_identities
+
+ *file-name* specifies the name of a PEM-format file containing the user's certificate. If *key-file-name* is not specified, the user's private key is expected to be in file-name as well. Otherwise, *key-file-name* is the name of the file containing the private key.
+
+ | pkinit_anchors
+ | pkinit_pool
+
+ *file-name* is assumed to be the name of an OpenSSL-style ca-bundle file.
+
+
+DIR:directory-name
+ This option has context-specific behavior.
+
+ | pkinit_identity
+ | pkinit_identities
+
+ *directory-name* specifies a directory with files named \*.crt and \*.key, where the first part of the file name is the same for matching pairs of certificate and private key files. When a file with a name ending with .crt is found, a matching file ending with .key is assumed to contain the private key. If no such file is found, then the certificate in the .crt is not used.
+
+ | pkinit_anchors
+ | pkinit_pool
+
+ *directory-name* is assumed to be an OpenSSL-style hashed CA directory where each CA cert is stored in a file named *hash-of-ca-cert.#*. This infrastructure is encouraged, but all files in the directory will be examined and if they contain certificates (in PEM format), they will be used.
+
+ pkinit_revoke
+ *directory-name* is assumed to be an OpenSSL-style hashed CA directory where each revocation list is stored in a file named *hash-of-ca-cert.r#*. This infrastructure is encouraged, but all files in the directory will be examined and if they contain a revocation list (in PEM format), they will be used.
+
+
+PKCS12:pkcs12-file-name
+ *pkcs12-file-name* is the name of a PKCS #12 format file, containing the user's certificate and private key.
+PKCS11:[module_name=]module-name[:slotid=slot-id][:token=token-label][:certid=cert-id][:certlabel=cert-label]
+ All keyword/values are optional. module-name specifies the location of a library implementing PKCS #11. If a value is encountered with no keyword, it is assumed to be the *module-name*. If no module-name is specified, the default is *opensc-pkcs11.so*. *slotid=* and/or *token=* may be specified to force the use of a particular smard card reader or token if there is more than one available. *certid=* and/or *certlabel=* may be specified to force the selection of a particular certificate on the device. See the *pkinit_cert_match* configuration option for more ways to select a particular certificate to use for pkinit.
+ENV:environment-variable-name
+ environment-variable-name specifies the name of an environment variable which has been set to a value conforming to one of the previous values. For example, *ENV:X509_PROXY*, where environment variable *X509_PROXY* has been set to *FILE:/tmp/my_proxy.pem*.
+
+
+
+PKINIT krb5.conf options
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+
+pkinit_identities
+ Specifies the location(s) to be used to find the user's X.509 identity information. This option may be specified multiple times. Each value is attempted in order until identity information is found and authentication is attempted. Note that these values are not used if the user specifies X509_user_identity on the command line.
+pkinit_anchors
+ Specifies the location of trusted anchor (root) certificates which the client trusts to sign KDC certificates. This option may be specified multiple times. These values from the config file are not used if the user specifies X509_anchors on the command line.
+pkinit_pool
+ Specifies the location of intermediate certificates which may be used by the client to complete the trust chain between a KDC certificate and a trusted anchor. This option may be specified multiple times.
+pkinit_revoke
+ Specifies the location of Certificate Revocation List (CRL) information to be used by the client when verifying the validity of the KDC certificate presented. This option may be specified multiple times.
+pkinit_require_crl_checking
+ The default certificate verification process will always check the available revocation information to see if a certificate has been revoked. If a match is found for the certificate in a CRL, verification fails. If the certificate being verified is not listed in a CRL, or there is no CRL present for its issuing CA, and pkinit_require_crl_checking is false, then verification succeeds.
+
+ However, if pkinit_require_crl_checking is true and there is no CRL information available for the issuing CA, then verification fails.
+
+ pkinit_require_crl_checking should be set to true if the policy is such that up-to-date CRLs must be present for every CA.
+pkinit_dh_min_bits
+ Specifies the size of the Diffie-Hellman key the client will attempt to use. The acceptable values are currently 1024, 2048, and 4096. The default is 2048.
+pkinit_win2k
+ This flag specifies whether the target realm is assumed to support only the old, pre-RFC version of the protocol. The default is false.
+pkinit_win2k_require_binding
+ If this flag is set to true, it expects that the target KDC is patched to return a reply with a checksum rather than a nonce. The default is false.
+pkinit_eku_checking
+ This option specifies what Extended Key Usage value the KDC certificate presented to the client must contain. (Note that if the KDC certificate has the pkinit SubjectAlternativeName encoded as the Kerberos TGS name, EKU checking is not necessary since the issuing CA has certified this as a KDC certificate.) The values recognized in the krb5.conf file are:
+
+ kpKDC
+ This is the default value and specifies that the KDC must have the id-pkinit-KPKdc EKU as defined in :rfc:`4556`.
+ kpServerAuth
+ If kpServerAuth is specified, a KDC certificate with the id-kp-serverAuth EKU as used by Microsoft will be accepted.
+ none
+ If none is specified, then the KDC certificate will not be checked to verify it has an acceptable EKU. The use of this option is not recommended.
+
+
+pkinit_kdc_hostname
+ The presense of this option indicates that the client is willing to accept a KDC certificate with a dNSName SAN (Subject Alternative Name) rather than requiring the id-pkinit-san as defined in :rfc:`4556`. This option may be specified multiple times. Its value should contain the acceptable hostname for the KDC (as contained in its certificate).
+pkinit_cert_match
+ Specifies matching rules that the client certificate must match before it is used to attempt pkinit authentication. If a user has multiple certificates available (on a smart card, or via other media), there must be exactly one certificate chosen before attempting pkinit authentication. This option may be specified multiple times. All the available certificates are checked against each rule in order until there is a match of exactly one certificate.
+
+ The Subject and Issuer comparison strings are the :rfc:`2253` string representations from the certificate Subject DN and Issuer DN values.
+
+ The syntax of the matching rules is::
+
+ [relation-operator]component-rule ...
+
+
+ where
+
+ *relation-operator*
+ can be either **&&**, meaning all component rules must match, or **||**, meaning only one component rule must match. The default is &&.
+ *component-rule*
+ can be one of the following. Note that there is no punctuation or whitespace between component rules.
+
+ *<SUBJECT>regular-expression*
+
+ *<ISSUER>regular-expression*
+
+ *<SAN>regular-expression*
+
+ *<EKU>extended-key-usage-list*
+ where *extended-key-usage-list* is a comma-separated list of required Extended Key Usage values. All values in the list must be present in the certificate.
+
+ - pkinit
+ - msScLogin
+ - clientAuth
+ - emailProtection
+
+
+
+ *<KU>key-usage-list*
+ where *key-usage-list* is a comma-separated list of required Key Usage values. All values in the list must be present in the certificate.
+
+ - digitalSignature
+ - keyEncipherment
+
+
+ Examples::
+
+ pkinit_cert_match = ||<SUBJECT>.*DoE.*<SAN>.*@EXAMPLE.COM
+ pkinit_cert_match = &&<EKU>msScLogin,clientAuth<ISSUER>.*DoE.*
+ pkinit_cert_match = <EKU>msScLogin,clientAuth<KU>digitalSignature
+
+
+
+
+.. _krb5_conf_sample_label:
+
+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
+ }
+ OPENLDAP.MIT.EDU = {
+ kdc = kerberos.mit.edu
+ admin_server = kerberos.mit.edu
+ database_module = openldap_ldapconf
+ }
+
+ [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
+ [dbdefaults]
+ ldap_kerberos_container_dn = cn=krbcontainer,dc=example,dc=com
+ [dbmodules]
+ openldap_ldapconf = {
+ db_library = kldap
+ ldap_kerberos_container_dn = cn=krbcontainer,dc=example,dc=com
+ ldap_kdc_dn = "cn=krbadmin,dc=example,dc=com"
+ # this object needs to have read rights on
+ # the realm container and principal subtrees
+ ldap_kadmind_dn = "cn=krbadmin,dc=example,dc=com"
+ # this object needs to have read and write rights on
+ # the realm container and principal subtrees
+ ldap_service_password_file = /etc/kerberos/service.keyfile
+ ldap_servers = ldaps://kerberos.mit.edu
+ ldap_conns_per_server = 5
+ }
+
+
+--------------
+
+Feedback:
+
+Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___conf_files
+
+
--- /dev/null
+.. _salts_label:
+
+Salts
+=========
+
+Your Kerberos key is derived from your password. To ensure that people who happen to pick the same password do not have the same key, Kerberos 5 incorporates more information into the key using something called a salt. The supported values for salts are as follows.
+
+================= ============================================
+normal default for Kerberos Version 5
+v4 the only type used by Kerberos Version 4, no salt
+norealm same as the default, without using realm information
+onlyrealm uses only realm information as the salt
+afs3 AFS version 3, only used for compatibility with Kerberos 4 in AFS
+special only used in very special cases; not fully supported
+================= ============================================
+
+--------------
+
+Feedback:
+
+Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___conf_files
+
+
--- /dev/null
+Configuring Kerberos with OpenLDAP back-end
+=================================================
+
+.. note:: This document was copied from **Kerberos V5 System Administrator's Guide** with minor changes. Currently it is under review. Please, send your feedback, corrections and additions to krb5-bugs@mit.edu. Your contribution is greatly appreciated.
+
+.. seealso:: :ref:`ldap_be_ubuntu`
+
+1. Set up SSL on the OpenLDAP server and client to ensure secure communication when the KDC service and LDAP server are on different machines. *ldapi\://* can be used if the LDAP server and KDC service are running on the same machine.
+ \A. Setting up SSL on the OpenLDAP server:
+ a) Get a CA certificate using OpenSSL tools
+ b) Configure OpenLDAP server for using SSL/TLS
+
+ For the latter, you need to specify the location of CA certificate location in *slapd.conf* file.
+
+ Refer to the following link for more information: http://www.openldap.org/doc/admin23/tls.html
+
+ \B. Setting up SSL on OpenLDAP Client:
+ a) For the KDC and Admin Server, you need to do the client-side configuration in *ldap.conf*.
+
+ For example::
+
+ TLS_CACERT /etc/openldap/certs/cacert.pem
+
+
+2. Include the Kerberos schema file (*kerberos.schema*) in the configuration file (*slapd.conf*) on the LDAP Server, by providing the location where it is stored.
+
+ include /etc/openldap/schema/kerberos.schema
+
+
+3. Choose DNs for the KDC and kadmin servers to bind to the LDAP server, and create them if necessary. These DNs will be specified with the *ldap_kdc_dn* and *ldap_kadmind_dn* directives in *krb5.conf*; their passwords can be stashed with *kdb5_ldap_util stashsrvpw* and the resulting file specified with the *ldap_service_password_file* directive.
+
+4. Choose a DN for the global Kerberos container entry (but do not create the entry at this time). This DN will be specified with the *ldap_kerberos_container_dn* directive in *krb5.conf*. Realm container entries will be created underneath this DN. Principal entries may exist either underneath the realm container (the default) or in separate trees referenced from the realm container.
+
+5. Configure the LDAP server ACLs to enable the KDC and kadmin server DNs to read and write the Kerberos data.
+
+ Sample access control information::
+
+ access to dn.base=""
+ by * read
+
+ access to dn.base="cn=Subschema"
+ by * read
+
+ access to attrs=userPassword,userPKCS12
+ by self write
+ by * auth
+
+ access to attrs=shadowLastChange
+ by self write
+ by * read
+
+ # Providing access to realm container
+ access to dn.subtree= "cn=EXAMPLE.COM,cn=krbcontainer,dc=example,dc=com"
+ by dn.exact="cn=kdc-service,dc=example,dc=com" read
+ by dn.exact="cn=adm-service,dc=example,dc=com" write
+ by * none
+
+ # Providing access to principals, if not underneath realm container
+ access to dn.subtree= "ou=users,dc=example,dc=com"
+ by dn.exact="cn=kdc-service,dc=example,dc=com" read
+ by dn.exact="cn=adm-service,dc=example,dc=com" write
+ by * none
+
+ access to *
+ by * read
+
+
+ If the locations of the container and principals or the DNs of the service objects for a realm are changed then this information should be updated.
+
+6. Start the LDAP server as follows::
+
+ slapd -h "ldapi:/// ldaps:///"
+
+
+7. Modify the *krb5.conf* file to include LDAP specific items listed below::
+
+ realms
+ database_module
+
+ dbmodules
+ db_library
+ db_module_dir
+ ldap_kdc_dn
+ ldap_kadmind_dn
+ ldap_service_password_file
+ ldap_servers
+ ldap_conns_per_server
+
+
+
+ For the sample krb5.conf file, refer to :ref:`krb5_conf_sample_label`. For more details, refer to :ref:`krb5_conf_label`
+
+8. Create the realm using *kdb5_ldap_util* (see :ref:`ldap_create_realm_label`)::
+
+ kdb5_ldap_util -D cn=admin,dc=example,dc=com create -subtrees ou=users,dc=example,dc=com -r EXAMPLE.COM -s
+
+
+
+ Use the *-subtrees* option if the principals are to exist in a separate subtree from the realm container. Before executing the command, make sure that the subtree mentioned above *(ou=users,dc=example,dc=com)* exists. If the principals will exist underneath the realm container, omit the *-subtrees* option and do not worry about creating the principal subtree.
+
+ For more information, refer to the section :ref:`ops_on_ldap_label`
+
+ The realm object is created under the *ldap_kerberos_container_dn* specified in the configuration file. This operation will also create the Kerberos container, if not present already. This will be used to store information related to all realms.
+
+9. Stash the password of the service object used by the KDC and Administration service to bind to the LDAP server using the *stashsrvpw* command of *kdb5_ldap_util* (see :ref:`stash_ldap_label`). The object DN should be the same as *ldap_kdc_dn* and *ldap_kadmind_dn* values specified in the *krb5.conf* file::
+
+ kdb5_ldap_util -D cn=admin,dc=example,dc=com stashsrvpw -f /etc/kerberos/service.keyfile cn=krbadmin,dc=example,dc=com
+
+
+10. Add *krb5principalname* to the indexes in *slapd.conf* to speed up the access.
+
+With the LDAP back end it is possible to provide aliases for principal entries. Currently we provide no mechanism provided for creating aliases, so it must be done by direct manipulation of the LDAP entries.
+
+An entry with aliases contains multiple values of the *krbPrincipalName* attribute. Since LDAP attribute values are not ordered, it is necessary to specify which principal name is canonical, by using the *krbCanonicalName* attribute. Therefore, to create aliases for an entry, first set the *krbCanonicalName* attribute of the entry to the canonical principal name (which should be identical to the pre-existing *krbPrincipalName* value), and then add additional *krbPrincipalName* attributes for the aliases.
+
+Principal aliases are only returned by the KDC when the client requests canonicalization. Canonicalization is normally requested for service principals; for client principals, an explicit flag is often required (e.g. *kinit -C*) and canonicalization is only performed for initial ticket requests.
+
+----------------------------------
+
+Feedback:
+
+Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___conf_ldap
--- /dev/null
+Changing the *krbtgt* key
+=============================
+
+A Kerberos Ticket Granting Ticket (TGT) is a service ticket for the principal *krbtgt\/REALM*. The key for this principal is created when the Kerberos database is initialized and need not be changed. However, it will only have the encryption types supported by the KDC at the time of the initial database creation. To allow use of newer encryption types for the TGT, this key has to be changed.
+
+
+Changing this key using the normal kadmin *change_password* command would invalidate any previously issued TGTs. Therefore, when changing this key, normally one should use the *-keepold* flag to change_password to retain the previous key in the database as well as the new key. For example::
+
+ kadmin: change_password -randkey -keepold krbtgt/ATHENA.MIT.EDU@ATHENA.MIT.EDU
+
+
+.. warning:: After issuing this command, the old key is still valid and is still vulnerable to (for instance) brute force attacks. To completely retire an old key or encryption type, run the *purgekeys* command to delete keys with older kvnos, ideally first making sure that all tickets issued with the old keys have expired.
+
+
+------------
+
+Feedback:
+
+Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___db
+
--- /dev/null
+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"
+
+
+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
+========================== ============================================
+
+
+.. note:: 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.
+
+
+------------
+
+Feedback:
+
+Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___db
+
--- /dev/null
+Creating and destroying a Kerberos database
+===================================================
+
+If you need to create a new Kerberos database, use the *kdb5_util create* command. The syntax is::
+
+ kdb5_util create [-s]
+
+
+If you specify the -s option, kdb5_util will stash a copy of the master key in a stash file. (See :ref:`create_stash`) For example::
+
+ shell% /usr/local/sbin/kdb5_util -r ATHENA.MIT.EDU create -s
+ kdb5_util: No such file or directory while setting active database to
+ => '/usr/local/var/krb5kdc/principal'
+ Initializing database '/usr/local/var/krb5kdc/principal' for
+ => realm 'ATHENA.MIT.EDU',
+ master key name 'K/M@ATHENA.MIT.EDU'
+ You will be prompted for the database Master Password.
+ It is important that you NOT FORGET this password.
+ Enter KDC database master key: <= Type the master password.
+ Re-enter KDC database master key to verify: <= Type it again.
+ shell%
+
+
+If you need to destroy the current Kerberos database, use the *kdb5_util destroy* command. The syntax is::
+
+ kdb5_util destroy [-f]
+
+
+The *destroy* command destroys the database, first overwriting the disk sectors and then unlinking the files. If you specify the *-f* option, *kdb5_util* will not prompt you for a confirmation before destroying the database.
+
+::
+
+ shell% /usr/local/sbin/kdb5_util -r ATHENA.MIT.EDU destroy
+ kdb5_util: Deleting KDC database stored in /usr/local/var/krb5kdc/principal, are you sure
+ (type yes to confirm)? <== yes
+ OK, deleting database '/usr/local/var/krb5kdc/principal'...
+
+ shell%
+
+------------
+
+Feedback:
+
+Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___db_operations
+
--- /dev/null
+.. _create_stash:
+
+Creating a Stash File
+============================
+
+A stash file allows a KDC to authenticate itself to the database utilities, such as *kadmin, kadmind, krb5kdc*, and *kdb5_util*.
+
+To create a stash file, use the *kdb5_util stash* command. The syntax is::
+
+ kdb5_util stash [-f keyfile]
+
+
+For example::
+
+ shell% kdb5_util stash
+ kdb5_util: Cannot find/read stored master key while reading master key
+ kdb5_util: Warning: proceeding without master key
+ Enter KDC database master key: <= Type the KDC database master password.
+ shell%
+
+
+If you do not specify a stash file, *kdb5_util* will stash the key in the file specified in your *kdc.conf* file.
+
+
+
+------------
+
+Feedback:
+
+Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___db_operations
+
--- /dev/null
+Dumping a Kerberos database to a file
+=============================================
+
+To dump a Kerberos database into a file, use the *kdb5_util dump* command on one of the KDCs. The syntax is:
+
+ kdb5_util dump [-old] [-b6] [-b7] [-ov]
+ [-verbose] [-mkey_convert] [-new_mkey_file] [filename
+ [principals...]]
+
+
+The kdb5_util dump command takes the following options
+
+================= ============================================================
+-old Causes the dump to be in the Kerberos 5 Beta 5 and earlier dump format ("kdb5_edit load_dump version 2.0").
+-b6 Causes the dump to be in the Kerberos 5 Beta 6 format ("kdb5_edit load_dump version 3.0").
+-b7 Causes the dump to be in the Kerberos 5 Beta 7 format ("kdbt_edit load_dump version 4").
+-ov Causes the dump to be in ovsec_adm_export format. Currently, the only way to preserve per-principal policy information is to use this in conjunction with a normal dump.
+-verbose Causes the name of each principal and policy to be printed as it is dumped.
+-mkey_convert Prompts for a new master password, and then dumps the database with all keys reencrypted in this new master key
+-new_mkey_file Reads a new key from the default keytab and then dumps the database with all keys reencrypted in this new master key
+================= ============================================================
+
+For example::
+
+ shell% kdb5_util dump dumpfile
+ shell%
+
+
+ shell% kbd5_util dump -verbose dumpfile
+ kadmin/admin@ATHENA.MIT.EDU
+ krbtgt/ATHENA.MIT.EDU@ATHENA.MIT.EDU
+ kadmin/history@ATHENA.MIT.EDU
+ K/M@ATHENA.MIT.EDU
+ kadmin/changepw@ATHENA.MIT.EDU
+ shell%
+
+
+If you specify which principals to dump, you must use the full principal, as in the following example. (The line beginning with => is a continuation of the previous line.)::
+
+ shell% kdb5_util dump -verbose dumpfile K/M@ATHENA.MIT.EDU
+ => kadmin/admin@ATHENA.MIT.EDU
+ kadmin/admin@ATHENA.MIT.EDU
+ K/M@ATHENA.MIT.EDU
+ shell%
+
+
+Otherwise, the principals will not match those in the database and will not be dumped::
+
+ shell% kdb5_util dump -verbose dumpfile K/M kadmin/admin
+ shell%
+
+
+If you do not specify a dump file, *kdb5_util* will dump the database to the standard output.
+
+There is currently a bug where the default dump format omits the per-principal policy information. In order to dump all the data contained in the Kerberos database, you must perform a normal dump (with no option flags) and an additional dump using the "-ov" flag to a different file.
+
+
+
+------------
+
+Feedback:
+
+Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___db_operations
+
--- /dev/null
+.. _restore_from_dump:
+
+
+Restoring a Kerberos database from a dump file
+================================================
+
+To restore a Kerberos database dump from a file, use the *kdb5_util load* command on one of the KDCs. The syntax is::
+
+ kdb5_util load [-old] [-b6] [-b7] [-ov] [-verbose]
+ [-update] [-hash] dumpfilename dbname [admin_dbname]
+
+
+The kdb5_util load command takes the following options
+
+==================== ===========================================================
+-old Requires the dump to be in the Kerberos 5 Beta 5 and earlier dump format ("kdb5_edit load_dump version 2.0").
+-b6 Requires the dump to be in the Kerberos 5 Beta 6 format ("kdb5_edit load_dump version 3.0").
+-b7 Requires the dump to be in the Kerberos 5 Beta 7 format ("kdb5_edit load_dump version 4").
+-ov Requires the dump to be in ovsec_adm_export format.
+-verbose Causes the name of each principal and policy to be printed as it is loaded.
+-update Causes records from the dump file to be updated in or added to the existing database. This is useful in conjunction with an ovsec_adm_export format dump if you want to preserve per-principal policy information, since the current default format does not contain this data.
+-hash Causes the database to be stored as a hash rather than a binary tree.
+==================== ===========================================================
+
+For example::
+
+ shell% kdb5_util load dumpfile principal
+ shell%
+
+
+ shell% kdb5_util load -update dumpfile principal
+ shell%
+
+
+If the database file exists, and the *-update* flag was not given, kdb5_util will overwrite the existing database.
+
+
+------------
+
+Feedback:
+
+Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___db_operations
+
--- /dev/null
+Operations on the Kerberos database
+=============================================
+
+The *kdb5_util command* is the primary tool for administrating the Kerberos database. The syntax is::
+
+ kdb5_util command [kdb5_util_options] [command_options]
+
+
+The *kdb5_util command* takes the following options, which **override the defaults** specified in the configuration files:
+
+========================== =============================================================
+-r *realm* Specifies the the Kerberos realm of the database.
+-d *database_name* Specifies the name under which the principal database is stored.
+-k *master_key_type* Specifies the key type of the master key in the database.
+-M *master_key_name* Specifies the principal name of the master key in the database.
+-m Indicates that the master database password should be read from the TTY rather than fetched from a file on disk.
+-sf *stash_file* Specifies the stash file of the master database password
+-P *password* Specifies the master database password. MIT does not recommend using this option.
+========================== =============================================================
+
+|
+
+.. toctree::
+ :maxdepth: 1
+
+
+ db2file.rst
+ file2db.rst
+ create_stash.rst
+ create_destroy_db.rst
+
+
+
+------------
+
+Feedback:
+
+Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___db_operations
+
--- /dev/null
+*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* 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.
+-x *db_args* Specifies the database specific arguments.
+-x host=*<hostname>* Specifies the LDAP server to connect to by a LDAP URI. It is recommend to use ldapi:// or ldaps:// interface to connect to the LDAP server.
+-x binddn=*<bind_dn>* Specifies the Distinguished Name (DN) of the object used by the administration server to bind to the LDAP server. This object should have the read and write rights on the realm container, principal container and realm subtree.
+-x bindpwd=*<bind_password>* Specifies the password for the above mentioned binddn. It is recommended not to use this option. Instead, the password can be stashed using the *stashsrvpw* command of *kdb5_ldap_util*. Note: This database specific argument is applicable only to *kadmin.local* and the KADM5 server.
+-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.
+======================= ===============================================
+
+------------
+
+Feedback:
+
+Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___db
+
--- /dev/null
+Deleting policies
+========================
+
+To delete a policy, use the kadmin *delete_policy* command, which requires the "delete" administrative privilege. The syntax is::
+
+ delete_policy [-force] policy_name
+
+
+The *delete_policy* command has the alias **delpol**. It prompts for confirmation before deletion.
+
+For example::
+
+ kadmin: delete_policy guests
+ Are you sure you want to delete the policy "guests"?
+ (yes/no): yes
+ kadmin:
+
+.. note:: You must cancel the policy from *all* principals before deleting it. The *delete_policy* command will fail if it is in use by any principals.
+
+
+
+------------
+
+Feedback:
+
+Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___db_policies
+
--- /dev/null
+.. _db_policies_label:
+
+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.
+
+
+.. toctree::
+ :maxdepth: 1
+
+ retr_pol.rst
+ retr_list_pol.rst
+ mod_pol.rst
+ del_pol.rst
+ update_histkey.rst
+
+
+------------
+
+Feedback:
+
+Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___db_policies
+
+
+
+
--- /dev/null
+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
+
+*add_policy* has the alias **addpol**.
+
+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
+
+*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. This option is not supported for LDAP database.
+========================= ==================================
+
+|
+
+.. note:: The policies are created under *realm* container in the LDAP database.
+
+
+------------
+
+Feedback:
+
+Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___db_policies
+
+
--- /dev/null
+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:
+
+
+------------
+
+Feedback:
+
+Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___db_policies
+
+
--- /dev/null
+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:
+
+------------
+
+Feedback:
+
+Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___db_policies
+
+
--- /dev/null
+Updating the history key
+==================================
+
+The following text is for release < 1.8.
+
+If a policy specifies a number of old keys kept of two or more, the stored old keys are encrypted in a history key, which is found in the key data of the *kadmin/history* principal.
+
+Currently there is no support for proper rollover of the history key, but you can change the history key (for example, to use a better encryption type) at the cost of invalidating currently stored old keys. To change the history key, run::
+
+ kadmin: change_password -randkey kadmin/history
+
+
+This command will fail if you specify the *-keepold* flag. Only one new history key will be created, even if you specify multiple key/salt combinations.
+
+In the future, we plan to migrate towards encrypting old keys in the master key instead of the history key, and implementing proper rollover support for stored old keys. - implemented in 1.8+
+
+------------
+
+Feedback:
+
+Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___db_policies
+
+
--- /dev/null
+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:
+
+------------
+
+Feedback:
+
+Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___db_princs
+
--- /dev/null
+Principals
+===============
+
+Each entry in the Kerberos database contains a Kerberos principal and the attributes and policies associated with that principal.
+
+.. toctree::
+ :maxdepth: 2
+
+
+ info_princ.rst
+ priv_princ.rst
+ modify_princ.rst
+ delete_princ.rst
+ pass_princ.rst
+
--- /dev/null
+
+Retrieving information about a principal
+=============================================
+
+
+Retrieving a list of 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:
+
+.. _get_list_princs:
+
+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.
+
+------------
+
+Feedback:
+
+Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___db_princs
+
+
--- /dev/null
+.. _add_mod_princs_label:
+
+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
+
+*add_principali* has the aliases **addprinc** and **ank2**.
+
+
+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
+
+*modify_principal* has the alias **modprinc**.
+
+|
+
+The *add_principal* and *modify_principal* commands take the following switches:
+
+*-x db_princ_args*
+Denotes the database specific options.
+
+The options for LDAP database are:
+
+*-x dn=<dn>*
+Specifies the LDAP object that will contain the Kerberos principal being created.
+
+*-x linkdn=<dn>*
+Specifies the LDAP object to which the newly created Kerberos principal object will point to.
+
+*-x containerdn=<container_dn>*
+Specifies the container object under which the Kerberos principal is to be created.
+
+*-x tktpolicy=<policy>*
+Associates a ticket policy to the Kerberos principal. Specifying an empty string value clears the ticket policy associated with the principal.
+
+.. note::
+ - *dn* and *containerdn* options are not valid while modifying the principal.
+ - *containerdn* and *linkdn* options cannot be specified with dn option.
+ - If *dn* or *containerdn* options are not specified while adding the principal, the principals are created under the prinicipal container configured in the realm or the realm container.
+ - *dn* and *containerdn* should be within the subtrees or principal container configured in the realm.
+
+*-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 :ref:`db_policies_label`) 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.
+
+*{-|+}ok_as_delegate*
+The "+ok_as_delegate" option sets a flag in tickets issued for the service principal. Some client programs may recognize this flag as indicating that it is okay to delegate credentials to the service. If ok_as_delegate is set on a cross-realm TGT, it indicates that the foreign realm's ok_as_delegate flags should be honored by clients in the local realm. The default is "-ok_as_delegate".
+
+*-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 :ref:`senct_label` and :ref:`salts_label` 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 you want to create a principal which is contained by a LDAP object, all you need to do is::
+
+ kadmin: addprinc -x dn=cn=jennifer,dc=example,dc=com 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 you want to create a principal under a specific LDAP container and link to an existing LDAP object, all you need to do is::
+
+ kadmin: addprinc -x containerdn=dc=example,dc=com -x linkdn=cn=david,dc=example,dc=com david
+ WARNING: no policy specified for "david@ATHENA.MIT.EDU";
+ defaulting to no policy.
+ 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 want to associate a ticket policy to a principal, all you need to do is::
+
+ kadmin: modprinc -x tktpolicy=userpolicy david
+ Principal "david@ATHENA.MIT.EDU" modified.
+ 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 need cross-realm authentication, you will 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 :ref:`xrealm_authn_label` for more details.
+
+
+------------
+
+Feedback:
+
+Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___db_princs
+
+
--- /dev/null
+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 :ref:`senct_label` and :ref:`salts_label` for possible values.
+ -keepold Keeps the previous kvno's keys around. This flag is usually not necessary except perhaps for TGS keys. Don't use this flag unless you know what you're doing. This option is not supported for the LDAP database
+========================= ============================================================
+
+
+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:: *change_password* will not let you change the password to one that is in the principal's password history.
+
+
+------------
+
+Feedback:
+
+Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___db_princs
+
+
--- /dev/null
+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::
+
+ */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
+
+.. note:: The order is important; permissions are determined by the first matching entry.
+
+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.
+
+------------
+
+Feedback:
+
+Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___db_princs
+
+
--- /dev/null
+Database administration
+======================================
+
+.. note:: This document was copied from **Kerberos V5 System Administrator's Guide** with minor changes. Currently it is under review. Please, send your feedback, corrections and additions to krb5-bugs@mit.edu. Your contribution is greatly appreciated.
+
+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. *kadmin.local* need not run on the kdc if the database is LDAP. 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.
+
+
+.. toctree::
+ :maxdepth: 2
+
+ db_options.rst
+ date_format.rst
+ db_princs/index.rst
+ db_policies/index.rst
+ db_operations/index.rst
+ ldap_operations/index.rst
+ xrealm_authn.rst
+ change_tgtkey.rst
+
+------------
+
+Feedback:
+
+Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___db
+
--- /dev/null
+.. _edir_create_realm_label:
+
+
+eDir: Creating a Kerberos realm
+=================================
+
+See :ref:`ldap_create_realm_label`
+
+The following are the eDirectory specific options
+
+==================================== ==============================================
+-kdcdn *kdc_servce_list* Specifies the list of KDC service objects serving the realm. The list contains the DNs of the KDC service objects separated by colon(:).
+-admindn *admin_service_list* Specifies the list of Administration service objects serving the realm. The list contains the DNs of the Administration service objects separated by colon(:).
+==================================== ==============================================
+
+|
+
+For example::
+
+ shell% kdb5_ldap_util -D cn=admin,dc=example,dc=com -H ldaps://ldap-server1.mit.edu create -sscope 2
+ -subtree ou=users,dc=example,dc=com -kdcdn cn=krbkdc,dc=example,dc=com -admindn cn=krbadmin,dc=example,dc=com -r ATHENA.MIT.EDU
+
+
+
+ Password for "cn=admin,dc=example,dc=com":
+ Initializing database for realm 'ATHENA.MIT.EDU'
+ You will be prompted for the database Master Password.
+ It is important that you NOT FORGET this password.
+ Enter KDC database master key:
+ Re-enter KDC database master key to verify:
+ shell%
+
+
+
+------------
+
+Feedback:
+
+Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___edir
+
+
--- /dev/null
+eDir: Creating a Service Object
+========================================
+
+To create a service object in directory and assign appropriate rights on the container holding kerberos data, use the following command::
+
+ create_service -kdc|-admin|-pwd [-servicehost service_host_list] [-realm realm_list] [-randpw|
+ -fileonly] [-filename] service_dn
+
+Options are as follows
+
+================================================== ============================================
+-kdc Specifies the KDC service
+-admin Specifies the Administration service
+-pwd Specifies the Password service
+-servicehost *service_host_list* Specifies the list of entries separated by a colon (:). Each entry consists of the hostname or IP address of the server hosting the service, transport protocol and the port number of the service separated by a pound sign (#). For example *server1#tcp#88:server2#udp#89*.
+-realm *realm_list* Specifies the list of realms that are to be associated with this service. The list contains the name of the realms separated by a colon (:).
+-randpw Generates and sets a random password. This option is used to set the random password for the service object in directory and also to store it in the file. *-fileonly* option cannot be used with *-randpw* option.
+-fileonly Stores the password only in a file and not in directory. The *-randpw* option can not be used when *-fileonly* option is specified.
+-f *filename* Specifies the complete path of the file where the service object password is stashed. If this option is not specified, the default file will be */usr/local/var/service_passwd*
+service_dn Specifies the Distinguished Name (DN) of the Kerberos service to be created.
+================================================== ============================================
+
+For example::
+
+ shell% kdb5_ldap_util -D cn=admin,dc=example,dc=com -H ldaps://ldap-server1.mit.edu
+ create_service -kdc -randpw -f /home/andrew/service_passwd cn=service-kdc,dc=example,dc=com
+
+
+ Password for "cn=admin,dc=example,dc=com":
+ File does not exist. Creating the file /home/andrew/service_passwd...
+ shell%
+
+
+
+------------
+
+Feedback:
+
+Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___edir
+
+
--- /dev/null
+eDir: Destroying a Service Object
+===================================
+
+
+The *destroy_service* command is used to destroy an existing service::
+
+ destroy_service [-force] [-f stashfilename] service_dn
+
+
+Options are as follows
+
+=================== ======================
+-force If specified, will not prompt for user's confirmation, instead will force destruction of service.
+-f *stashfilename* Complete path of the service password file from where the entry corresponding to the service_dn needs to be removed.
+service_dn Distinguished Name (DN) of the Kerberos service to be destroyed.
+=================== ======================
+
+For example::
+
+ shell% kdb5_ldap_util -D cn=admin,dc=example,dc=com -H ldaps://ldap-server1.mit.edu
+ destroy_service cn=service-kdc,dc=example,dc=com
+
+ Password for "cn=admin,dc=example,dc=com":
+ This will delete the service object 'cn=service-kdc,dc=example,dc=com', are you sure?
+ (type 'yes' to confirm)? Yes
+ ** service object 'cn=service-kdc,dc=example,dc=com' deleted.
+ shell%
+
+
+------------
+
+Feedback:
+
+Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___edir
+
+
--- /dev/null
+eDir: Retrieving Service Object Information
+==============================================================
+
+To display the attributes of a service, use the folowing command::
+
+ view_service service_dn
+
+where *service_dn* specifies the Distinguished Name (DN) of the Kerberos service to be viewed.
+
+For example::
+
+ shell% kdb5_ldap_util -D cn=admin,dc=example,dc=com -H ldaps://ldap-server1.mit.edu
+ view_service cn=service-kdc,dc=example,dc=com
+
+
+ Password for "cn=admin,dc=example,dc=com":
+ Service dn: cn=service-kdc,dc=example,dc=com
+ Service type: kdc
+ Service host list:
+ Realm DN list: cn=ATHENA.MIT.EDU,cn=Kerberos,dc=example,dc=com
+ shell%
+
+
+
+------------
+
+Feedback:
+
+Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___edir
+
+
--- /dev/null
+.. _edir_mod_realm_label:
+
+
+eDir: Modifying a Kerberos realm
+=================================
+
+See :ref:`ldap_mod_realm_label`
+
+The following are the eDirectory specific options
+
+
+========================================= ================================================
+-kdcdn *kdc_service_list* Specifies the list of KDC service objects serving the realm. The list contains the DNs of the KDC service objects separated by a colon (:). This list replaces the existing list.
+-clearkdcdn *kdc_service_list* Specifies the list of KDC service objects that need to be removed from the existing list. The list contains the DNs of the KDC service objects separated by a colon (:).
+-addkdcdn *kdc_service_list* Specifies the list of KDC service objects that need to be added to the existing list. The list contains the DNs of the KDC service objects separated by a colon (:).
+-admindn *admin_service_list* Specifies the list of Administration service objects serving the realm. The list contains the DNs of the Administration service objects separated by a colon (:). This list replaces the existing list.
+-clearadmindn *admin_service_list* Specifies the list of Administration service objects that need to be removed from the existing list. The list contains the DNs of the Administration service objects separated by a colon (:).
+-addadmindn *admin_service_list* Specifies the list of Administration service objects that need to be added to the existing list. The list contains the DNs of the Administration service objects separated by a colon (:).
+========================================= ================================================
+
+
+
+------------
+
+Feedback:
+
+Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___edir
+
+
--- /dev/null
+eDir: Modifying a Service Object
+=================================
+
+To modify the attributes of a service and assign appropriate rights, if realm associations are changed, use the following command::
+
+ modify_service [-servicehost service_host_list |[-clearservicehost service_host_list] [-addservicehost service_host_list]] [-realm realm_list | [-clearrealm realm_list] [-addrealm realm_list]] service_dn
+
+
+
+Options are as follows
+
+
+========================================= ==================================================
+-servicehost *service_host_list* List of entries separated by a colon (:) where each entry consists of host name or IP address of the server hosting the service, transport protocol, and port number of the service separated by a pound sign (#). This list replaces the existing list. For example, *server1#tcp#88:server2#udp#89*
+-clearservicehost *service_host_list* Specifies the list of servicehost entries to be removed from the existing list. This is a colon separated list.
+-addservicehost *service_host_list* Specifies the list of servicehost entries to be added to the existing list. This is a colon separated list.
+-realm *realm_list* Specifies the list of realms that are to be associated with this service. The list contains the name of the realms separated by a colon (:). This list replaces the existing list.
+-clearrealm *realm_list* Specifies the list of realms to be removed from the existing list. The list contains the name of the realms separated by a colon (:).
+-addrealm *realm_list* Specifies the list of realms to be added to the existing list. The list contains the name of the realms separated by a colon (:).
+service_dn Specifies the Distinguished Name (DN) of the Kerberos service to be modified.
+========================================= ==================================================
+
+For example::
+
+ shell% kdb5_ldap_util -D cn=admin,dc=example,dc=com -H ldaps://ldap-server1.mit.edu
+ modify_service -realm ATHENA.MIT.EDU cn=service-kdc,dc=example,dc=com
+
+
+ Password for "cn=admin,dc=example,dc=com":
+ Changing rights for the service object. Please wait ... done
+ shell%
+
+------------
+
+Feedback:
+
+Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___edir
+
+
--- /dev/null
+eDir: Listing Available Service Objects
+===========================================
+
+The *list_service* command lists the name of services under a given base in directory::
+
+ list_service [-basedn base_dn]
+
+where *-basedn base_dn* option specifies the base DN for searching the policies, limiting the search to a particular subtree. If this option is not provided, LDAP Server specific search base will be used. For e.g., in the case of OpenLDAP, value of *defaultsearchbase* from *slapd.conf* file will be used, where as in the case of eDirectory, the default value for the base DN is *root*.
+
+For example::
+
+ shell% kdb5_ldap_util -D cn=admin,dc=example,dc=com -H ldaps://ldap-server1.mit.edu list_service
+
+
+ Password for "cn=admin,dc=example,dc=com":
+ cn=service-kdc,dc=example,dc=com
+ cn=service-adm,dc=example,dc=com
+ cn=service-pwd,dc=example,dc=com
+ shell%
+
+------------
+
+Feedback:
+
+Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___edir
+
+
--- /dev/null
+eDir: Passwords for Service Objects
+============================================
+
+The command *setsrvpw* allows an administrator to set password for service objects such as KDC and Administration server in eDirectory and store them in a file. The syntax is::
+
+ setsrvpw [-randpw|-fileonly][-f filename] service_dn
+
+Options are as follows:
+
+================= =================================================================
+-randpw Generates and sets a random password on the directory object and stores it in the file. The -fileonly option can not be used if -randpw option is already specified.
+-fileonly Stores the password only in a file and not in eDirectory. The -randpw option can not be used when -fileonly option is specified.
+-f *filename* Specifies the complete path of the file where the service object password is stashed. If this option is not specified, the default file will be /usr/local/var/service_passwd.
+service_dn Specifies the Distinguished Name (DN) of the service object whose password is to be set.
+================= =================================================================
+
+For example::
+
+ shell% kdb5_ldap_util setsrvpw -D cn=admin,dc=example,dc=com -H ldaps://ldap-server1.mit.edu
+ setsrvpw -f /home/andrew/conf_keyfile cn=service-kdc,dc=example,dc=com
+
+
+ Password for "cn=admin,dc=example,dc=com":
+ Password for "cn=service-kdc,dc=example,dc=com":
+ Re-enter password for "cn=service-kdc,dc=example,dc=com":
+ shell%
+
+
+------------
+
+Feedback:
+
+Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___edir
+
+
--- /dev/null
+.. _ops_on_ldap_label:
+
+Operations on the LDAP database
+===================================================
+
+The *kdb5_ldap_util* is the primary tool for administrating the Kerberos LDAP database. It allows an administrator to manage realms, Kerberos services ( KDC and Admin Server) and ticket policies.
+
+The syntax is::
+
+ kdb5_ldap_util [-D user_dn [-w passwd]] [-H ldap_uri] command [command_options]
+
+======================= ====================================================
+-D *user_dn* Specifies the Distinguished Name (DN) of the user who has sufficient rights to perform the operation on the LDAP server.
+-w *passwd* Specifies the password of *user_dn*. This option is not recommended.
+-H *ldap_uri* Specifies the URI of the LDAP server. It is recommended to use *ldapi://* or *ldaps://* to connect to the LDAP server.
+======================= ====================================================
+
+
+LDAP
+----------
+
+.. toctree::
+ :maxdepth: 2
+
+ ldap_create_realm.rst
+ ldap_mod_realm.rst
+ ldap_del_realm.rst
+ ldap_realm_info.rst
+ ldap_realm_list.rst
+ ldap_stash_pass.rst
+ ldap_tkt_pol.rst
+
+
+eDirectory
+-----------
+
+.. toctree::
+ :maxdepth: 1
+
+ edir_create_realm.rst
+ edir_mod_realm.rst
+ edir_create_so.rst
+ edir_mod_so.rst
+ edir_get_so.rst
+ edir_del_so.rst
+ edir_so_list.rst
+ edir_so_pass.rst
+
+
--- /dev/null
+.. _ldap_create_realm_label:
+
+Creating a Kerberos realm
+================================
+
+If you need to create a new realm, use the command as follows::
+
+
+ create [-r realm] [-subtrees subtree_dn_list] [-sscope search_scope] [-containerref container_reference_dn]
+ [-k mkeytype] [-m|-P password][-sf stashlename] [-s] [-maxtktlife max_ticket_life]
+ [-maxrenewlife max_renewable_ticket_life] [ticket_flags]
+
+
+
+Options to create realm in directory are as follows
+
+=========================================== ==============================================
+-r *realm* Specifies the Kerberos realm of the database; by default the realm returned by krb5_default_local_realm (3) is used.
+-subtrees *subtree_dn_list* Specifies the list of subtrees containing principals of a realm. The list contains the DN of the subtree objects separated by colon(:).
+-sscope *search_scope* Specifies the scope for searching the principals under the subtree. The possible values are 1 or one (one level), 2 or sub (subtree).
+-containerref *container_reference_dn* Specfies the DN of the container object in which the principals of a realm will be created. If the container reference is not configured for a realm, the principals will be created in the realm container.
+-k *mkeytype* Specifies the key type of the master key in the database; the default is that given in kdc.conf.
+-m Specifies that the master database password should be read from the TTY rather than fetched from a file on disk.
+-p *password* Specifies the master database password. This option is not recommended.
+-sf *stashfilename* Specifies the stash file of the master database password.
+-s Specifies that the stash file is to be created.
+-maxtktlife *max_ticket_life* Specifies maximum ticket life for principals in this realm. This value is used, if it is not set on the principal.
+-maxrenewlife *max_renewable_ticket_life* Specifies maximum renewable life of tickets for principals in this realm. This value is used, if it is not set on the principal.
+ticket_flags Specifies the ticket flags_. If this option is not specified, by default, none of the flags are set. This means all the ticket options will be allowed and no restriction will be set. This value is used, if it is not set on the principal.
+=========================================== ==============================================
+
+.. _flags:
+
+The various **ticket flags** are:
+
+ {-\|+}allow_postdated
+ -allow_postdated prohibits principals from obtaining postdated tickets. (Sets the KRB5_KDB_DISALLOW_POSTDATED flag.).+allow_postdated clears this flag.
+ {-\|+}allow_forwardable
+ -allow_forwardable prohibits principals from obtaining forwardable tickets. (Sets the KRB5_KDB_DISALLOW_FORWARDABLE flag.) +allow_forwardable clears this flag.
+ {-\|+}allow_renewable
+ -allow_renewable prohibits principals from obtaining renewable tickets. (Sets the KRB5_KDB_DISALLOW_RENEWABLE flag.) +allow_renewable clears this flag.
+ {-\|+}allow_proxiable
+ -allow_proxiable prohibits principals from obtaining proxiable tickets. (Sets the KRB5_KDB_DISALLOW_PROXABLE flag.) +allow_proxiable clears this flag.
+ {-\|+}allow_dup_skey
+ -allow_dup_skey disables user-to-user authentication for principals by prohibiting principals from obtaining a sessions key for another user. (Sets the KRB5_KDB_DISALLOW_DUP_SKEY flag.) +allow_dup_skey clears this flag.
+ {-\|+}requires_preauth
+ +requires_preauth requires principals to preauthenticate before being allowed to kinit. (Sets the KRB5_KDB_REQURES_PRE_AUTH flag.) -requires_preauth clears this flag.
+ {-\|+}requires_hwauth
+ +requires_hwauth requires principals to preauthenticate using a hardware device before being allowed to kinit. (Sets the KRB5_KDB_REQURES_HW_AUTH flag.) -requires_hwauth clears this flag.
+ {-\|+}ok_as_delegate
+ +ok_as_delegate sets the OK-AS-DELEGATE flag on tickets issued for use with this principal as the service, which clients may use as a hint that credentials can and should be delegated when authenticating to the service. (Sets the KRB5_KDB_OK_AS_DELEGATE flag.) -ok_as_delegate clears this flag.
+ {-\|+}allow_svr
+ -allow_svr prohibits the issuance of service tickets for principals. (Sets the KRB5_KDB_DISALLOW_SVR flag.) +allow_svr clears this flag.
+ {-\|+}allow_tgs_req
+ -allow_tgs_req specifies that a Ticket-Granting Service (TGS) request for a service ticket for principals is not permitted. This option is useless for most things.+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 principals in the database.
+ {-\|+}allow_tix
+ -allow_tix forbids the issuance of any tickets for principals. +allow_tix clears this flag. The default is +allow_tix. In effect, -allow_tix sets the KRB5_KDB_DISALLOW_ALL_TIX flag on principals in the database.
+ {-\|+}needchange
+ +needchange 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_REQURES_PWCHANGE flag on principals in the database.
+ {-\|+}password_changing_service
+ +password_changing_service sets a flag in the attributes field marking principal as a password change service principal (useless for most things). -password_changing_service clears the flag. This flag intentionally has a long name. The default is -password_changing_service. In effect, +password_changing_service sets the KRB5_KDB_PWCHANGE_SERVICE flag on principals in the database.
+
+|
+
+For example::
+
+ shell% kdb5_ldap_util -D cn=admin,dc=example,dc=com -H ldaps://ldap-server1.mit.edu create -sscope 2
+ -subtree ou=users,dc=example,dc=com -r ATHENA.MIT.EDU
+ Password for "cn=admin,dc=example,dc=com":
+ Initializing database for realm 'ATHENA.MIT.EDU'
+ You will be prompted for the database Master Password.
+ It is important that you NOT FORGET this password.
+ Enter KDC database master key:
+ Re-enter KDC database master key to verify:
+ shell%
+
+
+
+.. seealso:: :ref:`edir_create_realm_label`
+
+------------
+
+Feedback:
+
+Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___db_ldap
+
--- /dev/null
+Destroying a Kerberos realm
+===============================================
+
+
+To destroy a Kerberos realm, use the command as follows::
+
+
+ destroy [-f] [-r realm]
+
+Options are as follows
+
+============= =======================
+-f If specified, will not prompt the user for confirmation.
+-r *realm* Specifies the Kerberos realm of the database; by default the realm returned by krb5_default_local_realm (3)is used.
+============= =======================
+
+|
+
+For example::
+
+ shell% kdb5_ldap_util -D cn=admin,dc=example,dc=com -H ldap-server1.mit.edu destroy -r ATHENA.MIT.EDU
+
+
+ Password for "cn=admin,dc=example,dc=com":
+ Deleting KDC database of 'ATHENA.MIT.EDU', are you sure?
+ type 'yes' to confirm)? Yes
+ OK, deleting database of 'ATHENA.MIT.EDU'...
+ shell%
+
+------------
+
+Feedback:
+
+Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___db_ldap
+
+
--- /dev/null
+.. _ldap_mod_realm_label:
+
+Modifying a Kerberos realm
+==================================
+
+If you need to modify a realm, use the command as follows::
+
+
+ modify [-r realm] [-subtrees subtree_dn] [-sscope search_scope][-containerref container_reference_dn]
+ [-maxtktlifemax_ticket_life][-maxrenewlife max_renewable_ticket_life] [ticket_flags]
+
+
+
+Options to modify realm in directory are as follows
+
+================================================= ================================================
+-r *realm* Specifies the Kerberos realm of the database; by default the realm returned by krb5_default_local_realm (3) is used.
+-subtrees *subtree_dn_list* Specifies the list of subtrees containing principal objects in the realm.The list contains the DN of the subtree objects separated by colon(:). This list replaces the existing list.
+-sscope *search_scope* Specifies the scope for searching the principals under the subtrees. The possible values are 1 or one (one level), 2 or sub (subtrees).
+-containerref *container_reference_dn* Specifies the Distinguished Name (DN) of the container object in which the principals of a realm will be created.
+-maxtktlife *max_ticket_life* Specifies maximum ticket life for principals in this realm. This value is used, if it is not set on the principal.
+-maxrenewlife *max_renewable_ticket_life* Specifies maximum renewable life of tickets for principals in this realm. This value is used, if it is not set on the principal.
+ticket_flags Specifies the ticket flags_. If this option is not specified, by default, none of the flags are set. This means all the ticket options will be allowed and no restriction will be set. This value is used, if it is not set on the principal.
+================================================= ================================================
+
+.. _flags:
+
+The various **ticket flags** are:
+
+ {-\|+}allow_postdated
+ -allow_postdated prohibits principals from obtaining postdated tickets. (Sets the KRB5_KDB_DISALLOW_POSTDATED flag.).+allow_postdated clears this flag.
+ {-\|+}allow_forwardable
+ -allow_forwardable prohibits principals from obtaining forwardable tickets. (Sets the KRB5_KDB_DISALLOW_FORWARDABLE flag.) +allow_forwardable clears this flag.
+ {-\|+}allow_renewable
+ -allow_renewable prohibits principals from obtaining renewable tickets. (Sets the KRB5_KDB_DISALLOW_RENEWABLE flag.) +allow_renewable clears this flag.
+ {-\|+}allow_proxiable
+ -allow_proxiable prohibits principals from obtaining proxiable tickets. (Sets the KRB5_KDB_DISALLOW_PROXABLE flag.) +allow_proxiable clears this flag.
+ {-\|+}allow_dup_skey
+ -allow_dup_skey Disables user-to-user authentication for principals by prohibiting principals from obtaining a sessions key for another user. (Sets the KRB5_KDB_DISALLOW_DUP_SKEY flag.). +allow_dup_skey clears This flag.
+ {-\|+}requires_preauth
+ +requires_preauth requires principals to preauthenticate before being allowed to kinit. Sets the KRB5_KDB_REQURES_PRE_AUTH flag.-requires_preauth clears this flag.
+ {-\|+}requires_hwauth
+ +requires_hwauth requires principals to preauthenticate using a hardware device before being allowed to kinit. (Sets the KRB5_KDB_REQURES_HW_AUTH flag.)-requires_hwauth clears this flag.
+ {-\|+}allow_svr
+ -allow_svr prohibits the issuance of service tickets for principals. (Sets the KRB5_KDB_DISALLOW_SVR flag.) +allow_svr clears This flag.
+ {-\|+}allow_tgs_req
+ -allow_tgs_req specifies that a Ticket-Granting Service (TGS) request for a service ticket for principals is not permitted. This option is useless for most things.+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 principals in the database.
+ {-\|+}allow_tix
+ -allow_tix forbids the issuance of any tickets for principals. +allow_tix clears this flag. The default is +allow_tix. In effect, -allow_tix sets the KRB5_KDB_DISALLOW_ALL_TIX flag on principals in the database.
+ {-\|+}needchange
+ +needchange 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_REQURES_PWCHANGE flag on principals in the database.
+ {-\|+}password_changing_service
+ +password_changing_service sets a flag in the attributes field marking principal as a password change service principal (useless for most things).-password_changing_service clears the flag. This flag intentionally has a long name. The default is -password_changing_service In effect, +password_changing_service sets the KRB5_KDB_PWCHANGE_SERVICE flag on principals in the database.
+
+|
+
+For example::
+
+ shell% kdb5_ldap_util -D cn=admin,dc=example,dc=com -H ldaps://ldap-server1.mit.edu
+ modify -r ATHENA.MIT.EDU +requires_preauth
+ Password for "cn=admin,dc=example,dc=com":
+ shell%
+
+.. seealso:: :ref:`edir_mod_realm_label`
+
+
+------------
+
+Feedback:
+
+Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___db_ldap
+
+
--- /dev/null
+Retrieving information about a Kerberos realm
+===============================================
+
+To display the attributes of a realm, use the command as follows::
+
+ view [-r realm]
+
+where *-r realm* specifies the Kerberos realm of the database; by default the realm returned by krb5_default_local_realm (3)is used.
+
+|
+
+For example::
+
+ shell% kdb5_ldap_util -D cn=admin,dc=example,dc=com -H ldaps://ldap-server1.mit.edu view -r ATHENA.MIT.EDU
+
+
+ Password for "cn=admin,dc=example,dc=com":
+ Realm Name: ATHENA.MIT.EDU
+ Subtree: ou=users,dc=example,dc=com
+ Subtree: ou=servers,dc=example,dc=com
+ SearchScope: ONE
+ Maximum ticket life: 0 days 01:00:00
+ Maximum renewable life: 0 days 10:00:00
+ Ticket flags: DISALLOW_FORWARDABLE
+ shell%
+
+
+------------
+
+Feedback:
+
+Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___db_ldap
+
+
--- /dev/null
+Listing available Kerberos realms
+===============================================
+
+To display the list of the realms, use the **list** command.
+
+|
+
+For example::
+
+ shell% kdb5_ldap_util -D cn=admin,dc=example,dc=com -H ldaps://ldap-server1.mit.edu list
+ Password for "cn=admin,dc=example,dc=com":
+ ATHENA.MIT.EDU
+ OPENLDAP.MIT.EDU
+ MEDIA-LAB.MIT.EDU
+ shell%
+
+
+------------
+
+Feedback:
+
+Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___db_ldap
+
+
--- /dev/null
+.. _stash_ldap_label:
+
+Stashing Service object's password
+========================================
+
+::
+
+ stashsrvpw [-f filename] servicedn
+
+This command allows an administrator to store the password of service object in a file. The KDC and Administration server uses this password to authenticate to the LDAP server.
+
+Options are as follows
+
+=============== ==================================
+-f *filename* Specifies the complete path of the service password file. By default, /usr/local/var/service_passwd is used.
+servicedn Specifies the Distinguished Name (DN) of the service object whose password is to be stored in file.
+=============== ==================================
+
+|
+
+For example::
+
+ shell% kdb5_ldap_util stashsrvpw -f /home/andrew/conf_keyle cn=service-kdc,dc=example,dc=com
+
+
+ Password for "cn=service-kdc,dc=example,dc=com":
+ Re-enter password for "cn=service-kdc,dc=example,dc=com":
+ shell%
+
+
+------------
+
+Feedback:
+
+Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___db_ldap
+
+
--- /dev/null
+Ticket Policy operations
+===========================
+
+Creating and modifying a Ticket Policy
+------------------------------------------
+
+
+This command creates a ticket policy in directory::
+
+ create_policy [-r realm] [-maxrenewlife max_renewable_ticket_life] [ticket_flags] policy_name
+
+
+Ticket policy objects are created under the realm container.
+
+This command modifies a ticket policy in directory::
+
+ modify_policy [-r realm] [-maxrenewlife max_renewable_ticket_life] [ticket_flags] policy_name
+
+
+Options are as follows
+
+=========================================== =========================================================
+-r *realm* Specifies the Kerberos realm of the database; by default the realm returned by krb5_default_local_realm(3) is used.
+-maxtktlife *max_ticket_life* Specifies maximum ticket life for principals.
+-maxrenewlife *max_renewable_ticket_life* Specifies maximum renewable life of tickets for principals.
+ticket_flags Specifies the ticket flags_. If this option is not specified, by default, none of the flags are set. This means all the ticket options will be allowed and no restriction will be set.
+policy_name Specifies the name of the ticket policy.
+=========================================== =========================================================
+
+.. _flags:
+
+The various **ticket flags** are:
+
+ {-\|+}allow_postdated
+ -allow_postdated prohibits principals from obtaining postdated tickets. (Sets the KRB5_KDB_DISALLOW_POSTDATED flag.).+allow_postdated clears this flag.
+ {-\|+}allow_forwardable
+ -allow_forwardable prohibits principals from obtaining forwardable tickets. (Sets the KRB5_KDB_DISALLOW_FORWARDABLE flag.) +allow_forwardable clears this flag.
+ {-\|+}allow_renewable
+ -allow_renewable prohibits principals from obtaining renewable tickets. (Sets the KRB5_KDB_DISALLOW_RENEWABLE flag.) +allow_renewable clears this flag.
+ {-\|+}allow_proxiable
+ -allow_proxiable prohibits principals from obtaining proxiable tickets. (Sets the KRB5_KDB_DISALLOW_PROXABLE flag.) +allow_proxiable clears this flag.
+ {-\|+}allow_dup_skey
+ -allow_dup_skey Disables user-to-user authentication for principals by prohibiting principals from obtaining a sessions key for another user. (Sets the KRB5_KDB_DISALLOW_DUP_SKEY flag.). +allow_dup_skey clears This flag.
+ {-\|+}requires_preauth
+ +requires_preauth requires principals to preauthenticate before being allowed to kinit. (Sets the KRB5_KDB_REQURES_PRE_AUTH flag.) -requires_preauth clears this flag.
+ {-\|+}requires_hwauth
+ +requires_hwauth requires principals to preauthenticate using a hardware device before being allowed to kinit. (Sets the KRB5_KDB_REQURES_HW_AUTH flag.) -requires_hwauth clears this flag.
+ {-\|+}allow_svr
+ -allow_svr prohibits the issuance of service tickets for principals. (Sets the KRB5_KDB_DISALLOW_SVR flag.) +allow_svr clears This flag.
+ {-\|+}allow_tgs_req
+ -allow_tgs_req specifies that a Ticket-Granting Service (TGS) request for a service ticket for principals is not permitted. This option is useless for most things.+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 principals in the database.
+ {-\|+}allow_tix
+ -allow_tix forbids the issuance of any tickets for principals. +allow_tix clears this flag. The default is +allow_tix. In effect, -allow_tix sets the KRB5_KDB_DISALLOW_ALL_TIX flag on principals in the database.
+ {-\|+}needchange
+ +needchange 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_REQURES_PWCHANGE flag on principals in the database.
+ {-\|+}password_changing_service
+ +password_changing_service sets a flag in the attributes field marking principal as a password change service principal (useless for most things). -password_changing_service clears the flag. This flag intentionally has a long name. The default is -password_changing_service. In effect, +password_changing_service sets the KRB5_KDB_PWCHANGE_SERVICE flag on principals in the database.
+
+
+For example::
+
+ shell% kdb5_ldap_util -D cn=admin,dc=example,dc=com -H ldaps://ldap-server1.mit.edu create_policy
+ -r ATHENA.MIT.EDU -maxtktlife "1 day" -maxrenewlife "1 week" -allow_forwardable usertktpolicy
+
+
+ Password for "cn=admin,dc=example,dc=com":
+ shell%
+
+
+Retrieving Information About a Ticket Policy
+---------------------------------------------
+
+
+To display the attributes of a ticket policy, use the following command::
+
+ view_policy [-r realm] policy_name
+
+Options are as follows
+
+=============== ==========================
+-r *realm* Specifies the Kerberos realm of the database; by default the realm returned by krb5_default_local_realm(3) is used.
+policy_name Specifies the name of the ticket policy
+=============== ==========================
+
+
+For example::
+
+ shell% kdb5_ldap_util -D cn=admin,dc=example,dc=com -H ldaps://ldap-server1.mit.edu view_policy
+ -r ATHENA.MIT.EDU usertktpolicy
+
+
+ Password for "cn=admin,dc=example,dc=com":
+ Ticket policy: usertktpolicy
+ Maxmum ticket life: 0 days 01:00:00
+ Maxmum renewable life: 0 days 10:00:00
+ Ticket flags: DISALLOW_FORWARDABLE REQUIRES_PWCHANGE
+ shell%
+
+
+Destroying a Ticket Policy
+--------------------------------
+
+To destroy an existing ticket policy, use the following command::
+
+ destroy_policy [-force] [-r realm] policy_name
+
+
+Options are as follows
+
+=============== =========================================================
+-force Forces the deletion of the policy object. If not specified, will be prompted for confirmation while deleting the policy. Enter yes to confirm the deletion.
+-r *realm* Specifies the Kerberos realm of the database; by default the realm returned by krb5_default_local_realm(3) is used.
+policy_name Specifies the name of the ticket policy.
+=============== =========================================================
+
+
+For example::
+
+ shell% kdb5_ldap_util -D cn=admin,dc=example,dc=com -H ldaps://ldap-server1.mit.edu
+ destroy_policy -r ATHENA.MIT.EDU usertktpolicy
+
+
+ Password for "cn=admin,dc=example,dc=com":
+ This will delete the policy object 'usertktpolicy', are you sure?
+ (type 'yes' to confirm)? Yes
+ ** policy object 'usertktpolicy' deleted.
+ shell%
+
+
+Listing available Ticket Policies
+-----------------------------------
+
+To list the name of ticket policies in a realm, use the fillowing command::
+
+ list_policy [-r realm]
+
+Option is as follows:
+
+-r *realm*
+ Specifies the Kerberos realm of the database; by default the realm returned by krb5_default_local_realm(3) is used.
+
+
+For example::
+
+ shell% kdb5_ldap_util -D cn=admin,dc=example,dc=com -H ldaps://ldap-server1.mit.edu list_policy -r ATHENA.MIT.EDU
+
+
+ Password for "cn=admin,dc=example,dc=com":
+ usertktpolicy
+ tempusertktpolicy
+ krbtktpolicy
+ shell%
+
+
+------------
+
+Feedback:
+
+Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___db_ldap
+
+
--- /dev/null
+.. _xrealm_authn_label:
+
+Cross-realm authentication
+============================
+
+In order for a KDC in one realm to authenticate Kerberos users in a different realm, it must share a key with the KDC in the other realm. In both databases, there must be krbtgt service principals for realms. These principals should all have the same passwords, key version numbers, and encryption types.
+
+For example, if the administrators of ATHENA.MIT.EDU and EXAMPLE.COM wanted to authenticate across the realms, they would run the following commands on the KDCs in both realms::
+
+ shell%: kadmin.local -e "des3-hmac-sha1:normal des-cbc-crc:v4"
+ kadmin: addprinc -requires_preauth krbtgt/ATHENA.MIT.EDU@EXAMPLE.COM
+ Enter password for principal krbtgt/ATHENA.MIT.EDU@EXAMPLE.COM:
+ Re-enter password for principal krbtgt/ATHENA.MIT.EDU@EXAMPLE.COM:
+ kadmin: addprinc -requires_preauth krbtgt/EXAMPLE.COM@ATHENA.MIT.EDU
+ Enter password for principal krbtgt/EXAMPLE.COM@ATHENA.MIT.EDU:
+ Enter password for principal krbtgt/EXAMPLE.COM@ATHENA.MIT.EDU:
+ kadmin:
+
+.. note:: Even if most principals in a realm are generally created with the *requires_preauth* flag enabled, this flag is not desirable on cross-realm authentication keys because doing so makes it impossible to disable preauthentication on a service-by-service basis. Disabling it as in the example above is recommended.
+
+
+.. note:: It is very important that these principals have good passwords. MIT recommends that TGT principal passwords be at least 26 characters of random ASCII textck:
+
+------------
+
+Feedback:
+
+Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___db
+
+
--- /dev/null
+.. _udns_label:
+
+Using DNS
+=========================
+
+.. note:: This document was copied from **Kerberos V5 System Administrator's Guide** with minor changes. Currently it is under review. Please, send your feedback, corrections and additions to krb5-bugs@mit.edu. Your contribution is greatly appreciated.
+
+
+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 :ref:`krb5_conf_label` configuration file. 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 :ref:`krb5_conf_label`.
+_kpasswd._udp
+ This should list port 464 on your master KDC. It is used when a user changes her password.
+
+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.
+
+--------------
+
+Feedback
+
+Please, provide your feedback or suggest a new topic at krb5-bugs@mit.edu?subject=Documentation___admin_dns
+
+
+
--- /dev/null
+For administrators
+============================
+
+::
+
+ A collection of documents how to setup Kerberos in various environments.
+ Simple admin tasks
+ Installation
+ Configuration
+ Trobleshooting (errors etc)
+ Advanced topics
+
+Contents:
+---------
+
+.. toctree::
+ :maxdepth: 2
+
+ conf_files/index.rst
+ dns.rst
+ database/index.rst
+ conf_ldap.rst
+ appl_servers/index.rst
+ backup_host.rst
+
+
+.. toctree::
+ :maxdepth: 1
+
+ troubleshoot.rst
+ advanced/index.rst
+ install.rst
+ various_envs.rst
+
+
+------------
+
+Feedback:
+
+Please, provide your feedback or suggest a new topic at krb5-bugs@mit.edu?subject=Documentation___admin
+
--- /dev/null
+Installation guide
+===================
+
+#. Debian Setting up of Kerberos <http://techpubs.spinlocksolutions.com/dklar/kerberos.html>_
+
+..
+
+Feedback
+------------------
+
+
+Please, provide your feedback on this document at krb5-bugs@mit.edu?subject=Documentation___install_guide
+
--- /dev/null
+Troubleshooting
+================
+
+List
+----
+
+
+.. error:: KDC has no support for encryption type while getting initial credentials
+
+.. error:: credential verification failed: KDC has no support for encryption type
+
+
+
+Add **allow_weak_crypto = true** to the [libdefaults] section of krb5.conf
+
+Version 1.7+
+
+Seen in: clients
+
+--------------------------------------------------------------------------------------------
+
+.. error:: Hostname cannot be canonicalized
+
+The problem is that ssh is attempting to authenticate to the
+canonicalization of inside-host in DNS, but since that's inside your
+internal network, there is no DNS available to do the
+canonicalization, so one needs to tell GSSAPI what the hostname is separately.
+
+| Host inside-host
+| GSSAPITrustDns no
+| HostName inside-host.inside.domain
+| ProxyCommand ssh -t jump-box.example.com "nc -w2 %h %p"
+
+
+GSSAPITrustDns yes is setting the exact opposite of rdns = false. It's the equivalent of rdns = true.
+
+External links: [http://www.mail-archive.com/kerberos@mit.edu/msg17101.html]
+
+Seen in: ssh
+
+
+--------------------------------------------------------------------------------------------
+
+.. error:: Wrong principal in request
+
+
+If referrals are being used, specifying the host to realm mapping in the krb5 profile results
+in the referrals logic being disabled and may solve the problem.
+
+External links: [http://www.mail-archive.com/kerberos@mit.edu/msg16257.html]
+
+Seen in: ssh
+
+--------------------------------------------------------------------------------------------
+
+..
+
+------------------
+
+Feedback
+
+
+Please, provide your feedback on this document at krb5-bugs@mit.edu?subject=Documentation___errors
+
--- /dev/null
+Various links
+==============================================================
+
+Whitepapers:
+------------
+
+#. http://kerberos.org/software/whitepapers.html
+
+
+Tutorials:
+-----------
+
+#. Fulvio Ricciardi <http://www.kerberos.org/software/tutorial.html>_
+
+
+Troubleshooting:
+----------------
+
+#. http://www.ncsa.illinois.edu/UserInfo/Resources/Software/kerberos/troubleshooting.html
+
+#. http://nfsv4.bullopensource.org/doc/kerberosnfs/krbnfs_howto_v3.pdf
+
+#. http://sysdoc.doors.ch/HP/T1417-90005.pdf
+
+#. http://www.shrubbery.net/solaris9ab/SUNWaadm/SYSADV6/p27.html
+
+#. http://download.oracle.com/docs/cd/E19253-01/816-4557/trouble-1/index.html
+
+#. http://technet.microsoft.com/en-us/library/bb463167.aspx#EBAA
+
+#. https://bugs.launchpad.net/ubuntu/+source/libpam-heimdal/+bug/86528
+
+#. http://h71000.www7.hp.com/doc/83final/ba548_90007/ch06s05.html
+
+..
+
+------------------
+
+Feedback
+
+
+Please, provide your feedback on this document at krb5-bugs@mit.edu?subject=Documentation___various_envs
--- /dev/null
+Differences between Heimdal and MIT Kerberos API
+==================================================================================
+
+.. note:: :c:func:`krb5_auth_con_getaddrs()`
+
+Heimdal: If either of the pointers to local_addr and remote_addr is not NULL,
+ it is freed first and then reallocated before being populated with
+ the content of corresponding address from authentication context.
+
+.. note:: :c:func:`krb5_auth_con_setaddrs()`
+
+Heimdal: If either address is NULL, the previous address remains in place
+
+.. note:: :c:func:`krb5_auth_con_setports()`
+
+Heimdal: Not implemented as of version 1.3.3
+
+.. note:: :c:func:`krb5_auth_con_setrecvsubkey()`
+
+Heimdal: If either port is NULL, the previous port remains in place
+
+.. note:: :c:func:`krb5_auth_con_setsendsubkey()`
+
+Heimdal: Not implemented as of version 1.3.3
+
+.. note:: :c:func:`krb5_cc_set_config()`
+
+MIT: Before version 1.10 it was assumed that the last arguments *data* is ALWAYS non-zero.
+
+.. note:: :c:func:`krb5_cccol_last_change_time ()`
+
+Prototype difference.
+
+Heimdal takes three arguments:
+
+ | krb5_context context,
+ | const char type,
+ | krb5_timestamp \* change_time
+
+MIT takes two arguments:
+
+ | krb5_context context,
+ | krb5_timestamp * change_time
+
+.. note:: :c:func:`krb5_set_default_realm()`
+
+Heimdal: Caches the computed default realm context field.
+ If the second argument is NULL, it tries to retrieve it from libdefaults or DNS.
+
+MIT: Computes the default realm each time if it wasn't explicitly set in the context
+
+..
+
+------------------
+
+Feedback
+
+
+Please, provide your feedback on this document at krb5-bugs@mit.edu?subject=Documentation___h5lMITdiff
+
+
--- /dev/null
+.. _tutorial_ctx_basic:
+
+For application developers
+===================================
+
+Contents:
+---------
+
+
+.. toctree::
+ :maxdepth: 1
+
+ h5l_mit_apidiff.rst
+ princ_handle.rst
+
+
+Topics in TODO list:
+----------------------
+
+#. A basic introduction to GSS-API, making use of the sample client and server, with special attention paid to Kerberos-related GSS-API issues.
+
+#. How to tell the GSS-API library on the client side where the existing Kerberos ticket cache is.
+
+#. How to write mechanism-independent GSS-API code and when to do so.
+
+#. SASL: how to use it, and how it interacts with GSS-API.
+
+#. How to get servers to use any key in a keytab.
+
+#. A more advanced introduction to using the Kerberos libraries for initial authentication, focusing on the authentication steps, validating initial credentials
+
+#. An introduction to ticket caches and keytabs and their corresponding APIs.
+
+#. An advanced guide to the pre-auth mechanisms, FAST
+
+#. An advanced guide to the principal manipulation and parsing,
+
+#. A guide to GSS-API naming as compared to Kerberos principal naming.
+
+#. Establish, save, restore and delete context ( server and client sides)
+
+#. Obtain context status, flags
+
+#. Wrap and send message
+
+#. Read and verify message
+
+#. Working with credentials
+
+#. Server side operations
+
+#. Delegating credentials
+
+#. Anonymous Authentication
+
+#. Developing or selecting cryptosystem
+
+#. Developing or selecting PRNG
+
+#. Developing applications for smart card
+
+#. Indicate authentication strength
+
+#. Implementing IAKERB
+
+#. Using Smartcard with PK-INIT
+
+#. Thread safety
+
+------------
+
+Feedback:
+
+Please, provide your feedback or suggest a new topic at krb5-bugs@mit.edu?subject=Documentation___appdev
+
--- /dev/null
+Principal manipulation and parsing
+============================================
+
+Kerberos principal structure
+
+..
+
+:c:type:`krb5_principal_data`
+
+:c:type:`krb5_principal`
+
+..
+
+Create and free principal
+
+..
+
+:c:func:`krb5_build_principal()`
+
+:c:func:`krb5_build_principal_alloc_va()`
+
+:c:func:`krb5_build_principal_ext()`
+
+:c:func:`krb5_copy_principal()`
+
+:c:func:`krb5_free_principal()`
+
+:c:func:`krb5_cc_get_principal()`
+
+..
+
+Comparing
+
+..
+
+:c:func:`krb5_principal_compare()`
+
+:c:func:`krb5_principal_compare_flags()`
+
+:c:func:`krb5_principal_compare_any_realm()`
+
+:c:func:`krb5_sname_match()`
+
+:c:func:`krb5_sname_to_principal()`
+
+..
+
+
+Parsing:
+
+..
+
+:c:func:`krb5_parse_name()`
+
+:c:func:`krb5_parse_name_flags()`
+
+:c:func:`krb5_unparse_name()`
+
+:c:func:`krb5_unparse_name_flags()`
+
+..
+
+Utilities:
+
+..
+
+:c:func:`krb5_is_config_principal()`
+
+:c:func:`krb5_kuserok()`
+
+:c:func:`krb5_set_password()`
+
+:c:func:`krb5_set_password_using_ccache()`
+
+:c:func:`krb5_set_principal_realm()`
+
+:c:func:`krb5_realm_compare()`
+
+..
+
+------------------
+
+Feedback
+
+
+Please, provide your feedback on this document at krb5-bugs@mit.edu?subject=Documentation___princ_handle
+
--- /dev/null
+For users
+===========
+
+::
+
+ A collection of documents for Kerberos users
+
+.. note:: This document was copied from **Kerberos V5 UNIX User's Guide**. Currently it is under review. Please, send your feedback, corrections and additions to krb5-bugs@mit.edu. Your contribution is greatly appreciated.
+
+Contents:
+---------
+
+.. toctree::
+ :maxdepth: 2
+
+ pwd_mgmt/index.rst
+ tkt_mgmt/index.rst
+ user_appl/index.rst
+
+------------
+
+Feedback:
+
+Please, provide your feedback or suggest a new topic at krb5-bugs@mit.edu?subject=Documentation___users
+
--- /dev/null
+.. _gatya_label:
+
+Granting access to your account
+======================================
+
+If you need to give someone access to log into your account, you can do so through Kerberos, without telling the person your password. Simply create a file called .k5login in your home directory. This file should contain the Kerberos principal of each person to whom you wish to give access. Each principal must be on a separate line. Here is a sample *.k5login* file::
+
+ jennifer@ATHENA.MIT.EDU
+ david@EXAMPLE.COM
+
+This file would allow the users *jennifer* and *david* to use your user ID, provided that they had Kerberos tickets in their respective realms. If you will be logging into other hosts across a network, you will want to include your own Kerberos principal in your *.k5login* file on each of these hosts.
+
+Using a *.k5login* file is much safer than giving out your password, because:
+
+- You can take access away any time simply by removing the principal from your *.k5login* file.
+- Although the user has full access to your account on one particular host (or set of hosts if your *.k5login* file is shared, e.g., over NFS), that user does not inherit your network privileges.
+- Kerberos keeps a log of who obtains tickets, so a system administrator could find out, if necessary, who was capable of using your user ID at a particular time.
+
+One common application is to have a *.k5login* file in root's home directory, giving root access to that machine to the Kerberos principals listed. This allows system administrators to allow users to become root locally, or to log in remotely as root, without their having to give out the root password, and without anyone having to type the root password over the network.
+
+------------------
+
+Feedback:
+
+Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___users_pwd_mgmt
+
+
--- /dev/null
+Password management
+============================
+
+.. note:: This document was copied from **Kerberos V5 UNIX User's Guide**. Currently it is under review. Please, send your feedback, corrections and additions to krb5-bugs@mit.edu. Your contribution is greatly appreciated.
+
+
+
+Your password is the only way Kerberos has of verifying your identity. If someone finds out your password, that person can masquerade as you—send email that comes from you, read, edit, or delete your files, or log into other hosts as you—and no one will be able to tell the difference. For this reason, it is important that you choose a good password, and keep it secret. If you need to give access to your account to someone else, you can do so through Kerberos. (See :ref:`gatya_label`.) You should never tell your password to anyone, including your system administrator, for any reason. You should change your password frequently, particularly any time you think someone may have found out what it is.
+
+
+
+.. toctree::
+ :maxdepth: 1
+
+ pwd_management.rst
+ grant_access.rst
+ pwd_quality.rst
+
+------------------
+
+Feedback:
+
+Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___users_pwd_mgmt
+
+
--- /dev/null
+Changing your password
+==========================
+
+To change your Kerberos password, use the *kpasswd* command. It will ask you for your old password (to prevent someone else from walking up to your computer when you're not there and changing your password), and then prompt you for the new one twice. (The reason you have to type it twice is to make sure you have typed it correctly.) For example, user *david* would do the following::
+
+ shell% kpasswd
+ Password for david: <- Type your old password.
+ Enter new password: <- Type your new password.
+ Enter it again: <- Type the new password again.
+ Password changed.
+ shell%
+
+If *david* typed the incorrect old password, he would get the following message::
+
+ shell% kpasswd
+ Password for david: <- Type the incorrect old password.
+ kpasswd: Password incorrect while getting initial ticket
+ shell%
+
+If you make a mistake and don't type the new password the same way twice, *kpasswd* will ask you to try again::
+
+ shell% kpasswd
+ Password for david: <- Type the old password.
+ Enter new password: <- Type the new password.
+ Enter it again: <- Type a different new password.
+ kpasswd: Password mismatch while reading password
+ shell%
+
+Once you change your password, it takes some time for the change to propagate through the system. Depending on how your system is set up, this might be anywhere from a few minutes to an hour or more. If you need to get new Kerberos tickets shortly after changing your password, try the new password. If the new password doesn't work, try again using the old one.
+
+------------------
+
+Feedback:
+
+Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___users_pwd_mgmt
+
+
--- /dev/null
+Password quality verification
+==============================
+
+TODO
+
+------------------
+
+Feedback:
+
+Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___users_pwd_mgmt
+
+
--- /dev/null
+Destroying tickets with *kdestroy*
+=====================================
+
+Your Kerberos tickets are proof that you are indeed yourself, and tickets can be stolen. If this happens, the person who has them can masquerade as you until they expire. For this reason, you should destroy your Kerberos tickets when you are away from your computer.
+
+Destroying your tickets is easy. Simply type *kdestroy*::
+
+ shell% kdestroy
+ shell%
+
+If *kdestroy* fails to destroy your tickets, it will beep and give an error message. For example, if *kdestroy* can't find any tickets to destroy, it will give the following message::
+
+ shell% kdestroy
+ kdestroy: No credentials cache file found while destroying cache
+ shell%
+
+------------------
+
+Feedback:
+
+Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___users_tkt_mgmt
+
+
+
--- /dev/null
+Ticket management
+============================
+
+.. note:: This document was copied from **Kerberos V5 UNIX User's Guide**. Currently it is under review. Please, send your feedback, corrections and additions to krb5-bugs@mit.edu. Your contribution is greatly appreciated.
+
+
+
+On many systems, Kerberos is built into the login program, and you get tickets automatically when you log in. Other programs, such as *rsh, rcp, telnet*, and *rlogin*, can forward copies of your tickets to the remote host. Most of these programs also automatically destroy your tickets when they exit. However, MIT recommends that you explicitly destroy your Kerberos tickets when you are through with them, just to be sure. One way to help ensure that this happens is to add the *kdestroy* command to your *.logout* file. Additionally, if you are going to be away from your machine and are concerned about an intruder using your permissions, it is safest to either destroy all copies of your tickets, or use a screensaver that locks the screen.
+
+.. toctree::
+ :maxdepth: 1
+
+ tkt_management.rst
+ obtain_kinit.rst
+ view_klist.rst
+ destroy_tkt.rst
+
+------------------
+
+Feedback:
+
+Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___users_tkt_mgmt
+
--- /dev/null
+.. _otwk_labal:
+
+Obtaining tickets with *kinit*
+==================================
+
+If your site is using the Kerberos V5 login program, you will get Kerberos tickets automatically when you log in. If your site uses a different login program, you may need to explicitly obtain your Kerberos tickets, using the *kinit* program. Similarly, if your Kerberos tickets expire, use the *kinit* program to obtain new ones.
+
+To use the *kinit* program, simply type *kinit* and then type your password at the prompt. For example, Jennifer (whose username is *jennifer*) works for Bleep, Inc. (a fictitious company with the domain name mit.edu and the Kerberos realm ATHENA.MIT.EDU). She would type::
+
+ shell% kinit
+ Password for jennifer@ATHENA.MIT.EDU: <-- [Type jennifer's password here.]
+ shell%
+
+If you type your password incorrectly, *kinit* will give you the following error message::
+
+ shell% kinit
+ Password for jennifer@ATHENA.MIT.EDU: <-- [Type the wrong password here.]
+ kinit: Password incorrect
+ shell%
+
+and you won't get Kerberos tickets.
+
+Notice that *kinit* assumes you want tickets for your own username in your default realm. Suppose Jennifer's friend David is visiting, and he wants to borrow a window to check his mail. David needs to get tickets for himself in his own realm, EXAMPLE.COM [1]_. He would type::
+
+ shell% kinit david@EXAMPLE.COM
+ Password for david@EXAMPLE.COM: <-- [Type david's password here.]
+ shell%
+
+David would then have tickets which he could use to log onto his own machine. Note that he typed his password locally on Jennifer's machine, but it never went over the network. Kerberos on the local host performed the authentication to the KDC in the other realm.
+
+If you want to be able to forward your tickets to another host, you need to request forwardable tickets. You do this by specifying the **-f** option::
+
+ shell% kinit -f
+ Password for jennifer@ATHENA.MIT.EDU: <-- [Type your password here.]
+ shell%
+
+Note that *kinit* does not tell you that it obtained forwardable tickets; you can verify this using the *klist* command (see :ref:`vytwk_label`).
+
+Normally, your tickets are good for your system's default ticket lifetime, which is ten hours on many systems. You can specify a different ticket lifetime with the **-l** option. Add the letter **s** to the value for seconds, **m** for minutes, **h** for hours, or **d** for days. For example, to obtain forwardable tickets for *david@EXAMPLE.COM* that would be good for *three hours*, you would type::
+
+ shell% kinit -f -l 3h david@EXAMPLE.COM
+ Password for david@EXAMPLE.COM: <-- [Type david's password here.]
+ shell%
+
+.. note::You cannot mix units; specifying a lifetime of 3h30m would result in an error. Note also that most systems specify a maximum ticket lifetime. If you request a longer ticket lifetime, it will be automatically truncated to the maximum lifetime.
+
+
+.. [1] Note: the realm EXAMPLE.COM must be listed in your computer's Kerberos configuration file, */etc/krb5.conf*.
+
+------------------
+
+Feedback:
+
+Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___users_tkt_mgmt
+
+
--- /dev/null
+Kerberos ticket properties
+===========================
+
+There are various properties that Kerberos tickets can have:
+
+If a ticket is **forwardable**, then the KDC can issue a new ticket with a different network address based on the forwardable ticket. This allows for authentication forwarding without requiring a password to be typed in again. For example, if a user with a forwardable TGT logs into a remote system, the KDC could issue a new TGT for that user with the netword address of the remote system, allowing authentication on that host to work as though the user were logged in locally.
+
+When the KDC creates a new ticket based on a forwardable ticket, it sets the **forwarded** flag on that new ticket. Any tickets that are created based on a ticket with the forwarded flag set will also have their forwarded flags set.
+
+A **proxiable** ticket is similar to a forwardable ticket in that it allows a service to take on the identity of the client. Unlike a forwardable ticket, however, a proxiable ticket is only issued for specific services. In other words, a ticket-granting ticket cannot be issued based on a ticket that is proxiable but not forwardable.
+
+A **proxy** ticket is one that was issued based on a proxiable ticket.
+
+A **postdated** ticket is issued with the invalid flag set. After the starting time listed on the ticket, it can be presented to the KDC to obtain valid tickets.
+
+Tickets with the **postdateable** flag set can be used to issue postdated tickets.
+
+**Renewable** tickets can be used to obtain new session keys without the user entering their password again. A renewable ticket has two expiration times. The first is the time at which this particular ticket expires. The second is the latest possible expiration time for any ticket issued based on this renewable ticket.
+
+A ticket with the **initial flag** set was issued based on the authentication protocol, and not on a ticket-granting ticket. Clients that wish to ensure that the user's key has been recently presented for verification could specify that this flag must be set to accept the ticket.
+
+An **invalid** ticket must be rejected by application servers. Postdated tickets are usually issued with this flag set, and must be validated by the KDC before they can be used.
+
+A **preauthenticated** ticket is one that was only issued after the client requesting the ticket had authenticated itself to the KDC.
+
+The **hardware authentication** flag is set on a ticket which required the use of hardware for authentication. The hardware is expected to be possessed only by the client which requested the tickets.
+
+If a ticket has the **transit policy** checked flag set, then the KDC that issued this ticket implements the transited-realm check policy and checked the transited-realms list on the ticket. The transited-realms list contains a list of all intermediate realms between the realm of the KDC that issued the first ticket and that of the one that issued the current ticket. If this flag is not set, then the application server must check the transited realms itself or else reject the ticket.
+
+The okay as **delegate** flag indicates that the server specified in the ticket is suitable as a delegate as determined by the policy of that realm. A server that is acting as a delegate has been granted a proxy or a forwarded TGT. This flag is a new addition to the Kerberos V5 protocol and is not yet implemented on MIT servers.
+
+An **anonymous** ticket is one in which the named principal is a generic principal for that realm; it does not actually specify the individual that will be using the ticket. This ticket is meant only to securely distribute a session key. This is a new addition to the Kerberos V5 protocol and is not yet implemented on MIT servers.
+
+------------------
+
+Feedback:
+
+Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___users_tkt_mgmt
+
+
--- /dev/null
+.. _vytwk_label:
+
+Viewing tickets with *klist*
+================================
+
+
+The klist command shows your tickets. When you first obtain tickets, you will have only the ticket-granting ticket. The listing would look like this::
+
+ shell% klist
+ Ticket cache: /tmp/krb5cc_ttypa
+ Default principal: jennifer@ATHENA.MIT.EDU
+
+ Valid starting Expires Service principal
+ 06/07/04 19:49:21 06/08/04 05:49:19 krbtgt/ATHENA.MIT.EDU@ATHENA.MIT.EDU
+ shell%
+
+The ticket cache is the location of your ticket file. In the above example, this file is named */tmp/krb5cc_ttypa*. The default principal is your kerberos principal.
+
+The *valid starting* and *expires* fields describe the period of time during which the ticket is valid. The service principal describes each ticket. The ticket-granting ticket has the primary *krbtgt*, and the instance is the realm name.
+
+Now, if *jennifer* connected to the machine *daffodil.mit.edu*, and then typed *klist* again, she would have gotten the following result::
+
+ shell% klist
+ Ticket cache: /tmp/krb5cc_ttypa
+ Default principal: jennifer@ATHENA.MIT.EDU
+
+ Valid starting Expires Service principal
+ 06/07/04 19:49:21 06/08/04 05:49:19 krbtgt/ATHENA.MIT.EDU@ATHENA.MIT.EDU
+ 06/07/04 20:22:30 06/08/04 05:49:19 host/daffodil.mit.edu@ATHENA.MIT.EDU
+ shell%
+
+Here's what happened: when *jennifer* used telnet to connect to the host *daffodil.mit.edu*, the telnet program presented her ticket-granting ticket to the KDC and requested a host ticket for the host *daffodil.mit.edu*. The KDC sent the host ticket, which telnet then presented to the host *daffodil.mit.edu*, and she was allowed to log in without typing her password.
+
+Suppose your Kerberos tickets allow you to log into a host in another domain, such as *trillium.example.com*, which is also in another Kerberos realm, *EXAMPLE.COM*. If you telnet to this host, you will receive a ticket-granting ticket for the realm *EXAMPLE.COM*, plus the new host ticket for *trillium.example.com*. *klist* will now show::
+
+ shell% klist
+ Ticket cache: /tmp/krb5cc_ttypa
+ Default principal: jennifer@ATHENA.MIT.EDU
+
+ Valid starting Expires Service principal
+ 06/07/04 19:49:21 06/08/04 05:49:19 krbtgt/ATHENA.MIT.EDU@ATHENA.MIT.EDU
+ 06/07/04 20:22:30 06/08/04 05:49:19 host/daffodil.mit.edu@ATHENA.MIT.EDU
+ 06/07/04 20:24:18 06/08/04 05:49:19 krbtgt/EXAMPLE.COM@ATHENA.MIT.EDU
+ 06/07/04 20:24:18 06/08/04 05:49:19 host/trillium.example.com@ATHENA.MIT.EDU
+ shell%
+
+You can use the **-f** option to view the flags that apply to your tickets. The flags are:
+
+===== =========================
+ F Forwardable
+ f forwarded
+ P Proxiable
+ p proxy
+ D postDateable
+ d postdated
+ R Renewable
+ I Initial
+ i invalid
+ H Hardware authenticated
+ A preAuthenticated
+ T Transit policy checked
+ O Okay as delegate
+ a anonymous
+===== =========================
+
+Here is a sample listing. In this example, the user *jennifer* obtained her initial tickets (**I**), which are forwardable (**F**) and postdated (**d**) but not yet validated (**i**)::
+
+ shell% klist -f
+ Ticket cache: /tmp/krb5cc_320
+ Default principal: jennifer@ATHENA.MIT.EDU
+
+ Valid starting Expires Service principal
+ 31/07/05 19:06:25 31/07/05 19:16:25 krbtgt/ATHENA.MIT.EDU@ATHENA.MIT.EDU
+ Flags: FdiI
+ shell%
+
+
+In the following example, the user *david*'s tickets were forwarded (**f**) to this host from another host. The tickets are reforwardable (**F**)::
+
+ shell% klist -f
+ Ticket cache: /tmp/krb5cc_p11795
+ Default principal: david@EXAMPLE.COM
+
+ Valid starting Expires Service principal
+ 07/31/05 11:52:29 07/31/05 21:11:23 krbtgt/EXAMPLE.COM@EXAMPLE.COM
+ Flags: Ff
+ 07/31/05 12:03:48 07/31/05 21:11:23 host/trillium.example.com@EXAMPLE.COM
+ Flags: Ff
+ shell%
+
+------------------
+
+Feedback:
+
+Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___users_tkt_mgmt
+
+
--- /dev/null
+ftp
+=============
+
+The Kerberos V5 FTP program works exactly like the standard UNIX FTP program, with the following Kerberos features added:
+
+=========================== ===================================================================================================
+-k *realm* requests tickets for the remote host in the specified realm, instead of determining the realm itself.
+-f requests that your tickets be forwarded to the remote host. The -f argument must be the last argument on the command line.
+protect *level* (issued at the ftp> prompt) sets the protection level. **clear** is no protection; **safe** ensures data integrity by verifying the checksum, and **private** encrypts the data. Encryption also ensures data integrity.
+=========================== ===================================================================================================
+
+For example, suppose *jennifer* wants to get her RMAIL file from the directory *~jennifer/Mail*, on the host *daffodil.mit.edu*. She wants to encrypt the file transfer. The exchange would look like the following::
+
+ shell% ftp daffodil.mit.edu
+ Connected to daffodil.mit.edu.
+ 220 daffodil.mit.edu FTP server (Version 5.60) ready.
+ 334 Using authentication type GSSAPI; ADAT must follow
+ GSSAPI accepted as authentication type
+ GSSAPI authentication succeeded
+ 200 Data channel protection level set to private.
+ Name (daffodil.mit.edu:jennifer):
+ 232 GSSAPI user jennifer@ATHENA.MIT.EDU is authorized as jennifer
+ 230 User jennifer logged in.
+ Remote system type is UNIX.
+ Using binary mode to transfer files.
+ ftp> protect private
+ 200 Protection level set to Private.
+ ftp> cd ~jennifer/MAIL
+ 250 CWD command successful.
+ ftp> get RMAIL
+ 227 Entering Passive Mode (128,0,0,5,16,49)
+ 150 Opening BINARY mode data connection for RMAIL (361662 bytes).
+ 226 Transfer complete.
+ 361662 bytes received in 2.5 seconds (1.4e+02 Kbytes/s)
+ ftp> quit
+ shell%
+
+------------------
+
+Feedback:
+
+Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___users_appl
+
--- /dev/null
+Kerberized LINUX/UNIX applications
+====================================
+
+.. note:: This document was copied from **Kerberos V5 UNIX User's Guide**. Currently it is under review. Please, send your feedback, corrections and additions to krb5-bugs@mit.edu. Your contribution is greatly appreciated.
+
+
+
+Kerberos V5 is a single-sign-on system. This means that you only have to type your password once, and the Kerberos V5 programs do the authenticating (and optionally encrypting) for you. The way this works is that Kerberos has been built into each of a suite of network programs. For example, when you use a Kerberos V5 program to connect to a remote host, the program, the KDC, and the remote host perform a set of rapid negotiations. When these negotiations are completed, your program has proven your identity on your behalf to the remote host, and the remote host has granted you access, all in the space of a few seconds.o
+
+The Kerberos V5 network programs are those programs that connect to another host somewhere on the internet. These programs include rlogin, telnet, ftp, rsh, rcp, and ksu. These programs have all of the original features of the corresponding non-Kerberos rlogin, telnet, ftp, rsh, rcp, and su programs, plus additional features that transparently use your Kerberos tickets for negotiating authentication and optional encryption with the remote host. In most cases, all you'll notice is that you no longer have to type your password, because Kerberos has already proven your identity.
+
+The Kerberos V5 network programs allow you the options of forwarding your tickets to the remote host (if you obtained forwardable tickets with the *kinit* program; see :ref:`otwk_labal`), and encrypting data transmitted between you and the remote host.
+
+The Kerberos V5 applications are versions of existing UNIX network programs with the Kerberos features added.
+
+.. toctree::
+ :maxdepth: 1
+
+ telnet.rst
+ ftp.rst
+ rcp.rst
+ rlogin.rst
+ rsh.rst
+ ksu.rst
+ ssh.rst
+
+
+------------------
+
+Feedback:
+
+Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___users_appl
+
+
--- /dev/null
+ksu
+=============
+
+The Kerberos V5 *ksu* program replaces the standard UNIX *su* program (See ksu_su_label_). *ksu* first authenticates you to Kerberos. Depending on the configuration of your system, *ksu* may ask for your Kerberos password if authentication fails. Note that you should never type your password if you are remotely logged in using an unencrypted connection.
+
+Once *ksu* has authenticated you, if your Kerberos principal appears in the target's *.k5login* file (see Granting Access to Your Account) or in the target's *.k5users* file (see below), it switches your user ID to the target user ID.
+
+For example, *david* has put *jennifer*'s Kerberos principal in his *.k5login* file. If *jennifer* uses *ksu* to become *david*, the exchange would look like this. (To differentiate between the two shells, *jennifer*'s prompt is represented as *jennifer* and *david*'s prompt is represented as *david*.)::
+
+ jennifer% ksu david
+ Account david: authorization for jennifer@ATHENA.MIT.EDU successful
+ Changing uid to david (3382)
+ david%
+
+Note that the new shell has a copy of *jennifer*'s tickets. The ticket filename contains *david*'s UID with .1 appended to it::
+
+ david% klist
+ Ticket cache: /tmp/krb5cc_3382.1
+ Default principal: jennifer@ATHENA.MIT.EDU
+
+ Valid starting Expires Service principal
+ 07/31/04 21:53:01 08/01/04 07:52:53 krbtgt/ATHENA.MIT.EDU@ATHENA.MIT.EDU
+ 07/31/04 21:53:39 08/01/04 07:52:53 host/daffodil.mit.edu@ATHENA.MIT.EDU
+ david%
+
+If *jennifer* had not appeared in *david*'s *.k5login* file (and the system was configured to ask for a password), the exchange would have looked like this (assuming *david* has taken appropriate precautions in protecting his password)::
+
+ jennifer% ksu david
+ WARNING: Your password may be exposed if you enter it here and are logged
+ in remotely using an unsecure (non-encrypted) channel.
+ Kerberos password for david@ATHENA.MIT.EDU: <- jennifer types the wrong password here.
+ ksu: Password incorrect
+ Authentication failed.
+ jennifer%
+
+Now, suppose *david* did not want to give *jennifer* full access to his account, but wanted to give her permission to list his files and use the "more" command to view them. He could create a *.k5users* file giving her permission to run only those specific commands.
+
+The *.k5users* file is like the *.k5login* file, except that each principal is optionally followed by a list of commands. *ksu* will let those principals execute only the commands listed, using the -e option. *david*'s *.k5users* file might look like the following::
+
+ jennifer@ATHENA.MIT.EDU /bin/ls /usr/bin/more
+ joeadmin@ATHENA.MIT.EDU /bin/ls
+ joeadmin/admin@ATHENA.MIT.EDU *
+ david@EXAMPLE.COM
+
+The above *.k5users* file would let *jennifer* run only the commands /bin/ls and /usr/bin/more. It would let joeadmin run only the command /bin/ls if he had regular tickets, but if he had tickets for his admin instance, joeadmin/admin@ATHENA.MIT.EDU, he would be able to execute any command. The last line gives *david* in the realm EXAMPLE.COM permission to execute any command. (I.e., having only a Kerberos principal on a line is equivalent to giving that principal permission to execute \*.) This is so that *david* can allow himself to execute commands when he logs in, using Kerberos, from a machine in the realm EXAMPLE.COM.
+
+Then, when *jennifer* wanted to list his home directory, she would type::
+
+ jennifer% ksu david -e ls ~david
+ Authenticated jennifer@ATHENA.MIT.EDU
+ Account david: authorization for jennifer@ATHENA.MIT.EDU for execution of
+ /bin/ls successful
+ Changing uid to david (3382)
+ Mail News Personal misc bin
+ jennifer%
+
+If *jennifer* had tried to give a different command to *ksu*, it would have prompted for a password as with the previous example.
+
+Note that unless the *.k5users* file gives the target permission to run any command, the user must use *ksu* with the -e command option.
+
+The *ksu* options you are most likely to use are:
+
+=================== ====================================
+-n *principal* specifies which Kerberos principal you want to use for *ksu*. (e.g., the user *joeadmin* might want to use his admin instance.)
+-c specifies the location of your Kerberos credentials cache (ticket file).
+-k tells *ksu* not to destroy your Kerberos tickets when *ksu* is finished.
+-f requests forwardable tickets. (See :ref:`otwk_labal`.) This is only applicable if *ksu* needs to obtain tickets.
+-l *lifetime* sets the ticket lifetime. (See :ref:`otwk_labal`.) This is only applicable if *ksu* needs to obtain tickets.
+-z tells *ksu* to copy your Kerberos tickets only if the UID you are switching is the same as the Kerberos primary (either yours or the one specified by the **-n** option).
+-Z tells *ksu* not to copy any Kerberos tickets to the new UID.
+-e *command* tells *ksu* to execute command and then exit. See the description of the *.k5users* file above.
+-a *text* (at the end of the command line) tells *ksu* to pass everything after **-a** to the target shell.
+=================== ====================================
+
+----------------------------------
+
+.. _ksu_su_label:
+
+*ksu* vs *su*
+-----------------------
+
+From from the discussion at [http://mailman.mit.edu/pipermail/kerberos/2011-January/016886.html]:
+
+The main reason why we use *ksu* instead of *su* is because every person who
+can *su* to root has their own separate */root* principal with a separate
+password and we want them to use those passwords instead. In many cases,
+the set of people who know the actual root password is more limited than
+the people who can *ksu* (perhaps because the formula for it is shared with
+other systems those people should not be root on, for instance).
+
+You can do this with *su* and an appropriate PAM configuration, or with *sudo*
+and an appropriate PAM configuration, but it's fiddly and annoying and
+it's often easier to just use *ksu*. Plus, you'd probably have to use my
+pam-krb5 module rather than whatever came with your system, since it would
+be extremely difficult to set this up without the aid of the *alt_auth_map*
+configuration option.
+
+Don't need to leak my root password to client users
+
+Client users shall use *ksu* under local machine, not remote machines:
+Ideally in Kerberos you never enter your password into any remote
+system, but always authenticate locally and then use Kerberos to
+authenticate to remote systems. We're moving in that way (by allowing
+root logins only via *GSSAPI*), but the tradeoff is that you have to allow
+remote direct root logins, which makes some a bit uncomfortable.
+
+------------------
+
+Feedback:
+
+Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___users_appl
+
+
--- /dev/null
+rcp
+=============
+
+The Kerberos V5 *rcp* program works exactly like the standard UNIX *rcp* program, with the following Kerberos features added:
+
+============= ================
+-k *realm* requests tickets for the remote host in the specified realm, instead of determining the realm itself.
+-x turns on encryption.
+============= ================
+
+For example, if you wanted to copy the file */etc/motd* from the host *daffodil.mit.edu* into the current directory, via an encrypted connection, you would simply type::
+
+ shell% rcp -x daffodil.mit.edu:/etc/motd .
+
+The *rcp* program negotiates authentication and encryption transparently.
+
+------------------
+
+Feedback:
+
+Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___users_appl
+
+
--- /dev/null
+rlogin
+=================
+
+The Kerberos V5 *rlogin* command works exactly like the standard UNIX *rlogin* program, with the following Kerberos options added:
+
+============= ================================================================================================================
+-f forwards a copy of your tickets to the remote host.
+-F forwards a copy of your tickets to the remote host, and marks them re-forwardable from the remote host.
+-k *realm* requests tickets for the remote host in the specified realm, instead of determining the realm itself.
+-x encrypts the input and output data streams (the username is sent unencrypted)
+============= ================================================================================================================
+
+For example, if *david* wanted to use the standard UNIX *rlogin* to connect to the machine daffodil.example.com, he would type::
+
+ shell% rlogin daffodil.example.com -l david
+ Password: <- david types his password here
+ Last login: Fri Jun 21 10:36:32 from :0.0
+ Copyright (c) 1980, 1983, 1986, 1988, 1990, 1991, 1993, 1994
+ The Regents of the University of California. All rights reserved.
+
+ NetBSD 1.1: Tue May 21 00:31:42 EDT 1996
+
+ Welcome to NetBSD!
+ shell%
+
+Note that the machine daffodil.example.com asked for *david*'s password. When he typed it, his password was sent over the network unencrypted. If an intruder were watching network traffic at the time, that intruder would know *david*'s password.
+
+If, on the other hand, *jennifer* wanted to use Kerberos V5 *rlogin* to connect to the machine *trillium.mit.edu*, she could forward a copy of her tickets, mark them as not forwardable from the remote host, and request an encrypted session as follows::
+
+ shell% rlogin trillium.mit.edu -f -x
+ This rlogin session is using DES encryption for all data transmissions.
+ Last login: Thu Jun 20 16:20:50 from daffodil
+ Athena Server (sun4) Version 9.1.11 Tue Jul 30 14:40:08 EDT 2002
+ shell%
+
+Note that *jennifer*'s machine used Kerberos to authenticate her to *trillium.mit.edu*, and logged her in automatically as herself. She had an encrypted session, a copy of her tickets were waiting for her, and she never typed her password.
+
+If you forwarded your Kerberos tickets, *rlogin* automatically destroys them when it exits.
+
+------------------
+
+Feedback:
+
+Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___users_appl
+
+
+
+
--- /dev/null
+rsh
+================
+The Kerberos V5 rsh program works exactly like the standard UNIX rlogin program, with the following Kerberos features added:
+
+========== ======================
+-f forwards a copy of your tickets to the remote host.
+-F forwards a copy of your tickets to the remote host, and marks them re-forwardable from the remote host.
+-k *realm* requests tickets for the remote host in the specified realm, instead of determining the realm itself.
+-x encrypts the input and output data streams (the command line is not encrypted)
+========== ======================
+
+For example, if your Kerberos tickets allowed you to run programs on the host *trillium@example.com* as root, you could run the date program as follows::
+
+ shell% rsh trillium.example.com -l root -x date
+ This rsh session is using DES encryption for all data transmissions.
+ Tue Jul 30 19:34:21 EDT 2002
+ shell%
+
+If you forwarded your Kerberos tickets, *rsh* automatically destroys them when it exits.
+
+------------------
+
+Feedback:
+
+Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___users_appl
+
+
--- /dev/null
+ssh
+=======================
+
+
+TODO
+
+#. Configuration
+
+#. Cross realm and *ssh*
+
+#.
+
+.. seealso:: man pages ssh_config and sshd_config
+
+------------------
+
+Feedback:
+
+Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___users_appl
+
+
--- /dev/null
+telnet
+=================
+
+The Kerberos V5 telnet command works exactly like the standard UNIX telnet program, with the following Kerberos options added:
+
+============== ==========================================================================================================================
+-f forwards a copy of your tickets to the remote host.
+-F forwards a copy of your tickets to the remote host, and marks them re-forwardable from the remote host.
+-k *realm* requests tickets for the remote host in the specified realm, instead of determining the realm itself.
+-K uses your tickets to authenticate to the remote host, but does not log you in.
+-a attempt automatic login using your tickets. telnet will assume the same username unless you explicitly specify another.
+-x turns on encryption.
+============== ==========================================================================================================================
+
+For example, if david wanted to use the standard UNIX telnet to connect to the machine daffodil.mit.edu, he would type::
+
+ shell% telnet daffodil.example.com
+ Trying 128.0.0.5 ...
+ Connected to daffodil.example.com.
+ Escape character is '^]'.
+
+ NetBSD/i386 (daffodil) (ttyp3)
+
+ login: david
+ Password: <- david types his password here
+ Last login: Fri Jun 21 17:13:11 from trillium.mit.edu
+ Copyright (c) 1980, 1983, 1986, 1988, 1990, 1991, 1993, 1994
+ The Regents of the University of California. All rights reserved.
+
+ NetBSD 1.1: Tue May 21 00:31:42 EDT 1996
+
+ Welcome to NetBSD!
+ shell%
+
+Note that the machine *daffodil.example.com* asked for *david*'s password. When he typed it, his password was sent over the network unencrypted. If an intruder were watching network traffic at the time, that intruder would know david's password.
+
+If, on the other hand, *jennifer* wanted to use the Kerberos V5 telnet to connect to the machine *trillium.mit.edu*, she could forward a copy of her tickets, request an encrypted session, and log on as herself as follows::
+
+ shell% telnet -a -f -x trillium.mit.edu
+ Trying 128.0.0.5...
+ Connected to trillium.mit.edu.
+ Escape character is '^]'.
+ [ Kerberos V5 accepts you as ``jennifer@mit.edu'' ]
+ [ Kerberos V5 accepted forwarded credentials ]
+ What you type is protected by encryption.
+ Last login: Tue Jul 30 18:47:44 from daffodil.example.com
+ Athena Server (sun4) Version 9.1.11 Tue Jul 30 14:40:08 EDT 2002
+
+ shell%
+
+Note that *jennifer*'s machine used Kerberos to authenticate her to *trillium.mit.edu*, and logged her in automatically as herself. She had an encrypted session, a copy of her tickets already waiting for her, and she never typed her password.
+
+If you forwarded your Kerberos tickets, *telnet* automatically destroys them when it exits.
+
+------------------
+
+Feedback:
+
+Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___users_appl
+
+
--- /dev/null
+.. highlight:: rst
+
+.. note:: This is a Draft. The list is incomplete.
+
+MIT Kerberos features
+=======================================
+
+http://web.mit.edu/kerberos
+
+Quick facts
+-----------------------
+
+ +---------------------------------+------------------------+
+ | | MIT |
+ +=================================+========================+
+ | Latest stable version | 1.9.1 |
+ +---------------------------------+------------------------+
+ | Supported versions | 1.7.2, 1.8.4, 1.9.1 |
+ +---------------------------------+------------------------+
+ | Release cycle | 9 - 12 months |
+ +---------------------------------+------------------------+
+ | Supported platforms/ | - Solaris |
+ | OS distributions | - SPARC |
+ | | - x86_64/x86 |
+ | | - GNU/Linux |
+ | | - Debian x86_64/x86 |
+ | | - Ubuntu x86_64/x86 |
+ | | - RedHat x86_64/x86 |
+ | | - BSD |
+ | | - NetBSD x86_64/x86 |
+ +---------------------------------+------------------------+
+ | Crypto backends | - OSSL 1.0+ |
+ | | - builtin |
+ | | - NSS 3.12.9+ |
+ +---------------------------------+------------------------+
+ | Database backends | - LDAP |
+ | | - DB2 |
+ +---------------------------------+------------------------+
+ | krb4 support | < 1.8 |
+ +---------------------------------+------------------------+
+ | DES support | configurable |
+ +---------------------------------+------------------------+
+ | Extensions (1.8+) | - S4U2Self |
+ | | - S4U2Proxy |
+ | | - GSS naming exts |
+ | | - GSS to store creds |
+ +---------------------------------+------------------------+
+
+Interoperabiity
+---------------
+
+Microsoft
+~~~~~~~~~~
+
+Starting from version 1.7:
+
+* Follow client principal referrals in the client library when obtaining initial tickets.
+
+* KDC can issue realm referrals for service principals based on domain names.
+
+* Extensions supporting DCE RPC, including three-leg GSS context setup and unencapsulated GSS tokens inside SPNEGO.
+
+* Microsoft GSS_WrapEX, implemented using the gss_iov API, which is similar to the equivalent SSPI functionality. This is needed to support some instances of DCE RPC.
+
+* NTLM recognition support in GSS-API, to facilitate dropping in an NTLM implementation for improved compatibility with older releases of Microsoft Windows.
+
+* KDC support for principal aliases, if the back end supports them. Currently, only the LDAP back end supports aliases.
+
+* Support Microsoft set/change password (RFC 3244) protocol in kadmind.
+
+* Implement client and KDC support for GSS_C_DELEG_POLICY_FLAG, which allows a GSS application to request credential delegation only if permitted by KDC policy.
+
+
+Starting from version 1.8:
+
+* Microsoft Services for User (S4U) compatibility`
+
+Heimdal
+~~~~~~~~~~
+
+* Support for reading Heimdal database starting from version 1.8
+
+
+Feature list
+--------------------------
+
+
+ +-----------------------------------------------+-----------+-------------------+
+ | | Available | Additional |
+ | | | information |
+ +===============================================+===========+===================+
+ | PKINIT | 1.7 | |
+ +-----------------------------------------------+-----------+-------------------+
+ | Anonymous PKINIT | 1.8 | |
+ +-----------------------------------------------+-----------+-------------------+
+ | IPv6 support in iprop | | |
+ +-----------------------------------------------+-----------+-------------------+
+ | kadmin over IPv6 | 1.9 | |
+ +-----------------------------------------------+-----------+-------------------+
+ | Trace logging | 1.9 | |
+ +-----------------------------------------------+-----------+-------------------+
+ | IAKERB | 1.8 | |
+ +-----------------------------------------------+-----------+-------------------+
+ | GSSAPI/KRB5 multi-realm support | | |
+ +-----------------------------------------------+-----------+-------------------+
+ | Plugins to test password quality | 1.9 | |
+ +-----------------------------------------------+-----------+-------------------+
+ | Plugins to synchronize password changes | 1.9 | |
+ +-----------------------------------------------+-----------+-------------------+
+ | Parallel KDC | | |
+ +-----------------------------------------------+-----------+-------------------+
+ | Credentials delegation | 1.2 | |
+ +-----------------------------------------------+-----------+-------------------+
+ | Constrained delegation | 1.8 | |
+ +-----------------------------------------------+-----------+-------------------+
+ | Cross-realm auth and referrals | 1.7 | |
+ +-----------------------------------------------+-----------+-------------------+
+ | GS2 | 1.9 | |
+ +-----------------------------------------------+-----------+-------------------+
+ | Purging old keys | 1.9 | |
+ +-----------------------------------------------+-----------+-------------------+
+ | Naming extensions for delegation chain | 1.9 | |
+ +-----------------------------------------------+-----------+-------------------+
+ | Password expiration API | 1.9 | |
+ +-----------------------------------------------+-----------+-------------------+
+ | Windows client support (build-only) | 1.9 | |
+ +-----------------------------------------------+-----------+-------------------+
+ | pre-auth mechanisms: | | | | |
+ | | | | | |
+ | - PW-SALT | | | | :rfc:`4120` |
+ | - ENC-TIMESTAMP | | | | :rfc:`4120` |
+ | - SAM-2 | | | | |
+ | - FAST negotiation framework | | 1.8 | | |
+ | - PKINIT | | | | |
+ | - FX-COOKIE | | | | |
+ | - S4U-X509-USER | | | | |
+ | | | |
+ +-----------------------------------------------+-----------+-------------------+
+ | KDC support for SecurID preauthentication | 1.9 | SAM-2 protocol |
+ +-----------------------------------------------+-----------+-------------------+
+ | Account lockout on bad login attempts | 1.8 | |
+ +-----------------------------------------------+-----------+-------------------+
+ | Camellia encryption (CTS-MAC mode) | 1.9 | experimental |
+ | | | |
+ +-----------------------------------------------+-----------+-------------------+
+ | PRNG | | | |
+ | | | | |
+ | - modularity: | | 1.9 | |
+ | - Yarrow PRNG | | < 1.10 | |
+ | - Fortuna PRNG | | 1.9 | |
+ | - OS PRNG | | 1.10 | |
+ +-----------------------------------------------+-----------+-------------------+
+ | Advance warning on password expiry | 1.9 | |
+ +-----------------------------------------------+-----------+-------------------+
+ | Heimdal bridge plugin for KDC backend | 1.8 | |
+ +-----------------------------------------------+-----------+-------------------+
+ | Zero configuration | | |
+ +-----------------------------------------------+-----------+-------------------+
+ | Master key migration | 1.7 | |
+ +-----------------------------------------------+-----------+-------------------+
+ | | | |
+ +-----------------------------------------------+-----------+-------------------+
+
+
+
+Report the problem
+------------------
+
+
+Please, provide your feedback on this document at krb5-bugs@mit.edu?subject=Documentation___krb5_implementation_features
+
+
--- /dev/null
+Kerberos Documentation Relay
+=======================================
+
+
+Philosophy.
+-----------
+
+#. The documentation must be useful;
+
+#. The documentation must be correct;
+
+#. The documentation must be detailed, but optimized. No verbose mode;
+
+#. The documentation should be built incrementally;
+
+#. The documentation should be easy to maintain;
+
+#. The documentation should be examined to identify the approaches that do not work;
+
+
+
+Process.
+------------
+
+#. The Work-To-Do list is created and updated based on the input from the community.
+#. Administrator supports the Work-To-Do list.
+#. Writer picks up the item from this list (such as specific API) and writes the documentation
+#. Committee reviews the documentation and recommends it to be accepted as-is or to be revised
+#. If the documentation needs revision, it is sent to the initial writer or someone else for completion
+#. Once Committee approves the document, it is proofread by the designated engineer
+#. Documented is posted on the web
+
+Feedback and Comments.
+------------------------
+
+At the moment the comments should be sent via email to krb5-bugs@mit.edu. Normally, every document has an email link with the pre-constructed subject line similar to the following:
+
+Please, provide your feedback on this document at krb5-bugs@mit.edu?subject=Documentation___relay_feedback
+
projects / krb5.git / commitdiff
