getprpwent(3)

NAME

getprpwent(), getprpwuid(), getprpwnam(), getprpwaid(), setprpwent(), endprpwent(), putprpwnam() — manipulate protected password database entries (for trusted systems only)

SYNOPSIS

#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

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 */
     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? */
          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 user-specific override.

The user-specific entry is keyed on the fd_name field, which is a cross reference to the /etc/passwd entry for the user. The fd_uid field must match the UID in that file. 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. The init command 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.

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 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. The entries are scanned in the order they appear in /etc/passwd.

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.

Notes

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 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 the Name Service Switch. The protected password database exists only in the /tcb directory on the local system.

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).

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

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. The Name Service Switch database used for the protected database API is passwd. For example, an entry in /etc/nsswitch.conf would contain passwd: files.

RETURN VALUE

getprpwent, getprpwuid, getprpwaid, and getprpwnam return NULL pointers on EOF or error. putprpwnam returns 0 if it cannot add or update the entry.

WARNINGS

HP-UX 11i Version 3 is the last release to support trusted systems functionality.

FILES

/etc/passwd: System Password file
/tcb/files/auth/*/*: Protected Password database
/tcb/files/auth/system/default: System Defaults database

getprpwent(3)

Technical documentation

» Table of Contents

» Index