Use anon realm for anonymous PKINIT
[heimdal.git] / lib / kadm5 / kadm5_pwcheck.3
blob5174d9b9283ca10921990184db94c7e617bbe3a5
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" .
102 .Ft name
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 .
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 .
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.
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