getprpwent(S) 6 January 1993 getprpwent(S) Name getprpwent, getprpwuid, getprpwnam, setprpwent, endprpwent, putprpwnam - manipulate protected password database entry Syntax cc . . . -lprot -lx #include <sys/types.h> #include <sys/security.h> #include <sys/audit.h> #include <prot.h> struct pr_passwd *getprpwent () struct pr_passwd *getprpwuid (uid) int uid; struct pr_passwd *getprpwnam (name) char *name; void setprpwent () void endprpwent () int putprpwnam (name, pr) char *name; struct pr_passwd *pr; Description The getprpwent, getprpwuid and getprpwnam routines each returns a pointer to an object with the following structure containing the broken-out fields of a line in the protected password database. Only entries in the database dealing with users are scanned. Before using getprpwent, call the setauthparameters(S) routine. This routine is documented on the identity(S) manual page. Each line in the database contains a prpasswd structure, declared in the <prot.h> header file: struct pr_passwd { /* Fields associated with this user */ struct pr_field ufld; /* Flags associated with this user */ struct pr_flag uflg; /* Fields associated with system */ struct pr_field sfld; /* Flags associated with system */ struct pr_flag sflg; }; struct pr_field { /* Identity: */ /* uses 8 character maximum from utmp */ char fd_name[9]; /* uid associated with name above */ ushort fd_uid; /* Encrypted password, 8 characters max */ char fd_encrypt[14]; /* user type - see user_type */ mask_t fd_type[AUTH_TYPEVEC_SIZE]; /* if a pseudo -user, the user behind it */ char fd_owner[9]; /* nice value with which to login */ /* command privilege vector */ int fd_nice; mask_t fd_cprivs[AUTH_CPRIVVEC_SIZE]; /* system privilege vector */ mask_t fd_sprivs[SEC_SPRIVVEC_SIZE]; /* audit control */ mask_t fd_auditcntl[AUTH_AUDITMASKVEC_SIZE]; /* audit disposition */ mask_t fd_auditdisp[AUTH_AUDITMASKVEC_SIZE]; /* Password maintenance parameters: */ /* min time between pswd changes */ time_t fd_min; /* maximum length of password */ int fd_maxlen; /* expiration time duration in secs */ time_t fd_expire; /* account death time duration in secs */ time_t fd_lifetime; /* last successful change */ time_t fd_schange; /* last unsuccessful change */ time_t fd_uchange; /* who can change this user's password */ ushort fd_pswduser; /* can user pick his own passwords? */ char fd_pick_pwd; /* can user get pswds generated for him? */ char fd_gen_pwd; /* should generated pswds be restricted? */ char fd_restrict; /* is user allowed to have a null password? */ char fd_nullpw; /* Login parameters: */ /* last successful login */ time_t fd_slogin; /* tty of last successful login */ char fd_suctty[12]; /* last unsuccessful login */ time_t fd_ulogin; /* tty of last unsuccessful login */ char fd_unsuctty[12]; /* consecutive unsuccessful logins */ short fd_nlogins; /* maximum unsuccessful login tries allowed */ ushort fd_max_tries; /* unconditionally lock account? */ char fd_lock; /* System parameters: */ /* require a password on single user shell? */ char fd_standpswd; /* system security class */ mask_t fd_secclass[AUTH_SECCLASSVEC_SIZE]; }; struct pr_flag { unsigned /* Identity: */ fg_name:1, /* Is fd_name set? */ fg_uid:1, /* Is fd_uid set? */ fg_encrypt:1, /* Is fd_encrypt set? */ fg_type:1, /* Is fd_type set? */ fg_owner:1, /* Is fd_owner set? */ fg_nice:1, /* Is fd_nice set? */ fg_cprivs:1, /* Is fd_sprivs set? */ fg_sprivs:1, /* Is fd_sprivs set? */ fg_auditcntl:1, /* Is fd_auditcntl set? */ fg_auditdisp: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_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? */ /* 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? */ fg_standpswd:1, /* Is fd_standpswd set? */ fg_secclass:1; /* Is fd_secclass set? */ }; Because these structures are declared in <prot.h>, it is not necessary to redeclare them. When the getprpwent routine is first called, it returns a pointer to the first user prpasswd structure in the database. Thereafter, it returns a pointer to the next user prpasswd structure in the database. So, succes- sive calls can be used to search the entire database. Note that entries without a corresponding entry in the /etc/passwd file are skipped. The entries are scanned in the order they appear in /etc/passwd. getprpwent(S) truncates the encrypted password string (upwd) in the pro- tected password entry, so that a comparison of the value returned by bigcrypt(S) (described on the getpasswd(S) manual page) succeeds if the password would have matched on the first (upwseg * 8) cleartext charac- ters. For the purposes of checking passwords, this is transparent to the appli- cation. To provide backward compatibility to applications and allow upwseg to be reduced and then increased again without losing informa- tion, it is important that the stored encrypted password (set using putprpwnam(S) when the password is changed) not be truncated. So that the sequence of getprpwent, putprpwnam does not truncate the stored password when upwseg is smaller than the password in the entry, the operating system stores the original stored value of upwd. putprpwnam restores upwd to this saved value if the new value matches the truncated saved value. The getprpwuid routine searches from the beginning of the database until a numerical user ID matching the argument uid is found. getprpwuid returns a pointer to the particular prpasswd structure in which the argument uid was found. Like getprpwuid, the getprpwnam routine searches from the beginning of the database file until a login name matching the argument name is found. getprpwnam returns a pointer to the particular prpasswd structure in which the argument name was found. The setprpwent routine resets the file pointer to the beginning of the protected password files to allow repeated searches. The endprpwent rou- tine closes the protected password files when processing is complete. The putprpwnam routine puts a new or replaced protected password entry pr with key name into the protected password database. If the uflg.fgname structure member is 0, the requested entry is deleted from the protected password database. The putprpwnam routine locks the database for all update operations, and performs an endprpwent after the update or failed attempt. Return value Upon successful completion, the routines getprpwent, getprpwuid, and get- prpwnam each returns a pointer to a prpasswd structure. The putprpwnam routine returns a non-zero value on a successful substitution, deletion, or addition and a value of zero upon failure. If an end-of-file or an error is encountered on reading, these routines return a NULL pointer. No errors are defined for the setprpwent or endprpwent routines. Diagnostics Use feof() to test if a null return value is caused by an end-of-file or from a syntax error in the protected password database file. The feof macro is described in the ferror(S) manual page. Warning These routine fail if setauthparameters has not been called before using getprpwent. setauthparameters is described in the identity(S) manual page. Note All information is contained in a static area, so it must be copied if it is to be saved. Otherwise, it may be overwritten on subsequent calls to these routines. These routines assume one name per user ID and one user ID per name. Oth- erwise, the sequential search loops between the first two instances of a multiple user ID. Files /etc/passwd /tcb/files/auth/*/* See also authcap(F), authcap(S), bigcrypt(S), getpasswd(S), getprdfent(S), getprfient(S), getprpwent(S), getprtcent(S), getpwent(S), identity(S) Standards conformance endprpwent, getprpwent, getprpwnam, getprpwuid, putprpwnam and setprpwent are not part of any currently supported standard; they are an extension of AT&T System V provided by the Santa Cruz Operation.