document new password quality api

git-svn-id: svn://svn.h5l.se/heimdal/trunk/heimdal@13965 ec53bebd-3082-4978-b11e-865c3cabbd6b

lib/kadm5/kadm5_pwcheck.3

@@ -0,0 +1,109 @@
+.\" Copyright (c) 2003 - 2004 Kungliga Tekniska H<>gskolan
+.\" (Royal Institute of Technology, Stockholm, Sweden).
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\"
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\"
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" 3. Neither the name of the Institute nor the names of its contributors
+.\"    may be used to endorse or promote products derived from this software
+.\"    without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\" $Id$
+.\"
+.Dd February 29, 2004
+.Dt KADM5_PWCHECK 3
+.Os HEIMDAL
+.Sh NAME
+.Nm krb5_pwcheck ,
+.Nm kadm5_setup_passwd_quality_check ,
+.Nm kadm5_check_password_quality
+.Nd Heimdal warning and error functions
+.Sh LIBRARY
+Kerberos 5 Library (libkadm5srv, -lkadm5srv)
+.Sh SYNOPSIS
+.In kadm5-protos.h
+.In kadm5-pwcheck.h
+.Ft void
+.Fo kadm5_setup_passwd_quality_check
+.Fa "krb5_context context"
+.Fa "const char *check_library"
+.Fa "const char *check_function"
+.Fc
+.Ft "const char *"
+.Fo kadm5_check_password_quality
+.Fa "krb5_context context"
+.Fa "krb5_principal principal"
+.Fa "krb5_data *pwd_data"
+.Fc
+.Ft "krb5_error_code"
+.Fo kadm5_verify_password_quality
+.Fa "krb5_context context"
+.Fa "krb5_principal principal"
+.Fa "krb5_data *pwd_data"
+.Fc
+.Sh DESCRIPTION
+These functions preforms that quality check for the heimdal database
+library.
+.Pp
+Two versions of the shared object API, old version (0) deprecated, but
+supported still supported.  New version (1) support multiple password
+quality checking modules in the same shared object.
+.Pp
+In case a password doesn't pass the password quality check, the
+.Fn kadm5_verify_password_quality
+returns a more version description of the error in the krb5_context,
+you can get the error with
+.Fn krb5_get_error_string .
+.Pp
+The password quality checker will run over all tests that is
+configured by the user.
+.Pp
+Modules names are on the form
+.Ql vendor:test-name ,
+or if the the test name is unique enough, just
+.Ql test-name .
+.Sh IMPLEMENTING A PASSWORD QUALITY CHECKING SHARED OBJECT
+The object needs to provide a entry point called
+.Ql kadm5_password_verifier
+of the type
+.Ft "struct kadm5_pw_policy_verifier" .
+.Pp
+.Ft name 
+and
+.Ft vendor
+is filled in with the obvious information and
+.Ft version
+is set to
+.Dv KADM5_PASSWD_VERSION_V1 .
+The
+.Ft type
+contains a array of
+.Ft "struct kadm5_pw_policy_check_func"
+structures that is terminated with a entry where the
+.Ft name
+component is
+.Dv NULL .
+.Sh SEE ALSO
+.Xr krb5 3 ,
+.Xr krb5_get_error_string 3