Technical Reference: Base Operating System and Extensions, Volume 1

newpass Subroutine

Purpose

Generates a new password for a user.

Library

Security Library (libc.a)

Syntax

#include <usersec.h>
#include <userpw.h>

char *newpass( Password) struct userpw *Password;

Description

The newpass subroutine generates a new password for the user specified by the Password parameter. The new password is then checked to ensure that it meets the password rules on the system unless the user is exempted from these restrictions. Users must have root user authority to invoke this subroutine. The password rules are defined in the /etc/security/user file and are described in both the user file and the passwd command.

Passwords can contain almost any legal value for a character but cannot contain (National Language Support (NLS) code points. Passwords cannot have more than the value specified by MAX_PASS.

The newpass subroutine authenticates the user prior to changing the password. If the PW_ADMCHG flag is set in the upw_flags member of the Password parameter, the supplied password is checked against the password to determine the user corresponding to the real user ID of the process instead of the user specified by the upw_name member of the Password parameter structure.

If a password is successfully generated, a pointer to a buffer containing the new password is returned and the last update time is reset.

Note

The newpass subroutine is not safe in a multi-threaded environment. To use newpass in a threaded application, the application must keep the integrity of each thread.

Parameters

Password

Specifies a user password structure. This structure is defined in the userpw.h file and contains the following members:

upw_name

A pointer to a character buffer containing the user name.

upw_passwd

A pointer to a character buffer containing the current password.

upw_lastupdate

The time the password was last changed, in seconds since the epoch.

upw_flags

A bit mask containing 0 or more of the following values:

PW_NOCHECK: This bit indicates that new passwords need not meet the composition criteria for passwords on the system.
PW_ADMIN: This bit indicates that password information for this user may only be changed by the root user.
PW_ADMCHG: This bit indicates that the password is being changed by an administrator and the password will have to be changed upon the next successful running of the login or su commands to this account.

Security

Policy: Authentication

To change a password, the invoker must be properly authenticated.

Note

Programs that invoke the newpass subroutine should be written to conform to the authentication rules enforced by newpass. The PW_ADMCHG flag should always be explicitly cleared unless the invoker of the command is an administrator.

Return Values

If a new password is successfully generated, a pointer to the new encrypted password is returned. If an error occurs, a null pointer is returned and the errno global variable is set to indicate the error.

Error Codes

The newpass subroutine fails if one or more of the following are true;

EINVAL	The structure passed to the newpass subroutine is invalid.
ESAD	Security authentication is denied for the invoker.
EPERM	The user is unable to change the password of a user with the PW_ADMCHG bit set, and the real user ID of the process is not the root user.
ENOENT	The user is not properly defined in the database.

Related Information

The getpass (getpass Subroutine) subroutine, getuserpw (getuserpw, putuserpw, or putuserpwhist Subroutine) subroutine.

The login command, passwd command, pwdadm command.

List of Security and Auditing Subroutines, Subroutines Overview in AIX 5L Version 5.2 General Programming Concepts: Writing and Debugging Programs.