getprpwent(3) getprpwent(3)
NAME [Toc] [Back]
getprpwent, getprpwuid, getprpwnam, getprpwaid, setprpwent,
endprpwent, putprpwnam - manipulate protected password database
entries (for trusted systems only).
SYNOPSIS [Toc] [Back]
#include <sys/types.h>
#include <hpsecurity.h>
#include <prot.h>
struct pr_passwd *getprpwent(void);
struct pr_passwd *getprpwuid(uid_t uid);
struct pr_passwd *getprpwnam(const char *name);
struct pr_passwd *getprpwaid(aid_t aid)
void setprpwent(void);
void endprpwent(void);
int putprpwnam(const char *name, struct pr_passwd *pr);
DESCRIPTION [Toc] [Back]
getprpwent, getprpwuid, getprpwaid, and getprpwnam each returns a
pointer to a pr_passwd structure containing the broken-out fields of a
line in the protected password database. Each line in the database
contains a pr_passwd structure, declared in the <prot.h> header file:
struct pr_field {
/* Identity: */
char fd_name[9]; /* uses 8 character maximum(and NULL) from utmp */
uid_t fd_uid; /* uid associated with name above */
char fd_encrypt[xxx]; /* encrypted password */
char fd_owner[9]; /* if a pseudo-user, the user accountable */
char fd_boot_auth; /* boot authorization */
mask_t fd_auditcntl; /* reserved */
mask_t audit_reserve1; /* reserved */
mask_t fd_auditdisp; /* reserved */
mask_t audit_reserve2; /* reserved */
aid_t fd_pw_audid; /* audit ID */
int fd_pw_audflg; /* audit flag */
/* Password maintenance parameters: */
time_t fd_min; /* minimum time between password changes */
int fd_maxlen; /* maximum length of password */
time_t fd_expire; /* expiration time duration in secs */
time_t fd_lifetime; /* account death duration in seconds */
time_t fd_schange; /* last successful change in secs past 1/1/70 */
time_t fd_uchange; /* last unsuccessful change */
Hewlett-Packard Company - 1 - HP-UX 11i Version 2: August 2003
getprpwent(3) getprpwent(3)
time_t fd_acct_expire; /* absolute account lifetime in seconds */
time_t fd_max_llogin; /* max time allowed between logins */
time_t fd_pw_expire_warning; /* password expiration warning */
uid_t fd_pswduser; /* who can change this user's password */
char fd_pick_pwd; /* can user pick his own passwords? */
char fd_gen_pwd; /* can user get passwords generated for him? */
char fd_restrict; /* should generated passwords be restricted? */
char fd_nullpw; /* is user allowed to have a NULL password? */
uid_t fd_pwchanger; /* who last changed user's password */
long fd_pw_admin_num; /* password generation verifier */
char fd_gen_chars; /* can have password of random ASCII? */
char fd_gen_letters; /* can have password of random letters? */
char fd_tod[AUTH_TOD_SIZE]; /* times when user may login */
/* Login parameters: */
time_t fd_slogin; /* last successful login */
time_t fd_ulogin; /* last unsuccessful login */
char fd_suctty[14]; /* tty of last successful login */
int fd_nlogins; /* consecutive unsuccessful logins */
char fd_unsuctty[14]; /* tty of last unsuccessful login */
int fd_max_tries; /* maximum unsuc login tries allowed */
char fd_lock; /* Unconditionally lock account? */
};
struct pr_flag {
unsigned short
/* Identity: */
fg_name:1, /* Is fd_name set? */
fg_uid:1, /* Is fd_uid set? */
fg_encrypt:1, /* Is fd_encrypt set? */
fg_owner:1, /* Is fd_owner set? */
fg_boot_auth:1, /* Is fd_boot_auth set? */
fg_pw_audid:1, /* Is fd_auditcntl set? */
fg_pw_audflg:1, /* Is fd_auditdisp set? */
/* Password maintenance parameters: */
fg_min:1, /* Is fd_min set? */
fg_maxlen:1, /* Is fd_maxlen set? */
fg_expire:1, /* Is fd_expire set? */
fg_lifetime:1, /* Is fd_lifetime set? */
fg_schange:1, /* Is fd_schange set? */
fg_uchange:1, /* Is fd_fchange set? */
fg_acct_expire:1, /* Is fd_acct_expire set? */
fg_max_llogin:1, /* Is fd_max_llogin set? */
fg_pw_expire_warning:1, /* Is fd_pw_expire_warning set? */
fg_pswduser:1, /* Is fd_pswduser set? */
fg_pick_pwd:1, /* Is fd_pick_pwd set? */
fg_gen_pwd:1, /* Is fd_gen_pwd set? */
fg_restrict:1, /* Is fd_restrict set? */
fg_nullpw:1, /* Is fd_nullpw set? */
fg_pwchanger:1, /* Is fd_pwchanger set? */
Hewlett-Packard Company - 2 - HP-UX 11i Version 2: August 2003
getprpwent(3) getprpwent(3)
fg_pw_admin_num:1, /* Is fd_pw_admin_num set? */
fg_gen_chars:1, /* Is fd_gen_chars set? */
fg_gen_letters:1, /* Is fd_gen_letters set? */
fg_tod:1, /* Is fd_tod set? */
/* Login parameters: */
fg_slogin:1, /* Is fd_slogin set? */
fg_suctty: 1, /* is fd_suctty set ? */
fg_unsuctty: 1, /* is fd_unsuctty set ? */
fg_ulogin:1, /* Is fd_ulogin set? */
fg_nlogins:1, /* Is fd_nlogins set? */
fg_max_tries:1, /* Is fd_max_tries set? */
fg_lock:1; /* Is fd_lock set? */
};
struct pr_passwd {
struct pr_field ufld; /* user specific fields */
struct pr_flag uflg; /* user specific flags */
struct pr_field sfld; /* system wide fields */
struct pr_flag sflg; /* system wide flags */
};
The protected password database stores user authentication profiles.
The pr_passwd structure in the user-specific entry refers to
parameters specific to a user. The pr_passwd structure in the system
default database sets parameters that are used when there is no userspecific
override.
The user-specific entry is keyed on the fd_name field, which is a
cross reference to the /etc/passwd or the Network Information Service
Plus (NIS+) passwd table entry for the user. The fd_uid field must
match the UID in that file or the NIS+ passwd table as well. The
fd_encrypt field is the encrypted password. The password is encrypted
in eight character segments, so the size of this field is a multiple
of the number of characters in an encrypted segment
(AUTH_CIPHERTEXT_SIZE macro).
fd_owner is the user name accountable for the account. The
fd_boot_auth field is used when the system default file specifies boot
authorization is required. init(1M) prompts for a user name and
password. If the authentication succeeds, a value in this field allows
the user to continue the system boot process.
fd_min is the time, in seconds, that must elapse before the user can
change passwords. fd_maxlen is the maximum password length (in
characters) for the user. fd_expire is the time, in seconds, until
the user's password expires. fd_lifetime is the number of seconds
that must elapse before the password dies. The account is considered
locked if the password is dead.
Hewlett-Packard Company - 3 - HP-UX 11i Version 2: August 2003
getprpwent(3) getprpwent(3)
fd_schange and fd_uchange record the last successful and unsuccessful
password change times.
The fd_acct_expire field specifies the absolute period of time in
seconds that the account can be used. An absolute expiration date may
be specified, which is then converted into seconds stored in this
field. This is different from fd_expire in that fd_acct_expire
specifies an absolute expiration date, while fd_expire is reset with
each password change.
fd_max_llogin specifies the maximum time in seconds allowed since the
last login before the account becomes locked. fd_pw_expire_warning is
the time in seconds before the end of fd_expire that the system warns
the user the password is about to expire. fd_pswduser stores the user
ID of the user allowed to change passwords for the account.
Typically, this is the account owner.
The next flag fields control password generation. fd_pick_pwd, if
set, allows the user to pick his or her own password. fd_nullpw, if
set, allows the account to be used without a password. fd_gen_pwd
enables the use of the random pronounceable password generator for
passwords for this account. fd_gen_chars and fd_gen_letters allow the
password generator to generate passwords composed of random printable
characters and random letters, neither of which is easy to remember.
The password change software allows the user to pick from whichever
options are available for his or her account. One of these three
fields (fd_gen_pwd, fd_gen_chars, or fd_gen_letters) must be set.
fd_pwchanger is the user ID of the user who last changed the password
on the user's account, if it was not the account owner. fd_restrict,
if set, causes triviality checks to be made after the account password
has been chosen to avoid palindromes, user name and machine name
permutations, and words appearing in the dictionary.
The fd_tod specifier is a string, formatted like the UUCP Systems
file, which specifies time intervals during which the user can log in.
The next fields are used to protect against login spoofing, listing
the time and location of last login. fd_slogin and fd_ulogin are time
stamps of the last successful and unsuccessful login attempts.
fd_suctty and fd_unsuctty are the terminal device or (if supported)
host names of the terminal or host from which the last login attempt
occurred.
fd_nlogins is the number of unsuccessful login attempts since the last
successful login. It is reset to zero after a successful login.
fd_max_tries is the number of unsuccessful attempts until the account
is considered locked.
fd_lock indicates whether the administrative lock on the account is
set. Note that an account may be considered disabled (locked) for
Hewlett-Packard Company - 4 - HP-UX 11i Version 2: August 2003
getprpwent(3) getprpwent(3)
reasons not indicated by fd_lock. The account is considered disabled
(locked) if one or more of these activities has occurred:
1. if the password is dead,
2. if the maximum number of unsuccessful attempts has been
exceeded,
3. if the administrative lock is set,
4. if the account expiration is reached, or
5. if the time since last login is exceeded.
When getprpwent is first called, it returns a pointer to the first
user pr_passwd structure in the database; thereafter, it returns a
pointer to the next pr_passwd structure in the database so that
successive calls can be used to search the database. Note that
entries without a corresponding entry in /etc/passwd are skipped.
However, if NIS+ is configured, the entries are not skipped for users
that have an entry in the NIS+ passwd table and the local protected
database. A local protected database entry is created at login time
for each NIS+ user that does not have an entry in the local protected
database. The entries are scanned in the order they appear in
/etc/passwd or in the NIS+ passwd table if NIS+ is configured and if
the nsswitch.conf file refers to NIS+ first (for example, an entry in
nsswitch.conf would contain passwd: nisplus files).
getprpwuid searches from the beginning of the database until a
numerical user ID matching uid is found and returns a pointer to the
particular structure in which it was found. getprpwaid functions like
getprpwuid only it uses the audit ID instead of the UID.
getprpwnam searches from the beginning of the database until a login
name matching name is found, and returns a pointer to the particular
structure in which it was found. If an end-of-file or an error is
encountered on reading, these functions return a NULL pointer.
A call to setprpwent has the effect of rewinding the protected
password database to allow repeated searches. endprpwent can be
called to close the protected password database when processing is
complete.
putprpwnam puts a new or replaces a protected password entry pr with
key name into the database. If the uflg.fg_name field is 0, the
requested entry is deleted from the protected password database.
putprpwnam locks the database for all update operations, and performs
a endprpwent after the update or failed attempt. For NIS+, this
function will add or remove protected password information from the
passwd table and/or trusted table and/or the local protected database.
NOTES [Toc] [Back]
The value returned by getprpwent and getprpwnam refers to a structure
that is overwritten by calls to these routines. To retrieve an entry,
modify it, and replace it in the database, copy the entry using
Hewlett-Packard Company - 5 - HP-UX 11i Version 2: August 2003
getprpwent(3) getprpwent(3)
structure assignment and supply the modified buffer to putprpwnam.
On systems supporting network connections, the fd_suctty and
fd_unsuctty fields can be the ASCII representation of the network
address of the host from which the last successful or unsuccessful
remote login to the account occurred. Use getdvagnam (see
getdvagent(3)) to investigate the type of device to determine whether
a host or a terminal was used for the last successful or unsuccessful
login.
Programs using these routines must be compiled with -lsec.
If you link your application with the archive version of libsec
(libsec.a), these routines work independent of NIS+ or the Name
Service Switch. The protected password database exists only in the
local system; for example, /tcb only and not the NIS+ passwd or
trusted table.
getprpwent assumes one name per UID and one UID per name. The
sequential scan loops between the first two instances of a multiple
UID.
getprpwent uses getpwent(3C) routines to sequentially scan databases.
User program references to password entries obtained using
getpwent(3C) routines will not be valid after using any routines
described here (that is, the * prp* routines).
If NIS+ is configured in your system, the protected password
information can be stored in three different repositories:
1. The NIS+ passwd Table for the local domain.
2. The NIS+ Trusted Table for the local domain.
3. The Local Protected Database file.
Additionally, all of these routines depend on the configuration of the
Name Service Switch file, /etc/nsswitch.conf. These routines use the
switch for the passwd database.
APPLICATION USAGE [Toc] [Back]
In a multithreaded application, these routines are safe to be called
only from one dedicated thread. These routines are not POSIX.1c
async-cancel safe nor async-signal safe. In an NIS+ namespace, the
user should be aware of the configuration of the /etc/nsswitch.conf
file because protected password information is stored in three
different repositories: passwd table, trusted table, and local
database. The Name Service Switch database used for the protected
database API is passwd (for example, an entry in /etc/nsswitch.conf
would contain passwd: nisplus files).
Hewlett-Packard Company - 6 - HP-UX 11i Version 2: August 2003
getprpwent(3) getprpwent(3)
RETURN VALUE [Toc] [Back]
getprpwent, getprpwuid, getprpwaid, and getprpwnam return NULL
pointers on EOF or error. putprpwnam returns 0 if it cannot add or
update the entry.
FILES [Toc] [Back]
/etc/passwd System Password file
/tcb/files/auth/*/* Protected Password
database
/tcb/files/auth/system/default System Defaults database
NIS+ TABLES
passwd, trusted
SEE ALSO [Toc] [Back]
authcap(4), getpwent(3C), getprdfent(3), prpwd(4), ttsyncd(1M),
nis+(1).
Hewlett-Packard Company - 7 - HP-UX 11i Version 2: August 2003 [ Back ] |
