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