next up previous contents
Next: Constants, Header Files, Libraries Up: Data Structures Previous: Principal keys   Contents


Field masks

The API functions for creating, retrieving, and modifying principals and policies allow for a relevant subset of the fields of the kadm5_principal_ent_t and kadm5_policy_ent_t to be specified or changed. The chosen fields are determined by a bitmask that is passed to the relevant function. Each API function has different rules for which mask values can be specified, and can specify whether a given mask value is mandatory, optional, or forbidden. Mandatory fields must be present and forbidden fields must not be present or an error is generated. When creating a principal or policy, optional fields have a default value if they are not specified. When modifying a principal or policy, optional fields are unchanged if they are not specified. When retrieving a principal, optional fields are simply not provided if they are not specified; not specifying undeeded fields for retrieval may improve efficiency. The values for forbidden fields are defined in the function semantics.

The masks for principals are in table 1 and the masks for policies are in table 2. They are defined in $<$kadm5/admin.h$>$. The KADM5_ prefix has been removed from the Name fields. In the Create and Modify fields, M means mandatory, F means forbidden, and O means optional. Create fields that are optional specify the default value. The notation ``K/M value'' means that the field inherits its value from the corresponding field in the Kerberos master principal, for KADM5_API_VERSION_1, and from the configuration parameters for KADM5_API_VERSION_2.

All masks for principals are optional for retrevial, except that the KEY_DATA mask is illegal when specified by a remote client; for details, see the function semantics for kadm5_get_principal.

Note that the POLICY and POLICY_CLR bits are special. When POLICY is set, the policy is assigned to the principal. When POLICY_CLR is specified, the policy is unassigned to the principal and as a result no policy controls the principal.

For convenience, the mask KADM5_PRINCIPAL_NORMAL_MASK contains all of the principal masks except KADM5_KEY_DATA and KADM5_TL_DATA, and the mask KADM5_POLICY_NORMAL_MASK contains all of the policy masks.


Table 1: Mask bits for creating, retrieving, and modifying principals.
 Name Value Fields Affected Create Modify
 PRINCIPAL 0x000001 principal M F
 PRINC_EXPIRE_TIME 0x000002 princ_expire_time O, K/M value O
 PW_EXPIRATION 0x000004 pw_expiration O, now+pw_max_life O
 LAST_PWD_CHANGE 0x000008 last_pwd_change F F
 ATTRIBUTES 0x000010 attributes O, 0 O
 MAX_LIFE 0x000020 max_life O, K/M value O
 MOD_TIME 0x000040 mod_date F F
 MOD_NAME 0x000080 mod_name F F
 KVNO 0x000100 kvno O, 1 O
 MKVNO 0x000200 mkvno F F
 AUX_ATTRIBUTES 0x000400 aux_attributes F F
 POLICY 0x000800 policy O, none O
 POLICY_CLR 0x001000 policy F O
 MAX_RLIFE 0x002000 max_renewable_life O, K/M value O
 LAST_SUCCESS 0x004000 last_success F F
 LAST_FAILED 0x008000 last_failed F F
 FAIL_AUTH_COUNT 0x010000 fail_auth_count F O
 KEY_DATA 0x020000 n_key_data, key_data F F
 TL_DATA 0x040000 n_tl_data, tl_data O, 0, NULL O



Table 2: Mask bits for creating/modifying policies.
 Name Value Field Affected Create Modify
 POLICY same policy M F
 PW_MAX_LIFE 0x004000 pw_max_life O, 0 (infinite) O
 PW_MIN_LIFE 0x008000 pw_min_life O, 0 O
 PW_MIN_LENGTH 0x010000 pw_min_length O, 1 O
 PW_MIN_CLASSES 0x020000 pw_min_classes O, 1 O
 PW_HISTORY_NUM 0x040000 pw_history_num O, 0 O
 REF_COUNT 0x080000 pw_refcnt F F



next up previous contents
Next: Constants, Header Files, Libraries Up: Data Structures Previous: Principal keys   Contents
Autobuild 2009-09-05