Add submodule dependency filesHEADmaster

Change-Id: Iaf8d18082d3991dec7c0ebbea540f092188eb4ec

1 files changed, 2014 insertions, 0 deletions

diff --git a/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/krb5/doc/kadm5/api-funcspec.tex b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/krb5/doc/kadm5/api-funcspec.tex
new file mode 100644
index 000000000..c13090a51
--- /dev/null
+++ b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/krb5/doc/kadm5/api-funcspec.tex
@@ -0,0 +1,2014 @@
+\documentstyle[12pt,fullpage,rcsid]{article}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%% Make _ actually generate an _, and allow line-breaking after it.
+\let\underscore=\_
+\catcode`_=13
+\def_{\underscore\penalty75\relax}
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\rcs$Id$
+
+\setlength{\parskip}{.7\baselineskip}
+\setlength{\parindent}{0pt}
+
+\def\v#1{\verb+#1+}
+
+\title{Kerberos Administration System \\
+        KADM5 API Functional Specifications\thanks{\rcsId}}
+\author{Barry Jaspan}
+
+\begin{document}
+
+\sloppy
+\maketitle
+
+{\setlength{\parskip}{0pt}\tableofcontents}
+
+\section{Introduction}
+
+This document describes the Admin API that can be used to maintain
+principals and policies.  It describes the data structures used for
+each function and the interpretation of each data type field, the
+semantics of each API function, and the possible return codes.
+
+The Admin API is intended to be used by remote clients using an RPC
+interface.  It is implemented by the admin server running on the
+Kerberos master server.  It is also possible for a program running on
+the Kerberos master server to use the Admin API directly, without
+going through the admin server.
+
+\section{Versions of the API}
+
+The versions of this API and a brief description of the changes for
+each are:
+
+\begin{description}
+\item[KADM5_API_VERSION_1] The initial version of this API, written by
+OpenVision Technologies and donated to MIT for including in the public
+release.  Originally called OVSEC_KADM_API_VERSION_1.  Most everything
+has been renamed in one way or another, including functions, header
+files, and data structures.  Where possible, the old OVSEC_KADM names
+have been left behind for compatibility with version 1, and
+KADM5_API_VERSION_1 is compatible with OVSEC_KADM_API_VERSION_1 at
+compile-, link-, and run-time.
+
+The OVSEC_KADM name compatibility will not be extended to new
+functionality in future versions because no existing OVSEC_KADM
+clients will use that functionality; new clients should be written to
+the KADM5 API.
+
+\item[KADM5_API_VERSION_2] This version contains the initial changes
+necessary to make the OpenVision administration system work with the
+mid-1996 MIT version of Kerberos 5.  Changes include
+\begin{enumerate}
+\item The kadm5_init functions now take a structure of parameters
+instead of just a realm name, allowing the calling program to specify
+non-default values for various configuration options.  See section
+\ref{sec:configparams} for details.
+
+\item The KADM5 API has been extended to support new features of the
+Kerberos database, including multiple encryption and salt types per
+principal.  See section \ref{sec:keys} for details.
+
+\item kadm5_get_principal now allows a principal's keys to be
+retrieved {\it by local clients only}.  This is necessary in order for
+the kadm5 API to provide the primary Kerberos database interface.
+
+\item The KADM5 authorization system has been completely changed.
+
+\item The functions kadm5_flush, kadm5_get_principals, and
+kadm5_get_policies have been added.
+
+\item The KADM5 API now obeys a caller-allocates rather than
+callee-allocates system.  kadm5_get_principal and kadm5_get_policy are
+affected.
+\end{enumerate}
+\end{description}
+
+\section{Policies and Password Quality}
+
+The Admin API Password Quality mechanism provides the following
+controls.  Note that two strings are defined to be ``significantly
+different'' if they differ by at least one character. The compare is not
+case sensitive.
+
+\begin{itemize}
+\item A minimum length can be required; a password with
+fewer than the specified number of characters will not be accepted.
+
+\item A minimum number of character classes can be required; a
+password that does not contain at least one character from at least
+the specified number of character classes will not be accepted.  The
+character classes are defined by islower(), isupper(), isdigit(),
+ispunct(), and other.
+
+\item Passwords can be required to be different from
+previous passwords; a password that generates the same encryption key
+as any of the principal's specified previous number of passwords will
+not be accepted.  This comparison is performed on the encryption keys
+generated from the passwords, not on the passwords themselves.
+
+\item A single ``forbidden password'' dictionary can be specified for all
+users; a password that is not significantly different from every word
+in the dictionary will not be accepted.
+\end{itemize}
+
+\section{Data Structures}
+
+This section describes the data structures used by the Admin API.
+They are defined in $<$kadm5/admin.h$>$.
+
+\subsection{Principals, kadm5_principal_ent_t}
+\label{sec:principal-structure}
+
+A Kerberos principal entry is represented by a kadm5_principal_ent_t.
+It contains a subset of the information stored in the master Kerberos
+database as well as the additional information maintained by the admin
+system.  In the current version, the only additional information is
+the principal's policy and the aux_attributes flags.
+
+The principal may or may not have a policy enforced on it.  If the
+POLICY bit (see section \ref{sec:masks}) is set in aux_attributes, the
+policy field names the principal's policy.  If the POLICY bit is not
+set in aux_attributes, no policy is enforced on the principal and the
+value of the policy field is undefined.
+
+\begin{figure}[htbp]
+\begin{verbatim}
+typedef struct _kadm5_principal_ent_t {
+        krb5_principal principal;
+
+        krb5_timestamp princ_expire_time;
+        krb5_timestamp last_pwd_change;
+        krb5_timestamp pw_expiration;
+        krb5_deltat max_life;
+        krb5_principal mod_name;
+        krb5_timestamp mod_date;
+        krb5_flags attributes;
+        krb5_kvno kvno;
+        krb5_kvno mkvno;
+
+        char * policy;
+        u_int32 aux_attributes;
+
+        krb5_deltat max_renewable_life;
+        krb5_timestamp last_success;
+        krb5_timestamp last_failed;
+        krb5_kvno fail_auth_count;
+        krb5_int16 n_key_data;
+        krb5_int16 n_tl_data;
+        krb5_tl_data *tl_data;
+        krb5_key_data *key_data;
+} kadm5_principal_ent_rec, *kadm5_principal_ent_t;
+\end{verbatim}
+\caption{Definition of kadm5_principal_ent_t.}
+\label{fig:princ-t}
+\end{figure}
+
+The fields of an kadm5_principal_ent_t are interpreted as
+follows.
+
+\begin{description}
+\item[principal] The name of the principal; must conform to Kerberos
+naming specifications.
+
+\item[princ_expire_time] The expire time of the principal as a Kerberos
+timestamp.  No Kerberos tickets will be issued for a principal after
+its expire time.
+
+\item[last_pwd_change] The time this principal's password was last
+changed, as a Kerberos timestamp.
+
+\item[pw_expiration] The expire time of the user's current password, as a
+Kerberos timestamp.  No application service tickets will be issued for the
+principal once the password expire time has passed.  Note that the user can
+only obtain tickets for services that have the PW_CHANGE_SERVICE bit set in
+the attributes field.
+
+\item[max_life] The maximum lifetime of any Kerberos ticket issued to
+this principal.
+
+\item[attributes] A bitfield of attributes for use by the KDC.  The
+symbols and constant values are defined below; their interpretation
+appears in the libkdb functional specification.
+
+\begin{tabular}{clr}
+{\bf Name} & {\bf Value} \\
+KRB5_KDB_DISALLOW_POSTDATED     & 0x00000001 \\
+KRB5_KDB_DISALLOW_FORWARDABLE   & 0x00000002 \\
+KRB5_KDB_DISALLOW_TGT_BASED     & 0x00000004 \\
+KRB5_KDB_DISALLOW_RENEWABLE     & 0x00000008 \\
+KRB5_KDB_DISALLOW_PROXIABLE     & 0x00000010 \\
+KRB5_KDB_DISALLOW_DUP_SKEY      & 0x00000020 \\
+KRB5_KDB_DISALLOW_ALL_TIX       & 0x00000040 \\
+KRB5_KDB_REQUIRES_PRE_AUTH      & 0x00000080 \\
+KRB5_KDB_REQUIRES_HW_AUTH       & 0x00000100 \\
+KRB5_KDB_REQUIRES_PWCHANGE      & 0x00000200 \\
+KRB5_KDB_DISALLOW_SVR           & 0x00001000 \\
+KRB5_KDB_PWCHANGE_SERVICE       & 0x00002000 \\
+KRB5_KDB_SUPPORT_DESMD5         & 0x00004000 \\
+KRB5_KDB_NEW_PRINC              & 0x00008000
+\end{tabular}
+
+\item[mod_name] The name of the Kerberos principal that most recently
+modified this principal.
+
+\item[mod_date] The time this principal was last modified, as a Kerberos
+timestamp.
+
+\item[kvno] The version of the principal's current key.
+
+\item[mkvno] The version of the Kerberos Master Key in effect when
+this principal's key was last changed.  In KADM5_API_VERSION_2, this
+field is always zero.
+
+\item[policy] If the POLICY bit is set in aux_attributes, the name
+of the policy controlling this principal.
+
+\item[aux_attributes]  A bitfield of flags for use by the
+administration system.  Currently, the only valid flag is POLICY, and
+it indicates whether or not the principal has a policy enforced on it.
+
+\item[max_renewable_life] The maximum renewable lifetime of any
+Kerberos ticket issued to or for this principal.  This field only
+exists in KADM5_API_VERSION_2.
+
+\item[last_success] The KDC time of the last successful AS_REQ.  This
+is only updated if KRBCONF_KDC_MODIFIES_KDB is defined during
+compilation of the KDC.  This field only exists in
+KADM5_API_VERSION_2.
+
+\item[last_failed] The KDC time of the last failed AS_REQ.  This is
+only updated if KRBCONF_KDC_MODIFIES_KDB is defined during compilation
+of the KDC.  This field only exists in KADM5_API_VERSION_2.
+
+\item[fail_auth_count] The number of consecutive failed AS_REQs.  When
+this number reaches KRB5_MAX_FAIL_COUNT, the KRB5_KDC_DISALLOW_ALL_TIX
+is set on the principal.  This is only updated if
+KRBCONF_KDC_MODIFIES_KDB is defined during compilation.  This field
+only exists in KADM5_API_VERSION_2.
+
+\item[n_tl_data] The number of elements in the \v{tl_data} linked
+list.  This field only exists in KADM5_API_VERSION_2.
+
+\item[n_key_data] The number of elements in the \v{key_data}
+array. This field only exists in KADM5_API_VERSION_2.
+
+\item[tl_data] A linked list of tagged data.  This list is a mechanism
+by which programs can store extended information in a principal entry,
+without having to modify the database API.  Each element is of type
+krb5_tl_data:
+\begin{verbatim}
+typedef struct _krb5_tl_data {
+    struct _krb5_tl_data* tl_data_next;
+    krb5_int16            tl_data_type;         
+    krb5_int16            tl_data_length;       
+    krb5_octet          * tl_data_contents;     
+} krb5_tl_data;
+\end{verbatim}
+%
+The KADM5 API only allows elements whose tl_data_type is greater than
+or equal to 256.  Values less than 256 are reserved for internal use
+by the KADM5 or kdb system.  They are filtered out of the list
+returned by kadm5_get_principal, and generate an error if given to
+kadm5_modify_principal.
+
+The libkdb library defines the tagged data types
+KRB5_TL_LAST_PWD_CHANGE, KRB5_TL_MOD_PRINC, and KRB5_TL_KADM_DATA, all
+with values less than 256, which store the last password modification
+time, time and modifier of last principal modification, and
+administration system data.  All of these entries are expected by the
+administration system and parsed out into fields of the
+kadm5_principal_ent_rec structure; as described above, they are not
+included in the tl_data list.
+
+Tagged data elements with types greater than 256 are handled without
+interpretation by KADM5.  Note that an application that calls
+kadm5_modify_principal with the KADM5_TL_DATA mask bit set is
+responsible for providing the {\it complete} tl_data list, which it
+necessarily must obtain from kadm5_get_principal.  It is {\it never}
+possible for an application to construct a complete tl_data list from
+scratch.
+
+\item[key_data] An array of the principal's keys.  The keys contained
+in this array are encrypted in the Kerberos master key.  See section
+\ref{sec:keys} for a discussion of the krb5_key_data structure.
+\end{description}
+
+\subsection{Policies, kadm5_policy_ent_t}
+\label{sec:policy-fields}
+
+If the POLICY bit is set in aux_attributes, the \v{policy} name field
+in the kadm5_principal_ent_t structure refers to a password policy
+entry defined in a \v{kadm5_policy_ent_t}.
+
+\begin{verbatim}
+typedef struct _kadm5_policy_ent_t {
+        char *policy;
+
+        u_int32 pw_min_life;
+        u_int32 pw_max_life;
+        u_int32 pw_min_length;
+        u_int32 pw_min_classes;
+        u_int32 pw_history_num;
+        u_int32 policy_refcnt;
+} kadm5_policy_ent_rec, *kadm5_policy_ent_t;
+\end{verbatim}
+
+The fields of an kadm5_policy_ent_t are interpreted as follows.
+Note that a policy's values only apply to a principal using that
+policy.
+
+\begin{description}
+\item[policy] The name of this policy, as a NULL-terminated string.
+The ASCII characters between 32 (space) and 126 (tilde), inclusive,
+are legal.
+
+\item[pw_min_life] The minimum password lifetime, in seconds.
+A principal cannot change its password before pw_min_life seconds have
+passed since last_pwd_change.
+
+\item[pw_max_life] The default duration, in seconds, used to compute
+pw_expiration when a principal's password is changed.
+
+\item[pw_min_length] The minimum password length, in characters.  A
+principal cannot set its password to anything with fewer than this
+number of characters.  This value must be greater than zero.
+
+\item[pw_min_classes] The minimum number of character classes in the
+password.  This value can only be 1, 2, 3, 4, or 5.  A principal cannot
+set its password to anything with fewer than this number of character
+classes in it.
+
+\item[pw_history_num] The number of past passwords that are
+stored for the principal; the minimum value is 1 and the maximum value
+is 10.  A principal cannot set its password to any of its previous
+pw_history_num passwords.  The first ``previous'' password is the
+current password; thus, a principal with a policy can never reset its
+password to its current value.
+
+\item[policy_refcnt]  The number of principals currently using this policy.
+A policy cannot be deleted unless this number is zero.
+\end{description}
+
+\subsection{Configuration parameters}
+\label{sec:configparams}
+
+The KADM5 API acquires configuration information from the Kerberos
+configuration file (\$KRB5_CONFIG or DEFAULT_PROFILE_PATH) and from
+the KDC configuration file (\$KRB5_KDC_CONFIG or DEFAULT_KDC_PROFILE).
+In KADM5_API_VERSION_2, some of the configuration parameters used by
+the KADM5 API can be controlled by the caller by providing a
+kadm5_config_params structure to kadm5_init:
+%
+\begin{verbatim}
+typedef struct _kadm5_config_params {
+        u_int32 mask;
+
+        /* Client and server fields */
+        char *realm;
+        char *profile;
+        int kadmind_port;
+
+        /* client fields */
+        char *admin_server;
+
+        /* server fields */
+        char *dbname;
+        char *admin_dbname;
+        char *admin_lockfile;
+        char *acl_file;
+        char *dict_file;
+        char *admin_keytab;
+
+        /* server library (database) fields */
+        int mkey_from_kbd;
+        char *stash_file;
+        char *mkey_name;
+        krb5_enctype enctype;
+        krb5_deltat max_life;
+        krb5_deltat max_rlife;
+        krb5_timestamp expiration;
+        krb5_flags flags;
+        krb5_key_salt_tuple *keysalts;
+        krb5_int32 num_keysalts;
+} kadm5_config_params;
+\end{verbatim}
+%
+The following list describes each of the fields of the structure,
+along with the profile relation it overrides, its mask value, its
+default value, and whether it is valid on the client, server, or both,
+or neither.
+\begin{description}
+\item[mask] No variable.  No mask value.  A bitfield specifying which
+fields of the structure contain valid information.  A caller sets this
+mask before calling kadm5_init_*, indicating which parameters are
+specified.  The mask values are defined in $<$kadm5/admin.h$>$ and are
+all prefixed with KADM5_CONFIG_; the prefix is not included in the
+descriptions below.
+
+\item[realm] No variable.  REALM.  Client and server.  The realm to
+which these parameters apply, and the realm for which additional
+parameters are to be acquired, if any.  If this field is not specified
+in the mask, the default local realm is used.
+
+\item[profile] Variable: profile (server only).  PROFILE.  Client and
+server.  The Kerberos profile to use.  On the client, the default is
+the value of the KRB5_CONFIG environment variable, or
+DEFAULT_PROFILE_PATH if that is not set.  On the server, the value of
+the ``profile'' variable of the KDC configuration file will be used as
+the first default if it exists; otherwise, the default is the value of
+the KRB5_KDC_PROFILE environment variable or DEFAULT_KDC_PROFILE.
+
+\item[kadmind_port] Variable: kadmind_port.  KADMIND_PORT.  Client and
+server.  The port number the kadmind server listens on.  The client
+uses this field to determine where to connect, and the server to
+determine where to listen.  The default is 749, which has been
+assigned by IANA.
+
+\item[admin_server] Variable: admin_server.  ADMIN_SERVER.  Client.
+The host name of the admin server to which to connect.  There is no
+default.  If the value of this field contains a colon (:), the text
+following the colon is treated as an integer and assigned to the
+kadmind_port field, overriding any value of the kadmind_port variable.
+
+\item[dbname] Variable: dbname.  DBNAME.  Server.  The Kerberos
+database name to use; the Kerberos database stores principal
+information.  The default is DEFAULT_KDB_FILE.
+
+\item[admin_dbname] Variable: admin_database_name.  ADBNAME.
+Neither.  If the dbname field is set, this field is set to the value
+of dbname followed by ``.kadm5''.
+
+\item[admin_lockfile] Variable: admin_database_lockfile.
+ADB_LOCKFILE.  Neither.  If the admin_dbname field is set, this field
+is set to the value of admin_dbname followed by ``.lock''.
+
+\item[acl_file] Variable: acl_file.  ACL_FILE.  Server.  The admin
+server's ACL file.  The default is DEFAULT_KADM5_ACL_FILE.
+
+\item[dict_file] Variable: admin_dict_file.  DICT_FILE.  Server.  The
+admin server's dictionary file of passwords to disallow.  No default.
+
+\item[admin_keytab] Variable: admin_keytab. ADMIN_KEYTAB.  Server.
+The keytab file containing the kadmin/admin and kadmin/changepw
+entries for the server to use.  The default is the value of the
+KRB5_KTNAME environment variable, if defined, else
+DEFAULT_KADM5_KEYTAB.
+
+\item[mkey_from_keyboard] No variable. MKEY_FROM_KEYBOARD.  Server.
+If non-zero, prompt for the master password via the tty instead of
+using the stash file.  If this mask bit is not set, or is set and the
+value is zero, the stash file is used.
+
+\item[stash_file] Variable: key_stash_file.  STASH_FILE. Server.  The
+file name containing the master key stash file.  No default; libkdb
+will work with a NULL value.
+
+\item[mkey_name] Variable: master_key_name.  MKEY_NAME.  Server.  The
+name of the master principal for the realm.  No default; lbkdb will
+work with a NULL value.
+
+\item[enctype] Variable: master_key_type.  ENCTYPE.  Server.  The
+encryption type of the master principal.  The default is
+DEFAULT_KDC_ENCTYPE.
+
+\item[max_life] Variable: max_life.  MAX_LIFE.  Maximum lifetime for
+all tickets issued to the principal.  The default is 28800, which is 8
+hours.
+
+\item[max_rlife, expiration, flags] Variables: max_renewable_life,
+default_principal_expiration, default_principal_flags.  MAX_LIFE,
+MAX_RLIFE, EXPIRATION, FLAGS.  Server.  Default values for new
+principals.  All default to 0.
+
+\item[keysalts, num_keysalts] Variable: supported_enctypes.  ENCTYPES.
+Server.  The list of supported encryption type/salt type tuples; both
+fields must be assigned if ENCTYPES is set.  The default is a list
+containing one enctype, DES-CBC-CRC with normal salt.
+\end{description}
+
+\subsection{Principal keys}
+\label{sec:keys}
+
+In KADM5_API_VERSION_1, all principals had a single key.  The
+encryption method was always DES, and the salt type was determined
+outside the API (by command-line options to the administration
+server).
+
+In KADM5_API_VERSION_2, principals can have multiple keys, each with
+its own encryption type and salt.  Each time a principal's key is
+changed with kadm5_create_principal, kadm5_chpass_principal or
+kadm5_randkey_principal, existing key entries are removed and a key
+entry for each encryption and salt type tuple specified in the
+configuration parameters is added.  There is no provision for
+specifying encryption and salt type information on a per-principal
+basis; in a future version, this will probably be part of the admin
+policy.  There is also presently no provision for keeping multiple key
+versions for a single principal active in the database.
+
+A single key is represented by a krb5_key_data:
+%
+\begin{verbatim}
+typedef struct _krb5_key_data {
+        krb5_int16            key_data_ver;         /* Version */
+        krb5_int16            key_data_kvno;        /* Key Version */
+        krb5_int16            key_data_type[2];     /* Array of types */
+        krb5_int16            key_data_length[2];   /* Array of lengths */
+        krb5_octet          * key_data_contents[2]; /* Array of pointers */
+} krb5_key_data;
+\end{verbatim}
+%
+\begin{description}
+\item[key_data_ver] The verion number of the structure.  Versions 1
+and 2 are currently defined.  If key_data_ver is 1 then the key is
+either a random key (not requiring a salt) or the salt is the normal
+v5 salt which is the same as the realm and therefore doesn't need to
+be saved in the database.
+
+\item[key_data_kvno] The key version number of this key.
+
+\item[key_data_type] The first element is the enctype of this key.  In
+a version 2 structure, the second element is the salttype of this key.
+The legal encryption types are defined in $<$krb5.h$>$.  The legal
+salt types are defined in $<$k5-int.h$>$.
+
+\item[key_data_length] The first element is length this key.  In a
+version 2 structure, the second element is length of the salt for this
+key.
+
+\item[key_data_contents] The first element is the content of this key.
+In a version 2 structure, the second element is the contents of the
+salt for this key.
+\end{description}
+
+\subsection{Field masks}
+\label{sec:masks}
+
+The API functions for creating, retrieving, and modifying principals
+and policies allow for a relevant subset of the fields of the
+kadm5_principal_ent_t and kadm5_policy_ent_t to be specified or
+changed.  The chosen fields are determined by a bitmask that is passed
+to the relevant function.  Each API function has different rules for
+which mask values can be specified, and can specify whether a given
+mask value is mandatory, optional, or forbidden.  Mandatory fields
+must be present and forbidden fields must not be present or an error
+is generated.  When creating a principal or policy, optional fields
+have a default value if they are not specified.  When modifying a
+principal or policy, optional fields are unchanged if they are not
+specified.  When retrieving a principal, optional fields are simply
+not provided if they are not specified; not specifying undeeded fields
+for retrieval may improve efficiency.  The values for forbidden fields
+are defined in the function semantics.
+
+The masks for principals are in table \ref{tab:princ-bits} and the
+masks for policies are in table \ref{tab:policy-bits}.  They are
+defined in $<$kadm5/admin.h$>$. The KADM5_ prefix has been removed
+from the Name fields.  In the Create and Modify fields, M means
+mandatory, F means forbidden, and O means optional.  Create fields
+that are optional specify the default value.  The notation ``K/M
+value'' means that the field inherits its value from the corresponding
+field in the Kerberos master principal, for KADM5_API_VERSION_1, and
+from the configuration parameters for KADM5_API_VERSION_2.
+
+All masks for principals are optional for retrevial, {\it except} that
+the KEY_DATA mask is illegal when specified by a remote client; for
+details, see the function semantics for kadm5_get_principal.
+
+Note that the POLICY and POLICY_CLR bits are special.  When POLICY is
+set, the policy is assigned to the principal.  When POLICY_CLR is
+specified, the policy is unassigned to the principal and as a result
+no policy controls the principal.
+
+For convenience, the mask KADM5_PRINCIPAL_NORMAL_MASK contains all of
+the principal masks {\it except} KADM5_KEY_DATA and KADM5_TL_DATA, and
+the mask KADM5_POLICY_NORMAL_MASK contains all of the policy masks.
+
+\begin{table}[htbp]
+\begin{tabular}{@{}lclll}
+{\bf Name} & {\bf Value} & {\bf Fields Affected} & {\bf Create} & 
+        {\bf Modify} \\
+PRINCIPAL               & 0x000001 & principal & M & F \\
+PRINC_EXPIRE_TIME       & 0x000002 & princ_expire_time & O, K/M value & O \\
+PW_EXPIRATION           & 0x000004 & pw_expiration & O, now+pw_max_life & O \\
+LAST_PWD_CHANGE         & 0x000008 & last_pwd_change & F & F \\
+ATTRIBUTES              & 0x000010 & attributes & O, 0 & O \\
+MAX_LIFE                & 0x000020 & max_life & O, K/M value & O \\
+MOD_TIME                & 0x000040 & mod_date & F & F \\
+MOD_NAME                & 0x000080 & mod_name & F & F \\
+KVNO                    & 0x000100 & kvno & O, 1 & O \\
+MKVNO                   & 0x000200 & mkvno & F & F \\
+AUX_ATTRIBUTES          & 0x000400 & aux_attributes & F & F \\
+POLICY                  & 0x000800 & policy & O, none & O \\
+POLICY_CLR              & 0x001000 & policy & F & O \\
+MAX_RLIFE               & 0x002000 & max_renewable_life & O, K/M value & O \\
+LAST_SUCCESS            & 0x004000 & last_success & F & F \\
+LAST_FAILED             & 0x008000 & last_failed & F & F \\
+FAIL_AUTH_COUNT         & 0x010000 & fail_auth_count & F & O \\
+KEY_DATA                & 0x020000 & n_key_data, key_data & F & F \\
+TL_DATA                 & 0x040000 & n_tl_data, tl_data & O, 0, NULL & O
+\end{tabular}
+\caption{Mask bits for creating, retrieving, and modifying principals.}
+\label{tab:princ-bits}
+\end{table}
+
+\begin{table}[htbp]
+\begin{tabular}{@{}lclll}
+Name & Value & Field Affected & Create & Modify \\
+POLICY                  & same     & policy & M & F \\
+PW_MAX_LIFE             & 0x004000 & pw_max_life & O, 0 (infinite) & O \\
+PW_MIN_LIFE             & 0x008000 & pw_min_life & O, 0 & O \\
+PW_MIN_LENGTH           & 0x010000 & pw_min_length & O, 1 & O \\
+PW_MIN_CLASSES          & 0x020000 & pw_min_classes & O, 1 & O \\
+PW_HISTORY_NUM          & 0x040000 & pw_history_num & O, 0 & O \\
+REF_COUNT               & 0x080000 & pw_refcnt & F & F
+\end{tabular}
+\caption{Mask bits for creating/modifying policies.}
+\label{tab:policy-bits}
+\end{table}
+
+\section{Constants, Header Files, Libraries}
+
+$<$kadm5/admin.h$>$ includes a number of required header files,
+including RPC, Kerberos 5, com_err, and admin com_err
+defines.  It contains prototypes for all kadm5 routines mentioned
+below, as well as all Admin API data structures, type definitions and
+defines mentioned in this document.  
+
+Before \v{\#include}ing $<$kadm5/admin.h$>$, the programmer can
+specify the API version number that the program will use by
+\v{\#define}ing USE_KADM5_API_VERSION; for example, define that symbol
+to be 1 to use KADM5_API_VERSION_1.  This will ensure that the correct
+functional protoypes and data structures are defined.  If no version
+symbol is defined, the most recent version supported by the header
+files will be used.
+
+Some of the defines and their values contained in $<$kadm5/admin.h$>$
+include the following, whose KADM5_ prefixes have been removed.
+Symbols that do not exist in KADM5_API_VERSION_2 do not have a KADM5_
+prefix, but instead retain only with OVSEC_KADM_ prefix for
+compatibility.
+\begin{description}
+\item[admin service principal] ADMIN_SERVICE (``kadmin/admin'')
+\item[admin history key] HIST_PRINCIPAL (``kadmin/history'')
+\item[change password principal] CHANGEPW_SERVICE (``kadmin/changepw'')
+\item[server acl file path] ACLFILE (``/krb5/ovsec_adm.acl'').  In
+KADM5_API_VERSION 2, this is controlled by configuration parameters.
+\item[dictionary] WORDFILE (``/krb5/kadmind.dict'').    In
+KADM5_API_VERSION 2, this is controlled by configuration parameters.
+\end{description}
+
+KADM5 errors are described in $<$kadm5/kadm_err.h$>$, which
+is included by $<$kadm5/admin.h$>$.
+
+The locations of the admin policy and principal databases, as well as
+defines and type definitions for the databases, are defined in
+$<$kadm5/adb.h$>$.  Some of the defines in that file are:
+\begin{description}
+\item[admin policy database] POLICY_DB (``/krb5/kadm5_policy.db'').    In
+KADM5_API_VERSION 2, this is controlled by configuration parameters.
+\item[admin principal database] PRINCIPAL_DB
+(``/krb5/ovsec_principal.db'').  In KADM5_API_VERSION 2, this is
+controlled by configuration parameters.
+\end{description}
+
+Client applications will link against libkadm5clnt.a and server
+programs against libkadm5srv.a.  Client applications must also link
+against: libgssapi_krb5.a, libkrb5.a, libcrypto.a, libgssrpc.a,
+libcom_err.a, and libdyn.a.  Server applications must also link
+against: libkdb5.a, libkrb5.a, libcrypto.a, libgssrpc.a, libcom_err.a,
+and libdyn.a.
+
+\section{Error Codes}
+
+The error codes that can be returned by admin functions are listed
+below.  Error codes indicated with a ``*'' can be returned by every
+admin function and always have the same meaning; these codes are
+omitted from the list presented with each function.  
+
+The admin system guarantees that a function that returns an error code
+has no other side effect.
+
+The Admin system will use \v{com_err} for error codes.  Note that this
+means \v{com_err} codes may be returned from functions that the admin
+routines call (e.g. the kerberos library). Callers should not expect
+that only KADM5 errors will be returned.  The Admin system error code
+table name will be ``ovk'', and the offsets will be the same as the
+order presented here. As mentioned above, the error table include file
+will be $<$kadm5/kadm_err.h$>$.
+
+Note that these error codes are also used as protocol error code
+constants and therefore must not change between product releases.
+Additional codes should be added at the end of the list, not in the
+middle.  The integer value of KADM5_FAILURE is 43787520; the
+remaining values are assigned in sequentially increasing order.
+
+\begin{description}
+\item[* KADM5_FAILURE] Operation failed for unspecified reason
+\item[* KADM5_AUTH_GET] Operation requires ``get'' privilege
+\item[* KADM5_AUTH_ADD] Operation requires ``add'' privilege
+\item[* KADM5_AUTH_MODIFY] Operation requires ``modify'' privilege
+\item[* KADM5_AUTH_DELETE] Operation requires ``delete'' privilege
+\item[* KADM5_AUTH_INSUFFICIENT] Insufficient authorization for
+operation
+\item[* KADM5_BAD_DB] Database inconsistency detected
+\item[KADM5_DUP] Principal or policy already exists
+\item[KADM5_RPC_ERROR] Communication failure with server
+\item[KADM5_NO_SRV] No administration server found for realm
+\item[KADM5_BAD_HIST_KEY] Password history principal key version
+mismatch
+\item[KADM5_NOT_INIT] Connection to server not initialized
+\item[KADM5_UNK_PRINC]  Principal does not exist
+\item[KADM5_UNK_POLICY] Policy does not exist
+\item[KADM5_BAD_MASK] Invalid field mask for operation
+\item[KADM5_BAD_CLASS] Invalid number of character classes
+\item[KADM5_BAD_LENGTH] Invalid password length
+\item[KADM5_BAD_POLICY] Illegal policy name
+\item[KADM5_BAD_PRINCIPAL] Illegal principal name.
+\item[KADM5_BAD_AUX_ATTR] Invalid auxillary attributes
+\item[KADM5_BAD_HISTORY] Invalid password history count
+\item[KADM5_BAD_MIN_PASS_LIFE] Password minimum life is greater
+then password maximum life
+\item[KADM5_PASS_Q_TOOSHORT] Password is too short
+\item[KADM5_PASS_Q_CLASS] Password does not contain enough
+character classes
+\item[KADM5_PASS_Q_DICT] Password is in the password dictionary
+\item[KADM5_PASS_REUSE] Cannot resuse password
+\item[KADM5_PASS_TOOSOON] Current password's minimum life has not
+expired
+\item[KADM5_POLICY_REF] Policy is in use
+\item[KADM5_INIT] Connection to server already initialized
+\item[KADM5_BAD_PASSWORD] Incorrect password
+\item[KADM5_PROTECT_PRINCIPAL] Cannot change protected principal
+\item[* KADM5_BAD_SERVER_HANDLE] Programmer error!  Bad Admin server handle
+\item[* KADM5_BAD_STRUCT_VERSION] Programmer error!  Bad API structure version
+\item[* KADM5_OLD_STRUCT_VERSION] API structure version specified by application is no longer supported (to fix, recompile application against current Admin API header files and libraries)
+\item[* KADM5_NEW_STRUCT_VERSION] API structure version specified by application is unknown to libraries (to fix, obtain current Admin API header files and libraries and recompile application)
+\item[* KADM5_BAD_API_VERSION] Programmer error!  Bad API version
+\item[* KADM5_OLD_LIB_API_VERSION] API version specified by application is no longer supported by libraries (to fix, update application to adhere to current API version and recompile)
+\item[* KADM5_OLD_SERVER_API_VERSION] API version specified by application is no longer supported by server (to fix, update application to adhere to current API version and recompile)
+\item[* KADM5_NEW_LIB_API_VERSION] API version specified by application is unknown to libraries (to fix, obtain current Admin API header files and libraries and recompile application)
+\item[* KADM5_NEW_SERVER_API_VERSION] API version specified by
+application is unknown to server (to fix, obtain and install newest
+Admin Server)
+\item[KADM5_SECURE_PRINC_MISSING] Database error! Required principal missing
+\item[KADM5_NO_RENAME_SALT] The salt type of the specified principal
+does not support renaming
+\item[KADM5_BAD_CLIENT_PARAMS] Illegal configuration parameter for
+remote KADM5 client
+\item[KADM5_BAD_SERVER_PARAMS] Illegal configuration parameter for
+local KADM5 client.
+\item[KADM5_AUTH_LIST] Operation requires ``list'' privilege
+\item[KADM5_AUTH_CHANGEPW] Operation requires ``change-password'' privilege
+\item[KADM5_BAD_TL_TYPE] Programmer error!  Illegal tagged data list
+element type
+\item[KADM5_MISSING_CONF_PARAMS] Required parameters in kdc.conf missing
+\item[KADM5_BAD_SERVER_NAME] Bad krb5 admin server hostname
+\item[KADM5_AUTH_SETKEY] Operation requires ``set-key'' privilege
+\item[KADM5_SETKEY_DUP_ENCTYPES] Multiple values for single or folded enctype
+\end{description}
+
+\section{Authentication and Authorization}
+\label{sec:auth}
+
+Two Kerberos principals exist for use in communicating with the Admin
+system: kadmin/admin and kadmin/changepw.  Both principals
+have the KRB5_KDB_DISALLOW_TGT_BASED bit set in their attributes so
+that service tickets for them can only be acquired via a
+password-based (AS_REQ) request.  Additionally, kadmin/changepw
+has the KRB5_KDB_PWCHANGE_SERVICE bit set so that a principal with an
+expired password can still obtain a service ticket for it.
+
+The Admin system accepts requests that are authenticated to either
+service principal, but the sets of operations that can be performed by
+a request authenticated to each service are different.  In particular,
+only the functions chpass_principal, randkey_principal, get_principal,
+and get_policy can be performed by a request authenticated to the
+kadmin/changepw service, and they can only be performed when the
+target principal of the operation is the same as the authenticated
+client principal; the function semantics descriptions below give the
+precise details.  This means that administrative operations can only
+be performed when authenticated to the kadmin/admin service.  The
+reason for this distinction is that tickets for kadmin/changepw can be
+acquired with an expired password, and the KADM system does not want
+to allow an administrator with an expired password to perform
+administrative operations on arbitrary principals.
+
+Each Admin API operation authenticated to the kadmin/admin service
+requires a specific authorization to run.  This version uses a simple
+named privilege system with the following names and meanings:
+
+\begin{description}
+\item[Get] Able to examine the attributes (NOT key data) of principals
+and policies. 
+\item[Add] Able to add principals and policies.
+\item[Modify] Able to modify attributes of existing principals and
+policies; this does not include changing passwords.
+\item[Delete] Able to remove principals and policies.
+\item[List] Able to retrieve a list of principals and policies.
+\item[Changepw] Able to change the password of principals.
+\item[Setkey] Able to set principal keys directly.
+\end{description}
+
+Privileges are specified via an external configuration file on the
+Kerberos master server.
+
+Table \ref{tab:func-overview} summarizes the authorization
+requirements of each function.  Additionally, each API function
+description identifies the privilege required to perform it.  The
+Authorization checks only happen if you are using the RPC mechanism.
+If you are using the server-side API functions locally on the admin
+server, the only authorization check is if you can access the
+approporiate local files.
+
+\section{Functions}
+
+\subsection{Overview}
+
+The functions provided by the Admin API, and the authorization they
+require, are listed in the table \ref{tab:func-overview}.  The
+``kadm5_'' prefix has been removed from each function name.
+
+The function semantics in the following sections omit details that are
+the same for every function.
+
+\begin{itemize}
+\item The effects of every function are atomic.
+
+\item Every function performs an authorization check and returns
+the appropriate KADM5_AUTH_* error code if the caller does not
+have the required privilege.  No other information or error code is
+ever returned to an unauthorized user.
+
+\item Every function checks its arguments for NULL pointers or other
+obviously invalid values, and returns EINVAL if any are detected.
+
+\item Any function that performs a policy check uses the policy named
+in the principal's policy field.  If the POLICY bit is not set in the
+principal's aux_attributes field, however, the principal has no
+policy, so the policy check is not performed.
+
+\item Unless otherwise specified, all functions return KADM5_OK.
+\end{itemize}
+
+\begin{table}[htbp]
+\caption{Summary of functions and required authorization.}
+\label{tab:func-overview}
+\begin{tabular}{@{}llp{3.24in}}
+\\
+{\bf Function Name} & {\bf Authorization} & {\bf Operation} \\
+
+init & none & Open a connection with the kadm5 library.  OBSOLETE
+but still provided---use init_with_password instead. \\
+init_with_password & none & Open a connection with the kadm5
+library using a password to obtain initial credentials. \\
+init_with_skey & none & Open a connection with the kadm5 library
+using the keytab entry to obtain initial credentials. \\
+destroy & none & Close the connection with the kadm5 library. \\
+flush & none & Flush all database changes to disk; no-op when called
+remotely. \\
+create_principal & add & Create a new principal. \\
+delete_principal & delete & Delete a principal. \\
+modify_principal & modify & Modify the attributes of an existing
+        principal (not password). \\
+rename_principal & add and delete & Rename a principal. \\
+get_principal & get\footnotemark & Retrieve a principal. \\
+get_principals & list & Retrieve some or all principal names. \\
+chpass_principal & changepw\footnotemark[\thefootnote] &
+         Change a principal's password. \\
+chpass_principal_util & changepw\footnotemark[\thefootnote] & Utility wrapper around chpass_principal. \\
+randkey_principal & changepw\footnotemark[\thefootnote] &
+        Randomize a principal's key. \\
+setkey_principal & setkey & Explicitly set a principal's keys. \\
+decrypt_key & none & Decrypt a principal key. \\
+create_policy & add & Create a new policy. \\
+delete_policy & delete & Delete a policy. \\
+modify_policy & modify & Modify the attributes of a policy. \\
+get_policy & get & Retrieve a policy. \\
+get_policies & list & Retrieve some or all policy names. \\
+free_principal_ent & none & Free the memory associated with an
+                kadm5_principal_ent_t. \\
+free_policy_ent & none & Free the memory associated with an
+                kadm5_policy_ent_t. \\
+get_privs & none & Return the caller's admin server privileges.
+\end{tabular}
+\end{table}
+\footnotetext[\thefootnote]{These functions also allow a principal to
+perform the operation on itself; see the function's semantics for
+details.}
+
+\subsection{kadm5_init_*}
+
+In KADM5_API_VERSION 1:
+
+\begin{verbatim}
+kadm5_ret_t kadm5_init_with_password(char *client_name, char *pass,
+                                 char *service_name, char *realm,
+                                 unsigned long struct_version,
+                                 unsigned long api_version,
+                                 void **server_handle)
+
+kadm5_ret_t kadm5_init_with_skey(char *client_name, char *keytab,
+                                 char *service_name, char *realm,
+                                 unsigned long struct_version,
+                                 unsigned long api_version,
+                                 void **server_handle)
+
+kadm5_ret_t kadm5_init(char *client_name, char *pass,
+                                 char *service_name, char *realm,
+                                 unsigned long struct_version,
+                                 unsigned long api_version,
+                                 void **server_handle)
+\end{verbatim}
+
+In KADM5_API_VERSION 2:
+
+\begin{verbatim}
+kadm5_ret_t kadm5_init_with_password(char *client_name, char *pass,
+                                 char *service_name,
+                                 kadm5_config_params *realm_params,
+                                 unsigned long struct_version,
+                                 unsigned long api_version,
+                                 void **server_handle)
+
+kadm5_ret_t kadm5_init_with_skey(char *client_name, char *keytab,
+                                 char *service_name,
+                                 kadm5_config_params *realm_params,
+                                 unsigned long struct_version,
+                                 unsigned long api_version,
+                                 void **server_handle)
+
+kadm5_ret_t kadm5_init(char *client_name, char *pass,
+                                 char *service_name,
+                                 kadm5_config_params *realm_params,
+                                 unsigned long struct_version,
+                                 unsigned long api_version,
+                                 void **server_handle)
+
+kadm5_ret_t kadm5_init_with_creds(char *client_name,
+                                  krb5_ccache ccache,
+                                  char *service_name,
+                                  kadm5_config_params *params,
+                                  krb5_ui_4 struct_version,
+                                  krb5_ui_4 api_version,
+                                  void **server_handle)
+\end{verbatim}
+
+AUTHORIZATION REQUIRED: none
+
+NOTE: kadm5_init is an obsolete function provided for backwards
+compatibility.  It is identical to kadm5_init_with_password.
+
+These three functions open a connection to the kadm5 library and
+initialize any neccessary state information.  They behave differently
+when called from local and remote clients.  
+
+In KADM5_API_VERSION_2, these functions take a kadm5_config_params
+structure instead of a realm name as an argument.  The semantics are
+similar: if a NULL pointer is passed for the realm_params argument,
+the default realm and default parameters for that realm, as specified
+in the krb5 configuration file (e.g. /etc/krb5.conf) are used.  If a
+realm_params structure is provided, the fields that are set override
+the default values.  If a parameter is specified to the local or
+remote libraries that does not apply to that side, an error code
+(KADM5_BAD_CLIENT_PARAMS or KADM5_BAD_SERVER_PARAMS) is returned.  See
+section \ref{sec:configparams} for a discussion of configuration
+parameters.
+
+For remote clients, the semantics are:
+
+\begin{enumerate}
+\item Initializes all the com_err error tables used by the Admin
+system.
+
+\item Acquires configuration parameters.  In KADM5_API_VERSION_1, all
+the defaults specified in the configuration file are used, according
+to the realm.  In KADM5_API_VERSION_2, the values in params_in are
+merged with the default values.  If an illegal mask value is
+specified, KADM5_BAD_CLIENT_PARAMS is returned.
+
+\item Acquires a Kerberos ticket for the specified service.
+
+\begin{enumerate}
+\item The ticket's client is client_name, which can be any valid
+Kerberos principal.  If client_name does not include a realm, the
+default realm of the local host is used
+\item The ticket's service is service_name@realm.  service_name must
+be one of the constants KADM5_ADMIN_SERVICE or
+KADM5_CHANGEPW_SERVICE.
+\item If realm is NULL, client_name's realm is used.
+
+\item For init_with_password, an initial ticket is acquired and
+decoded with the password pass, which must be client_name's password.
+If pass is NULL or an empty string, the user is prompted (via the tty)
+for a password.
+
+\item For init_with_skey, an initial ticket is acquired and decoded
+with client_name's key obtained from the specified keytab.  If keytab
+is NULL or an empty string the default keytab is used.
+
+\item For init_with_creds, ccache must be an open credential cache
+that already has a ticket for the specified client and server.
+Alternatively, if a site chooses to disable the DISALLOW_TGT_BASED
+flag on the admin and changepw principals, the ccache can contain a
+ticket-granting ticket for client_name.
+\end{enumerate}
+
+\item Creates a GSS-API authenticated connection to the Admin server,
+using the just-acquired Kerberos ticket.
+
+\item Verifies that the struct_version and api_version specified by
+the caller are valid and known to the library.
+
+\item Sends the specified api_version to the server.
+
+\item Upon successful completion, fills in server_handle with a handle
+for this connection, to be used in all subsequent API calls.
+\end{enumerate}
+
+The caller should always specify KADM5_STRUCT_VERSION for the
+struct_version argument, a valid and supported API version constant
+for the api_version argument (currently, KADM5_API_VERSION_1 or
+KADM5_API_VERSION_2), and a valid pointer in which the server handle
+will be stored.
+
+If any kadm5_init_* is invoked locally its semantics are:
+
+\begin{enumerate}
+\item Initializes all the com_err error tables used by the Admin
+system.
+
+\item Acquires configuration parameters.  In KADM5_API_VERSION_1, all
+the defaults specified in the configuration file are used, according
+to the realm.  In KADM5_API_VERSION_2, the values in params_in are
+merged with the default values.  If an illegal mask value is
+specified, KADM5_BAD_SERVER_PARAMS is returned.
+
+\item Initializes direct access to the KDC database.  In
+KADM5_API_VERISON_1, if pass (or keytab) is NULL or an empty string,
+reads the master password from the stash file; otherwise, the non-NULL
+password is ignored and the user is prompted for it via the tty.  In
+KADM5_API_VERSION_2, if the MKEY_FROM_KEYBOARD parameter mask is set
+and the value is non-zero, reads the master password from the user via
+the tty; otherwise, the master key is read from the stash file.
+Calling init_with_skey or init_with_creds with the MKEY_FROM_KEYBOARD
+mask set with a non-zero field is illegal, and calling them without
+the mask set is exactly like calling init_with_password.
+
+\item Initializes the dictionary (if present) for dictionary checks.
+
+\item Parses client_name as a Kerberos principal.  client_name should
+usually be specified as the name of the program.
+
+\item Verifies that the struct_version and api_version specified by
+the caller are valid.
+
+\item Fills in server_handle with a handle containing all state
+information (version numbers and client name) for this ``connection.''
+\end{enumerate}
+The service_name argument is not used.
+
+RETURN CODES: 
+
+\begin{description}
+\item[KADM5_NO_SRV] No Admin server can be found for the
+specified realm.
+
+\item[KADM5_RPC_ERROR] The RPC connection to the server cannot be
+initiated.
+
+\item[KADM5_BAD_PASSWORD] Incorrect password.
+
+\item[KADM5_SECURE_PRINC_MISSING] The principal
+KADM5_ADMIN_SERVICE or KADM5_CHANGEPW_SERVICE does not
+exist.  This is a special-case replacement return code for ``Server
+not found in database'' for these required principals.
+
+\item[KADM5_BAD_CLIENT_PARAMS] A field in the parameters mask was
+specified to the remote client library that is not legal for remote
+clients.
+
+\item[KADM5_BAD_SERVER_PARAMS] A field in the parameters mask was
+specified to the local client library that is not legal for local
+clients.
+\end{description}
+
+\subsection{kadm5_flush}
+
+\begin{verbatim}
+kadm5_ret_t kadm5_flush(void *server_handle)
+\end{verbatim}
+
+AUTHORIZATION REQUIRED: none
+
+Flush all changes to the Kerberos databases, leaving the connection to
+the Admin API open.  This function behaves differently when called by
+local and remote clients.
+
+For local clients, the function closes and reopens the Kerberos
+database with krb5_db_fini() and krb5_db_init().
+Although it is unlikely, either of these functions
+could return errors; in that case, this function calls
+kadm5_destroy and returns the error code.  Therefore, if
+kadm5_flush does not return KADM5_OK, the connection to the
+Admin server has been terminated and, in principle, the databases
+might be corrupt.
+
+For remote clients, the function is a no-op.
+
+\subsection{kadm5_destroy}
+
+\begin{verbatim}
+kadm5_ret_t kadm5_destroy(void *server_handle)
+\end{verbatim}
+
+AUTHORIZATION REQUIRED: none
+
+Close the connection to the Admin server and releases all related
+resources.  This function behaves differently when called by local and
+remote clients.
+
+For remote clients, the semantics are:
+
+\begin{enumerate}
+\item Destroy the temporary credential cache created by
+kadm5_init.
+
+\item Tear down the GSS-API context negotiated with the server.
+
+\item Close the RPC connection.
+
+\item Free storage space associated with server_handle, after erasing
+its magic number so it won't be mistaken for a valid handle by the
+library later.
+\end{enumerate}
+
+For local clients, this function just frees the storage space
+associated with server_handle after erasing its magic number.
+
+RETURN CODES:
+
+\subsection{kadm5_create_principal}
+
+\begin{verbatim}
+kadm5_ret_t
+kadm5_create_principal(void *server_handle,
+                            kadm5_principal_ent_t princ, u_int32 mask,
+                            char *pw);
+\end{verbatim}
+
+AUTHORIZATION REQUIRED: add
+
+\begin{enumerate}
+
+\item Return KADM5_BAD_MASK if the mask is invalid.
+\item If the named principal exists, return KADM5_DUP.
+\item If the POLICY bit is set and the named policy does not exist,
+return KADM5_UNK_POLICY.
+\item If KADM5_POLICY bit is set in aux_attributes check to see if
+the password does not meets quality standards, return the appropriate
+KADM5_PASS_Q_* error code if it fails.
+\item Store the principal, set the key; see section \ref{sec:keys}.
+\item If the POLICY bit is set, increment the named policy's reference
+count by one.
+
+\item Set the pw_expiration field.
+\begin{enumerate}
+\item If the POLICY bit is set in mask, then if pw_max_life is non-zero,
+set pw_expiration to now + pw_maxlife, otherwise set pw_max_life to
+never.
+\item If the PW_EXPIRATION bit is set in mask, set pw_expiration to
+the requested value, overriding the value set above.
+\end{enumerate}
+NOTE: This is a change from the original semantics, in which policy
+expiration was enforced even on administrators.  The old semantics are
+not preserved, even for version 1 callers, because this is a
+server-specific policy decision; besides, the new semantics are less
+restrictive, so all previous callers should continue to function
+properly.
+
+\item Set mod_date to now and set mod_name to caller.
+\item Set last_pwd_change to now.
+\end{enumerate}
+
+RETURN CODES:
+
+\begin{description}
+\item[KADM5_BAD_MASK] The field mask is invalid for a create
+operation.
+\item[KADM5_DUP] Principal already exists.
+\item[KADM5_UNK_POLICY] Policy named in entry does not exist.
+\item[KADM5_PASS_Q_*] Specified password does not meet policy
+standards.
+\end{description}
+
+\subsection{kadm5_delete_principal}
+
+\begin{verbatim}
+kadm5_ret_t
+kadm5_delete_principal(void *server_handle, krb5_principal princ);
+\end{verbatim}
+
+AUTHORIZATION REQUIRED: delete 
+
+\begin{enumerate}
+\item Return KADM5_UNK_PRINC if the principal does not exist.
+\item If the POLICY bit is set in aux_attributes, decrement the named
+policy's reference count by one.
+\item Delete principal.
+\end{enumerate}
+
+RETURN CODES: 
+
+\begin{description}
+\item[KADM5_UNK_PRINC] Principal does not exist.
+\end{description}
+
+\subsection{kadm5_modify_principal}
+
+\begin{verbatim}
+kadm5_ret_t
+kadm5_modify_principal(void *server_handle,
+                            kadm5_principal_ent_t princ, u_int32 mask);
+\end{verbatim}
+
+Modify the attributes of the principal named in
+kadm5_principal_ent_t. This does not allow the principal to be
+renamed or for its password to be changed.
+
+AUTHORIZATION REQUIRED: modify
+
+Although a principal's pw_expiration is usually computed based on its
+policy and the time at which it changes its password, this function
+also allows it to be specified explicitly.  This allows an
+administrator, for example, to create a principal and assign it to a
+policy with a pw_max_life of one month, but to declare that the new
+principal must change its password away from its initial value
+sometime within the first week.
+
+\begin{enumerate}
+\item Return KADM5_UNK_PRINC if the principal does not exist.
+\item Return KADM5_BAD_MASK if the mask is invalid.
+\item If POLICY bit is set but the new policy does not exist, return
+KADM5_UNK_POLICY.
+\item If either the POLICY or POLICY_CLR bits are set, update the
+corresponding bits in aux_attributes.
+
+\item Update policy reference counts.
+\begin{enumerate}
+\item If the POLICY bit is set, then increment policy count on new
+policy.
+\item If the POLICY or POLICY_CLR bit is set, and the POLICY bit in
+aux_attributes is set, decrement policy count on old policy.
+\end{enumerate}
+
+\item Set pw_expiration appropriately.  pw_expiration can change if:
+the POLICY bit is set in mask, so the principal is changing to a
+policy (either from another policy or no policy); the POLICY_CLR bit
+is set in mask, so the principal is changing to no policy; or
+PW_EXPIRATION is set.
+\begin{enumerate}
+\item If the POLICY bit is set in mask, set pw_expiration to
+last_pwd_change + pw_max_life if pw_max_life is non-zero, otherwise
+set pw_expiration to never.
+\item If the POLICY_CLR biti s set in mask, set pw_expiration to
+never.
+\item If PW_EXPIRATION is set, set pw_expiration to the requested
+value, overriding the value from the previous two cases.  NOTE: This
+is a change from the original semantics, in which policy expiration
+was enforced even on administrators.  The old semantics are not
+preserved, even for version 1 callers, because this is a
+server-specific policy decision; besides, the new semantics are less
+restrictive, so all previous callers should continue to function
+properly.
+\end{enumerate}
+
+% Here is the previous, and confusing, text of pw_expiration semantics:
+%\begin{enumerate}
+%\item If the POLICY bit is not set in aux_attributes, then
+%\begin{enumerate}
+%\item if the PW_EXPIRATION bit is set, set pw_expiration to the given
+%value, else
+%\item set pw_expiration to never.
+%\end{enumerate}
+%\item Otherwise, if the PW_EXPIRATION bit is set, set pw_expiration to
+%the sooner of the given value and last_pwd_change + pw_max_life.
+%\item Otherwise, set pw_expiration to last_pwd_change + pw_max_life.
+%\end{enumerate}
+
+\item Update the remaining fields specified in the mask.
+\item Update mod_name field to caller and mod_date to now.
+\end{enumerate}
+
+RETURN CODES:
+
+\begin{description}
+\item[KADM5_UNK_PRINC] Entry does not exist.
+\item[KADM5_BAD_MASK] The mask is not valid for a modify
+operation.
+\item[KADM5_UNK_POLICY] The POLICY bit is set but the new
+policy does not exist.
+\item[KADM5_BAD_TL_TYPE] The KADM5_TL_DATA bit is set in mask, and the
+given tl_data list contains an element whose type is less than 256.
+\end{description}
+
+\subsection{kadm5_rename_principal}
+
+\begin{verbatim}
+kadm5_ret_t
+kadm5_rename_principal(void *server_handle, krb5_principal source,
+                            krb5_principal target);
+\end{verbatim}
+
+AUTHORIZATION REQUIRED: add and delete
+
+\begin{enumerate}
+\item Check to see if source principal exists, if not return
+KADM5_UNK_PRINC error. 
+\item Check to see if target exists, if so return KADM5_DUP error.
+\item Create the new principal named target, then delete the old
+principal named source.  All of target's fields will be the same as
+source's fields, except that mod_name and mod_date will be updated to
+reflect the current caller and time.
+\end{enumerate}
+
+Note that since the principal name may have been used as the salt for
+the principal's key, renaming the principal may render the principal's
+current password useless; with the new salt, the key generated by
+string-to-key on the password will suddenly be different.  Therefore,
+an application that renames a principal must also require the user to
+specify a new password for the principal (and administrators should
+notify the affected party).
+
+Note also that, by the same argument, renaming a principal will
+invalidate that principal's password history information; since the
+salt will be different, a user will be able to select a previous
+password without error.
+
+RETURN CODES: 
+
+\begin{description}
+\item[KADM5_UNK_PRINC] Source principal does not exist.
+\item[KADM5_DUP] Target principal already exist.
+\end{description}
+
+\subsection{kadm5_chpass_principal}
+
+\begin{verbatim}
+kadm5_ret_t
+kadm5_chpass_principal(void *server_handle, krb5_principal princ,
+                            char *pw);
+\end{verbatim}
+
+AUTHORIZATION REQUIRED: changepw, or the calling principal being the
+same as the princ argument.  If the request is authenticated to the
+kadmin/changepw service, the changepw privilege is disregarded.
+
+Change a principal's password.   See section \ref{sec:keys} for a
+description of how the keys are determined.
+
+This function enforces password policy and dictionary checks.  If the new
+password specified is in the password dictionary, and the policy bit is set
+KADM5_PASS_DICT is returned.  If the principal's POLICY bit is set in
+aux_attributes, compliance with each of the named policy fields is verified
+and an appropriate error code is returned if verification fails.
+
+Note that the policy checks are only be performed if the POLICY bit is
+set in the principal's aux_attributes field.
+
+\begin{enumerate}
+\item Make sure principal exists, if not return KADM5_UNK_PRINC error.
+\item If caller does not have modify privilege, (now - last_pwd_change) $<$
+pw_min_life, and the KRB5_KDB_REQUIRES_PWCHANGE bit is not set in the
+principal's attributes, return KADM5_PASS_TOOSOON.
+\item If the principal your are trying to change is kadmin/history
+return KADM5_PROTECT_PRINCIPAL.
+\item If the password does not meet the quality
+standards, return the appropriate KADM5_PASS_Q_* error code.
+\item Convert password to key; see section \ref{sec:keys}.
+\item If the new key is in the principal's password history, return
+KADM5_PASS_REUSE.
+\item Store old key in history.
+\item Update principal to have new key.
+\item Increment principal's key version number by one.
+\item If the POLICY bit is set, set pw_expiration to now +
+max_pw_life.  If the POLICY bit is not set, set pw_expiration to
+never.
+\item If the KRB5_KDB_REQUIRES_PWCHANGE bit is set in the principal's
+attributes, clear it.
+\item Update last_pwd_change and mod_date to now, update mod_name to
+caller.
+\end{enumerate}
+
+RETURN CODES:
+
+\begin{description}
+\item[KADM5_UNK_PRINC] Principal does not exist.
+\item[KADM5_PASS_Q_*] Requested password does not meet quality
+standards. 
+\item[KADM5_PASS_REUSE] Requested password is in user's
+password history. 
+\item[KADM5_PASS_TOOSOON] Current password has not reached minimum life
+\item[KADM5_PROTECT_PRINCIPAL] Cannot change the password of a special principal
+\end{description}
+
+
+\subsection{kadm5_chpass_principal_util}
+
+\begin{verbatim}
+kadm5_ret_t
+kadm5_chpass_principal_util(void *server_handle, krb5_principal princ,
+                                 char *new_pw, char **pw_ret,
+                                 char *msg_ret);
+\end{verbatim}
+
+AUTHORIZATION REQUIRED: changepw, or the calling principal being the
+same as the princ argument.  If the request is authenticated to the
+kadmin/changepw service, the changepw privilege is disregarded.
+
+This function is a wrapper around kadm5_chpass_principal. It can
+read a new password from a user, change a principal's password, and
+return detailed error messages.  msg_ret should point to a char buffer
+in the caller's space of sufficient length for the error messages
+described below. 1024 bytes is recommended.  It will also return the
+new password to the caller if pw_ret is non-NULL.
+
+\begin{enumerate}
+\item If new_pw is NULL, this routine will prompt the user for the new
+password (using the strings specified by KADM5_PW_FIRST_PROMPT and
+KADM5_PW_SECOND_PROMPT) and read (without echoing) the password input.
+Since it is likely that this will simply call krb5_read_password only
+terminal-based applications will make use of the password reading
+functionality. If the passwords don't match the string ``New passwords do
+not match - password not changed.'' will be copied into msg_ret, and the
+error code KRB5_LIBOS_BADPWDMATCH will be returned.  For other errors that
+ocurr while reading the new password, copy the string ``<com_err message$>$
+occurred while trying to read new password.'' followed by a blank line and
+the string specified by CHPASS_UTIL_PASSWORD_NOT_CHANGED into msg_ret and
+return the error code returned by krb5_read_password.
+
+\item If pw_ret is non-NULL, and the password was prompted, set *pw_ret to
+point to a static buffer containing the password.  If pw_ret is non-NULL
+and the password was supplied, set *pw_ret to the supplied password.
+
+\item Call kadm5_chpass_principal with princ, and new_pw.
+
+\item If successful copy the string specified by CHPASS_UTIL_PASSWORD_CHANGED
+into msg_ret and return zero.
+
+\item For a policy related failure copy the appropriate message (from below) 
+followed by a newline and ``Password not changed.'' into msg_ret
+filling in the parameters from the principal's policy information. If
+the policy information cannot be obtained copy the generic message if
+one is specified below. Return the error code from
+kadm5_chpass_principal.
+
+Detailed messages:
+\begin{description}
+
+\item[PASS_Q_TOO_SHORT]
+New password is too short. Please choose a
+password which is more than $<$pw-min-len$>$ characters.
+
+\item[PASS_Q_TOO_SHORT - generic]
+New password is too short. Please choose a longer password.
+
+\item[PASS_REUSE]
+New password was used previously. Please choose a
+different password.
+
+\item[PASS_Q_CLASS]
+New password does not have enough character classes. Classes include
+lower class letters, upper case letters, digits, punctuation and all
+other characters.  Please choose a password with at least
+$<$min-classes$>$ character classes.
+
+\item[PASS_Q_CLASS - generic]
+New password does not have enough character classes. Classes include
+lower class letters, upper case letters, digits, punctuation and all
+other characters. 
+
+\item[PASS_Q_DICT] 
+New password was found in a dictionary of possible passwords and
+therefore may be easily guessed.  Please choose another password. See
+the kpasswd man page for help in choosing a good password.
+
+\item[PASS_TOOSOON]
+Password cannot be changed because it was changed too recently. Please
+wait until $<$last-pw-change+pw-min-life$>$ before you change it. If you
+need to change your password before then, contact your system
+security administrator.
+
+\item[PASS_TOOSOON - generic]
+Password cannot be changed because it was changed too recently. If you
+need to change your now please contact your system security
+administrator.
+\end{description}
+
+\item For other errors copy the string ``$<$com_err message$>$
+occurred while trying to change password.'' following by a blank line
+and ``Password not changed.'' into msg_ret. Return the error code
+returned by kadm5_chpass_principal.
+\end{enumerate}
+
+
+RETURN CODES:
+
+\begin{description}
+\item[KRB5_LIBOS_BADPWDMATCH] Typed new passwords did not match.
+\item[KADM5_UNK_PRINC] Principal does not exist.
+\item[KADM5_PASS_Q_*] Requested password does not meet quality
+standards. 
+\item[KADM5_PASS_REUSE] Requested password is in user's
+password history. 
+\item[KADM5_PASS_TOOSOON] Current password has not reached minimum
+life. 
+\end{description}
+
+\subsection{kadm5_randkey_principal}
+
+In KADM5_API_VERSION_1:
+
+\begin{verbatim}
+kadm5_ret_t
+kadm5_randkey_principal(void *server_handle, krb5_principal princ,
+                             krb5_keyblock **new_key)
+\end{verbatim}
+
+In KADM5_API_VERSION_2:
+
+\begin{verbatim}
+kadm5_ret_t
+kadm5_randkey_principal(void *server_handle, krb5_principal princ,
+                        krb5_keyblock **new_keys, int *n_keys)
+\end{verbatim}
+
+AUTHORIZATION REQUIRED: changepw, or the calling principal being the
+same as the princ argument.  If the request is authenticated to the
+kadmin/changepw service, the changepw privilege is disregarded.
+
+Generate and assign a new random key to the named principal, and
+return the generated key in allocated storage.  In
+KADM5_API_VERSION_2, multiple keys may be generated and returned as an
+array, and n_new_keys is filled in with the number of keys generated.
+See section \ref{sec:keys} for a description of how the keys are
+chosen.  In KADM5_API_VERSION_1, the caller must free the returned
+krb5_keyblock * with krb5_free_keyblock.  In KADM5_API_VERSION_2, the
+caller must free each returned keyblock with krb5_free_keyblock.
+
+If the principal's POLICY bit is set in aux_attributes and the caller does
+not have modify privilege , compliance with the password minimum life
+specified by the policy is verified and an appropriate error code is returned
+if verification fails. 
+
+\begin{enumerate}
+\item If the principal does not exist, return KADM5_UNK_PRINC.
+\item If caller does not have modify privilege, (now - last_pwd_change) $<$
+pw_min_life, and the KRB5_KDB_REQUIRES_PWCHANGE bit is not set in the
+principal's attributes, return KADM5_PASS_TOOSOON.
+\item If the principal you are trying to change is kadmin/history return
+KADM5_PROTECT_PRINCIPAL.
+\item Store old key in history.
+\item Update principal to have new key.
+\item Increment principal's key version number by one.
+\item If the POLICY bit in aux_attributes is set, set pw_expiration to
+now + max_pw_life.
+\item If the KRB5_KDC_REQUIRES_PWCHANGE bit is set in the principal's
+attributes, clear it.
+\item Update last_pwd_change and mod_date to now, update mod_name to
+caller.
+\end{enumerate}
+
+RETURN CODES:
+
+\begin{description}
+\item[KADM5_UNK_PRINC] Principal does not exist.
+\item[KADM5_PASS_TOOSOON] The minimum lifetime for the current
+key has not expired.
+\item[KADM5_PROTECT_PRINCIPAL] Cannot change the password of a special
+principal
+\end{description}
+
+This function can also be used as part of a sequence to create a new
+principal with a random key.  The steps to perform the operation
+securely are
+
+\begin{enumerate}
+\item Create the principal with kadm5_create_principal with a
+random password string and with the KRB5_KDB_DISALLOW_ALL_TIX bit set
+in the attributes field.
+
+\item Randomize the principal's key with kadm5_randkey_principal.
+
+\item Call kadm5_modify_principal to reset the
+KRB5_KDB_DISALLOW_ALL_TIX bit in the attributes field.
+\end{enumerate}
+
+The three steps are necessary to ensure secure creation.  Since an
+attacker might be able to guess the initial password assigned by the
+client program, the principal must be disabled until the key can be
+truly randomized.
+
+\subsection{kadm5_setkey_principal}
+
+\begin{verbatim}
+kadm5_ret_t
+kadm5_setkey_principal(void *server_handle, krb5_principal princ,
+                       krb5_keyblock *new_keys, int n_keys)
+\end{verbatim}
+
+AUTHORIZATION REQUIRED: setkey.  This function does not allow the use
+of regular changepw authorization because it bypasses the password
+policy mechanism.
+
+This function only exists in KADM5_API_VERSION_2.
+
+Explicitly sets the specified principal's keys to the n_keys keys in
+the new_keys array.  The keys in new_keys should not be encrypted in
+the Kerberos master key; this function will perform that operation
+itself (the keys will be protected during transmission from the
+calling client to the kadmind server by the AUTH_GSSAPI RPC layer).
+This function completely bypasses the principal's password policy, if
+set.
+
+\begin{enumerate}
+\item If the principal does not exist, return KADM5_UNK_PRINC.
+\item If the principal you are trying to change is kadmin/history return
+KADM5_PROTECT_PRINCIPAL.
+\item If new_keys contains more than one key of any ENCTYPE_DES_CBC_*
+type that is folded, return KADM5_SETKEY_DUP_ENCTYPES.
+\item Store old key in history.
+\item Update principal to have new key.
+\item Increment principal's key version number by one.
+\item If the POLICY bit in aux_attributes is set, set pw_expiration to
+now + max_pw_life.
+\item If the KRB5_KDC_REQUIRES_PWCHANGE bit is set in the principal's
+attributes, clear it.
+\item Update last_pwd_change and mod_date to now, update mod_name to
+caller.
+\end{enumerate}
+
+RETURN CODES:
+
+\begin{description}
+\item[KADM5_UNK_PRINC] Principal does not exist.
+\item[KADM5_PROTECT_PRINCIPAL] Cannot change the password of a special
+principal
+\end{description}
+
+This function can also be used as part of a sequence to create a new
+principal with an explicitly key.  The steps to perform the operation
+securely are
+
+\begin{enumerate}
+\item Create the principal with kadm5_create_principal with a
+random password string and with the KRB5_KDB_DISALLOW_ALL_TIX bit set
+in the attributes field.
+
+\item Set the principal's key with kadm5_setkey_principal.
+
+\item Call kadm5_modify_principal to reset the
+KRB5_KDB_DISALLOW_ALL_TIX bit in the attributes field.
+\end{enumerate}
+
+The three steps are necessary to ensure secure creation.  Since an
+attacker might be able to guess the initial password assigned by the
+client program, the principal must be disabled until the key can be
+truly randomized.
+
+\subsection{kadm5_get_principal}
+
+In KADM5_API_VERSION_1:
+
+\begin{verbatim}
+kadm5_ret_t
+kadm5_get_principal(void *server_handle, krb5_principal princ, 
+                         kadm5_principal_ent_t *ent);  
+\end{verbatim}
+
+In KADM5_API_VERSION_2:
+
+\begin{verbatim}
+kadm5_ret_t
+kadm5_get_principal(void *server_handle, krb5_principal princ, 
+                         kadm5_principal_ent_t ent, u_int32 mask);  
+\end{verbatim}
+
+AUTHORIZATION REQUIRED: get, or the calling principal being the same
+as the princ argument.  If the request is authenticated to the
+kadmin/changepw service, the get privilege is disregarded.
+
+In KADM5_API_VERSION_1, return all of the principal's attributes in
+allocated memory; if an error is returned entry is set to NULL.  In
+KADM5_API_VERSION_2, fill in the fields of the principal structure
+specified in the mask; memory for the structure is not allocated.
+Typically, a caller will specify the mask KADM5_PRINCIPAL_NORMAL_MASK,
+which includes all the fields {\it except} key_data and tl_data to
+improve time and memory efficiency.  A caller that wants key_data and
+tl_data can bitwise-OR those masks onto NORMAL_MASK.  Note that even
+if KADM5_TL_DATA is specified, this function will not return internal
+tl_data elements whose type is less than 256.
+
+The caller must free the returned entry with kadm5_free_principal_ent.
+
+The function behaves differently for local and remote clients.  For
+remote clients, the KEY_DATA mask is illegal and results in a
+KADM5_BAD_MASK error.
+
+RETURN CODES:
+
+\begin{description}
+\item[KADM5_UNK_PRINC] Principal does not exist.
+\item[KADM5_BAD_MASK] The mask is not valid for a get operation.
+
+\end{description}
+
+\subsection{kadm5_decyrpt_key}
+
+\begin{verbatim}
+kadm5_ret_t kadm5_decrypt_key(void *server_handle,
+                              kadm5_principal_ent_t entry, krb5_int32
+                              ktype, krb5_int32 stype, krb5_int32
+                              kvno, krb5_keyblock *keyblock,
+                              krb5_keysalt *keysalt, int *kvnop)
+\end{verbatim}
+
+AUTHORIZATION REQUIRED: none, local function
+
+Searches a principal's key_data array to find a key with the specified
+enctype, salt type, and kvno, and decrypts the key into keyblock and
+keysalt if found.  entry must have been returned by
+kadm5_get_principal with at least the KADM5_KEY_DATA mask set.
+Returns ENOENT if the key cannot be found, EINVAL if the key_data
+array is empty (as it always is in an RPC client).
+
+If ktype or stype is -1, it is ignored for the search.  If kvno is -1,
+ktype and stype are ignored and the key with the max kvno is returned.
+If kvno is 0, only the key with the max kvno is returned and only if
+it matches the ktype and stype; otherwise, ENOENT is returned.
+
+\subsection{kadm5_get_principals}
+
+\begin{verbatim}
+kadm5_ret_t
+kadm5_get_principals(void *server_handle, char *exp,
+                          char ***princs, int *count)
+\end{verbatim}
+
+Retrieves the list of principal names.  
+
+AUTHORIZATION REQUIRED: list
+
+If \v{exp} is NULL, all principal names are retrieved; otherwise,
+principal names that match the expression exp are retrieved.
+\v{princs} is filled in with a pointer to a NULL-terminated array of
+strings, and \v{count} is filled in with the number of principal names
+in the array.  \v{princs} must be freed with a call to
+\v{kadm5_free_name_list}.
+
+All characters in the expression match themselves except ``?'' which
+matches any single character, ``*'' which matches any number of
+consecutive characters, and ``[chars]'' which matches any single
+character of ``chars''. Any character which follows a ``$\backslash$''
+matches itself exactly, and a ``$\backslash$'' cannot be the last
+character in the string.
+
+\subsection{kadm5_create_policy}
+
+\begin{verbatim}
+kadm5_ret_t
+kadm5_create_policy(void *server_handle,
+                         kadm5_policy_ent_t policy, u_int32 mask); 
+\end{verbatim}
+
+Create a new policy.
+
+AUTHORIZATION REQUIRED: add
+
+\begin{enumerate}
+\item Check to see if mask is valid, if not return KADM5_BAD_MASK error.
+\item Return KADM5_BAD_POLICY if the policy name contains illegal
+characters.
+
+\item Check to see if the policy already exists, if so return
+KADM5_DUP error. 
+\item If the PW_MIN_CLASSES bit is set and pw_min_classes is not 1, 2,
+3, 4, or 5, return KADM5_BAD_CLASS.
+\item Create a new policy setting the appropriate fields determined
+by the mask.
+\end{enumerate}
+
+RETURN CODES:
+
+\begin{description}
+\item[KADM5_DUP] Policy already exists
+\item[KADM5_BAD_MASK] The mask is not valid for a create
+operation.
+\item[KADM5_BAD_CLASS] The specified number of character classes
+is invalid.
+\item[KADM5_BAD_POLICY] The policy name contains illegal characters.
+\end{description}
+
+\subsection{kadm5_delete_policy}
+
+\begin{verbatim}
+kadm5_ret_t
+kadm5_delete_policy(void *server_handle, char *policy);
+\end{verbatim}
+
+Deletes a policy.
+
+AUTHORIZATION REQUIRED: delete
+
+\begin{enumerate}
+\item Return KADM5_BAD_POLICY if the policy name contains illegal
+characters.
+\item Return KADM5_UNK_POLICY if the named policy does not exist.
+\item Return KADM5_POLICY_REF if the named policy's refcnt is not 0.
+\item Delete policy.
+\end{enumerate}
+
+RETURN CODES:
+
+\begin{description}
+\item[KADM5_BAD_POLICY] The policy name contains illegal characters.
+\item[KADM5_UNK_POLICY] Policy does not exist.
+\item[KADM5_POLICY_REF] Policy is being referenced. 
+\end{description}
+
+\subsection{kadm5_modify_policy}
+
+\begin{verbatim}
+kadm5_ret_t
+kadm5_modify_policy(void *server_handle,
+                         kadm5_policy_ent_t policy, u_int32 mask);
+\end{verbatim}
+
+Modify an existing policy.  Note that modifying a policy has no affect
+on a principal using the policy until the next time the principal's
+password is changed.
+
+AUTHORIZATION REQUIRED: modify
+
+\begin{enumerate}
+\item Return KADM5_BAD_POLICY if the policy name contains illegal
+characters.
+\item Check to see if mask is legal, if not return KADM5_BAD_MASK error.
+\item Check to see if policy exists, if not return
+KADM5_UNK_POLICY error.
+\item If the PW_MIN_CLASSES bit is set and pw_min_classes is not 1, 2,
+3, 4, or 5, return KADM5_BAD_CLASS.
+\item Update the fields specified in the mask.
+\end{enumerate}
+
+RETURN CODES: 
+
+\begin{description}
+\item[KADM5_BAD_POLICY] The policy name contains illegal characters.
+\item[KADM5_UNK_POLICY] Policy not found.
+\item[KADM5_BAD_MASK] The mask is not valid for a modify
+operation.
+\item[KADM5_BAD_CLASS] The specified number of character classes
+is invalid.
+\end{description}
+
+\subsection{kadm5_get_policy}
+
+In KADM5_API_VERSION_1:
+
+\begin{verbatim}
+kadm5_ret_t
+kadm5_get_policy(void *server_handle, char *policy, kadm5_policy_ent_t *ent); 
+\end{verbatim}
+
+In KADM5_API_VERSION_2:
+
+\begin{verbatim}
+kadm5_ret_t
+kadm5_get_policy(void *server_handle, char *policy, kadm5_policy_ent_t ent); 
+\end{verbatim}
+
+AUTHORIZATION REQUIRED: get, or the calling principal's policy being
+the same as the policy argument.  If the request is authenticated to
+the kadmin/changepw service, the get privilege is disregarded.
+
+In KADM5_API_VERSION_1, return the policy's attributes in allocated
+memory; if an error is returned entry is set to NULL.  In
+KADM5_API_VERSION_2, fill in fields of the policy structure allocated
+by the caller.  The caller must free the returned entry with
+kadm5_free_policy_ent
+
+RETURN CODES: 
+
+\begin{description}
+\item[KADM5_BAD_POLICY] The policy name contains illegal characters.
+\item[KADM5_UNK_POLICY] Policy not found.
+\end{description}
+
+\subsection{kadm5_get_policies}
+
+\begin{verbatim}
+kadm5_ret_t
+kadm5_get_policies(void *server_handle, char *exp,
+                          char ***pols, int *count)
+\end{verbatim}
+
+Retrieves the list of principal names.  
+
+AUTHORIZATION REQUIRED: list
+
+If \v{exp} is NULL, all principal names are retrieved; otherwise,
+principal names that match the expression exp are retrieved.  \v{pols}
+is filled in with a pointer to a NULL-terminated array of strings, and
+\v{count} is filled in with the number of principal names in the
+array.  \v{pols} must be freed with a call to
+\v{kadm5_free_name_list}.
+
+All characters in the expression match themselves except ``?'' which
+matches any single character, ``*'' which matches any number of
+consecutive characters, and ``[chars]'' which matches any single
+character of ``chars''. Any character which follows a ``$\backslash$''
+matches itself exactly, and a ``$\backslash$'' cannot be the last
+character in the string.
+
+\subsection{kadm5_free_principal_ent, _policy_ent}
+
+\begin{verbatim}
+void kadm5_free_principal_ent(void *server_handle,
+                                   kadm5_principal_ent_t princ);
+\end{verbatim}
+
+In KADM5_API_VERSION_1, free the structure and contents allocated by a
+call to kadm5_get_principal.  In KADM5_API_VERSION_2, free the
+contents allocated by a call to kadm5_get_principal.
+
+AUTHORIZATION REQUIRED: none (local operation)
+
+\begin{verbatim}
+void kadm5_free_policy_ent(kadm5_policy_ent_t policy);
+\end{verbatim}
+
+Free memory that was allocated by a call to kadm5_get_policy.  If
+the argument is NULL, the function returns succesfully.
+
+AUTHORIZATION REQUIRED: none (local operation)
+
+\subsection{kadm5_free_name_list}
+
+\begin{verbatim}
+void kadm5_free_name_list(void *server_handle,
+                               char **names, int *count);
+\end{verbatim}
+
+Free the memory that was allocated by kadm5_get_principals or
+kadm5_get_policies.  names and count must be a matched pair of
+values returned from one of those two functions.
+
+\subsection{kadm5_free_key_data}
+
+\begin{verbatim}
+void kadm5_free_key_data(void *server_handle,
+                         krb5_int16 *n_key_data, krb5_key_data *key_data)
+\end{verbatim}
+
+Free the memory that was allocated by kadm5_randkey_principal.
+n_key_data and key_data must be a matched pair of values returned from
+that function.
+
+\subsection{kadm5_get_privs}
+
+\begin{verbatim}
+kadm5_ret_t
+kadm5_get_privs(void *server_handle, u_int32 *privs);
+\end{verbatim}
+
+Return the caller's admin server privileges in the integer pointed to
+by the argument.  The Admin API does not define any way for a
+principal's privileges to be set.  Note that this function will
+probably be removed or drastically changed in future versions of this
+system.
+
+The returned value is a bitmask indicating the caller's privileges:
+
+\begin{tabular}{llr}
+{\bf Privilege} & {\bf Symbol} & {\bf Value} \\
+Get & KADM5_PRIV_GET & 0x01 \\
+Add & KADM5_PRIV_ADD & 0x02 \\
+Modify & KADM5_PRIV_MODIFY & 0x04 \\
+Delete & KADM5_PRIV_DELETE & 0x08 \\
+List & KADM5_PRIV_LIST & 0x10 \\
+Changepw & KADM5_PRIV_CPW & 0x20
+\end{tabular}
+
+There is no guarantee that a caller will have a privilege indicated by
+this function for any length of time or for any particular target;
+applications using this function must still be prepared to handle all
+possible KADM5_AUTH_* error codes.
+
+In the initial MIT Kerberos version of the admin server, permissions
+depend both on the caller and the target; this function returns a
+bitmask representing all privileges the caller can possibly have for
+any possible target.
+
+\end{document}