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 46Kerberos 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 77These functions perform the quality check for the heimdal database 78library. 79.Pp 80There are two versions of the shared object API; the old version (0) 81is deprecated, but still supported. The new version (1) supports 82multiple password quality checking policies in the same shared object. 83See below for details. 84.Pp 85The password quality checker will run all policies that are 86configured by the user. If any policy rejects the password, the password 87will be rejected. 88.Pp 89Policy names are of the form 90.Ql module-name:policy-name 91or, 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 96Module shared objects may conveniently be compiled and linked with 97.Xr libtool 1 . 98An object needs to export a symbol called 99.Ql kadm5_password_verifier 100of the type 101.Ft "struct kadm5_pw_policy_verifier" . 102.Pp 103Its 104.Ft name 105and 106.Ft vendor 107fields should contain the obvious information. 108.Ft name 109must match the 110.Ql module-name 111portion of the policy name (the part before the colon), if the policy name 112contains a colon, or the policy will not be run. 113.Ft version 114should be 115.Dv KADM5_PASSWD_VERSION_V1 . 116.Pp 117.Ft funcs 118contains an array of 119.Ft "struct kadm5_pw_policy_check_func" 120structures that is terminated with an entry whose 121.Ft name 122component is 123.Dv NULL . 124The 125.Ft name 126field of the array must match the 127.Ql policy-name 128portion of a policy name (the part after the colon, or the complete policy 129name if there is no colon) specified by the user or the policy will not be 130run. The 131.Ft func 132fields of the array elements are functions that are exported by the 133module to be called to check the password. They get the following 134arguments: the Kerberos context, principal, password, a tuning parameter, and 135a pointer to a message buffer and its length. The tuning parameter 136for the quality check function is currently always 137.Dv NULL . 138If the password is acceptable, the function returns zero. Otherwise 139it returns non-zero and fills in the message buffer with an 140appropriate explanation. 141.Sh RUNNING THE CHECKS 142.Nm kadm5_setup_passwd_quality_check 143sets up type 0 checks. It sets up all type 0 checks defined in 144.Xr krb5.conf 5 145if called with the last two arguments null. 146.Pp 147.Nm kadm5_add_passwd_quality_verifier 148sets up type 1 checks. It sets up all type 1 tests defined in 149.Xr krb5.conf 5 150if called with a null second argument. 151.Nm kadm5_check_password_quality 152runs the checks in the order in which they are defined in 153.Xr krb5.conf 5 154and the order in which they occur in a 155module's 156.Ft funcs 157array until one returns non-zero. 158.Sh SEE ALSO 159.Xr libtool 1 , 160.Xr krb5 3 , 161.Xr krb5.conf 5 162