crypto/dist/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 .\" $Heimdal: kadm5_pwcheck.3 15237 2005-05-25 13:16:27Z lha $
  33 .\" $NetBSD$
  34 .\"
  35 .Dd February 29, 2004
  36 .Dt KADM5_PWCHECK 3
  37 .Os
  38 .Sh NAME
  39 .Nm krb5_pwcheck ,
  40 .Nm kadm5_setup_passwd_quality_check ,
  41 .Nm kadm5_add_passwd_quality_verifier ,
  42 .Nm kadm5_check_password_quality
  43 .Nd Heimdal warning and error functions
  44 .Sh LIBRARY
  45 Kerberos 5 Library (libkadm5srv, -lkadm5srv)
  46 .Sh SYNOPSIS
  47 .In kadm5-protos.h
  48 .In kadm5-pwcheck.h
  49 .Ft void
  50 .Fo kadm5_setup_passwd_quality_check
  51 .Fa "krb5_context context"
  52 .Fa "const char *check_library"
  53 .Fa "const char *check_function"
  54 .Fc
  55 .Ft "krb5_error_code"
  56 .Fo kadm5_add_passwd_quality_verifier
  57 .Fa "krb5_context context"
  58 .Fa "const char *check_library"
  59 .Fc
  60 .Ft "const char *"
  61 .Fo kadm5_check_password_quality
  62 .Fa "krb5_context context"
  63 .Fa "krb5_principal principal"
  64 .Fa "krb5_data *pwd_data"
  65 .Fc
  66 .Ft int
  67 .Fo "(*kadm5_passwd_quality_check_func)"
  68 .Fa "krb5_context context"
  69 .Fa "krb5_principal principal"
  70 .Fa "krb5_data *password"
  71 .Fa "const char *tuning"
  72 .Fa "char *message"
  73 .Fa "size_t length"
  74 .Fc
  75 .Sh DESCRIPTION
  76 These functions perform the quality check for the heimdal database
  77 library.
  78 .Pp
  79 There are two versions of the shared object API; the old version (0)
  80 is deprecated, but still supported.  The new version (1) supports
  81 multiple password quality checking modules in the same shared object.
  82 See below for details.
  83 .Pp
  84 The password quality checker will run over all tests that are
  85 configured by the user.
  86 .Pp
  87 Module names are of the form
  88 .Ql vendor:test-name
  89 or, if the the test name is unique enough, just
  90 .Ql test-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 be contain the obvious information and
 106 .Ft version
 107 should be
 108 .Dv KADM5_PASSWD_VERSION_V1 .
 109 .Ft funcs
 110 contains an array of
 111 .Ft "struct kadm5_pw_policy_check_func"
 112 structures that is terminated with an entry whose
 113 .Ft name
 114 component is
 115 .Dv NULL .
 116 The
 117 .Ft func
 118 Fields of the array elements are functions that are exported by the
 119 module to be called to check the password.  They get the following
 120 arguments:  the Kerberos context, principal, password, a tuning parameter, and
 121 a pointer to a message buffer and its length.  The tuning parameter
 122 for the quality check function is currently always
 123 .Dv NULL .
 124 If the password is acceptable, the function returns zero.  Otherwise
 125 it returns non-zero and fills in the message buffer with an
 126 appropriate explanation.
 127 .Sh RUNNING THE CHECKS
 128 .Nm kadm5_setup_passwd_quality_check
 129 sets up type 0 checks.  It sets up all type 0 checks defined in
 130 .Xr krb5.conf 5
 131 if called with the last two arguments null.
 132 .Pp
 133 .Nm kadm5_add_passwd_quality_verifier
 134 sets up type 1 checks.  It sets up all type 1 tests defined in
 135 .Xr krb5.conf 5
 136 if called with a null second argument.
 137 .Nm kadm5_check_password_quality
 138 runs the checks in the order in which they are defined in
 139 .Xr krb5.conf 5
 140 and the order in which they occur in a
 141 module's
 142 .Ft funcs
 143 array until one returns non-zero.
 144 .Sh SEE ALSO
 145 .Xr libtool 1 ,
 146 .Xr krb5 3 ,
 147 .Xr krb5.conf 5