crypto/heimdal/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: kadm5_pwcheck.3 15237 2005-05-25 13:16:27Z lha $
  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 modules in the same shared object.
  81 See below for details.
  82 .Pp
  83 The password quality checker will run over all tests that are
  84 configured by the user.
  85 .Pp
  86 Module names are of the form
  87 .Ql vendor:test-name
  88 or, if the the test name is unique enough, just
  89 .Ql test-name .
  90 .Sh IMPLEMENTING A PASSWORD QUALITY CHECKING SHARED OBJECT
  91 (This refers to the version 1 API only.)
  92 .Pp
  93 Module shared objects may conveniently be compiled and linked with
  94 .Xr libtool 1 .
  95 An object needs to export a symbol called
  96 .Ql kadm5_password_verifier
  97 of the type
  98 .Ft "struct kadm5_pw_policy_verifier" .
  99 .Pp
 100 Its
 101 .Ft name
 102 and
 103 .Ft vendor
 104 fields should be contain the obvious information and
 105 .Ft version
 106 should be
 107 .Dv KADM5_PASSWD_VERSION_V1 .
 108 .Ft funcs
 109 contains an array of
 110 .Ft "struct kadm5_pw_policy_check_func"
 111 structures that is terminated with an entry whose
 112 .Ft name
 113 component is
 114 .Dv NULL .
 115 The
 116 .Ft func
 117 Fields of the array elements are functions that are exported by the
 118 module to be called to check the password.  They get the following
 119 arguments:  the Kerberos context, principal, password, a tuning parameter, and
 120 a pointer to a message buffer and its length.  The tuning parameter
 121 for the quality check function is currently always
 122 .Dv NULL .
 123 If the password is acceptable, the function returns zero.  Otherwise
 124 it returns non-zero and fills in the message buffer with an
 125 appropriate explanation.
 126 .Sh RUNNING THE CHECKS
 127 .Nm kadm5_setup_passwd_quality_check
 128 sets up type 0 checks.  It sets up all type 0 checks defined in
 129 .Xr krb5.conf 5
 130 if called with the last two arguments null.
 131 .Pp
 132 .Nm kadm5_add_passwd_quality_verifier
 133 sets up type 1 checks.  It sets up all type 1 tests defined in
 134 .Xr krb5.conf 5
 135 if called with a null second argument.
 136 .Nm kadm5_check_password_quality
 137 runs the checks in the order in which they are defined in
 138 .Xr krb5.conf 5
 139 and the order in which they occur in a
 140 module's
 141 .Ft funcs
 142 array until one returns non-zero.
 143 .Sh SEE ALSO
 144 .Xr libtool 1 ,
 145 .Xr krb5 3 ,
 146 .Xr krb5.conf 5