\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(), and closes and reopens the Admin policy database with adb_policy_close() and adb_policy_open(). Although it is unlikely, any other 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 ``$ 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}