1  .\" Copyright (c) 2003 - 2004 Kungliga Tekniska Högskolan
  2  .\" (Royal Institute of Technology, Stockholm, Sweden).
  3  .\" All rights reserved.
  4  .\"
  5  .\" Redistribution and use in source and binary forms, with or without
  6  .\" modification, are permitted provided that the following conditions
  7  .\" are met:
  8  .\"
  9  .\" 1. Redistributions of source code must retain the above copyright
 10  .\"    notice, this list of conditions and the following disclaimer.
 11  .\"
 12  .\" 2. Redistributions in binary form must reproduce the above copyright
 13  .\"    notice, this list of conditions and the following disclaimer in the
 14  .\"    documentation and/or other materials provided with the distribution.
 15  .\"
 16  .\" 3. Neither the name of the Institute nor the names of its contributors
 17  .\"    may be used to endorse or promote products derived from this software
 18  .\"    without specific prior written permission.
 19  .\"
 20  .\" THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND
 21  .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 22  .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 23  .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE
 24  .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 25  .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
 26  .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 27  .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 28  .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
 29  .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 30  .\" SUCH DAMAGE.
 31  .\"
 32  .\" $Id$
 33  .\"
 34  .Dd February 29, 2004
 35  .Dt KADM5_PWCHECK 3
 36  .Os HEIMDAL
 37  .Sh NAME
 38  .Nm krb5_pwcheck ,
 39  .Nm kadm5_setup_passwd_quality_check ,
 40  .Nm kadm5_add_passwd_quality_verifier ,
 41  .Nm kadm5_check_password_quality
 42  .Nd Heimdal warning and error functions
 43  .Sh LIBRARY
 44  Kerberos 5 Library (libkadm5srv, -lkadm5srv)
 45  .Sh SYNOPSIS
 46  .In kadm5-protos.h
 47  .In kadm5-pwcheck.h
 48  .Ft void
 49  .Fo kadm5_setup_passwd_quality_check
 50  .Fa "krb5_context context"
 51  .Fa "const char *check_library"
 52  .Fa "const char *check_function"
 53  .Fc
 54  .Ft "krb5_error_code"
 55  .Fo kadm5_add_passwd_quality_verifier
 56  .Fa "krb5_context context"
 57  .Fa "const char *check_library"
 58  .Fc
 59  .Ft "const char *"
 60  .Fo kadm5_check_password_quality
 61  .Fa "krb5_context context"
 62  .Fa "krb5_principal principal"
 63  .Fa "krb5_data *pwd_data"
 64  .Fc
 65  .Ft int
 66  .Fo "(*kadm5_passwd_quality_check_func)"
 67  .Fa "krb5_context context"
 68  .Fa "krb5_principal principal"
 69  .Fa "krb5_data *password"
 70  .Fa "const char *tuning"
 71  .Fa "char *message"
 72  .Fa "size_t length"
 73  .Fc
 74  .Sh DESCRIPTION
 75  These functions perform the quality check for the heimdal database
 76  library.
 77  .Pp
 78  There are two versions of the shared object API; the old version (0)
 79  is deprecated, but still supported.  The new version (1) supports
 80  multiple password quality checking policies in the same shared object.
 81  See below for details.
 82  .Pp
 83  The password quality checker will run all policies that are
 84  configured by the user.  If any policy rejects the password, the password
 85  will be rejected.
 86  .Pp
 87  Policy names are of the form
 88  .Ql module-name:policy-name
 89  or, if the the policy name is unique enough, just
 90  .Ql policy-name .
 91  .Sh IMPLEMENTING A PASSWORD QUALITY CHECKING SHARED OBJECT
 92  (This refers to the version 1 API only.)
 93  .Pp
 94  Module shared objects may conveniently be compiled and linked with
 95  .Xr libtool 1 .
 96  An object needs to export a symbol called
 97  .Ql kadm5_password_verifier
 98  of the type
 99  .Ft "struct kadm5_pw_policy_verifier" .
100  .Pp
101  Its
102  .Ft name
103  and
104  .Ft vendor
105  fields should contain the obvious information.
106  .Ft name
107  must match the
108  .Ql module-name
109  portion of the policy name (the part before the colon), if the policy name
110  contains a colon, or the policy will not be run.
111  .Ft version
112  should be
113  .Dv KADM5_PASSWD_VERSION_V1 .
114  .Pp
115  .Ft funcs
116  contains an array of
117  .Ft "struct kadm5_pw_policy_check_func"
118  structures that is terminated with an entry whose
119  .Ft name
120  component is
121  .Dv NULL .
122  The
123  .Ft name
124  field of the array must match the
125  .Ql policy-name
126  portion of a policy name (the part after the colon, or the complete policy
127  name if there is no colon) specified by the user or the policy will not be
128  run.  The
129  .Ft func
130  fields of the array elements are functions that are exported by the
131  module to be called to check the password.  They get the following
132  arguments:  the Kerberos context, principal, password, a tuning parameter, and
133  a pointer to a message buffer and its length.  The tuning parameter
134  for the quality check function is currently always
135  .Dv NULL .
136  If the password is acceptable, the function returns zero.  Otherwise
137  it returns non-zero and fills in the message buffer with an
138  appropriate explanation.
139  .Sh RUNNING THE CHECKS
140  .Nm kadm5_setup_passwd_quality_check
141  sets up type 0 checks.  It sets up all type 0 checks defined in
142  .Xr krb5.conf 5
143  if called with the last two arguments null.
144  .Pp
145  .Nm kadm5_add_passwd_quality_verifier
146  sets up type 1 checks.  It sets up all type 1 tests defined in
147  .Xr krb5.conf 5
148  if called with a null second argument.
149  .Nm kadm5_check_password_quality
150  runs the checks in the order in which they are defined in
151  .Xr krb5.conf 5
152  and the order in which they occur in a
153  module's
154  .Ft funcs
155  array until one returns non-zero.
156  .Sh SEE ALSO
157  .Xr libtool 1 ,
158  .Xr krb5 3 ,
159  .Xr krb5.conf 5