next up previous contents
Next: kadm5_setkey_principal Up: Functions Previous: kadm5_chpass_principal_util   Contents

kadm5_randkey_principal

In KADM5_API_VERSION_1:

kadm5_ret_t
kadm5_randkey_principal(void *server_handle, krb5_principal princ,
                             krb5_keyblock **new_key)

In KADM5_API_VERSION_2:

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

AUTHORIZATION REQUIRED: changepw, or the calling principal being the same as the princ argument. If the request is authenticated to the kadmin/changepw service, the changepw privilege is disregarded.

Generate and assign a new random key to the named principal, and return the generated key in allocated storage. In KADM5_API_VERSION_2, multiple keys may be generated and returned as an array, and n_new_keys is filled in with the number of keys generated. See section 4.4 for a description of how the keys are chosen. In KADM5_API_VERSION_1, the caller must free the returned krb5_keyblock * with krb5_free_keyblock. In KADM5_API_VERSION_2, the caller must free each returned keyblock with krb5_free_keyblock.

If the principal's POLICY bit is set in aux_attributes and the caller does not have modify privilege , compliance with the password minimum life specified by the policy is verified and an appropriate error code is returned if verification fails.

  1. If the principal does not exist, return KADM5_UNK_PRINC.
  2. If caller does not have modify privilege, (now - last_pwd_change) $<$ pw_min_life, and the KRB5_KDB_REQUIRES_PWCHANGE bit is not set in the principal's attributes, return KADM5_PASS_TOOSOON.
  3. If the principal you are trying to change is kadmin/history return KADM5_PROTECT_PRINCIPAL.
  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_PASS_TOOSOON
The minimum lifetime for the current key has not expired.
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 a random 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. Randomize the principal's key with kadm5_randkey_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_setkey_principal Up: Functions Previous: kadm5_chpass_principal_util   Contents
Autobuild 2009-09-05