passwdpolicy Subroutine
Purpose
Supports password strength policies on a per-user or per-named-policy basis.
Syntax
#include <pwdpolicy.h>
int passwdpolicy (const char *name, int type, const char *old_password,
const char *new_password, time64_t last_update);Description
The passwdpolicy subroutine supports application use of password strength policies on a per-user or per-named-policy basis. The policies that are supported include password dictionaries, history list length, history list expiration, maximum lifetime of a password, minimum period of time between permitted password changes, maximum period after which an expired password can be changed, maximum number of repeated characters in a password, minimum number of alphabetic characters in a password, minimum number of lower case alphabetic characters in a password, minimum number of upper case alphabetic characters in a password, minimum number of digits in a password, minimum number of special characters in a password, minimum number of non-alphabetic characters in a password, minimum length of a password, and a list of loadable modules that can be used to determine additional password strength rules.
The type parameter allows an application to select where the policy values are located. Privileged process can use either PWP_USERNAME or PWP_SYSTEMPOLICY. Unprivileged processes are limited to using PWP_LOCALPOLICY.
| Item | Description |
|---|---|
| dictionlist | A SEC_LIST value that gives a list of dictionaries to be checked. If new_password is found in any of the named dictionaries, this test fails. If this test fails, the return value contains the PWP_IN_DICTIONARY bit. |
| histsize | A SEC_INT value giving the permissible size of the named user's password history. The named user's password history is obtained by calling getuserattr with the S_HISTLIST attribute. If this attribute does not exist, password history checks are disabled. A value of 0 disables password history tests. If this test fails, the return value contains the PWP_REUSED_PW bit. |
| histexpire | A SEC_INT value that gives the number of weeks that must elapse before a password in the named user's password history list can be reused. If this test fails the return value contains the PWP_REUSED_TOO_SOON bit. |
| maxage | A SEC_INT value that gives the number of weeks a password can be considered valid. A password that has not been modified more recently than maxage weeks is considered to have expired and is subject to the maxexpired test. A value less than or equal to 0 disables this test. This attribute is used to determine if maxexpired must be tested, and it does not generate a return value. |
| minage | A SEC_INT value that gives the number of weeks before a password can be changed. A password that has been modified more recently than minage weeks fails this test. A value less than or equal to 0 disables this test. If this test fails, the return value contains the PWP_TOO_SOON bit. |
| maxexpired | A SEC_INT value that gives the number of weeks after which an expired password cannot be changed. 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. If this test fails, the return value contains the PWP_EXPIRED bit. |
| maxrepeats | A SEC_INT value that gives the maximum number of times any single character can appear in the new password. A value less than or equal to 0 disables this test. If this test fails, the return value contains the PWP_TOO_MANY_REPEATS bit. |
| mindiff | A SEC_INT value that gives the maximum number of characters in the new password that must not be present in the old password. A value less than or equal to 0 disables this test. If this test fails, the return value contains the PWP_TOO_MANY_SAME bit. |
| minalpha | A SEC_INT value that gives the minimum number of alphabetic characters that must be present in the password. A value less than or equal to 0 disables this test. If this test fails, the return value contains the PWP_TOO_FEW_ALPHA bit. |
| minother | A SEC_INT value that gives the minimum number of nonalphabetic characters that must be present in the password. A value less than or equal to 0 disables this test. If this test fails, the return value contains the bit PWP_TOO_FEW_OTHER bit. |
| minlen | A SEC_INT value that gives the minimum required length of a password. There is no maximum value for this attribute. A value less than or equal to 0 disables this test. If this test fails, the return value contains the PWP_TOO_SHORT bit. |
| pwdchecks | A SEC_LIST value that gives a list of named loadable modules that must be executed to validate the password. If this test fails, the return value contains the PWP_FAILED_OTHER bit. |
| minloweralpha | A SEC_INT value that gives the minimum number of lower case alphabetic characters that must be present in the password. A value less than or equal to 0 disables this test. If this test fails, the return value contains the PWP_TOO_FEW_LOWERALPHA bit. |
| minupperalpha | A SEC_INT value that gives the minimum number of upper case alphabetic characters that must be present in the password. A value less than or equal to 0 disables this test. If this test fails, the return value contains the PWP_TOO_FEW_UPPERALPHA bit. |
| mindigit | A SEC_INT value that gives the minimum number of digits that must be present in the password. A value less than or equal to 0 disables this test. If this test fails, the return value contains the PWP_TOO_FEW_DIGIT bit. |
| minspecialchar | A SEC_INT value that gives the minimum number of special characters that must be present in the password. A value less than or equal to 0 disables this test. If this test fails, the return value contains thePWP_TOO_FEW_SPECIALCHAR bit. |
Parameters
| Item | Description |
|---|---|
| name | The name of either a specific user or named policy. User names have policy information determined by invoking the getuserattr subroutine. Policy names have policy information determined by invoking the getconfattr subroutine. |
| type | One of three values:
|
| old_password | The current value of the password. This function does not verify that old_password is the correct current password. Invoking passwdpolicy with a NULL pointer for this parameter disables PWP_TOO_MANY_SAME tests. |
| new_password | The value of the new password. Invoking passwdpolicy with a NULL pointer for this parameter disables all tests except password age tests. |
| 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 disables password age tests regardless of the value of any other parameter. |
Return Values
The return value is a bit map representation of the tests that failed. A return value of 0 indicates that all password rules passed. A value of -1 indicates that some other error, other than a failed password test, has occurred. The errno variable indicates the cause of that error. Applications must compare a nonzero return value against -1 before checking any specific bits in the return value.
Files
The /usr/include/pwdpolicy.h header file.