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.
|