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

Note: This subroutine has been depreciated and its use is not recommended. The chpass subroutine should be used in its place.

The newpass subroutine generates a new password for the user specified by the Password parameter. This subroutine displays a dialogue to enter and confirm the user's new password.

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.

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 multithreaded environment. To use newpass in a threaded application, the application must keep the integrity of each thread.

Parameters

Item	Description
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_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 root and the password will have to be changed upon the next successful running of the login or su commands to this account.

Item

Description

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_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 root and the password will have to be changed upon the next successful running of the login or su commands to this account.

Security

Item	Description
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:

Item	Description
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.

Implementation Specifics

This subroutine is part of Base Operating System (BOS) Runtime.