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

kadm5_chpass_principal_util

kadm5_ret_t
kadm5_chpass_principal_util(void *server_handle, krb5_principal princ,
                                 char *new_pw, char **pw_ret,
                                 char *msg_ret);

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.

This function is a wrapper around kadm5_chpass_principal. It can read a new password from a user, change a principal's password, and return detailed error messages. msg_ret should point to a char buffer in the caller's space of sufficient length for the error messages described below. 1024 bytes is recommended. It will also return the new password to the caller if pw_ret is non-NULL.

  1. If new_pw is NULL, this routine will prompt the user for the new password (using the strings specified by KADM5_PW_FIRST_PROMPT and KADM5_PW_SECOND_PROMPT) and read (without echoing) the password input. Since it is likely that this will simply call krb5_read_password only terminal-based applications will make use of the password reading functionality. If the passwords don't match the string ``New passwords do not match - password not changed.'' will be copied into msg_ret, and the error code KRB5_LIBOS_BADPWDMATCH will be returned. For other errors that ocurr while reading the new password, copy the string `` occurred while trying to read new password.'' followed by a blank line and the string specified by CHPASS_UTIL_PASSWORD_NOT_CHANGED into msg_ret and return the error code returned by krb5_read_password.

  2. If pw_ret is non-NULL, and the password was prompted, set *pw_ret to point to a static buffer containing the password. If pw_ret is non-NULL and the password was supplied, set *pw_ret to the supplied password.

  3. Call kadm5_chpass_principal with princ, and new_pw.

  4. If successful copy the string specified by CHPASS_UTIL_PASSWORD_CHANGED into msg_ret and return zero.

  5. For a policy related failure copy the appropriate message (from below) followed by a newline and ``Password not changed.'' into msg_ret filling in the parameters from the principal's policy information. If the policy information cannot be obtained copy the generic message if one is specified below. Return the error code from kadm5_chpass_principal.

    Detailed messages:

    PASS_Q_TOO_SHORT
    New password is too short. Please choose a password which is more than $<$pw-min-len$>$ characters.

    PASS_Q_TOO_SHORT - generic
    New password is too short. Please choose a longer password.

    PASS_REUSE
    New password was used previously. Please choose a different password.

    PASS_Q_CLASS
    New password does not have enough character classes. Classes include lower class letters, upper case letters, digits, punctuation and all other characters. Please choose a password with at least $<$min-classes$>$ character classes.

    PASS_Q_CLASS - generic
    New password does not have enough character classes. Classes include lower class letters, upper case letters, digits, punctuation and all other characters.

    PASS_Q_DICT
    New password was found in a dictionary of possible passwords and therefore may be easily guessed. Please choose another password. See the kpasswd man page for help in choosing a good password.

    PASS_TOOSOON
    Password cannot be changed because it was changed too recently. Please wait until $<$last-pw-change+pw-min-life$>$ before you change it. If you need to change your password before then, contact your system security administrator.

    PASS_TOOSOON - generic
    Password cannot be changed because it was changed too recently. If you need to change your now please contact your system security administrator.

  6. For other errors copy the string ``$<$com_err message$>$ occurred while trying to change password.'' following by a blank line and ``Password not changed.'' into msg_ret. Return the error code returned by kadm5_chpass_principal.

RETURN CODES:

KRB5_LIBOS_BADPWDMATCH
Typed new passwords did not match.
KADM5_UNK_PRINC
Principal does not exist.
KADM5_PASS_Q_*
Requested password does not meet quality standards.
KADM5_PASS_REUSE
Requested password is in user's password history.
KADM5_PASS_TOOSOON
Current password has not reached minimum life.


next up previous contents
Next: kadm5_randkey_principal Up: Functions Previous: kadm5_chpass_principal   Contents
Autobuild 2009-09-05