newpassx Subroutine

Purpose

Generates a new password for a user (without a name length limit).

Library

Security Library (libc.a)

Syntax

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

char *newpassx (Password) struct userpwx *Password;

Description

Note: The newpassx subroutine has been obsoleted by the more current chpassx subroutine. Use the chpassx subroutine instead.

The newpassx 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 or the administrative domain for the user 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 characters than the value specified by PASS_MAX.

The newpassx subroutine authenticates the user prior to returning the new password. If the PW_ADMCHG flag is set in the upw_flags member of the Password parameter, the supplied password is checked against the calling user's password. This is done to authenticate 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 set to the current system time. The password value in the /etc/security/passwd file or user's administrative domain is not modified.

Note: The newpassx subroutine is not safe in a multithreaded environment. To use newpassx in a threaded application, the application must keep the integrity of each thread.

Parameters

Item	Description
Password	Specifies a user password structure.

The fields in a userpwx structure are defined in the userpw.h file, and they include the following members:

Item	Description
upw_name	Specifies the user's name.
upw_passwd	Specifies the user's encrypted password.
upw_lastupdate	Specifies the time, in seconds, since the epoch (that is, 00:00:00 GMT, 1 January 1970), when the password was last updated.
upw_flags	Specifies attributes of the password. This member is a bit mask of one or more of the following values, defined in the userpw.h file: PW_NOCHECK Specifies that new passwords need not meet password restrictions in effect for the system. PW_ADMCHG Specifies that the password was last set by an administrator and must be changed at the next successful use of the login or su command. PW_ADMIN Specifies that password information for this user can only be changed by the root user.
upw_authdb	Specifies the administrative domain containing the authentication data.

Security

Item	Description
Policy: Authentication	To change a password, the invoker must be properly authenticated.

Note: Programs that invoke the newpassx subroutine should be written to conform to the authentication rules enforced by newpassx. 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 newpassx subroutine fails if one or more of the following is true:

Item	Description
EINVAL	The structure passed to the newpassx subroutine is invalid.
ENOENT	The user is not properly defined in the database.
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.
ESAD	Security authentication is denied for the invoker.