"Fossies" - the Fresh Open Source Software Archive

Member "krb5-1.18/doc/kadm5/api-funcspec.tex" (12 Feb 2020, 80949 Bytes) of package /linux/misc/krb5-1.18.tar.gz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) TeX and LaTeX source code syntax highlighting (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1 % This document is included for historical purposes only, and does not
    2 % apply to krb5 today.
    3 
    4 \documentstyle[12pt,fullpage]{article}
    5 
    6 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    7 %% Make _ actually generate an _, and allow line-breaking after it.
    8 \let\underscore=\_
    9 \catcode`_=13
   10 \def_{\underscore\penalty75\relax}
   11 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   12 
   13 \setlength{\parskip}{.7\baselineskip}
   14 \setlength{\parindent}{0pt}
   15 
   16 \def\v#1{\verb+#1+}
   17 
   18 \title{Kerberos Administration System \\
   19         KADM5 API Functional Specifications}
   20 \author{Barry Jaspan}
   21 
   22 \begin{document}
   23 
   24 \sloppy
   25 \maketitle
   26 
   27 {\setlength{\parskip}{0pt}\tableofcontents}
   28 
   29 \section{Introduction}
   30 
   31 This document describes the Admin API that can be used to maintain
   32 principals and policies.  It describes the data structures used for
   33 each function and the interpretation of each data type field, the
   34 semantics of each API function, and the possible return codes.
   35 
   36 The Admin API is intended to be used by remote clients using an RPC
   37 interface.  It is implemented by the admin server running on the
   38 Kerberos master server.  It is also possible for a program running on
   39 the Kerberos master server to use the Admin API directly, without
   40 going through the admin server.
   41 
   42 \section{Versions of the API}
   43 
   44 The versions of this API and a brief description of the changes for
   45 each are:
   46 
   47 \begin{description}
   48 \item[KADM5_API_VERSION_1] The initial version of this API, written by
   49 OpenVision Technologies and donated to MIT for including in the public
   50 release.  Originally called OVSEC_KADM_API_VERSION_1.  Most everything
   51 has been renamed in one way or another, including functions, header
   52 files, and data structures.  Where possible, the old OVSEC_KADM names
   53 have been left behind for compatibility with version 1, and
   54 KADM5_API_VERSION_1 is compatible with OVSEC_KADM_API_VERSION_1 at
   55 compile-, link-, and run-time.
   56 
   57 The OVSEC_KADM name compatibility will not be extended to new
   58 functionality in future versions because no existing OVSEC_KADM
   59 clients will use that functionality; new clients should be written to
   60 the KADM5 API.
   61 
   62 \item[KADM5_API_VERSION_2] This version contains the initial changes
   63 necessary to make the OpenVision administration system work with the
   64 mid-1996 MIT version of Kerberos 5.  Changes include
   65 \begin{enumerate}
   66 \item The kadm5_init functions now take a structure of parameters
   67 instead of just a realm name, allowing the calling program to specify
   68 non-default values for various configuration options.  See section
   69 \ref{sec:configparams} for details.
   70 
   71 \item The KADM5 API has been extended to support new features of the
   72 Kerberos database, including multiple encryption and salt types per
   73 principal.  See section \ref{sec:keys} for details.
   74 
   75 \item kadm5_get_principal now allows a principal's keys to be
   76 retrieved {\it by local clients only}.  This is necessary in order for
   77 the kadm5 API to provide the primary Kerberos database interface.
   78 
   79 \item The KADM5 authorization system has been completely changed.
   80 
   81 \item The functions kadm5_flush, kadm5_get_principals, and
   82 kadm5_get_policies have been added.
   83 
   84 \item The KADM5 API now obeys a caller-allocates rather than
   85 callee-allocates system.  kadm5_get_principal and kadm5_get_policy are
   86 affected.
   87 \end{enumerate}
   88 \end{description}
   89 
   90 \section{Policies and Password Quality}
   91 
   92 The Admin API Password Quality mechanism provides the following
   93 controls.  Note that two strings are defined to be ``significantly
   94 different'' if they differ by at least one character. The compare is not
   95 case sensitive.
   96 
   97 \begin{itemize}
   98 \item A minimum length can be required; a password with
   99 fewer than the specified number of characters will not be accepted.
  100 
  101 \item A minimum number of character classes can be required; a
  102 password that does not contain at least one character from at least
  103 the specified number of character classes will not be accepted.  The
  104 character classes are defined by islower(), isupper(), isdigit(),
  105 ispunct(), and other.
  106 
  107 \item Passwords can be required to be different from
  108 previous passwords; a password that generates the same encryption key
  109 as any of the principal's specified previous number of passwords will
  110 not be accepted.  This comparison is performed on the encryption keys
  111 generated from the passwords, not on the passwords themselves.
  112 
  113 \item A single ``forbidden password'' dictionary can be specified for all
  114 users; a password that is not significantly different from every word
  115 in the dictionary will not be accepted.
  116 \end{itemize}
  117 
  118 \section{Data Structures}
  119 
  120 This section describes the data structures used by the Admin API.
  121 They are defined in $<$kadm5/admin.h$>$.
  122 
  123 \subsection{Principals, kadm5_principal_ent_t}
  124 \label{sec:principal-structure}
  125 
  126 A Kerberos principal entry is represented by a kadm5_principal_ent_t.
  127 It contains a subset of the information stored in the master Kerberos
  128 database as well as the additional information maintained by the admin
  129 system.  In the current version, the only additional information is
  130 the principal's policy and the aux_attributes flags.
  131 
  132 The principal may or may not have a policy enforced on it.  If the
  133 POLICY bit (see section \ref{sec:masks}) is set in aux_attributes, the
  134 policy field names the principal's policy.  If the POLICY bit is not
  135 set in aux_attributes, no policy is enforced on the principal and the
  136 value of the policy field is undefined.
  137 
  138 \begin{figure}[htbp]
  139 \begin{verbatim}
  140 typedef struct _kadm5_principal_ent_t {
  141         krb5_principal principal;
  142 
  143         krb5_timestamp princ_expire_time;
  144         krb5_timestamp last_pwd_change;
  145         krb5_timestamp pw_expiration;
  146         krb5_deltat max_life;
  147         krb5_principal mod_name;
  148         krb5_timestamp mod_date;
  149         krb5_flags attributes;
  150         krb5_kvno kvno;
  151         krb5_kvno mkvno;
  152 
  153         char * policy;
  154         u_int32 aux_attributes;
  155 
  156         krb5_deltat max_renewable_life;
  157         krb5_timestamp last_success;
  158         krb5_timestamp last_failed;
  159         krb5_kvno fail_auth_count;
  160         krb5_int16 n_key_data;
  161         krb5_int16 n_tl_data;
  162         krb5_tl_data *tl_data;
  163         krb5_key_data *key_data;
  164 } kadm5_principal_ent_rec, *kadm5_principal_ent_t;
  165 \end{verbatim}
  166 \caption{Definition of kadm5_principal_ent_t.}
  167 \label{fig:princ-t}
  168 \end{figure}
  169 
  170 The fields of an kadm5_principal_ent_t are interpreted as
  171 follows.
  172 
  173 \begin{description}
  174 \item[principal] The name of the principal; must conform to Kerberos
  175 naming specifications.
  176 
  177 \item[princ_expire_time] The expire time of the principal as a Kerberos
  178 timestamp.  No Kerberos tickets will be issued for a principal after
  179 its expire time.
  180 
  181 \item[last_pwd_change] The time this principal's password was last
  182 changed, as a Kerberos timestamp.
  183 
  184 \item[pw_expiration] The expire time of the user's current password, as a
  185 Kerberos timestamp.  No application service tickets will be issued for the
  186 principal once the password expire time has passed.  Note that the user can
  187 only obtain tickets for services that have the PW_CHANGE_SERVICE bit set in
  188 the attributes field.
  189 
  190 \item[max_life] The maximum lifetime of any Kerberos ticket issued to
  191 this principal.
  192 
  193 \item[attributes] A bitfield of attributes for use by the KDC.  The
  194 symbols and constant values are defined below; their interpretation
  195 appears in the libkdb functional specification.
  196 
  197 \begin{tabular}{clr}
  198 {\bf Name} & {\bf Value} \\
  199 KRB5_KDB_DISALLOW_POSTDATED     & 0x00000001 \\
  200 KRB5_KDB_DISALLOW_FORWARDABLE   & 0x00000002 \\
  201 KRB5_KDB_DISALLOW_TGT_BASED     & 0x00000004 \\
  202 KRB5_KDB_DISALLOW_RENEWABLE     & 0x00000008 \\
  203 KRB5_KDB_DISALLOW_PROXIABLE     & 0x00000010 \\
  204 KRB5_KDB_DISALLOW_DUP_SKEY      & 0x00000020 \\
  205 KRB5_KDB_DISALLOW_ALL_TIX       & 0x00000040 \\
  206 KRB5_KDB_REQUIRES_PRE_AUTH      & 0x00000080 \\
  207 KRB5_KDB_REQUIRES_HW_AUTH       & 0x00000100 \\
  208 KRB5_KDB_REQUIRES_PWCHANGE      & 0x00000200 \\
  209 KRB5_KDB_DISALLOW_SVR           & 0x00001000 \\
  210 KRB5_KDB_PWCHANGE_SERVICE       & 0x00002000 \\
  211 KRB5_KDB_SUPPORT_DESMD5         & 0x00004000 \\
  212 KRB5_KDB_NEW_PRINC              & 0x00008000
  213 \end{tabular}
  214 
  215 \item[mod_name] The name of the Kerberos principal that most recently
  216 modified this principal.
  217 
  218 \item[mod_date] The time this principal was last modified, as a Kerberos
  219 timestamp.
  220 
  221 \item[kvno] The version of the principal's current key.
  222 
  223 \item[mkvno] The version of the Kerberos Master Key in effect when
  224 this principal's key was last changed.  In KADM5_API_VERSION_2, this
  225 field is always zero.
  226 
  227 \item[policy] If the POLICY bit is set in aux_attributes, the name
  228 of the policy controlling this principal.
  229 
  230 \item[aux_attributes]  A bitfield of flags for use by the
  231 administration system.  Currently, the only valid flag is POLICY, and
  232 it indicates whether or not the principal has a policy enforced on it.
  233 
  234 \item[max_renewable_life] The maximum renewable lifetime of any
  235 Kerberos ticket issued to or for this principal.  This field only
  236 exists in KADM5_API_VERSION_2.
  237 
  238 \item[last_success] The KDC time of the last successful AS_REQ.  This
  239 is only updated if KRBCONF_KDC_MODIFIES_KDB is defined during
  240 compilation of the KDC.  This field only exists in
  241 KADM5_API_VERSION_2.
  242 
  243 \item[last_failed] The KDC time of the last failed AS_REQ.  This is
  244 only updated if KRBCONF_KDC_MODIFIES_KDB is defined during compilation
  245 of the KDC.  This field only exists in KADM5_API_VERSION_2.
  246 
  247 \item[fail_auth_count] The number of consecutive failed AS_REQs.  When
  248 this number reaches KRB5_MAX_FAIL_COUNT, the KRB5_KDC_DISALLOW_ALL_TIX
  249 is set on the principal.  This is only updated if
  250 KRBCONF_KDC_MODIFIES_KDB is defined during compilation.  This field
  251 only exists in KADM5_API_VERSION_2.
  252 
  253 \item[n_tl_data] The number of elements in the \v{tl_data} linked
  254 list.  This field only exists in KADM5_API_VERSION_2.
  255 
  256 \item[n_key_data] The number of elements in the \v{key_data}
  257 array. This field only exists in KADM5_API_VERSION_2.
  258 
  259 \item[tl_data] A linked list of tagged data.  This list is a mechanism
  260 by which programs can store extended information in a principal entry,
  261 without having to modify the database API.  Each element is of type
  262 krb5_tl_data:
  263 \begin{verbatim}
  264 typedef struct _krb5_tl_data {
  265     struct _krb5_tl_data* tl_data_next;
  266     krb5_int16            tl_data_type;         
  267     krb5_int16            tl_data_length;       
  268     krb5_octet          * tl_data_contents;     
  269 } krb5_tl_data;
  270 \end{verbatim}
  271 %
  272 The KADM5 API only allows elements whose tl_data_type is greater than
  273 or equal to 256.  Values less than 256 are reserved for internal use
  274 by the KADM5 or kdb system.  They are filtered out of the list
  275 returned by kadm5_get_principal, and generate an error if given to
  276 kadm5_modify_principal.
  277 
  278 The libkdb library defines the tagged data types
  279 KRB5_TL_LAST_PWD_CHANGE, KRB5_TL_MOD_PRINC, and KRB5_TL_KADM_DATA, all
  280 with values less than 256, which store the last password modification
  281 time, time and modifier of last principal modification, and
  282 administration system data.  All of these entries are expected by the
  283 administration system and parsed out into fields of the
  284 kadm5_principal_ent_rec structure; as described above, they are not
  285 included in the tl_data list.
  286 
  287 Tagged data elements with types greater than 256 are handled without
  288 interpretation by KADM5.  Note that an application that calls
  289 kadm5_modify_principal with the KADM5_TL_DATA mask bit set is
  290 responsible for providing the {\it complete} tl_data list, which it
  291 necessarily must obtain from kadm5_get_principal.  It is {\it never}
  292 possible for an application to construct a complete tl_data list from
  293 scratch.
  294 
  295 \item[key_data] An array of the principal's keys.  The keys contained
  296 in this array are encrypted in the Kerberos master key.  See section
  297 \ref{sec:keys} for a discussion of the krb5_key_data structure.
  298 \end{description}
  299 
  300 \subsection{Policies, kadm5_policy_ent_t}
  301 \label{sec:policy-fields}
  302 
  303 If the POLICY bit is set in aux_attributes, the \v{policy} name field
  304 in the kadm5_principal_ent_t structure refers to a password policy
  305 entry defined in a \v{kadm5_policy_ent_t}.
  306 
  307 \begin{verbatim}
  308 typedef struct _kadm5_policy_ent_t {
  309         char *policy;
  310 
  311         u_int32 pw_min_life;
  312         u_int32 pw_max_life;
  313         u_int32 pw_min_length;
  314         u_int32 pw_min_classes;
  315         u_int32 pw_history_num;
  316         u_int32 policy_refcnt;
  317 } kadm5_policy_ent_rec, *kadm5_policy_ent_t;
  318 \end{verbatim}
  319 
  320 The fields of an kadm5_policy_ent_t are interpreted as follows.
  321 Note that a policy's values only apply to a principal using that
  322 policy.
  323 
  324 \begin{description}
  325 \item[policy] The name of this policy, as a NULL-terminated string.
  326 The ASCII characters between 32 (space) and 126 (tilde), inclusive,
  327 are legal.
  328 
  329 \item[pw_min_life] The minimum password lifetime, in seconds.
  330 A principal cannot change its password before pw_min_life seconds have
  331 passed since last_pwd_change.
  332 
  333 \item[pw_max_life] The default duration, in seconds, used to compute
  334 pw_expiration when a principal's password is changed.
  335 
  336 \item[pw_min_length] The minimum password length, in characters.  A
  337 principal cannot set its password to anything with fewer than this
  338 number of characters.  This value must be greater than zero.
  339 
  340 \item[pw_min_classes] The minimum number of character classes in the
  341 password.  This value can only be 1, 2, 3, 4, or 5.  A principal cannot
  342 set its password to anything with fewer than this number of character
  343 classes in it.
  344 
  345 \item[pw_history_num] The number of past passwords that are
  346 stored for the principal; the minimum value is 1 and the maximum value
  347 is 10.  A principal cannot set its password to any of its previous
  348 pw_history_num passwords.  The first ``previous'' password is the
  349 current password; thus, a principal with a policy can never reset its
  350 password to its current value.
  351 
  352 \item[policy_refcnt]  The number of principals currently using this policy.
  353 A policy cannot be deleted unless this number is zero.
  354 \end{description}
  355 
  356 \subsection{Configuration parameters}
  357 \label{sec:configparams}
  358 
  359 The KADM5 API acquires configuration information from the Kerberos
  360 configuration file (\$KRB5_CONFIG or DEFAULT_PROFILE_PATH) and from
  361 the KDC configuration file (\$KRB5_KDC_CONFIG or DEFAULT_KDC_PROFILE).
  362 In KADM5_API_VERSION_2, some of the configuration parameters used by
  363 the KADM5 API can be controlled by the caller by providing a
  364 kadm5_config_params structure to kadm5_init:
  365 %
  366 \begin{verbatim}
  367 typedef struct _kadm5_config_params {
  368         u_int32 mask;
  369 
  370         /* Client and server fields */
  371         char *realm;
  372         char *profile;
  373         int kadmind_port;
  374 
  375         /* client fields */
  376         char *admin_server;
  377 
  378         /* server fields */
  379         char *dbname;
  380         char *admin_dbname;
  381         char *admin_lockfile;
  382         char *acl_file;
  383         char *dict_file;
  384         char *admin_keytab;
  385 
  386         /* server library (database) fields */
  387         int mkey_from_kbd;
  388         char *stash_file;
  389         char *mkey_name;
  390         krb5_enctype enctype;
  391         krb5_deltat max_life;
  392         krb5_deltat max_rlife;
  393         krb5_timestamp expiration;
  394         krb5_flags flags;
  395         krb5_key_salt_tuple *keysalts;
  396         krb5_int32 num_keysalts;
  397 } kadm5_config_params;
  398 \end{verbatim}
  399 %
  400 The following list describes each of the fields of the structure,
  401 along with the profile relation it overrides, its mask value, its
  402 default value, and whether it is valid on the client, server, or both,
  403 or neither.
  404 \begin{description}
  405 \item[mask] No variable.  No mask value.  A bitfield specifying which
  406 fields of the structure contain valid information.  A caller sets this
  407 mask before calling kadm5_init_*, indicating which parameters are
  408 specified.  The mask values are defined in $<$kadm5/admin.h$>$ and are
  409 all prefixed with KADM5_CONFIG_; the prefix is not included in the
  410 descriptions below.
  411 
  412 \item[realm] No variable.  REALM.  Client and server.  The realm to
  413 which these parameters apply, and the realm for which additional
  414 parameters are to be acquired, if any.  If this field is not specified
  415 in the mask, the default local realm is used.
  416 
  417 \item[profile] Variable: profile (server only).  PROFILE.  Client and
  418 server.  The Kerberos profile to use.  On the client, the default is
  419 the value of the KRB5_CONFIG environment variable, or
  420 DEFAULT_PROFILE_PATH if that is not set.  On the server, the value of
  421 the ``profile'' variable of the KDC configuration file will be used as
  422 the first default if it exists; otherwise, the default is the value of
  423 the KRB5_KDC_PROFILE environment variable or DEFAULT_KDC_PROFILE.
  424 
  425 \item[kadmind_port] Variable: kadmind_port.  KADMIND_PORT.  Client and
  426 server.  The port number the kadmind server listens on.  The client
  427 uses this field to determine where to connect, and the server to
  428 determine where to listen.  The default is 749, which has been
  429 assigned by IANA.
  430 
  431 \item[admin_server] Variable: admin_server.  ADMIN_SERVER.  Client.
  432 The host name of the admin server to which to connect.  There is no
  433 default.  If the value of this field contains a colon (:), the text
  434 following the colon is treated as an integer and assigned to the
  435 kadmind_port field, overriding any value of the kadmind_port variable.
  436 
  437 \item[dbname] Variable: dbname.  DBNAME.  Server.  The Kerberos
  438 database name to use; the Kerberos database stores principal
  439 information.  The default is DEFAULT_KDB_FILE.
  440 
  441 \item[admin_dbname] Variable: admin_database_name.  ADBNAME.
  442 Neither.  If the dbname field is set, this field is set to the value
  443 of dbname followed by ``.kadm5''.
  444 
  445 \item[admin_lockfile] Variable: admin_database_lockfile.
  446 ADB_LOCKFILE.  Neither.  If the admin_dbname field is set, this field
  447 is set to the value of admin_dbname followed by ``.lock''.
  448 
  449 \item[acl_file] Variable: acl_file.  ACL_FILE.  Server.  The admin
  450 server's ACL file.  The default is DEFAULT_KADM5_ACL_FILE.
  451 
  452 \item[dict_file] Variable: admin_dict_file.  DICT_FILE.  Server.  The
  453 admin server's dictionary file of passwords to disallow.  No default.
  454 
  455 \item[admin_keytab] Variable: admin_keytab. ADMIN_KEYTAB.  Server.
  456 The keytab file containing the kadmin/admin and kadmin/changepw
  457 entries for the server to use.  The default is the value of the
  458 KRB5_KTNAME environment variable, if defined, else
  459 DEFAULT_KADM5_KEYTAB.
  460 
  461 \item[mkey_from_keyboard] No variable. MKEY_FROM_KEYBOARD.  Server.
  462 If non-zero, prompt for the master password via the tty instead of
  463 using the stash file.  If this mask bit is not set, or is set and the
  464 value is zero, the stash file is used.
  465 
  466 \item[stash_file] Variable: key_stash_file.  STASH_FILE. Server.  The
  467 file name containing the master key stash file.  No default; libkdb
  468 will work with a NULL value.
  469 
  470 \item[mkey_name] Variable: master_key_name.  MKEY_NAME.  Server.  The
  471 name of the master principal for the realm.  No default; lbkdb will
  472 work with a NULL value.
  473 
  474 \item[enctype] Variable: master_key_type.  ENCTYPE.  Server.  The
  475 encryption type of the master principal.  The default is
  476 DEFAULT_KDC_ENCTYPE.
  477 
  478 \item[max_life] Variable: max_life.  MAX_LIFE.  Maximum lifetime for
  479 all tickets issued to the principal.  The default is 28800, which is 8
  480 hours.
  481 
  482 \item[max_rlife, expiration, flags] Variables: max_renewable_life,
  483 default_principal_expiration, default_principal_flags.  MAX_LIFE,
  484 MAX_RLIFE, EXPIRATION, FLAGS.  Server.  Default values for new
  485 principals.  All default to 0.
  486 
  487 \item[keysalts, num_keysalts] Variable: supported_enctypes.  ENCTYPES.
  488 Server.  The list of supported encryption type/salt type tuples; both
  489 fields must be assigned if ENCTYPES is set.  The default is a list
  490 containing one enctype, DES-CBC-CRC with normal salt.
  491 \end{description}
  492 
  493 \subsection{Principal keys}
  494 \label{sec:keys}
  495 
  496 In KADM5_API_VERSION_1, all principals had a single key.  The
  497 encryption method was always DES, and the salt type was determined
  498 outside the API (by command-line options to the administration
  499 server).
  500 
  501 In KADM5_API_VERSION_2, principals can have multiple keys, each with
  502 its own encryption type and salt.  Each time a principal's key is
  503 changed with kadm5_create_principal, kadm5_chpass_principal or
  504 kadm5_randkey_principal, existing key entries are removed and a key
  505 entry for each encryption and salt type tuple specified in the
  506 configuration parameters is added.  There is no provision for
  507 specifying encryption and salt type information on a per-principal
  508 basis; in a future version, this will probably be part of the admin
  509 policy.  There is also presently no provision for keeping multiple key
  510 versions for a single principal active in the database.
  511 
  512 A single key is represented by a krb5_key_data:
  513 %
  514 \begin{verbatim}
  515 typedef struct _krb5_key_data {
  516         krb5_int16            key_data_ver;         /* Version */
  517         krb5_int16            key_data_kvno;        /* Key Version */
  518         krb5_int16            key_data_type[2];     /* Array of types */
  519         krb5_int16            key_data_length[2];   /* Array of lengths */
  520         krb5_octet          * key_data_contents[2]; /* Array of pointers */
  521 } krb5_key_data;
  522 \end{verbatim}
  523 %
  524 \begin{description}
  525 \item[key_data_ver] The verion number of the structure.  Versions 1
  526 and 2 are currently defined.  If key_data_ver is 1 then the key is
  527 either a random key (not requiring a salt) or the salt is the normal
  528 v5 salt which is the same as the realm and therefore doesn't need to
  529 be saved in the database.
  530 
  531 \item[key_data_kvno] The key version number of this key.
  532 
  533 \item[key_data_type] The first element is the enctype of this key.  In
  534 a version 2 structure, the second element is the salttype of this key.
  535 The legal encryption types are defined in $<$krb5.h$>$.  The legal
  536 salt types are defined in $<$k5-int.h$>$.
  537 
  538 \item[key_data_length] The first element is length this key.  In a
  539 version 2 structure, the second element is length of the salt for this
  540 key.
  541 
  542 \item[key_data_contents] The first element is the content of this key.
  543 In a version 2 structure, the second element is the contents of the
  544 salt for this key.
  545 \end{description}
  546 
  547 \subsection{Field masks}
  548 \label{sec:masks}
  549 
  550 The API functions for creating, retrieving, and modifying principals
  551 and policies allow for a relevant subset of the fields of the
  552 kadm5_principal_ent_t and kadm5_policy_ent_t to be specified or
  553 changed.  The chosen fields are determined by a bitmask that is passed
  554 to the relevant function.  Each API function has different rules for
  555 which mask values can be specified, and can specify whether a given
  556 mask value is mandatory, optional, or forbidden.  Mandatory fields
  557 must be present and forbidden fields must not be present or an error
  558 is generated.  When creating a principal or policy, optional fields
  559 have a default value if they are not specified.  When modifying a
  560 principal or policy, optional fields are unchanged if they are not
  561 specified.  When retrieving a principal, optional fields are simply
  562 not provided if they are not specified; not specifying undeeded fields
  563 for retrieval may improve efficiency.  The values for forbidden fields
  564 are defined in the function semantics.
  565 
  566 The masks for principals are in table \ref{tab:princ-bits} and the
  567 masks for policies are in table \ref{tab:policy-bits}.  They are
  568 defined in $<$kadm5/admin.h$>$. The KADM5_ prefix has been removed
  569 from the Name fields.  In the Create and Modify fields, M means
  570 mandatory, F means forbidden, and O means optional.  Create fields
  571 that are optional specify the default value.  The notation ``K/M
  572 value'' means that the field inherits its value from the corresponding
  573 field in the Kerberos master principal, for KADM5_API_VERSION_1, and
  574 from the configuration parameters for KADM5_API_VERSION_2.
  575 
  576 All masks for principals are optional for retrevial, {\it except} that
  577 the KEY_DATA mask is illegal when specified by a remote client; for
  578 details, see the function semantics for kadm5_get_principal.
  579 
  580 Note that the POLICY and POLICY_CLR bits are special.  When POLICY is
  581 set, the policy is assigned to the principal.  When POLICY_CLR is
  582 specified, the policy is unassigned to the principal and as a result
  583 no policy controls the principal.
  584 
  585 For convenience, the mask KADM5_PRINCIPAL_NORMAL_MASK contains all of
  586 the principal masks {\it except} KADM5_KEY_DATA and KADM5_TL_DATA, and
  587 the mask KADM5_POLICY_NORMAL_MASK contains all of the policy masks.
  588 
  589 \begin{table}[htbp]
  590 \begin{tabular}{@{}lclll}
  591 {\bf Name} & {\bf Value} & {\bf Fields Affected} & {\bf Create} & 
  592         {\bf Modify} \\
  593 PRINCIPAL               & 0x000001 & principal & M & F \\
  594 PRINC_EXPIRE_TIME       & 0x000002 & princ_expire_time & O, K/M value & O \\
  595 PW_EXPIRATION           & 0x000004 & pw_expiration & O, now+pw_max_life & O \\
  596 LAST_PWD_CHANGE         & 0x000008 & last_pwd_change & F & F \\
  597 ATTRIBUTES              & 0x000010 & attributes & O, 0 & O \\
  598 MAX_LIFE                & 0x000020 & max_life & O, K/M value & O \\
  599 MOD_TIME                & 0x000040 & mod_date & F & F \\
  600 MOD_NAME                & 0x000080 & mod_name & F & F \\
  601 KVNO                    & 0x000100 & kvno & O, 1 & O \\
  602 MKVNO                   & 0x000200 & mkvno & F & F \\
  603 AUX_ATTRIBUTES          & 0x000400 & aux_attributes & F & F \\
  604 POLICY                  & 0x000800 & policy & O, none & O \\
  605 POLICY_CLR              & 0x001000 & policy & F & O \\
  606 MAX_RLIFE               & 0x002000 & max_renewable_life & O, K/M value & O \\
  607 LAST_SUCCESS            & 0x004000 & last_success & F & F \\
  608 LAST_FAILED             & 0x008000 & last_failed & F & F \\
  609 FAIL_AUTH_COUNT         & 0x010000 & fail_auth_count & F & O \\
  610 KEY_DATA                & 0x020000 & n_key_data, key_data & F & F \\
  611 TL_DATA                 & 0x040000 & n_tl_data, tl_data & O, 0, NULL & O
  612 \end{tabular}
  613 \caption{Mask bits for creating, retrieving, and modifying principals.}
  614 \label{tab:princ-bits}
  615 \end{table}
  616 
  617 \begin{table}[htbp]
  618 \begin{tabular}{@{}lclll}
  619 Name & Value & Field Affected & Create & Modify \\
  620 POLICY                  & same     & policy & M & F \\
  621 PW_MAX_LIFE             & 0x004000 & pw_max_life & O, 0 (infinite) & O \\
  622 PW_MIN_LIFE             & 0x008000 & pw_min_life & O, 0 & O \\
  623 PW_MIN_LENGTH           & 0x010000 & pw_min_length & O, 1 & O \\
  624 PW_MIN_CLASSES          & 0x020000 & pw_min_classes & O, 1 & O \\
  625 PW_HISTORY_NUM          & 0x040000 & pw_history_num & O, 0 & O \\
  626 REF_COUNT               & 0x080000 & pw_refcnt & F & F
  627 \end{tabular}
  628 \caption{Mask bits for creating/modifying policies.}
  629 \label{tab:policy-bits}
  630 \end{table}
  631 
  632 \section{Constants, Header Files, Libraries}
  633 
  634 $<$kadm5/admin.h$>$ includes a number of required header files,
  635 including RPC, Kerberos 5, com_err, and admin com_err
  636 defines.  It contains prototypes for all kadm5 routines mentioned
  637 below, as well as all Admin API data structures, type definitions and
  638 defines mentioned in this document.  
  639 
  640 Before \v{\#include}ing $<$kadm5/admin.h$>$, the programmer can
  641 specify the API version number that the program will use by
  642 \v{\#define}ing USE_KADM5_API_VERSION; for example, define that symbol
  643 to be 1 to use KADM5_API_VERSION_1.  This will ensure that the correct
  644 functional protoypes and data structures are defined.  If no version
  645 symbol is defined, the most recent version supported by the header
  646 files will be used.
  647 
  648 Some of the defines and their values contained in $<$kadm5/admin.h$>$
  649 include the following, whose KADM5_ prefixes have been removed.
  650 Symbols that do not exist in KADM5_API_VERSION_2 do not have a KADM5_
  651 prefix, but instead retain only with OVSEC_KADM_ prefix for
  652 compatibility.
  653 \begin{description}
  654 \item[admin service principal] ADMIN_SERVICE (``kadmin/admin'')
  655 \item[admin history key] HIST_PRINCIPAL (``kadmin/history'')
  656 \item[change password principal] CHANGEPW_SERVICE (``kadmin/changepw'')
  657 \item[server acl file path] ACLFILE (``/krb5/ovsec_adm.acl'').  In
  658 KADM5_API_VERSION 2, this is controlled by configuration parameters.
  659 \item[dictionary] WORDFILE (``/krb5/kadmind.dict'').    In
  660 KADM5_API_VERSION 2, this is controlled by configuration parameters.
  661 \end{description}
  662 
  663 KADM5 errors are described in $<$kadm5/kadm_err.h$>$, which
  664 is included by $<$kadm5/admin.h$>$.
  665 
  666 The locations of the admin policy and principal databases, as well as
  667 defines and type definitions for the databases, are defined in
  668 $<$kadm5/adb.h$>$.  Some of the defines in that file are:
  669 \begin{description}
  670 \item[admin policy database] POLICY_DB (``/krb5/kadm5_policy.db'').    In
  671 KADM5_API_VERSION 2, this is controlled by configuration parameters.
  672 \item[admin principal database] PRINCIPAL_DB
  673 (``/krb5/ovsec_principal.db'').  In KADM5_API_VERSION 2, this is
  674 controlled by configuration parameters.
  675 \end{description}
  676 
  677 Client applications will link against libkadm5clnt.a and server
  678 programs against libkadm5srv.a.  Client applications must also link
  679 against: libgssapi_krb5.a, libkrb5.a, libcrypto.a, libgssrpc.a,
  680 libcom_err.a, and libdyn.a.  Server applications must also link
  681 against: libkdb5.a, libkrb5.a, libcrypto.a, libgssrpc.a, libcom_err.a,
  682 and libdyn.a.
  683 
  684 \section{Error Codes}
  685 
  686 The error codes that can be returned by admin functions are listed
  687 below.  Error codes indicated with a ``*'' can be returned by every
  688 admin function and always have the same meaning; these codes are
  689 omitted from the list presented with each function.  
  690 
  691 The admin system guarantees that a function that returns an error code
  692 has no other side effect.
  693 
  694 The Admin system will use \v{com_err} for error codes.  Note that this
  695 means \v{com_err} codes may be returned from functions that the admin
  696 routines call (e.g. the kerberos library). Callers should not expect
  697 that only KADM5 errors will be returned.  The Admin system error code
  698 table name will be ``ovk'', and the offsets will be the same as the
  699 order presented here. As mentioned above, the error table include file
  700 will be $<$kadm5/kadm_err.h$>$.
  701 
  702 Note that these error codes are also used as protocol error code
  703 constants and therefore must not change between product releases.
  704 Additional codes should be added at the end of the list, not in the
  705 middle.  The integer value of KADM5_FAILURE is 43787520; the
  706 remaining values are assigned in sequentially increasing order.
  707 
  708 \begin{description}
  709 \item[* KADM5_FAILURE] Operation failed for unspecified reason
  710 \item[* KADM5_AUTH_GET] Operation requires ``get'' privilege
  711 \item[* KADM5_AUTH_ADD] Operation requires ``add'' privilege
  712 \item[* KADM5_AUTH_MODIFY] Operation requires ``modify'' privilege
  713 \item[* KADM5_AUTH_DELETE] Operation requires ``delete'' privilege
  714 \item[* KADM5_AUTH_INSUFFICIENT] Insufficient authorization for
  715 operation
  716 \item[* KADM5_BAD_DB] Database inconsistency detected
  717 \item[KADM5_DUP] Principal or policy already exists
  718 \item[KADM5_RPC_ERROR] Communication failure with server
  719 \item[KADM5_NO_SRV] No administration server found for realm
  720 \item[KADM5_BAD_HIST_KEY] Password history principal key version
  721 mismatch
  722 \item[KADM5_NOT_INIT] Connection to server not initialized
  723 \item[KADM5_UNK_PRINC]  Principal does not exist
  724 \item[KADM5_UNK_POLICY] Policy does not exist
  725 \item[KADM5_BAD_MASK] Invalid field mask for operation
  726 \item[KADM5_BAD_CLASS] Invalid number of character classes
  727 \item[KADM5_BAD_LENGTH] Invalid password length
  728 \item[KADM5_BAD_POLICY] Illegal policy name
  729 \item[KADM5_BAD_PRINCIPAL] Illegal principal name.
  730 \item[KADM5_BAD_AUX_ATTR] Invalid auxillary attributes
  731 \item[KADM5_BAD_HISTORY] Invalid password history count
  732 \item[KADM5_BAD_MIN_PASS_LIFE] Password minimum life is greater
  733 then password maximum life
  734 \item[KADM5_PASS_Q_TOOSHORT] Password is too short
  735 \item[KADM5_PASS_Q_CLASS] Password does not contain enough
  736 character classes
  737 \item[KADM5_PASS_Q_DICT] Password is in the password dictionary
  738 \item[KADM5_PASS_REUSE] Cannot resuse password
  739 \item[KADM5_PASS_TOOSOON] Current password's minimum life has not
  740 expired
  741 \item[KADM5_POLICY_REF] Policy is in use
  742 \item[KADM5_INIT] Connection to server already initialized
  743 \item[KADM5_BAD_PASSWORD] Incorrect password
  744 \item[KADM5_PROTECT_PRINCIPAL] Cannot change protected principal
  745 \item[* KADM5_BAD_SERVER_HANDLE] Programmer error!  Bad Admin server handle
  746 \item[* KADM5_BAD_STRUCT_VERSION] Programmer error!  Bad API structure version
  747 \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)
  748 \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)
  749 \item[* KADM5_BAD_API_VERSION] Programmer error!  Bad API version
  750 \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)
  751 \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)
  752 \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)
  753 \item[* KADM5_NEW_SERVER_API_VERSION] API version specified by
  754 application is unknown to server (to fix, obtain and install newest
  755 Admin Server)
  756 \item[KADM5_SECURE_PRINC_MISSING] Database error! Required principal missing
  757 \item[KADM5_NO_RENAME_SALT] The salt type of the specified principal
  758 does not support renaming
  759 \item[KADM5_BAD_CLIENT_PARAMS] Illegal configuration parameter for
  760 remote KADM5 client
  761 \item[KADM5_BAD_SERVER_PARAMS] Illegal configuration parameter for
  762 local KADM5 client.
  763 \item[KADM5_AUTH_LIST] Operation requires ``list'' privilege
  764 \item[KADM5_AUTH_CHANGEPW] Operation requires ``change-password'' privilege
  765 \item[KADM5_BAD_TL_TYPE] Programmer error!  Illegal tagged data list
  766 element type
  767 \item[KADM5_MISSING_CONF_PARAMS] Required parameters in kdc.conf missing
  768 \item[KADM5_BAD_SERVER_NAME] Bad krb5 admin server hostname
  769 \item[KADM5_AUTH_SETKEY] Operation requires ``set-key'' privilege
  770 \item[KADM5_SETKEY_DUP_ENCTYPES] Multiple values for single or folded enctype
  771 \end{description}
  772 
  773 \section{Authentication and Authorization}
  774 \label{sec:auth}
  775 
  776 Two Kerberos principals exist for use in communicating with the Admin
  777 system: kadmin/admin and kadmin/changepw.  Both principals
  778 have the KRB5_KDB_DISALLOW_TGT_BASED bit set in their attributes so
  779 that service tickets for them can only be acquired via a
  780 password-based (AS_REQ) request.  Additionally, kadmin/changepw
  781 has the KRB5_KDB_PWCHANGE_SERVICE bit set so that a principal with an
  782 expired password can still obtain a service ticket for it.
  783 
  784 The Admin system accepts requests that are authenticated to either
  785 service principal, but the sets of operations that can be performed by
  786 a request authenticated to each service are different.  In particular,
  787 only the functions chpass_principal, randkey_principal, get_principal,
  788 and get_policy can be performed by a request authenticated to the
  789 kadmin/changepw service, and they can only be performed when the
  790 target principal of the operation is the same as the authenticated
  791 client principal; the function semantics descriptions below give the
  792 precise details.  This means that administrative operations can only
  793 be performed when authenticated to the kadmin/admin service.  The
  794 reason for this distinction is that tickets for kadmin/changepw can be
  795 acquired with an expired password, and the KADM system does not want
  796 to allow an administrator with an expired password to perform
  797 administrative operations on arbitrary principals.
  798 
  799 Each Admin API operation authenticated to the kadmin/admin service
  800 requires a specific authorization to run.  This version uses a simple
  801 named privilege system with the following names and meanings:
  802 
  803 \begin{description}
  804 \item[Get] Able to examine the attributes (NOT key data) of principals
  805 and policies. 
  806 \item[Add] Able to add principals and policies.
  807 \item[Modify] Able to modify attributes of existing principals and
  808 policies; this does not include changing passwords.
  809 \item[Delete] Able to remove principals and policies.
  810 \item[List] Able to retrieve a list of principals and policies.
  811 \item[Changepw] Able to change the password of principals.
  812 \item[Setkey] Able to set principal keys directly.
  813 \end{description}
  814 
  815 Privileges are specified via an external configuration file on the
  816 Kerberos master server.
  817 
  818 Table \ref{tab:func-overview} summarizes the authorization
  819 requirements of each function.  Additionally, each API function
  820 description identifies the privilege required to perform it.  The
  821 Authorization checks only happen if you are using the RPC mechanism.
  822 If you are using the server-side API functions locally on the admin
  823 server, the only authorization check is if you can access the
  824 approporiate local files.
  825 
  826 \section{Functions}
  827 
  828 \subsection{Overview}
  829 
  830 The functions provided by the Admin API, and the authorization they
  831 require, are listed in the table \ref{tab:func-overview}.  The
  832 ``kadm5_'' prefix has been removed from each function name.
  833 
  834 The function semantics in the following sections omit details that are
  835 the same for every function.
  836 
  837 \begin{itemize}
  838 \item The effects of every function are atomic.
  839 
  840 \item Every function performs an authorization check and returns
  841 the appropriate KADM5_AUTH_* error code if the caller does not
  842 have the required privilege.  No other information or error code is
  843 ever returned to an unauthorized user.
  844 
  845 \item Every function checks its arguments for NULL pointers or other
  846 obviously invalid values, and returns EINVAL if any are detected.
  847 
  848 \item Any function that performs a policy check uses the policy named
  849 in the principal's policy field.  If the POLICY bit is not set in the
  850 principal's aux_attributes field, however, the principal has no
  851 policy, so the policy check is not performed.
  852 
  853 \item Unless otherwise specified, all functions return KADM5_OK.
  854 \end{itemize}
  855 
  856 \begin{table}[htbp]
  857 \caption{Summary of functions and required authorization.}
  858 \label{tab:func-overview}
  859 \begin{tabular}{@{}llp{3.24in}}
  860 \\
  861 {\bf Function Name} & {\bf Authorization} & {\bf Operation} \\
  862 
  863 init & none & Open a connection with the kadm5 library.  OBSOLETE
  864 but still provided---use init_with_password instead. \\
  865 init_with_password & none & Open a connection with the kadm5
  866 library using a password to obtain initial credentials. \\
  867 init_with_skey & none & Open a connection with the kadm5 library
  868 using the keytab entry to obtain initial credentials. \\
  869 destroy & none & Close the connection with the kadm5 library. \\
  870 flush & none & Flush all database changes to disk; no-op when called
  871 remotely. \\
  872 create_principal & add & Create a new principal. \\
  873 delete_principal & delete & Delete a principal. \\
  874 modify_principal & modify & Modify the attributes of an existing
  875         principal (not password). \\
  876 rename_principal & add and delete & Rename a principal. \\
  877 get_principal & get\footnotemark & Retrieve a principal. \\
  878 get_principals & list & Retrieve some or all principal names. \\
  879 chpass_principal & changepw\footnotemark[\thefootnote] &
  880          Change a principal's password. \\
  881 chpass_principal_util & changepw\footnotemark[\thefootnote] & Utility wrapper around chpass_principal. \\
  882 randkey_principal & changepw\footnotemark[\thefootnote] &
  883         Randomize a principal's key. \\
  884 setkey_principal & setkey & Explicitly set a principal's keys. \\
  885 decrypt_key & none & Decrypt a principal key. \\
  886 create_policy & add & Create a new policy. \\
  887 delete_policy & delete & Delete a policy. \\
  888 modify_policy & modify & Modify the attributes of a policy. \\
  889 get_policy & get & Retrieve a policy. \\
  890 get_policies & list & Retrieve some or all policy names. \\
  891 free_principal_ent & none & Free the memory associated with an
  892                 kadm5_principal_ent_t. \\
  893 free_policy_ent & none & Free the memory associated with an
  894                 kadm5_policy_ent_t. \\
  895 get_privs & none & Return the caller's admin server privileges.
  896 \end{tabular}
  897 \end{table}
  898 \footnotetext[\thefootnote]{These functions also allow a principal to
  899 perform the operation on itself; see the function's semantics for
  900 details.}
  901 
  902 \subsection{kadm5_init_*}
  903 
  904 In KADM5_API_VERSION 1:
  905 
  906 \begin{verbatim}
  907 kadm5_ret_t kadm5_init_with_password(char *client_name, char *pass,
  908                                  char *service_name, char *realm,
  909                                  unsigned long struct_version,
  910                                  unsigned long api_version,
  911                                  void **server_handle)
  912 
  913 kadm5_ret_t kadm5_init_with_skey(char *client_name, char *keytab,
  914                                  char *service_name, char *realm,
  915                                  unsigned long struct_version,
  916                                  unsigned long api_version,
  917                                  void **server_handle)
  918 
  919 kadm5_ret_t kadm5_init(char *client_name, char *pass,
  920                                  char *service_name, char *realm,
  921                                  unsigned long struct_version,
  922                                  unsigned long api_version,
  923                                  void **server_handle)
  924 \end{verbatim}
  925 
  926 In KADM5_API_VERSION 2:
  927 
  928 \begin{verbatim}
  929 kadm5_ret_t kadm5_init_with_password(char *client_name, char *pass,
  930                                  char *service_name,
  931                                  kadm5_config_params *realm_params,
  932                                  unsigned long struct_version,
  933                                  unsigned long api_version,
  934                                  void **server_handle)
  935 
  936 kadm5_ret_t kadm5_init_with_skey(char *client_name, char *keytab,
  937                                  char *service_name,
  938                                  kadm5_config_params *realm_params,
  939                                  unsigned long struct_version,
  940                                  unsigned long api_version,
  941                                  void **server_handle)
  942 
  943 kadm5_ret_t kadm5_init(char *client_name, char *pass,
  944                                  char *service_name,
  945                                  kadm5_config_params *realm_params,
  946                                  unsigned long struct_version,
  947                                  unsigned long api_version,
  948                                  void **server_handle)
  949 
  950 kadm5_ret_t kadm5_init_with_creds(char *client_name,
  951                                   krb5_ccache ccache,
  952                                   char *service_name,
  953                                   kadm5_config_params *params,
  954                                   krb5_ui_4 struct_version,
  955                                   krb5_ui_4 api_version,
  956                                   void **server_handle)
  957 \end{verbatim}
  958 
  959 AUTHORIZATION REQUIRED: none
  960 
  961 NOTE: kadm5_init is an obsolete function provided for backwards
  962 compatibility.  It is identical to kadm5_init_with_password.
  963 
  964 These three functions open a connection to the kadm5 library and
  965 initialize any neccessary state information.  They behave differently
  966 when called from local and remote clients.  
  967 
  968 In KADM5_API_VERSION_2, these functions take a kadm5_config_params
  969 structure instead of a realm name as an argument.  The semantics are
  970 similar: if a NULL pointer is passed for the realm_params argument,
  971 the default realm and default parameters for that realm, as specified
  972 in the krb5 configuration file (e.g. /etc/krb5.conf) are used.  If a
  973 realm_params structure is provided, the fields that are set override
  974 the default values.  If a parameter is specified to the local or
  975 remote libraries that does not apply to that side, an error code
  976 (KADM5_BAD_CLIENT_PARAMS or KADM5_BAD_SERVER_PARAMS) is returned.  See
  977 section \ref{sec:configparams} for a discussion of configuration
  978 parameters.
  979 
  980 For remote clients, the semantics are:
  981 
  982 \begin{enumerate}
  983 \item Initializes all the com_err error tables used by the Admin
  984 system.
  985 
  986 \item Acquires configuration parameters.  In KADM5_API_VERSION_1, all
  987 the defaults specified in the configuration file are used, according
  988 to the realm.  In KADM5_API_VERSION_2, the values in params_in are
  989 merged with the default values.  If an illegal mask value is
  990 specified, KADM5_BAD_CLIENT_PARAMS is returned.
  991 
  992 \item Acquires a Kerberos ticket for the specified service.
  993 
  994 \begin{enumerate}
  995 \item The ticket's client is client_name, which can be any valid
  996 Kerberos principal.  If client_name does not include a realm, the
  997 default realm of the local host is used
  998 \item The ticket's service is service_name@realm.  service_name must
  999 be one of the constants KADM5_ADMIN_SERVICE or
 1000 KADM5_CHANGEPW_SERVICE.
 1001 \item If realm is NULL, client_name's realm is used.
 1002 
 1003 \item For init_with_password, an initial ticket is acquired and
 1004 decoded with the password pass, which must be client_name's password.
 1005 If pass is NULL or an empty string, the user is prompted (via the tty)
 1006 for a password.
 1007 
 1008 \item For init_with_skey, an initial ticket is acquired and decoded
 1009 with client_name's key obtained from the specified keytab.  If keytab
 1010 is NULL or an empty string the default keytab is used.
 1011 
 1012 \item For init_with_creds, ccache must be an open credential cache
 1013 that already has a ticket for the specified client and server.
 1014 Alternatively, if a site chooses to disable the DISALLOW_TGT_BASED
 1015 flag on the admin and changepw principals, the ccache can contain a
 1016 ticket-granting ticket for client_name.
 1017 \end{enumerate}
 1018 
 1019 \item Creates a GSS-API authenticated connection to the Admin server,
 1020 using the just-acquired Kerberos ticket.
 1021 
 1022 \item Verifies that the struct_version and api_version specified by
 1023 the caller are valid and known to the library.
 1024 
 1025 \item Sends the specified api_version to the server.
 1026 
 1027 \item Upon successful completion, fills in server_handle with a handle
 1028 for this connection, to be used in all subsequent API calls.
 1029 \end{enumerate}
 1030 
 1031 The caller should always specify KADM5_STRUCT_VERSION for the
 1032 struct_version argument, a valid and supported API version constant
 1033 for the api_version argument (currently, KADM5_API_VERSION_1 or
 1034 KADM5_API_VERSION_2), and a valid pointer in which the server handle
 1035 will be stored.
 1036 
 1037 If any kadm5_init_* is invoked locally its semantics are:
 1038 
 1039 \begin{enumerate}
 1040 \item Initializes all the com_err error tables used by the Admin
 1041 system.
 1042 
 1043 \item Acquires configuration parameters.  In KADM5_API_VERSION_1, all
 1044 the defaults specified in the configuration file are used, according
 1045 to the realm.  In KADM5_API_VERSION_2, the values in params_in are
 1046 merged with the default values.  If an illegal mask value is
 1047 specified, KADM5_BAD_SERVER_PARAMS is returned.
 1048 
 1049 \item Initializes direct access to the KDC database.  In
 1050 KADM5_API_VERISON_1, if pass (or keytab) is NULL or an empty string,
 1051 reads the master password from the stash file; otherwise, the non-NULL
 1052 password is ignored and the user is prompted for it via the tty.  In
 1053 KADM5_API_VERSION_2, if the MKEY_FROM_KEYBOARD parameter mask is set
 1054 and the value is non-zero, reads the master password from the user via
 1055 the tty; otherwise, the master key is read from the stash file.
 1056 Calling init_with_skey or init_with_creds with the MKEY_FROM_KEYBOARD
 1057 mask set with a non-zero field is illegal, and calling them without
 1058 the mask set is exactly like calling init_with_password.
 1059 
 1060 \item Initializes the dictionary (if present) for dictionary checks.
 1061 
 1062 \item Parses client_name as a Kerberos principal.  client_name should
 1063 usually be specified as the name of the program.
 1064 
 1065 \item Verifies that the struct_version and api_version specified by
 1066 the caller are valid.
 1067 
 1068 \item Fills in server_handle with a handle containing all state
 1069 information (version numbers and client name) for this ``connection.''
 1070 \end{enumerate}
 1071 The service_name argument is not used.
 1072 
 1073 RETURN CODES: 
 1074 
 1075 \begin{description}
 1076 \item[KADM5_NO_SRV] No Admin server can be found for the
 1077 specified realm.
 1078 
 1079 \item[KADM5_RPC_ERROR] The RPC connection to the server cannot be
 1080 initiated.
 1081 
 1082 \item[KADM5_BAD_PASSWORD] Incorrect password.
 1083 
 1084 \item[KADM5_SECURE_PRINC_MISSING] The principal
 1085 KADM5_ADMIN_SERVICE or KADM5_CHANGEPW_SERVICE does not
 1086 exist.  This is a special-case replacement return code for ``Server
 1087 not found in database'' for these required principals.
 1088 
 1089 \item[KADM5_BAD_CLIENT_PARAMS] A field in the parameters mask was
 1090 specified to the remote client library that is not legal for remote
 1091 clients.
 1092 
 1093 \item[KADM5_BAD_SERVER_PARAMS] A field in the parameters mask was
 1094 specified to the local client library that is not legal for local
 1095 clients.
 1096 \end{description}
 1097 
 1098 \subsection{kadm5_flush}
 1099 
 1100 \begin{verbatim}
 1101 kadm5_ret_t kadm5_flush(void *server_handle)
 1102 \end{verbatim}
 1103 
 1104 AUTHORIZATION REQUIRED: none
 1105 
 1106 Flush all changes to the Kerberos databases, leaving the connection to
 1107 the Admin API open.  This function behaves differently when called by
 1108 local and remote clients.
 1109 
 1110 For local clients, the function closes and reopens the Kerberos
 1111 database with krb5_db_fini() and krb5_db_init().
 1112 Although it is unlikely, either of these functions
 1113 could return errors; in that case, this function calls
 1114 kadm5_destroy and returns the error code.  Therefore, if
 1115 kadm5_flush does not return KADM5_OK, the connection to the
 1116 Admin server has been terminated and, in principle, the databases
 1117 might be corrupt.
 1118 
 1119 For remote clients, the function is a no-op.
 1120 
 1121 \subsection{kadm5_destroy}
 1122 
 1123 \begin{verbatim}
 1124 kadm5_ret_t kadm5_destroy(void *server_handle)
 1125 \end{verbatim}
 1126 
 1127 AUTHORIZATION REQUIRED: none
 1128 
 1129 Close the connection to the Admin server and releases all related
 1130 resources.  This function behaves differently when called by local and
 1131 remote clients.
 1132 
 1133 For remote clients, the semantics are:
 1134 
 1135 \begin{enumerate}
 1136 \item Destroy the temporary credential cache created by
 1137 kadm5_init.
 1138 
 1139 \item Tear down the GSS-API context negotiated with the server.
 1140 
 1141 \item Close the RPC connection.
 1142 
 1143 \item Free storage space associated with server_handle, after erasing
 1144 its magic number so it won't be mistaken for a valid handle by the
 1145 library later.
 1146 \end{enumerate}
 1147 
 1148 For local clients, this function just frees the storage space
 1149 associated with server_handle after erasing its magic number.
 1150 
 1151 RETURN CODES:
 1152 
 1153 \subsection{kadm5_create_principal}
 1154 
 1155 \begin{verbatim}
 1156 kadm5_ret_t
 1157 kadm5_create_principal(void *server_handle,
 1158                             kadm5_principal_ent_t princ, u_int32 mask,
 1159                             char *pw);
 1160 \end{verbatim}
 1161 
 1162 AUTHORIZATION REQUIRED: add
 1163 
 1164 \begin{enumerate}
 1165 
 1166 \item Return KADM5_BAD_MASK if the mask is invalid.
 1167 \item If the named principal exists, return KADM5_DUP.
 1168 \item If the POLICY bit is set and the named policy does not exist,
 1169 return KADM5_UNK_POLICY.
 1170 \item If KADM5_POLICY bit is set in aux_attributes check to see if
 1171 the password does not meets quality standards, return the appropriate
 1172 KADM5_PASS_Q_* error code if it fails.
 1173 \item Store the principal, set the key; see section \ref{sec:keys}.
 1174 \item If the POLICY bit is set, increment the named policy's reference
 1175 count by one.
 1176 
 1177 \item Set the pw_expiration field.
 1178 \begin{enumerate}
 1179 \item If the POLICY bit is set in mask, then if pw_max_life is non-zero,
 1180 set pw_expiration to now + pw_maxlife, otherwise set pw_max_life to
 1181 never.
 1182 \item If the PW_EXPIRATION bit is set in mask, set pw_expiration to
 1183 the requested value, overriding the value set above.
 1184 \end{enumerate}
 1185 NOTE: This is a change from the original semantics, in which policy
 1186 expiration was enforced even on administrators.  The old semantics are
 1187 not preserved, even for version 1 callers, because this is a
 1188 server-specific policy decision; besides, the new semantics are less
 1189 restrictive, so all previous callers should continue to function
 1190 properly.
 1191 
 1192 \item Set mod_date to now and set mod_name to caller.
 1193 \item Set last_pwd_change to now.
 1194 \end{enumerate}
 1195 
 1196 RETURN CODES:
 1197 
 1198 \begin{description}
 1199 \item[KADM5_BAD_MASK] The field mask is invalid for a create
 1200 operation.
 1201 \item[KADM5_DUP] Principal already exists.
 1202 \item[KADM5_UNK_POLICY] Policy named in entry does not exist.
 1203 \item[KADM5_PASS_Q_*] Specified password does not meet policy
 1204 standards.
 1205 \end{description}
 1206 
 1207 \subsection{kadm5_delete_principal}
 1208 
 1209 \begin{verbatim}
 1210 kadm5_ret_t
 1211 kadm5_delete_principal(void *server_handle, krb5_principal princ);
 1212 \end{verbatim}
 1213 
 1214 AUTHORIZATION REQUIRED: delete 
 1215 
 1216 \begin{enumerate}
 1217 \item Return KADM5_UNK_PRINC if the principal does not exist.
 1218 \item If the POLICY bit is set in aux_attributes, decrement the named
 1219 policy's reference count by one.
 1220 \item Delete principal.
 1221 \end{enumerate}
 1222 
 1223 RETURN CODES: 
 1224 
 1225 \begin{description}
 1226 \item[KADM5_UNK_PRINC] Principal does not exist.
 1227 \end{description}
 1228 
 1229 \subsection{kadm5_modify_principal}
 1230 
 1231 \begin{verbatim}
 1232 kadm5_ret_t
 1233 kadm5_modify_principal(void *server_handle,
 1234                             kadm5_principal_ent_t princ, u_int32 mask);
 1235 \end{verbatim}
 1236 
 1237 Modify the attributes of the principal named in
 1238 kadm5_principal_ent_t. This does not allow the principal to be
 1239 renamed or for its password to be changed.
 1240 
 1241 AUTHORIZATION REQUIRED: modify
 1242 
 1243 Although a principal's pw_expiration is usually computed based on its
 1244 policy and the time at which it changes its password, this function
 1245 also allows it to be specified explicitly.  This allows an
 1246 administrator, for example, to create a principal and assign it to a
 1247 policy with a pw_max_life of one month, but to declare that the new
 1248 principal must change its password away from its initial value
 1249 sometime within the first week.
 1250 
 1251 \begin{enumerate}
 1252 \item Return KADM5_UNK_PRINC if the principal does not exist.
 1253 \item Return KADM5_BAD_MASK if the mask is invalid.
 1254 \item If POLICY bit is set but the new policy does not exist, return
 1255 KADM5_UNK_POLICY.
 1256 \item If either the POLICY or POLICY_CLR bits are set, update the
 1257 corresponding bits in aux_attributes.
 1258 
 1259 \item Update policy reference counts.
 1260 \begin{enumerate}
 1261 \item If the POLICY bit is set, then increment policy count on new
 1262 policy.
 1263 \item If the POLICY or POLICY_CLR bit is set, and the POLICY bit in
 1264 aux_attributes is set, decrement policy count on old policy.
 1265 \end{enumerate}
 1266 
 1267 \item Set pw_expiration appropriately.  pw_expiration can change if:
 1268 the POLICY bit is set in mask, so the principal is changing to a
 1269 policy (either from another policy or no policy); the POLICY_CLR bit
 1270 is set in mask, so the principal is changing to no policy; or
 1271 PW_EXPIRATION is set.
 1272 \begin{enumerate}
 1273 \item If the POLICY bit is set in mask, set pw_expiration to
 1274 last_pwd_change + pw_max_life if pw_max_life is non-zero, otherwise
 1275 set pw_expiration to never.
 1276 \item If the POLICY_CLR biti s set in mask, set pw_expiration to
 1277 never.
 1278 \item If PW_EXPIRATION is set, set pw_expiration to the requested
 1279 value, overriding the value from the previous two cases.  NOTE: This
 1280 is a change from the original semantics, in which policy expiration
 1281 was enforced even on administrators.  The old semantics are not
 1282 preserved, even for version 1 callers, because this is a
 1283 server-specific policy decision; besides, the new semantics are less
 1284 restrictive, so all previous callers should continue to function
 1285 properly.
 1286 \end{enumerate}
 1287 
 1288 % Here is the previous, and confusing, text of pw_expiration semantics:
 1289 %\begin{enumerate}
 1290 %\item If the POLICY bit is not set in aux_attributes, then
 1291 %\begin{enumerate}
 1292 %\item if the PW_EXPIRATION bit is set, set pw_expiration to the given
 1293 %value, else
 1294 %\item set pw_expiration to never.
 1295 %\end{enumerate}
 1296 %\item Otherwise, if the PW_EXPIRATION bit is set, set pw_expiration to
 1297 %the sooner of the given value and last_pwd_change + pw_max_life.
 1298 %\item Otherwise, set pw_expiration to last_pwd_change + pw_max_life.
 1299 %\end{enumerate}
 1300 
 1301 \item Update the remaining fields specified in the mask.
 1302 \item Update mod_name field to caller and mod_date to now.
 1303 \end{enumerate}
 1304 
 1305 RETURN CODES:
 1306 
 1307 \begin{description}
 1308 \item[KADM5_UNK_PRINC] Entry does not exist.
 1309 \item[KADM5_BAD_MASK] The mask is not valid for a modify
 1310 operation.
 1311 \item[KADM5_UNK_POLICY] The POLICY bit is set but the new
 1312 policy does not exist.
 1313 \item[KADM5_BAD_TL_TYPE] The KADM5_TL_DATA bit is set in mask, and the
 1314 given tl_data list contains an element whose type is less than 256.
 1315 \end{description}
 1316 
 1317 \subsection{kadm5_rename_principal}
 1318 
 1319 \begin{verbatim}
 1320 kadm5_ret_t
 1321 kadm5_rename_principal(void *server_handle, krb5_principal source,
 1322                             krb5_principal target);
 1323 \end{verbatim}
 1324 
 1325 AUTHORIZATION REQUIRED: add and delete
 1326 
 1327 \begin{enumerate}
 1328 \item Check to see if source principal exists, if not return
 1329 KADM5_UNK_PRINC error. 
 1330 \item Check to see if target exists, if so return KADM5_DUP error.
 1331 \item Create the new principal named target, then delete the old
 1332 principal named source.  All of target's fields will be the same as
 1333 source's fields, except that mod_name and mod_date will be updated to
 1334 reflect the current caller and time.
 1335 \end{enumerate}
 1336 
 1337 Note that since the principal name may have been used as the salt for
 1338 the principal's key, renaming the principal may render the principal's
 1339 current password useless; with the new salt, the key generated by
 1340 string-to-key on the password will suddenly be different.  Therefore,
 1341 an application that renames a principal must also require the user to
 1342 specify a new password for the principal (and administrators should
 1343 notify the affected party).
 1344 
 1345 Note also that, by the same argument, renaming a principal will
 1346 invalidate that principal's password history information; since the
 1347 salt will be different, a user will be able to select a previous
 1348 password without error.
 1349 
 1350 RETURN CODES: 
 1351 
 1352 \begin{description}
 1353 \item[KADM5_UNK_PRINC] Source principal does not exist.
 1354 \item[KADM5_DUP] Target principal already exist.
 1355 \end{description}
 1356 
 1357 \subsection{kadm5_chpass_principal}
 1358 
 1359 \begin{verbatim}
 1360 kadm5_ret_t
 1361 kadm5_chpass_principal(void *server_handle, krb5_principal princ,
 1362                             char *pw);
 1363 \end{verbatim}
 1364 
 1365 AUTHORIZATION REQUIRED: changepw, or the calling principal being the
 1366 same as the princ argument.  If the request is authenticated to the
 1367 kadmin/changepw service, the changepw privilege is disregarded.
 1368 
 1369 Change a principal's password.   See section \ref{sec:keys} for a
 1370 description of how the keys are determined.
 1371 
 1372 This function enforces password policy and dictionary checks.  If the new
 1373 password specified is in the password dictionary, and the policy bit is set
 1374 KADM5_PASS_DICT is returned.  If the principal's POLICY bit is set in
 1375 aux_attributes, compliance with each of the named policy fields is verified
 1376 and an appropriate error code is returned if verification fails.
 1377 
 1378 Note that the policy checks are only be performed if the POLICY bit is
 1379 set in the principal's aux_attributes field.
 1380 
 1381 \begin{enumerate}
 1382 \item Make sure principal exists, if not return KADM5_UNK_PRINC error.
 1383 \item If caller does not have modify privilege, (now - last_pwd_change) $<$
 1384 pw_min_life, and the KRB5_KDB_REQUIRES_PWCHANGE bit is not set in the
 1385 principal's attributes, return KADM5_PASS_TOOSOON.
 1386 \item If the principal your are trying to change is kadmin/history
 1387 return KADM5_PROTECT_PRINCIPAL.
 1388 \item If the password does not meet the quality
 1389 standards, return the appropriate KADM5_PASS_Q_* error code.
 1390 \item Convert password to key; see section \ref{sec:keys}.
 1391 \item If the new key is in the principal's password history, return
 1392 KADM5_PASS_REUSE.
 1393 \item Store old key in history.
 1394 \item Update principal to have new key.
 1395 \item Increment principal's key version number by one.
 1396 \item If the POLICY bit is set, set pw_expiration to now +
 1397 max_pw_life.  If the POLICY bit is not set, set pw_expiration to
 1398 never.
 1399 \item If the KRB5_KDB_REQUIRES_PWCHANGE bit is set in the principal's
 1400 attributes, clear it.
 1401 \item Update last_pwd_change and mod_date to now, update mod_name to
 1402 caller.
 1403 \end{enumerate}
 1404 
 1405 RETURN CODES:
 1406 
 1407 \begin{description}
 1408 \item[KADM5_UNK_PRINC] Principal does not exist.
 1409 \item[KADM5_PASS_Q_*] Requested password does not meet quality
 1410 standards. 
 1411 \item[KADM5_PASS_REUSE] Requested password is in user's
 1412 password history. 
 1413 \item[KADM5_PASS_TOOSOON] Current password has not reached minimum life
 1414 \item[KADM5_PROTECT_PRINCIPAL] Cannot change the password of a special principal
 1415 \end{description}
 1416 
 1417 
 1418 \subsection{kadm5_chpass_principal_util}
 1419 
 1420 \begin{verbatim}
 1421 kadm5_ret_t
 1422 kadm5_chpass_principal_util(void *server_handle, krb5_principal princ,
 1423                                  char *new_pw, char **pw_ret,
 1424                                  char *msg_ret);
 1425 \end{verbatim}
 1426 
 1427 AUTHORIZATION REQUIRED: changepw, or the calling principal being the
 1428 same as the princ argument.  If the request is authenticated to the
 1429 kadmin/changepw service, the changepw privilege is disregarded.
 1430 
 1431 This function is a wrapper around kadm5_chpass_principal. It can
 1432 read a new password from a user, change a principal's password, and
 1433 return detailed error messages.  msg_ret should point to a char buffer
 1434 in the caller's space of sufficient length for the error messages
 1435 described below. 1024 bytes is recommended.  It will also return the
 1436 new password to the caller if pw_ret is non-NULL.
 1437 
 1438 \begin{enumerate}
 1439 \item If new_pw is NULL, this routine will prompt the user for the new
 1440 password (using the strings specified by KADM5_PW_FIRST_PROMPT and
 1441 KADM5_PW_SECOND_PROMPT) and read (without echoing) the password input.
 1442 Since it is likely that this will simply call krb5_read_password only
 1443 terminal-based applications will make use of the password reading
 1444 functionality. If the passwords don't match the string ``New passwords do
 1445 not match - password not changed.'' will be copied into msg_ret, and the
 1446 error code KRB5_LIBOS_BADPWDMATCH will be returned.  For other errors that
 1447 ocurr while reading the new password, copy the string ``<com_err message$>$
 1448 occurred while trying to read new password.'' followed by a blank line and
 1449 the string specified by CHPASS_UTIL_PASSWORD_NOT_CHANGED into msg_ret and
 1450 return the error code returned by krb5_read_password.
 1451 
 1452 \item If pw_ret is non-NULL, and the password was prompted, set *pw_ret to
 1453 point to a static buffer containing the password.  If pw_ret is non-NULL
 1454 and the password was supplied, set *pw_ret to the supplied password.
 1455 
 1456 \item Call kadm5_chpass_principal with princ, and new_pw.
 1457 
 1458 \item If successful copy the string specified by CHPASS_UTIL_PASSWORD_CHANGED
 1459 into msg_ret and return zero.
 1460 
 1461 \item For a policy related failure copy the appropriate message (from below) 
 1462 followed by a newline and ``Password not changed.'' into msg_ret
 1463 filling in the parameters from the principal's policy information. If
 1464 the policy information cannot be obtained copy the generic message if
 1465 one is specified below. Return the error code from
 1466 kadm5_chpass_principal.
 1467 
 1468 Detailed messages:
 1469 \begin{description}
 1470 
 1471 \item[PASS_Q_TOO_SHORT]
 1472 New password is too short. Please choose a
 1473 password which is more than $<$pw-min-len$>$ characters.
 1474 
 1475 \item[PASS_Q_TOO_SHORT - generic]
 1476 New password is too short. Please choose a longer password.
 1477 
 1478 \item[PASS_REUSE]
 1479 New password was used previously. Please choose a
 1480 different password.
 1481 
 1482 \item[PASS_Q_CLASS]
 1483 New password does not have enough character classes. Classes include
 1484 lower class letters, upper case letters, digits, punctuation and all
 1485 other characters.  Please choose a password with at least
 1486 $<$min-classes$>$ character classes.
 1487 
 1488 \item[PASS_Q_CLASS - generic]
 1489 New password does not have enough character classes. Classes include
 1490 lower class letters, upper case letters, digits, punctuation and all
 1491 other characters. 
 1492 
 1493 \item[PASS_Q_DICT] 
 1494 New password was found in a dictionary of possible passwords and
 1495 therefore may be easily guessed.  Please choose another password. See
 1496 the kpasswd man page for help in choosing a good password.
 1497 
 1498 \item[PASS_TOOSOON]
 1499 Password cannot be changed because it was changed too recently. Please
 1500 wait until $<$last-pw-change+pw-min-life$>$ before you change it. If you
 1501 need to change your password before then, contact your system
 1502 security administrator.
 1503 
 1504 \item[PASS_TOOSOON - generic]
 1505 Password cannot be changed because it was changed too recently. If you
 1506 need to change your now please contact your system security
 1507 administrator.
 1508 \end{description}
 1509 
 1510 \item For other errors copy the string ``$<$com_err message$>$
 1511 occurred while trying to change password.'' following by a blank line
 1512 and ``Password not changed.'' into msg_ret. Return the error code
 1513 returned by kadm5_chpass_principal.
 1514 \end{enumerate}
 1515 
 1516 
 1517 RETURN CODES:
 1518 
 1519 \begin{description}
 1520 \item[KRB5_LIBOS_BADPWDMATCH] Typed new passwords did not match.
 1521 \item[KADM5_UNK_PRINC] Principal does not exist.
 1522 \item[KADM5_PASS_Q_*] Requested password does not meet quality
 1523 standards. 
 1524 \item[KADM5_PASS_REUSE] Requested password is in user's
 1525 password history. 
 1526 \item[KADM5_PASS_TOOSOON] Current password has not reached minimum
 1527 life. 
 1528 \end{description}
 1529 
 1530 \subsection{kadm5_randkey_principal}
 1531 
 1532 In KADM5_API_VERSION_1:
 1533 
 1534 \begin{verbatim}
 1535 kadm5_ret_t
 1536 kadm5_randkey_principal(void *server_handle, krb5_principal princ,
 1537                              krb5_keyblock **new_key)
 1538 \end{verbatim}
 1539 
 1540 In KADM5_API_VERSION_2:
 1541 
 1542 \begin{verbatim}
 1543 kadm5_ret_t
 1544 kadm5_randkey_principal(void *server_handle, krb5_principal princ,
 1545                         krb5_keyblock **new_keys, int *n_keys)
 1546 \end{verbatim}
 1547 
 1548 AUTHORIZATION REQUIRED: changepw, or the calling principal being the
 1549 same as the princ argument.  If the request is authenticated to the
 1550 kadmin/changepw service, the changepw privilege is disregarded.
 1551 
 1552 Generate and assign a new random key to the named principal, and
 1553 return the generated key in allocated storage.  In
 1554 KADM5_API_VERSION_2, multiple keys may be generated and returned as an
 1555 array, and n_new_keys is filled in with the number of keys generated.
 1556 See section \ref{sec:keys} for a description of how the keys are
 1557 chosen.  In KADM5_API_VERSION_1, the caller must free the returned
 1558 krb5_keyblock * with krb5_free_keyblock.  In KADM5_API_VERSION_2, the
 1559 caller must free each returned keyblock with krb5_free_keyblock.
 1560 
 1561 If the principal's POLICY bit is set in aux_attributes and the caller does
 1562 not have modify privilege , compliance with the password minimum life
 1563 specified by the policy is verified and an appropriate error code is returned
 1564 if verification fails. 
 1565 
 1566 \begin{enumerate}
 1567 \item If the principal does not exist, return KADM5_UNK_PRINC.
 1568 \item If caller does not have modify privilege, (now - last_pwd_change) $<$
 1569 pw_min_life, and the KRB5_KDB_REQUIRES_PWCHANGE bit is not set in the
 1570 principal's attributes, return KADM5_PASS_TOOSOON.
 1571 \item If the principal you are trying to change is kadmin/history return
 1572 KADM5_PROTECT_PRINCIPAL.
 1573 \item Store old key in history.
 1574 \item Update principal to have new key.
 1575 \item Increment principal's key version number by one.
 1576 \item If the POLICY bit in aux_attributes is set, set pw_expiration to
 1577 now + max_pw_life.
 1578 \item If the KRB5_KDC_REQUIRES_PWCHANGE bit is set in the principal's
 1579 attributes, clear it.
 1580 \item Update last_pwd_change and mod_date to now, update mod_name to
 1581 caller.
 1582 \end{enumerate}
 1583 
 1584 RETURN CODES:
 1585 
 1586 \begin{description}
 1587 \item[KADM5_UNK_PRINC] Principal does not exist.
 1588 \item[KADM5_PASS_TOOSOON] The minimum lifetime for the current
 1589 key has not expired.
 1590 \item[KADM5_PROTECT_PRINCIPAL] Cannot change the password of a special
 1591 principal
 1592 \end{description}
 1593 
 1594 This function can also be used as part of a sequence to create a new
 1595 principal with a random key.  The steps to perform the operation
 1596 securely are
 1597 
 1598 \begin{enumerate}
 1599 \item Create the principal with kadm5_create_principal with a
 1600 random password string and with the KRB5_KDB_DISALLOW_ALL_TIX bit set
 1601 in the attributes field.
 1602 
 1603 \item Randomize the principal's key with kadm5_randkey_principal.
 1604 
 1605 \item Call kadm5_modify_principal to reset the
 1606 KRB5_KDB_DISALLOW_ALL_TIX bit in the attributes field.
 1607 \end{enumerate}
 1608 
 1609 The three steps are necessary to ensure secure creation.  Since an
 1610 attacker might be able to guess the initial password assigned by the
 1611 client program, the principal must be disabled until the key can be
 1612 truly randomized.
 1613 
 1614 \subsection{kadm5_setkey_principal}
 1615 
 1616 \begin{verbatim}
 1617 kadm5_ret_t
 1618 kadm5_setkey_principal(void *server_handle, krb5_principal princ,
 1619                        krb5_keyblock *new_keys, int n_keys)
 1620 \end{verbatim}
 1621 
 1622 AUTHORIZATION REQUIRED: setkey.  This function does not allow the use
 1623 of regular changepw authorization because it bypasses the password
 1624 policy mechanism.
 1625 
 1626 This function only exists in KADM5_API_VERSION_2.
 1627 
 1628 Explicitly sets the specified principal's keys to the n_keys keys in
 1629 the new_keys array.  The keys in new_keys should not be encrypted in
 1630 the Kerberos master key; this function will perform that operation
 1631 itself (the keys will be protected during transmission from the
 1632 calling client to the kadmind server by the AUTH_GSSAPI RPC layer).
 1633 This function completely bypasses the principal's password policy, if
 1634 set.
 1635 
 1636 \begin{enumerate}
 1637 \item If the principal does not exist, return KADM5_UNK_PRINC.
 1638 \item If the principal you are trying to change is kadmin/history return
 1639 KADM5_PROTECT_PRINCIPAL.
 1640 \item If new_keys contains more than one key of any ENCTYPE_DES_CBC_*
 1641 type that is folded, return KADM5_SETKEY_DUP_ENCTYPES.
 1642 \item Store old key in history.
 1643 \item Update principal to have new key.
 1644 \item Increment principal's key version number by one.
 1645 \item If the POLICY bit in aux_attributes is set, set pw_expiration to
 1646 now + max_pw_life.
 1647 \item If the KRB5_KDC_REQUIRES_PWCHANGE bit is set in the principal's
 1648 attributes, clear it.
 1649 \item Update last_pwd_change and mod_date to now, update mod_name to
 1650 caller.
 1651 \end{enumerate}
 1652 
 1653 RETURN CODES:
 1654 
 1655 \begin{description}
 1656 \item[KADM5_UNK_PRINC] Principal does not exist.
 1657 \item[KADM5_PROTECT_PRINCIPAL] Cannot change the password of a special
 1658 principal
 1659 \end{description}
 1660 
 1661 This function can also be used as part of a sequence to create a new
 1662 principal with an explicitly key.  The steps to perform the operation
 1663 securely are
 1664 
 1665 \begin{enumerate}
 1666 \item Create the principal with kadm5_create_principal with a
 1667 random password string and with the KRB5_KDB_DISALLOW_ALL_TIX bit set
 1668 in the attributes field.
 1669 
 1670 \item Set the principal's key with kadm5_setkey_principal.
 1671 
 1672 \item Call kadm5_modify_principal to reset the
 1673 KRB5_KDB_DISALLOW_ALL_TIX bit in the attributes field.
 1674 \end{enumerate}
 1675 
 1676 The three steps are necessary to ensure secure creation.  Since an
 1677 attacker might be able to guess the initial password assigned by the
 1678 client program, the principal must be disabled until the key can be
 1679 truly randomized.
 1680 
 1681 \subsection{kadm5_get_principal}
 1682 
 1683 In KADM5_API_VERSION_1:
 1684 
 1685 \begin{verbatim}
 1686 kadm5_ret_t
 1687 kadm5_get_principal(void *server_handle, krb5_principal princ, 
 1688                          kadm5_principal_ent_t *ent);  
 1689 \end{verbatim}
 1690 
 1691 In KADM5_API_VERSION_2:
 1692 
 1693 \begin{verbatim}
 1694 kadm5_ret_t
 1695 kadm5_get_principal(void *server_handle, krb5_principal princ, 
 1696                          kadm5_principal_ent_t ent, u_int32 mask);  
 1697 \end{verbatim}
 1698 
 1699 AUTHORIZATION REQUIRED: get, or the calling principal being the same
 1700 as the princ argument.  If the request is authenticated to the
 1701 kadmin/changepw service, the get privilege is disregarded.
 1702 
 1703 In KADM5_API_VERSION_1, return all of the principal's attributes in
 1704 allocated memory; if an error is returned entry is set to NULL.  In
 1705 KADM5_API_VERSION_2, fill in the fields of the principal structure
 1706 specified in the mask; memory for the structure is not allocated.
 1707 Typically, a caller will specify the mask KADM5_PRINCIPAL_NORMAL_MASK,
 1708 which includes all the fields {\it except} key_data and tl_data to
 1709 improve time and memory efficiency.  A caller that wants key_data and
 1710 tl_data can bitwise-OR those masks onto NORMAL_MASK.  Note that even
 1711 if KADM5_TL_DATA is specified, this function will not return internal
 1712 tl_data elements whose type is less than 256.
 1713 
 1714 The caller must free the returned entry with kadm5_free_principal_ent.
 1715 
 1716 The function behaves differently for local and remote clients.  For
 1717 remote clients, the KEY_DATA mask is illegal and results in a
 1718 KADM5_BAD_MASK error.
 1719 
 1720 RETURN CODES:
 1721 
 1722 \begin{description}
 1723 \item[KADM5_UNK_PRINC] Principal does not exist.
 1724 \item[KADM5_BAD_MASK] The mask is not valid for a get operation.
 1725 
 1726 \end{description}
 1727 
 1728 \subsection{kadm5_decyrpt_key}
 1729 
 1730 \begin{verbatim}
 1731 kadm5_ret_t kadm5_decrypt_key(void *server_handle,
 1732                               kadm5_principal_ent_t entry, krb5_int32
 1733                               ktype, krb5_int32 stype, krb5_int32
 1734                               kvno, krb5_keyblock *keyblock,
 1735                               krb5_keysalt *keysalt, int *kvnop)
 1736 \end{verbatim}
 1737 
 1738 AUTHORIZATION REQUIRED: none, local function
 1739 
 1740 Searches a principal's key_data array to find a key with the specified
 1741 enctype, salt type, and kvno, and decrypts the key into keyblock and
 1742 keysalt if found.  entry must have been returned by
 1743 kadm5_get_principal with at least the KADM5_KEY_DATA mask set.
 1744 Returns ENOENT if the key cannot be found, EINVAL if the key_data
 1745 array is empty (as it always is in an RPC client).
 1746 
 1747 If ktype or stype is -1, it is ignored for the search.  If kvno is -1,
 1748 ktype and stype are ignored and the key with the max kvno is returned.
 1749 If kvno is 0, only the key with the max kvno is returned and only if
 1750 it matches the ktype and stype; otherwise, ENOENT is returned.
 1751 
 1752 \subsection{kadm5_get_principals}
 1753 
 1754 \begin{verbatim}
 1755 kadm5_ret_t
 1756 kadm5_get_principals(void *server_handle, char *exp,
 1757                           char ***princs, int *count)
 1758 \end{verbatim}
 1759 
 1760 Retrieves the list of principal names.  
 1761 
 1762 AUTHORIZATION REQUIRED: list
 1763 
 1764 If \v{exp} is NULL, all principal names are retrieved; otherwise,
 1765 principal names that match the expression exp are retrieved.
 1766 \v{princs} is filled in with a pointer to a NULL-terminated array of
 1767 strings, and \v{count} is filled in with the number of principal names
 1768 in the array.  \v{princs} must be freed with a call to
 1769 \v{kadm5_free_name_list}.
 1770 
 1771 All characters in the expression match themselves except ``?'' which
 1772 matches any single character, ``*'' which matches any number of
 1773 consecutive characters, and ``[chars]'' which matches any single
 1774 character of ``chars''. Any character which follows a ``$\backslash$''
 1775 matches itself exactly, and a ``$\backslash$'' cannot be the last
 1776 character in the string.
 1777 
 1778 \subsection{kadm5_create_policy}
 1779 
 1780 \begin{verbatim}
 1781 kadm5_ret_t
 1782 kadm5_create_policy(void *server_handle,
 1783                          kadm5_policy_ent_t policy, u_int32 mask); 
 1784 \end{verbatim}
 1785 
 1786 Create a new policy.
 1787 
 1788 AUTHORIZATION REQUIRED: add
 1789 
 1790 \begin{enumerate}
 1791 \item Check to see if mask is valid, if not return KADM5_BAD_MASK error.
 1792 \item Return KADM5_BAD_POLICY if the policy name contains illegal
 1793 characters.
 1794 
 1795 \item Check to see if the policy already exists, if so return
 1796 KADM5_DUP error. 
 1797 \item If the PW_MIN_CLASSES bit is set and pw_min_classes is not 1, 2,
 1798 3, 4, or 5, return KADM5_BAD_CLASS.
 1799 \item Create a new policy setting the appropriate fields determined
 1800 by the mask.
 1801 \end{enumerate}
 1802 
 1803 RETURN CODES:
 1804 
 1805 \begin{description}
 1806 \item[KADM5_DUP] Policy already exists
 1807 \item[KADM5_BAD_MASK] The mask is not valid for a create
 1808 operation.
 1809 \item[KADM5_BAD_CLASS] The specified number of character classes
 1810 is invalid.
 1811 \item[KADM5_BAD_POLICY] The policy name contains illegal characters.
 1812 \end{description}
 1813 
 1814 \subsection{kadm5_delete_policy}
 1815 
 1816 \begin{verbatim}
 1817 kadm5_ret_t
 1818 kadm5_delete_policy(void *server_handle, char *policy);
 1819 \end{verbatim}
 1820 
 1821 Deletes a policy.
 1822 
 1823 AUTHORIZATION REQUIRED: delete
 1824 
 1825 \begin{enumerate}
 1826 \item Return KADM5_BAD_POLICY if the policy name contains illegal
 1827 characters.
 1828 \item Return KADM5_UNK_POLICY if the named policy does not exist.
 1829 \item Return KADM5_POLICY_REF if the named policy's refcnt is not 0.
 1830 \item Delete policy.
 1831 \end{enumerate}
 1832 
 1833 RETURN CODES:
 1834 
 1835 \begin{description}
 1836 \item[KADM5_BAD_POLICY] The policy name contains illegal characters.
 1837 \item[KADM5_UNK_POLICY] Policy does not exist.
 1838 \item[KADM5_POLICY_REF] Policy is being referenced. 
 1839 \end{description}
 1840 
 1841 \subsection{kadm5_modify_policy}
 1842 
 1843 \begin{verbatim}
 1844 kadm5_ret_t
 1845 kadm5_modify_policy(void *server_handle,
 1846                          kadm5_policy_ent_t policy, u_int32 mask);
 1847 \end{verbatim}
 1848 
 1849 Modify an existing policy.  Note that modifying a policy has no affect
 1850 on a principal using the policy until the next time the principal's
 1851 password is changed.
 1852 
 1853 AUTHORIZATION REQUIRED: modify
 1854 
 1855 \begin{enumerate}
 1856 \item Return KADM5_BAD_POLICY if the policy name contains illegal
 1857 characters.
 1858 \item Check to see if mask is legal, if not return KADM5_BAD_MASK error.
 1859 \item Check to see if policy exists, if not return
 1860 KADM5_UNK_POLICY error.
 1861 \item If the PW_MIN_CLASSES bit is set and pw_min_classes is not 1, 2,
 1862 3, 4, or 5, return KADM5_BAD_CLASS.
 1863 \item Update the fields specified in the mask.
 1864 \end{enumerate}
 1865 
 1866 RETURN CODES: 
 1867 
 1868 \begin{description}
 1869 \item[KADM5_BAD_POLICY] The policy name contains illegal characters.
 1870 \item[KADM5_UNK_POLICY] Policy not found.
 1871 \item[KADM5_BAD_MASK] The mask is not valid for a modify
 1872 operation.
 1873 \item[KADM5_BAD_CLASS] The specified number of character classes
 1874 is invalid.
 1875 \end{description}
 1876 
 1877 \subsection{kadm5_get_policy}
 1878 
 1879 In KADM5_API_VERSION_1:
 1880 
 1881 \begin{verbatim}
 1882 kadm5_ret_t
 1883 kadm5_get_policy(void *server_handle, char *policy, kadm5_policy_ent_t *ent); 
 1884 \end{verbatim}
 1885 
 1886 In KADM5_API_VERSION_2:
 1887 
 1888 \begin{verbatim}
 1889 kadm5_ret_t
 1890 kadm5_get_policy(void *server_handle, char *policy, kadm5_policy_ent_t ent); 
 1891 \end{verbatim}
 1892 
 1893 AUTHORIZATION REQUIRED: get, or the calling principal's policy being
 1894 the same as the policy argument.  If the request is authenticated to
 1895 the kadmin/changepw service, the get privilege is disregarded.
 1896 
 1897 In KADM5_API_VERSION_1, return the policy's attributes in allocated
 1898 memory; if an error is returned entry is set to NULL.  In
 1899 KADM5_API_VERSION_2, fill in fields of the policy structure allocated
 1900 by the caller.  The caller must free the returned entry with
 1901 kadm5_free_policy_ent
 1902 
 1903 RETURN CODES: 
 1904 
 1905 \begin{description}
 1906 \item[KADM5_BAD_POLICY] The policy name contains illegal characters.
 1907 \item[KADM5_UNK_POLICY] Policy not found.
 1908 \end{description}
 1909 
 1910 \subsection{kadm5_get_policies}
 1911 
 1912 \begin{verbatim}
 1913 kadm5_ret_t
 1914 kadm5_get_policies(void *server_handle, char *exp,
 1915                           char ***pols, int *count)
 1916 \end{verbatim}
 1917 
 1918 Retrieves the list of principal names.  
 1919 
 1920 AUTHORIZATION REQUIRED: list
 1921 
 1922 If \v{exp} is NULL, all principal names are retrieved; otherwise,
 1923 principal names that match the expression exp are retrieved.  \v{pols}
 1924 is filled in with a pointer to a NULL-terminated array of strings, and
 1925 \v{count} is filled in with the number of principal names in the
 1926 array.  \v{pols} must be freed with a call to
 1927 \v{kadm5_free_name_list}.
 1928 
 1929 All characters in the expression match themselves except ``?'' which
 1930 matches any single character, ``*'' which matches any number of
 1931 consecutive characters, and ``[chars]'' which matches any single
 1932 character of ``chars''. Any character which follows a ``$\backslash$''
 1933 matches itself exactly, and a ``$\backslash$'' cannot be the last
 1934 character in the string.
 1935 
 1936 \subsection{kadm5_free_principal_ent, _policy_ent}
 1937 
 1938 \begin{verbatim}
 1939 void kadm5_free_principal_ent(void *server_handle,
 1940                                    kadm5_principal_ent_t princ);
 1941 \end{verbatim}
 1942 
 1943 In KADM5_API_VERSION_1, free the structure and contents allocated by a
 1944 call to kadm5_get_principal.  In KADM5_API_VERSION_2, free the
 1945 contents allocated by a call to kadm5_get_principal.
 1946 
 1947 AUTHORIZATION REQUIRED: none (local operation)
 1948 
 1949 \begin{verbatim}
 1950 void kadm5_free_policy_ent(kadm5_policy_ent_t policy);
 1951 \end{verbatim}
 1952 
 1953 Free memory that was allocated by a call to kadm5_get_policy.  If
 1954 the argument is NULL, the function returns succesfully.
 1955 
 1956 AUTHORIZATION REQUIRED: none (local operation)
 1957 
 1958 \subsection{kadm5_free_name_list}
 1959 
 1960 \begin{verbatim}
 1961 void kadm5_free_name_list(void *server_handle,
 1962                                char **names, int *count);
 1963 \end{verbatim}
 1964 
 1965 Free the memory that was allocated by kadm5_get_principals or
 1966 kadm5_get_policies.  names and count must be a matched pair of
 1967 values returned from one of those two functions.
 1968 
 1969 \subsection{kadm5_free_key_data}
 1970 
 1971 \begin{verbatim}
 1972 void kadm5_free_key_data(void *server_handle,
 1973                          krb5_int16 *n_key_data, krb5_key_data *key_data)
 1974 \end{verbatim}
 1975 
 1976 Free the memory that was allocated by kadm5_randkey_principal.
 1977 n_key_data and key_data must be a matched pair of values returned from
 1978 that function.
 1979 
 1980 \subsection{kadm5_get_privs}
 1981 
 1982 \begin{verbatim}
 1983 kadm5_ret_t
 1984 kadm5_get_privs(void *server_handle, u_int32 *privs);
 1985 \end{verbatim}
 1986 
 1987 Return the caller's admin server privileges in the integer pointed to
 1988 by the argument.  The Admin API does not define any way for a
 1989 principal's privileges to be set.  Note that this function will
 1990 probably be removed or drastically changed in future versions of this
 1991 system.
 1992 
 1993 The returned value is a bitmask indicating the caller's privileges:
 1994 
 1995 \begin{tabular}{llr}
 1996 {\bf Privilege} & {\bf Symbol} & {\bf Value} \\
 1997 Get & KADM5_PRIV_GET & 0x01 \\
 1998 Add & KADM5_PRIV_ADD & 0x02 \\
 1999 Modify & KADM5_PRIV_MODIFY & 0x04 \\
 2000 Delete & KADM5_PRIV_DELETE & 0x08 \\
 2001 List & KADM5_PRIV_LIST & 0x10 \\
 2002 Changepw & KADM5_PRIV_CPW & 0x20
 2003 \end{tabular}
 2004 
 2005 There is no guarantee that a caller will have a privilege indicated by
 2006 this function for any length of time or for any particular target;
 2007 applications using this function must still be prepared to handle all
 2008 possible KADM5_AUTH_* error codes.
 2009 
 2010 In the initial MIT Kerberos version of the admin server, permissions
 2011 depend both on the caller and the target; this function returns a
 2012 bitmask representing all privileges the caller can possibly have for
 2013 any possible target.
 2014 
 2015 \end{document}