 |
Index for
Section 3 |
|
 |
Alphabetical
listing for G |
|
 |
Bottom of
page |
|
getespwent(3)
NAME
getespwent, getespwuid, getespwnam, setprpwent, endprpwent, putespwnam,
getprpwent, getprpwuid, getprpwnam, putprpwnam, copyespwent - Manipulate
protected password database entry (Enhanced Security)
SYNOPSIS
#include <sys/types.h>
#include <sys/security.h>
#include <prot.h>
struct es_passwd *getespwent(
void );
struct es_passwd *getespwent(
void );
struct es_passwd *getespwuid(
int uid );
struct es_passwd *getespwnam(
char *name );
void setprpwent(
void );
void endprpwent(
void );
int putespwnam(
char *name,
struct es_passwd *pr );
struct es_passwd *copyespwent(
struct es_passwd *pr );
Note
The getprpwent(), getprpwuid(), getprpwnam(), and putprpwnam()
routines have been replaced by getespwent(), getespwuid(),
getespwnam(), and putespwnam() respectively.
LIBRARY
Security Library libsecurity.so
NOTE: In order to quickstart a program, the program must be linked as
follows:
-lsecurity -ldb -laud -lm
See the shared library discussion in the Programmer's Guide for more
information about using the quickstarting feature.
PARAMETERS
uid Specifies the user ID in the protected password database.
name
Specifies a protected password database entry name.
pr Specifies a protected password database entry structure.
DESCRIPTION
The getespwent(), getespwuid(), getespwnam(), and copyespwent() 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 es_passwd structure, declared in the prot.h
header file as follows:
/* Values for the "source" field in the escap prologue */
struct espw_field {
/* Identity: */
char *fd_name;
uid_t fd_uid; /* uid associated with name above */
char *fd_encrypt; /* Encrypted password */
char *fd_owner; /* if a pseudo -user, the user behind it */
int fd_nice; /* nice value with which to login */
mask_t *fd_cprivs; /* command authorization vector */
priv_t *fd_sprivs; /* kernel authorizations vector */
priv_t *fd_bprivs; /* base privilege vector */
char *fd_auditdisp; /* auditmask text */
uint_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 */
int fd_minchosen; /* minimum length of chosen password */
int fd_maxchosen; /* maximum length of chosen password */
time_t fd_expire; /* soft expiration interval (seconds) */
time_t fd_lifetime; /* hard expiration interval (seconds) */
time_t fd_schange; /* last success 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 gen. for him? */
char fd_restrict; /* should gen. passwords be restricted? */
char fd_policy; /* check passwords by policy callout ? */
char fd_nullpw; /* is user allowed a null password? */
uid_t fd_pwchanger; /* who last changed this user's password */
char fd_gen_chars; /* can have password of random ASCII? */
char fd_gen_letters; /* can have password of random letters? */
int fd_pwdepth; /* depth of password dictionary to keep */
char *fd_pwdict; /* password history dictionary */
uchar_t fd_oldcrypt; /* algorithm index for current crypt func */
uchar_t fd_newcrypt; /* algorithm index for next crypt func */
/* Mandatory policy parameters: */
mand_ir_t *fd_clearance; /* internal representation of clearance */
/* Login parameters: */
time_t fd_slogin; /* last successful login */
time_t fd_ulogin; /* last unsuccessful login */
char *fd_suctty; /* tty of last successful login */
int fd_nlogins; /* consecutive unsuccessful logins */
int fd_flogins; /* unsuccessful login attempts */
char *fd_unsuctty; /* tty of last unsuccessful login */
char *fd_tod; /* times when user may login */
int fd_max_tries; /* maximum unsuc login tries allowed */
time_t fd_unlockint; /* interval (secs) before unlocking again */
char fd_retired; /* Is account retired? */
char fd_lock; /* Unconditionally lock account? */
time_t fd_expdate; /* time to auto-retire the account */
char fd_istemplate; /* this account is a template only */
char *fd_template; /* name of (template) account for defaults */
time_t fd_vac_start; /* time of user's scheduled vacation */
time_t fd_vac_end; /* time when password policy is actived */
ulong_t fd_rlim_cpu; /* RLIMIT_CPU rlim_max for setrlimit */
ulong_t fd_rlim_fsize; /* RLIMIT_FSIZE rlim_max for setrlimit */
ulong_t fd_rlim_data; /* RLIMIT_DATA rlim_max for setrlimit */
ulong_t fd_rlim_stack; /* RLIMIT_STACK rlim_max for setrlimit */
ulong_t fd_rlim_core; /* RLIMIT_CORE rlim_max for setrlimit */
ulong_t fd_rlim_rss; /* RLIMIT_RSS rlim_max for setrlimit */
ulong_t fd_rlim_nofile; /* RLIMIT_NOFILE rlim_max for setrlimit */
ulong_t fd_rlim_vmem; /* RLIMIT_VMEM rlim_max for setrlimit */
time_t fd_max_login_int; /* max time between logins before lockout */
time_t fd_grace_limit; /* you have until this time to fix things */
char fd_psw_chg_reqd; /* password change required */
};
struct espw_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? */
fg_oldcrypt:1, /* Is fd_oldcrypt set? */
fg_newcrypt:1, /* Is fd_newcrypt 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? */
fg_istemplate:1, /* Is fd_istemplate set? */
fg_template:1, /* Is fd_template set? */
fg_vac_start:1, /* Is fd_vac_start set? */
fg_vac_end:1, /* Is fd_vac_end set? */
fg_rlim_cpu:1, /* Is fd_rlim_cpu set? */
fg_rlim_fsize:1, /* Is fd_rlim_fsize set? */
fg_rlim_data:1, /* Is fd_rlim_data set? */
fg_rlim_stack:1, /* Is fd_rlim_stack set? */
fg_rlim_core:1, /* Is fd_rlim_core set? */
fg_rlim_rss:1, /* Is fd_rlim_rss set? */
fg_rlim_nofile:1, /* Is fd_rlim_nofile set? */
fg_rlim_vmem:1, /* Is fd_rlim_vmem set? */
fg_max_login_int:1, /* Is fd_max_login_int set? */
fg_grace_limit:1, /* Is fd_grace_limit set? */
fg_psw_chg_reqd:1 /* Is fd_psw_chg_reqd set? */
;
};
struct es_passwd {
AUTH_ESCAP_COMMON /* overhead fields */
size_t fieldlen; /* length of 1 of our field structs */
struct espw_field *ufld; /* Fields assoc with this user */
struct espw_flag *uflg; /* Flags assoc with this user */
struct espw_field *sfld; /* Fields assoc with system */
struct espw_flag *sflg; /* Flags assoc with system */
}; typedef struct es_passwd es_profile;
The protected password database stores user authentication profiles. The
es_passwd structure in the user-specific entry refers to parameters
specific to a user, while the es_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.
fd_owner
This field is reserved for future use.
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. This field is reserved for
future use.
fd_bprivs
Stores the user's base privileges. The fd_sprivs filed must be a
superset of fd_bprivs. This field is reserved for future use.
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_minchosen
The number in this field specifies the minimum length of the user
account password for user-chosen passwords only. If the field is zero,
a dynamic value is calculated as defined in the Green Book.
fd_maxchosen
The number in this field specifies the maximum length of the user
account password for user-chosen passwords only. To encourage longer,
more secure user passwords, set it to allow the system-wide maximum
value defined by the <prot.h> constant AUTH_MAX_PASSWD_LENGTH.
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.
fd_auditdisp
Text string representing the audit mask to use for this entry.
fd_auditcntl
Audit mask user control (AUD_OR, etc., from <sys/audit.h>.
fd_minlen
Minimum length of a password, if non-zero. A value of 0 for fd_minlen
indicates that a calculated minimum should be used, based on the other
password generation parameters. To allow passwords of lengths 0 and
up, set this field to 1 and set fd_nullpw.
fd_flogins
Displayable count of the number of unsuccessful login attempts. The
system-wide default d_skip_fail_login_log controls whether or not this
field is updated at each login failure.
fd_policy
Flag determining that the site password policy callout should be
consulted to determine whether a given password is acceptable (whether
as the result of password generation or from user input). fd_policy
goes with fd_restrict.
fd_pwdepth
Number of old encrypted passwords to keep in the password dictionary.
If zero, the current password is still not eligible for re-use.
fd_pwdict
A comma-separated list of old encrypted passwords, which are not
eligible for re-use.
fd_oldcrypt
Encryption algorithm index associated with the current encrypted
password in fd_encrypt. For use with the dispcrypt() function in
password validation.
fd_newcrypt
The desired encryption algorithm to be used to encode the next password
which gets set for this user. For use with the dispcrypt() function in
password setting.
fd_unlockint
Seconds after fd_ulogin when fd_nlogins is ignored for determining
whether the account is locked, if this field is non-zero.
fd_expdate
Timestamp, from time(), of when the account is no longer considered
valid for logging in to.
fd_istemplate
Flag for whether this account is a template account only. Template
accounts are not allowed to log in, and may not have associated entries
in the /etc/passwd file.
fd_template
Name of a template account for default fields, in preference to those
in /etc/auth/system/default.
fd_vac_start
Timestamp of when the user's vacation begins.
fd_vac_end
Timestamp of when the user's vacation is over.
fd_rlim_cpu
RLIMIT_CPU rlim_max for the setrlimit() call during login.
fd_rlim_fsize
RLIMIT_FSIZE rlim_max for the setrlimit() call during login.
fd_rlim_data
RLIMIT_DATA rlim_max for the setrlimit() call during login.
fd_rlim_stack
RLIMIT_STACK rlim_max for the setrlimit() call during login.
fd_rlim_core
RLIMIT_CORE rlim_max for the setrlimit() call during login.
fd_rlim_rss
RLIMIT_RSS rlim_max for the setrlimit() call during login.
fd_rlim_nofile
RLIMIT_NOFILE rlim_max for the setrlimit() call during login.
fd_rlim_vmem
RLIMIT_VMEM rlim_max for the setrlimit() call during login.
fd_max_login_int
The maximum inter-login interval allowed (in seconds) before
considering the account to be locked. If zero, there is no limit.
fd_grace_limit
Timestamp, if set and non-zero, of a time limit for letting the user
log in despite anything which the locked_out_es() function describes as
locking out a user.
fd_psw_chg_reqd
Flag indicating that the user must change his or her password during
the next login before it can succeed, even if it has not yet
(otherwise) expired.
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. See
the locked_out_es(3) reference page for more detailed information.
fd_retired
An indicator of whether the account has been retired. Once retired,
the user ID and name may not be reused.
When the getespwent() function is first called, it returns a pointer to the
first user es_passwd structure in the database; thereafter, it returns a
pointer to the next es_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 getespwuid() 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 getespwnam() 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.
The copyespwent() function copies pr, and the fields to which it refers, to
a newly allocated data area. Because the getespwent() and putespwent()
functions reuse a static structure when accessing the database, the values
of any entry must be saved if the database routines are used again. The
es_passwd structure returned by copyespwent() can be freed using the free()
function.
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 putespwnam() 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
putespwnam() function locks the database for all update operations, and
calls the endprpwent() function after the update or failed attempt.
NOTES
Structures returned by the database routines contain pointers to character
strings and lists rather than being self-contained. The copy function must
be used rather than doing a structure assignment to save a returned
structure.
The value returned by the getespwent() and getespwnam() 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 copyespwent() and supply the modified buffer to putespwnam().
Programs using these functions must be compiled with -lsecurity.
The getespwent() 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 /tcb/bin/pwpolicy that allows
for site-specific security checks. The path to the file is defined by the
d_pw_site_callout entry in the /etc/auth/system/default file.
RESTRICTIONS
Programs must call set_auth_parameters() before any other action in main().
CAUTIONS
Structures returned by the database routines contain pointers to character
strings and lists rather than being self-contained. The copyespwent()
function must be used rather than doing a structure assignment to save a
returned structure.
The value returned by the getespwent(), getespwuid(), and getespwnam()
functions refers to a structure that is overwritten by calls to the
function. To retrieve an entry, modify it, and replace it in the database,
you must copy the entry using the copyespwent() function and supply the
modified buffer to the putespwent() function.
RETURN VALUES
The getespwent(), getespwuid(), and getespwnam() functions return null
pointers on EOF or error.
The putespwnam() function returns 0 (zero) if it cannot add or update the
entry.
The copyespwent() function returns a pointer, or NULL on (allocation)
error.
FILES
/etc/passwd
System password file
/tcb/files/auth.db
Protected password database for UIDs from 0 to 99.
/var/tcb/files/auth.db
Protected password database for UIDs 100 and up.
/tcb/files/auth/*/*
Old protected password database
/etc/auth/system/default
System defaults database
/usr/include/prot.h
General security databases file.
SEE ALSO
Functions: getpwent(3), getesdfent(3), locked_out_es(3)
Files: authcap(4), prpasswd(4)
Security
|
Index for
Section 3 |
|
|
Alphabetical
listing for G |
|
 |
Top of
page |
|