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