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