lib/kadm5/kadm5_pwcheck.3

   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