getuserpw, putuserpw, or putuserpwhist Subroutine

Purpose

Accesses the user authentication data.

Library

Security Library (libc.a)

Syntax

#include <userpw.h>

struct userpw *getuserpw ( User) char *User;

int putuserpw ( Password) struct userpw *Password;

int putuserpwhist ( Password, Message) struct userpw *Password; char **Message;

Description

These subroutines may be used to access user authentication information. Because of their greater granularity and extensibility, you should use them instead of the getpwent routines.

The getuserpw subroutine reads the user's locally defined password information. If the setpwdb subroutine has not been called, the getuserpw subroutine will call it as setpwdb (S_READ). This can cause problems if the putuserpw subroutine is called later in the program.

The putuserpw subroutine updates or creates a locally defined password information stanza in the /etc/security/passwd file. The password entry created by the putuserpw subroutine is used only if there is an ! (exclamation point) in the /etc/passwd file's password field. The user application can use the putuserattr subroutine to add an ! to this field.

The putuserpw subroutine will open the authentication database read/write if no other access has taken place, but the program should call setpwdb (S_READ | S_WRITE) before calling the putuserpw subroutine.

The putuserpwhist subroutine updates or creates a locally defined password information stanza in the etc/security/passwd file. The subroutine also manages a database of previous passwords used for password reuse restriction checking. It is recommended to use the putuserpwhist subroutine, rather than the putuserpw subroutine, to ensure the password is added to the password history database.

Parameters

Item	Description
Password	Specifies the password structure used to update the password information for this user. This structure is defined in the userpw.h file and contains the following members: upw_name Specifies the user's name. (The first eight characters must be unique, since longer names are truncated.) upw_passwd Specifies the user's password. upw_lastupdate Specifies the time, in seconds, since the epoch (that is, 00:00:00 GMT, January 1, 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 may only be changed by the root user.
Message	Indicates a message that specifies an error occurred while updating the password history database. Upon return, the value is either a pointer to a valid string within the memory allocated storage or a null pointer.
User	Specifies the name of the user for which password information is read. (The first eight characters must be unique, since longer names are truncated.)

Security

Files Accessed:

Mode	File
rw	/etc/security/passwd

Return Values

If successful, the getuserpw subroutine returns a valid pointer to a userpw structure. Otherwise, a null pointer is returned and the errno global variable is set to indicate the error. If the user exists but there is no user entry in the /etc/security/passwd file, the getuserpw subroutine returns success with the name field set to user name, the password field set to NULL, the lastupdate field set to 0 and the flags field set to 0. If the user exists and there is an entry in the /etc/security/passwd file but one or more fields are missing, the getuserpw subroutine returns the fields that exist.

If the user exists but there is no user entry in the /etc/security/passwd file, the putuserpw subroutine creates a user stanza in the /etc/security/passwd file. If the user exists and there is an entry in the /etc/security/passwd file but one or more fields are missing, the putuserpw subroutine updates the fields that exist and creates the fields that are missing.

If successful, the putuserpwhist subroutine returns a value of 0. If the subroutine failed to update or create a locally defined password information stanza in the /etc/security/passwd file, the putuserpwhist subroutine returns a nonzero value. If the subroutine was unable to update the password history database, a message is returned in the Message parameter and a return code of 0 is returned. If the user exists but there is no user entry in the /etc/security/passwd file, the putuserpwhist subroutine creates a user stanza in the /etc/security/passwd file and updates the password history. If the user exists and there is an entry in the /etc/security/passwd file but one or more fields are missing, the putuserpwhist subroutine updates the fields that exist, creates the fields that are missing and modifies the password history.

Error Codes

The getuserpw, putuserpw, and putuserpwhist subroutines fail if the following values are true:

Item	Description
EACCES	The user is not able to open the files that contain the password attributes.
ENOENT	The user does not exist in the /etc/passwd file.

Subroutines invoked by the getuserpw, putuserpw, or putuserpwhist subroutines can also set errors.

Files

Item	Description
/etc/security/passwd	Contains user passwords.