next up previous contents
Next: kadm5_get_principal Up: Functions Previous: kadm5_randkey_principal   Contents

kadm5_setkey_principal

kadm5_ret_t
kadm5_setkey_principal(void *server_handle, krb5_principal princ,
                       krb5_keyblock *new_keys, int n_keys)

AUTHORIZATION REQUIRED: setkey. This function does not allow the use of regular changepw authorization because it bypasses the password policy mechanism.

This function only exists in KADM5_API_VERSION_2.

Explicitly sets the specified principal's keys to the n_keys keys in the new_keys array. The keys in new_keys should not be encrypted in the Kerberos master key; this function will perform that operation itself (the keys will be protected during transmission from the calling client to the kadmind server by the AUTH_GSSAPI RPC layer). This function completely bypasses the principal's password policy, if set.

  1. If the principal does not exist, return KADM5_UNK_PRINC.
  2. If the principal you are trying to change is kadmin/history return KADM5_PROTECT_PRINCIPAL.
  3. If new_keys contains more than one key of any ENCTYPE_DES_CBC_* type that is folded, return KADM5_SETKEY_DUP_ENCTYPES.
  4. Store old key in history.
  5. Update principal to have new key.
  6. Increment principal's key version number by one.
  7. If the POLICY bit in aux_attributes is set, set pw_expiration to now + max_pw_life.
  8. If the KRB5_KDC_REQUIRES_PWCHANGE bit is set in the principal's attributes, clear it.
  9. Update last_pwd_change and mod_date to now, update mod_name to caller.

RETURN CODES:

KADM5_UNK_PRINC
Principal does not exist.
KADM5_PROTECT_PRINCIPAL
Cannot change the password of a special principal

This function can also be used as part of a sequence to create a new principal with an explicitly key. The steps to perform the operation securely are

  1. Create the principal with kadm5_create_principal with a random password string and with the KRB5_KDB_DISALLOW_ALL_TIX bit set in the attributes field.

  2. Set the principal's key with kadm5_setkey_principal.

  3. Call kadm5_modify_principal to reset the KRB5_KDB_DISALLOW_ALL_TIX bit in the attributes field.

The three steps are necessary to ensure secure creation. Since an attacker might be able to guess the initial password assigned by the client program, the principal must be disabled until the key can be truly randomized.


next up previous contents
Next: kadm5_get_principal Up: Functions Previous: kadm5_randkey_principal   Contents
Autobuild 2006-06-16