C Library Functions                              checkpassword(3)



NAME
     checkpassword,  configure_checkpassword,  init_checkpassword
     checkpassword_verify - password sanity checking

     password_history_update - update password history database

     init_debug, set_debug_tag - password check library tracing

SYNOPSIS
     #include "checkpassword.h"

     cc ... -I         -L           -
     lcheckpassword ... -lother-libs

     char *checkpassword(char *password, struct passwd *user);

     char *checkpassword_configure(char *command, int flagerror);

     char *checkpassword_verify();

     void init_checkpassword();

     int password_history_update(char *user, char *cryptpass, time_t epoch);

     void init_debug(int level);

     void set_debug_tag(char *tag);

DESCRIPTION
     The password check  library  is  designed  for  applications
     which  changes  passwords.  This password check engine is at
     the core of npasswd.

     The checkpassword() routine determines whether a password is
     suitable  for  use.  The password argument is the plain-text
     candidate password, user is a pointer to a passwd  structure
     from getpwent(3), getpwnam(3), or getpwuid(3).  This routine
     returns an  explanatory  message  if  the  password  is  not
     acceptable, and NULL otherwise.

     The  checkpassword_configure()  routine  sets  the  password
     check parameters.  The argument command is a string contain-
     ing a configuration directive.  If the flagerror argument is
     non-zero, unrecognized directives will be considered errors.

     This routine returns NULL  if  command  was  recognized  and
     accepted, and an error message otherwise.

     The configuration directives  are  a  subset  of  those  for
     npasswd.





SunOS 5.6                 Last change:                          1






C Library Functions                              checkpassword(3)



     The init_checkpassword() routine performs initialization for
     the  password  check  routines.  It is implicitly run on the
     first  invocation  of  checkpassword().   Each  call  resets
     resets the password check parameters to defaults.

     The checkpassword_verify() routine sanity checks the  confi-
     guration  of the password check routines. It returns NULL if
     the configuration is correct,  or  else  an  error  message.
     This  routine  should  be  called  after  the  last  use  of
     init_checkpassword() or checkpassword_configure().

     The password_history_update()  routine  inserts  a  password
     into  the  history  database.  The user argument is the user
     name, crypt-pass is the encrypted  password  to  enter,  and
     epoch  is  the  time  stamp to put on the password.  If this
     argument is 0, the current time is used.

     The use of this routine requires that the  history  database
     exists  and  the  user  has privileges to write to it.  This
     usually means an effective uid of root.

     This routine returns 0 if there is no  history  database,  1
     upon success, and -1 for failure.

     If  Digital  UNIX  enhanced   security   mode   is   active,
     password_history_update() is a no-op.

     See manual page  for  history_admin(1)  about  managing  the
     password history database.

INTERNALS
     Checkpassword subjects password candidates to  a  series  of
     guessability  tests.  The  password  is  accepted only if it
     passes all of them.

     The tests which are used and the order of their  application
     can  be  customized  by  configuration directives.  Some the
     following tests are mandatory, others optional:

     History (optional)
          Password  history  discourages  too  frequent  password
          reuse.   Password  candidates are compared to the pass-
          words in the history record for the user  and  rejected
          if found.

          The password  history  database  location  and  storage
          method can be specified in the configuration file.

     If Digital UNIX (OSF/1) enhanced security  mode  is  active,
     that history mechanism will be used.





SunOS 5.6                 Last change:                          2






C Library Functions                              checkpassword(3)



     Lexical (mandatory)
          These tests include:

          o    Enforcing a minimum length of six characters.

          o    Checking for non-printable  or  forbidden  charac-
               ters.  Default  is to allow non-printable and whi-
               tespace characters except common tty control char-
               acters.

          o    Denying excessive adjacent repeated characters.

          o    Encouraging  a  diversity  of  character   classes
               (mixed case, numbers, punctuation).

          o    Looking for easily guessed patterns  (U.S.  Social
               Security, telephone numbers).

          o    Passwords that do not have upper  and  lower  case
               alphabetics  may  be  rejected,  depending  on the
               check parameters.

     Local (optional)
          The password is checked  against  various  information.
          host name.

     Passwd (mandatory)
          The password is compared to a number of permutations of
          the information in the user argument.

     Dictionary (mandatory)
          The password is subjected to a series of tests from the
          Crack  password  guessing  program.  The  candidate  is
          rejected if it can be derived  from  any  word  in  the
          npasswd password check dictionaries.

     The password check library has extensive  internal  tracing.
     The following routines configure that facility.

     The set_debug_tag() routine sets the trace message  identif-
     ier.

     The init_debug() routine sets the  trace  level.   Refer  to
     checkpassword.h for trace level defines.

CONFIGURATION
     The configuration directives are:

     AlphaOnly yes | no
          Allow alpha-only passwords.  The default is to disallow
          alpha-only passwords.




SunOS 5.6                 Last change:                          3






C Library Functions                              checkpassword(3)



     CharClasses N
          Require at least N character classes in passwords.  The
          character classes are:

          o    Upper case alpha.

          o    Lower case alpha.

          o    Digits.

          o    Whitespace.

          o    Punctuation.

          o    Control characters.
     The higher the class requirement, the more  diverse  mixture
     of characters required.

     Debug N
          Sets internal debug level to N, which must be  a  digit
          [0-9].  Refer to the sources for debug levels.

     Dictionaries path ... path
          Adds directories to the dictionary search  list.   Each
          directory  in the path is scanned for hashed dictionary
          files.  Multiple directories can be  specified  in  one
          directive,  and  multiple directives can be given.  The
          hash files are built with makedict(1).

     DisallowedChars [+]string
          Sets the list of characters (usually non-printable) not
          allowed.   C  backslash sequences (e.g. \b or \007) may
          be used.  String may be enclosed in double quotes.   If
          the  initial  character  of string is a plus-sign, then
          the it is appended to the forbidden character list.

          The default disallowed character list contains  typical
          UNIX terminal special characters.

     History args
          Configure the password history mechanism.

          age N
               When a  password  history  record  is  fetched  or
               updated,  any passwords older than N days are dis-
               carded.  The  depth  limit  (see  below)  is  also
               enforced. The default age is 180 days.

          depth N
               When a  password  history  record  is  fetched  or
               updated,  all  but the most recent N passwords are
               discarded.  The age  limit  (see  above)  is  also



SunOS 5.6                 Last change:                          4






C Library Functions                              checkpassword(3)



               enforced.   The  default  is  to retain the last 5
               passwords.

          dbm path
               Use path as the history database  in  DBM  format.
               This  is  the default if the NDBM library routines
               are available.  The default  history  database  is
               npasswd-lib/history.

          file path
               Use path as the history database  in  "flat  file"
               format.

          none Disable password history.

     LengthWarn yes | no
          Warn if the  password  is  longer  than  the  effective
          length.  This does not affect the security of the pass-
          word, but such  a  warning  may  be  desirable  from  a
          human-interface  perspective.   The  default  is to not
          issue a warning.

     MaxPassword N
          Sets the maximum effective password length to N charac-
          ters.   The  default is platform dependent, but is usu-
          ally 8.

     MaxRepeat N
          Set allowed adjacent repeated  character  count  to  N.
          The default is 3.

     MinPassword N
          Sets the minimum acceptable length for a password to  N
          characters.   The  default  minimum length is 6 charac-
          ters.

     PasswordChecks proc proc ... proc
          Selects the order of  the  password  checks.   Use  the
          check  names  listed above.  The default check order is
          lexical passwd local history dictionary.

     PrintOnly yes | no
          Limit passwords to having  only  printable  characters.
          The  isprint(3) routine is used to determine this.  The
          default is to allow all non-printable characters except
          the  disallowed  characters.  Use of control characters
          may cause problems on some systems.

     SingleCase yes | no
          Allow single-case (all lower case or  all  upper  case)
          passwords.   The  default is to allow single-case pass-
          words.



SunOS 5.6                 Last change:                          5






C Library Functions                              checkpassword(3)



BUGS
     The npasswd history  database  is  protected   from  general
     access.  Any application using this library will need to run
     with privileges in order to  perform  the  password  history
     check.  On Digital UNIX systems, membership in group auth is
     needed to read the authorization files.

SEE ALSO
     npasswd(1), checkpassword(1)

AUTHOR
     Clyde Hoover
     Academic Computing  Services  and  Instructional  Technology
     Services
     The University of Texas at Austin
     c.hoover@cc.utexas.edu
     8c9 1998, The  University  of  Texas  at  Austin.  All  rights
     reserved.





































SunOS 5.6                 Last change:                          6