passwdstrength Subroutine
Purpose
Performs basic password age and construction tests.
Syntax
#include <pwdpolicy.h>
int passwdstrength (const char *old_password, const char *new_password,
time64_t last_update, passwd_policy_t *policy, int checks);Description
The passwdstrength subroutine performs basic password age and construction tests. Password history, reuse, and dictionary tests are not performed. The values contained in the policy parameter are used to validate the value of new_password.
The
following fields are used by the passwdstrength subroutine.
| Item | Description |
|---|---|
| pwp_version | Specifies the version of the passwd_policy_t structure. The current structure version number is PWP_VERSION_1. |
| pwp_minage | The number of seconds, as a time32_t, between the time a password is modified and the time the password can again be modified. This field is referenced if PWP_TOO_SOON is set in checks. |
| pwp_maxage | The number of seconds, as a time32_t, after which a password that has been modified is considered to be expired. This field is referenced if PWP_EXPIRED is set in checks. |
| pwp_maxexpired | The number of seconds, as a time32_t, since a password has expired after which it can no longer be modified. A value of 0 indicates that an expired password cannot be changed. A value of -1 indicates that an expired password can be changed after any length of time. This field is referenced if PWP_EXPIRED is set in checks. |
| pwp_minalpha | The minimum number of characters in the password that must be alphabetic characters, as determined by invoking the isalpha() macro. A value less than or equal to 0 disables this test. This field is referenced if PWP_TOO_FEW_ALPHA is set in checks. |
| pwp_minother | The minimum number of characters in the password that cannot be alphabetic characters, as determined by invoking the isalpha() macro. A value less than or equal to 0 disables this test. This field is referenced if PWP_TOO_FEW_OTHER is set in checks. |
| pwp_minlen | The minimum total number of characters in the password. A value less than or equal to 0 disables this test. This field is referenced if PWP_TOO_SHORT is set in checks. |
| pwp_maxrepeats | The maximum number of times an individual character can appear in the password. A value less than or equal to 0 disables this test. This field is referenced if PWP_TOO_MANY_REPEATS is set in checks. |
| pwp_mindiff | The minimum number of characters that must be changed between the old password and the new password. A value less than or equal to 0 disables this test. If this test fails, the return value contains the bit PWP_TOO_MANY_SAME. This field is referenced if PWP_TOO_MANY_SAME is set in checks. |
Parameters
| Item | Description |
|---|---|
| old_password | The value of the current password. This parameter must be non-NULL if PWP_TOO_MANY_SAME is set in checks or the results are undefined. |
| new_password | The value of the new password. This parameter must be non-NULL if any of PWP_TOO_SHORT, PWP_TOO_FEW_ALPHA, PWP_TOO_FEW_OTHER, PWP_TOO_MANY_SAME, or PWP_TOO_MANY_REPEATS are set in checks or the results are undefined. |
| last_update | The time the password was last changed, as a time64_t value, expressed in seconds since the UNIX epoch. A 0 value for this parameter indicates that the password has never been set. This might cause PWP_EXPIRED to be set in the return value if it is set in checks. |
| policy | A pointer to a passwd_policy_t containing the values for the password policy attributes. |
| checks | A bitmask value that indicates the set of password tests to be performed. The return value contains only those bits that are defined in checks. |
Return Values
The return value is a bit-mapped representation of the tests that failed. A return value of 0 indicates that all password rules requested in the checks parameter passed. A value of -1 indicates that some other error, other than a password test, has occurred. The errno variable indicates the cause of that error. Applications must compare a non-zero return value against -1 before checking any specific bits in the return value.
Files
The /usr/include/pwdpolicy.h header file.