Content-type: text/html Man page of getprpwent

getprpwent

Section: C Library Functions (3)
Index Return to Main Contents
 

NAME

getprpwent, getprpwuid, getprpwnam, putprpwnam - Manipulate protected password database entry (Enhanced Security)  

LIBRARY

Security Library libsecurity.a  

SYNOPSIS

#include <sys/types.h> #include <sys/security.h> #include <prot.h>

struct pr_passwd *getprpwent(void);

struct pr_passwd *getprpwent(void);

struct pr_passwd *getprpwuid(        int uid);

struct pr_passwd *getprpwnam(        char *name);

void setprpwent(void);

void endprpwent(void);

int putprpwnam(        char *name,
       struct pr_passwd *pr );

 

PARAMETERS

Specifies the user ID in the protected password database. Specifies a protected password database entry name. Specifies a protected password database entry structure.  

DESCRIPTION

The getprpwent(), getprpwuid() and getprpwnam() functions each return a pointer to an object with the following 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 as follows: struct pr_field {
 /* Identity: */
 char    fd_name[AUTH_MAX_UNAME_SIZE]; /* uses 8 character \
                                       maximum (and \0) from utmp */
 uid_t   fd_uid;         /* uid associated with name above */
 char    fd_encrypt[AUTH_MAX_CIPHERTEXT_LENGTH]; /* Encrypted \
                                                   password */
 char    fd_owner[AUTH_MAX_UNAME_SIZE];  /* if a pseudo -user, \
                                           the user behind it */
 int     fd_nice;        /* nice value with which to login */
 mask_t  fd_cprivs[AUTH_CPRIVVEC_SIZE];  /* command auths vector */
 privvec_t  fd_sprivs;   /* kernel auths vector */
 privvec_t  fd_bprivs;   /* base privilege vector */
 char    fd_auditdisp[AUTH_MAX_AUDIT_LENGTH];   /* auditmask text */
 uchar_t fd_auditcntl;   /* audit mask use control */


 /* Password maintenance parameters: */
 time_t  fd_min;         /* minimum time between password changes */
 int     fd_minlen;      /* minimum length of password */
 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 */
 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_policy;      /* check passwords by policy callout ? */
 char    fd_nullpw;      /* is user allowed to have a null \
                                                      password? */
 uid_t   fd_pwchanger;   /* who last changed user's password */
 char    fd_gen_chars;   /* can have password of random ASCII? */
 char    fd_gen_letters; /* can have password of random letters? */
 char    fd_pwdepth;     /* depth of password dictionary to keep */


 /* Mandatory policy parameters: */
 mand_ir_t fd_clearance; /* internal representation of clearance */
 char fd_clearance_filler[200]; /* MUST follow fd_clearance */


 /* 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 */
 short   fd_nlogins;     /* consecutive unsuccessful logins */
 char    fd_unsuctty[14];/* tty of last unsuccessful login */
 char    fd_tod[AUTH_TOD_SIZE];  /* times when user may login */
 short   fd_max_tries;   /* maximum unsuc login tries allowed */
 time_t  fd_unlockint;   /* interval (seconds) before unlocking \
                                                          again */
 char    fd_retired;    /* Is account retired? */

 char    fd_lock;        /* Unconditionally lock account? */
 time_t  fd_expdate;     /* time at which to auto-retire the \
                                                         account */ };

struct pr_flag {
 unsigned int
 /* 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_nice:1,              /* Is fd_nice set? */
 fg_cprivs:1,            /* Is fd_sprivs set? */
 fg_sprivs:1,            /* Is fd_sprivs set? */
 fg_bprivs:1,            /* Is fd_bprivs 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_minlen:1,            /* Is fd_minlen 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_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_policy:1,            /* Is fd_policy set? */
 fg_nullpw:1,            /* Is fd_nullpw set? */
 fg_pwchanger:1,         /* Is fd_pwchanger set? */
 fg_pwdepth:1,           /* Is fd_pwdepth set? */
 fg_pwdict:1,            /* Is fd_pwdict set? */
 fg_gen_chars:1,         /* Is fd_gen_chars set? */
 fg_gen_letters:1,       /* Is fd_gen_letters set? */


 /* Mandatory policy parameters: */
 fg_clearance:1,         /* Is fd_clearance 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_retired:1,          /* Is fd_retired set? */

 fg_lock:1,              /* Is fd_lock set? */
 fg_unlockint:1,         /* Is fd_unlockint set? */
 fg_tod:1,               /* Is fd_tod set? */
 fg_expdate:1,           /* Is fd_expdate 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, while 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 as well. The balance of the fields are defined as follows:

fd_encrypt
The encrypted password. The password is encrypted in 8-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
The user name accountable for the account. The system guarantees that only that user is allowed to use the su program to assume the identity of the user.
fd_nice
Sets the nice() value of the login shell.
fd_cprivs
The command authorizations vector for the user. This field is reserved for future use.
fd_sprivs
Stores the user's kernel authorizations.
fd_bprivs
Stores the user's base privileges. The fd_sprivs filed must be a superset of fd_bprivs. The audit control mask lists the user's overrides of the corresponding disposition bit. If the bit is on, the system always audits the event type for that user. If the bit is off, the user is never audited for that event type.
fd_min
The time, in seconds, that must elapse before the user can change passwords.
fd_maxlen
The maximum password length (in characters) for the user.
fd_expire
The time, in seconds, between the successful password change and the password expiration time.
fd_lifetime
The number of seconds that must elapse after a successful password change before the password dies. The account is considered locked if the password is dead.
fd_schange and fd_uchange
The last successful and unsuccessful password change times.

The following flag fields control password generation (the term "set" means anything non-zero and the term "not set" means zero):

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
Allows the password generator to generate passwords composed of random printable characters and random letters, which are not easy to remember. The password change software allows the user to pick from whichever options are available for their accounts.
fd_pwchanger
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.
fd_tod
A string, formatted like the UUCP systems file, which specifies time intervals, during which the user may log in. The following fields are used to protect against login spoofing, listing the time and location of last login:
fd_slogin and fd_ulogin
Timestamps of the last successful and unsuccessful login attempts.
fd_suctty and fd_unsuctty
The terminal device or host (if supported) names of the terminal or host from which the last login attempt occurred.
fd_nlogins
The number of unsuccessful login attempts since the last successful login. It is reset to zero after a successful login.
fd_max_tries
The number of unsuccessful attempts until the account is considered locked.
fd_lock
Indicates whether the administrative lock on the account is set. The account is considered disabled (locked) if the password is dead, if the maximum number of unsuccessful attempts has been exceeded, or the administrative lock is set.
fd_retired
An indicator of whether the account has been retired. Once retired, the user ID and name may not be reused.

When the getprpwent() function 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 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. The getprpwuid() function 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. The getprpwnam() function 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. The endprpwent() function may be called to close the protected password database when processing is complete.

The putprpwnam() function puts a new or replaced protected password entry pr with key name into the database. If the uflg.fg_name field is 0 (zero), the requested entry is deleted from the protected password database. The putprpwnam() function locks the database for all update operations, and calls the endprpwent() function after the update or failed attempt.  

RESTRICTIONS

The putprpwnam() routine can not be used to update the fields in a NIS-distributed protected password database entry.

Programs must call set_auth_parameters() before any other action in main().  

NOTES

The value returned by the getprpwent() and getprpwnam() functions refers to a structure that is overwritten by calls to these functions. To retrieve an entry, modify it, and replace it in the database, you must 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 are slave pty names.

Programs using these functions must be compiled with -lsecurity.

The getprpwent() function assumes one name per UID and one UID per name. The sequential scan loops between the first two instances of a multiple UID.

A program uses the getpwent() functions to sequentially scan the databases. User program references to password entries obtained using these functions will not be valid after using any of the functions in this reference page.

The policy callout is to a file located at that allows for site-specific security checks. The path to the file is defined by the entry in the file.  

RETURN VALUES

The getprpwent(), getprpwuid(), and getprpwnam() functions return null pointers on EOF or error. The putprpwnam() function returns 0 (zero) if it cannot add or update the entry.  

FILES

System password file Protected password database System defaults database General security databases file.  

RELATED INFORMATION

Functions: getpwent(3), getprdfent(3), time_lock(3) delim off


 

Index

NAME
LIBRARY
SYNOPSIS
PARAMETERS
DESCRIPTION
RESTRICTIONS
NOTES
RETURN VALUES
FILES
RELATED INFORMATION

This document was created by man2html, using the manual pages.
Time: 02:40:47 GMT, October 02, 2010