document kadm5_add_passwd_quality_verifier, improve text

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

lib/kadm5/kadm5_pwcheck.3

@@ -37,6 +37,7 @@
 .Sh NAME
 .Nm krb5_pwcheck ,
 .Nm kadm5_setup_passwd_quality_check ,
+.Nm kadm5_add_passwd_quality_verifier ,
 .Nm kadm5_check_password_quality
 .Nd Heimdal warning and error functions
 .Sh LIBRARY
@@ -50,60 +51,96 @@ Kerberos 5 Library (libkadm5srv, -lkadm5srv)
 .Fa "const char *check_library"
 .Fa "const char *check_function"
 .Fc
+.Ft "krb5_error_code"
+.Fo kadm5_add_passwd_quality_verifier
+.Fa "krb5_context context"
+.Fa "const char *check_library"
+.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
+.Ft int
+.Fo (*kadm5_passwd_quality_check_func)
 .Fa "krb5_context context"
 .Fa "krb5_principal principal"
-.Fa "krb5_data *pwd_data"
+.Fa "krb5_data *password"
+.Fa "const char *tuning"
+.Fa "char *message"
+.Fa "size_t length"
 .Fc
 .Sh DESCRIPTION
-These functions preforms that quality check for the heimdal database
+These functions perform the 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.
+There are two versions of the shared object API; the old version (0)
+is deprecated, but still supported.  The new version (1) supports
+multiple password quality checking modules in the same shared object.
+See below for details.
 .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
+The password quality checker will run over all tests that are
 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
+Module names are of 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
+(This refers to the version 1 API only.)
+.Pp
+Module shared objects may conveniently be compiled and linked with
+.Xr libtool 1 .
+An object needs to export a symbol called
 .Ql kadm5_password_verifier
 of the type
 .Ft "struct kadm5_pw_policy_verifier" .
 .Pp
+Its
 .Ft name 
 and
 .Ft vendor
-is filled in with the obvious information and
+fields should be contain the obvious information and
 .Ft version
-is set to
+should be
 .Dv KADM5_PASSWD_VERSION_V1 .
-The
-.Ft type
-contains a array of
+.Ft funcs
+contains an array of
 .Ft "struct kadm5_pw_policy_check_func"
-structures that is terminated with a entry where the
+structures that is terminated with an entry whose
 .Ft name
 component is
 .Dv NULL .
+The
+.Ft func
+Fields of the array elements are functions that are exported by the
+module to be called to check the password.  They get the following
+arguments:  the Kerberos context, principal, password, a tuning parameter, and
+a pointer to a message buffer and its length.  The tuning parameter
+for the quality check function is currently always
+.Dv NULL .
+If the password is acceptable, the function returns zero.  Otherwise
+it returns non-zero and fills in the message buffer with an
+appropriate explanation.
+.Sh RUNNING THE CHECKS
+.Nm kadm5_setup_passwd_quality_check
+sets up type 0 checks.  It sets up all type 0 checks defined in 
+.Xr krb5.conf 5
+if called with the last two arguments null.
+.Pp
+.Nm kadm5_add_passwd_quality_verifier
+sets up type 1 checks.  It sets up all type 1 tests defined in
+.Xr krb5.conf 5
+if called with a null second argument.
+.Nm kadm5_check_password_quality
+runs the checks in the order in which they are defined in
+.Xr krb5.conf 5
+and the order in which they occur in a
+module's
+.Ft funcs
+array until one returns non-zero.
 .Sh SEE ALSO
 .Xr krb5 3 ,
-.Xr krb5_get_error_string 3
+.Xr krb5.conf 5 ,
+.Xr libtool 1 .