diff options
Diffstat (limited to 'crypto/krb5/doc/kadm5/api-funcspec.tex')
| -rw-r--r-- | crypto/krb5/doc/kadm5/api-funcspec.tex | 2015 |
1 files changed, 0 insertions, 2015 deletions
diff --git a/crypto/krb5/doc/kadm5/api-funcspec.tex b/crypto/krb5/doc/kadm5/api-funcspec.tex deleted file mode 100644 index b633cef1ef33..000000000000 --- a/crypto/krb5/doc/kadm5/api-funcspec.tex +++ /dev/null @@ -1,2015 +0,0 @@ -% This document is included for historical purposes only, and does not -% apply to krb5 today. - -\documentstyle[12pt,fullpage]{article} - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -%% Make _ actually generate an _, and allow line-breaking after it. -\let\underscore=\_ -\catcode`_=13 -\def_{\underscore\penalty75\relax} -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - -\setlength{\parskip}{.7\baselineskip} -\setlength{\parindent}{0pt} - -\def\v#1{\verb+#1+} - -\title{Kerberos Administration System \\ - KADM5 API Functional Specifications} -\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 version 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 prototypes 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 auxiliary 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 reuse 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 necessary 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 -occur 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 successfully. - -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} |