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: kadm5_pwcheck.3 15237 2005-05-25 13:16:27Z lha $ 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 modules in the same shared object. 81See below for details. 82.Pp 83The password quality checker will run over all tests that are 84configured by the user. 85.Pp 86Module names are of the form 87.Ql vendor:test-name 88or, if the the test name is unique enough, just 89.Ql test-name . 90.Sh IMPLEMENTING A PASSWORD QUALITY CHECKING SHARED OBJECT 91(This refers to the version 1 API only.) 92.Pp 93Module shared objects may conveniently be compiled and linked with 94.Xr libtool 1 . 95An object needs to export a symbol called 96.Ql kadm5_password_verifier 97of the type 98.Ft "struct kadm5_pw_policy_verifier" . 99.Pp 100Its 101.Ft name 102and 103.Ft vendor 104fields should be contain the obvious information and 105.Ft version 106should be 107.Dv KADM5_PASSWD_VERSION_V1 . 108.Ft funcs 109contains an array of 110.Ft "struct kadm5_pw_policy_check_func" 111structures that is terminated with an entry whose 112.Ft name 113component is 114.Dv NULL . 115The 116.Ft func 117Fields of the array elements are functions that are exported by the 118module to be called to check the password. They get the following 119arguments: the Kerberos context, principal, password, a tuning parameter, and 120a pointer to a message buffer and its length. The tuning parameter 121for the quality check function is currently always 122.Dv NULL . 123If the password is acceptable, the function returns zero. Otherwise 124it returns non-zero and fills in the message buffer with an 125appropriate explanation. 126.Sh RUNNING THE CHECKS 127.Nm kadm5_setup_passwd_quality_check 128sets up type 0 checks. It sets up all type 0 checks defined in 129.Xr krb5.conf 5 130if called with the last two arguments null. 131.Pp 132.Nm kadm5_add_passwd_quality_verifier 133sets up type 1 checks. It sets up all type 1 tests defined in 134.Xr krb5.conf 5 135if called with a null second argument. 136.Nm kadm5_check_password_quality 137runs the checks in the order in which they are defined in 138.Xr krb5.conf 5 139and the order in which they occur in a 140module's 141.Ft funcs 142array until one returns non-zero. 143.Sh SEE ALSO 144.Xr libtool 1 , 145.Xr krb5 3 , 146.Xr krb5.conf 5 147