getespwuid man page on DigitalUNIX

Man page or keyword search:  
man Server   12896 pages
apropos Keyword Search (all sections)
Output format
DigitalUNIX logo
[printable version]

getespwent(3)							 getespwent(3)

NAME
       getespwent, getespwuid, getespwnam, setprpwent, endprpwent, putespwnam,
       getprpwent, getprpwuid, getprpwnam, putprpwnam, copyespwent  -  Manipu‐
       late 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
       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  getespwent(),  getespwuid(), getespwnam(), and copyespwent() func‐
       tions 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 */ };	 type‐
       def 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: The encrypted password.  This  field  is
       reserved	 for  future  use.   Sets the nice() value of the login shell.
       The command authorizations vector for the user. This field is  reserved
       for future use.	Stores the user's kernel authorizations. This field is
       reserved for future  use.   Stores  the	user's	base  privileges.  The
       fd_sprivs filed must be a superset of fd_bprivs. This field is reserved
       for future use.	The time, in seconds, that must elapse before the user
       can  change passwords.  The maximum password length (in characters) for
       the user.  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.   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.	 The time,  in
       seconds,	 between the successful password change and the password expi‐
       ration time.  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.	The last successful  and  unsuccessful
       password	 change times.	Text string representing the audit mask to use
       for  this  entry.   Audit  mask	user  control  (AUD_OR,	  etc.,	  from
       <sys/audit.h>.	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.	  Dis‐
       playable	 count	of the number of unsuccessful login attempts. The sys‐
       tem-wide default d_skip_fail_login_log controls	whether	 or  not  this
       field  is   updated  at	each login failure.  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 genera‐
       tion or from user input).  fd_policy goes with fd_restrict.  Number  of
       old  encrypted  passwords  to keep in the password dictionary. If zero,
       the current password is still not eligible for re-use.	A  comma-sepa‐
       rated  list  of old encrypted passwords, which are not eligible for re-
       use.  Encryption algorithm index associated with the current  encrypted
       password	 in fd_encrypt. For use with the dispcrypt() function in pass‐
       word validation.	 The desired encryption algorithm to be used to encode
       the  next password which gets set for this user.	 For use with the dis‐
       pcrypt() function in password setting.  Seconds	after  fd_ulogin  when
       fd_nlogins is ignored for determining whether the account is locked, if
       this field is non-zero.	Timestamp, from time(), of when the account is
       no  longer  considered  valid for logging in to.	 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.
       Name of a template account for default fields, in preference  to	 those
       in  /etc/auth/system/default.   Timestamp  of  when the user's vacation
       begins.	Timestamp of when the user's  vacation	is  over.   RLIMIT_CPU
       rlim_max	 for the setrlimit() call during login.	 RLIMIT_FSIZE rlim_max
       for the setrlimit() call during login.  RLIMIT_DATA  rlim_max  for  the
       setrlimit()  call  during  login.   RLIMIT_STACK rlim_max for the setr‐
       limit() call during login.  RLIMIT_CORE rlim_max	 for  the  setrlimit()
       call during login.  RLIMIT_RSS rlim_max for the setrlimit() call during
       login.  RLIMIT_NOFILE rlim_max for the setrlimit() call	during	login.
       RLIMIT_VMEM  rlim_max for the setrlimit() call during login.  The maxi‐
       mum inter-login interval allowed (in seconds)  before  considering  the
       account	to  be	locked. If zero, there is no limit.  Timestamp, if set
       and non-zero, of a time limit for letting the user log in despite  any‐
       thing  which  the  locked_out_es()  function describes as locking out a
       user.  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): If set,
       allows the user to pick his or her own password.	 If  set,  allows  the
       account	to  be used without a password.	 Enables the use of the random
       pronounceable  password	generator  for	passwords  for	this  account.
       Allows  the password generator to generate passwords composed of random
       printable characters and random letters, which are not easy  to	remem‐
       ber.   The password change software allows the user to pick from which‐
       ever options are available for their accounts.  The user ID of the user
       who  last changed the password on the user's account, if it was not the
       account owner.  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.   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: Timestamps of the last successful and unsuccessful login
       attempts.  The terminal device or host (if supported) names of the ter‐
       minal or host from which the last login attempt occurred.   The	number
       of  unsuccessful	 login attempts since the last successful login. It is
       reset to zero after a successful login.	 The  number  of  unsuccessful
       attempts until the account is considered locked.	 Indicates whether the
       administrative lock on the account is  set.  See	 the  locked_out_es(3)
       reference  page for more detailed information.  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  rou‐
       tines  are  used	 again.	  The es_passwd structure returned by copyesp‐
       went() can be freed using the free() function.

       A call to setprpwent() has the effect of rewinding the protected	 pass‐
       word 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	 char‐
       acter  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 data‐
       bases.  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	 char‐
       acter  strings and lists rather than being self-contained. The copyesp‐
       went() 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 data‐
       base, you must copy the entry using the copyespwent() function and sup‐
       ply 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
       System password file Protected password database for UIDs from 0 to 99.
       Protected  password  database for UIDs 100 and up.  Old protected pass‐
       word database System defaults database General security databases file.

SEE ALSO
       Functions: getpwent(3), getesdfent(3), locked_out_es(3)

       Files: authcap(4), prpasswd(4)

       Security

								 getespwent(3)
[top]

List of man pages available for DigitalUNIX

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net