getuserpw, putuserpw, or putuserpwhist Subroutine

AIX Version 4.3 Base Operating System and Extensions Technical Reference, Volume 1

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

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 pw structure. Otherwise, a null pointer is returned and the errno global variable is set to indicate the error.

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.

Error Codes

If the getuserpw, putuserpw, and putuserpwhist subroutines fail if one of the following values is true:

ENOENT

The user does not have an entry in the /etc/security/passwd file.

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

Implementation Specifics

These subroutines are part of Base Operating System (BOS) Runtime.

Files

/etc/security/passwd

Contains user passwords.

Related Information

The getgroupattr subroutine, getuserattr, IDtouser, nextuser, or putuserattr subroutine, setpwdb or endpwdb subroutine, setuserdb subroutine.

List of Security and Auditing Subroutines and Subroutines Overview in AIX Version 4.3 General Programming Concepts: Writing and Debugging Programs.