new man-page

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

lib/krb5/krb5_verify_user.3

@@ -0,0 +1,85 @@
+.\" Copyright (c) 2001 Kungliga Tekniska H<>gskolan
+.\" $Id$
+.Dd June 27, 2001
+.Dt KRB5_VERIFY_USER 3
+.Os HEIMDAL
+.Sh NAME
+.Nm krb5_verify_user ,
+.Nm krb5_verify_user_lrealm
+.Nd Heimdal password verifying functions
+.Sh SYNOPSIS
+.Fd #include <krb5.h>
+.Ft krb5_error_code
+.Fn "krb5_verify_user" "krb5_context context" " krb5_principal principal" "krb5_ccache ccache" "const char *password" "krb5_boolean secure" "const char *service"
+.Ft krb5_error_code
+.Fn "krb5_verify_user_lrealm" "krb5_context context" "krb5_principal principal" "krb5_ccache ccache" "const char *password" "krb5_boolean secure" "const char *service"
+.Sh DESCRIPTION
+The
+.Nm krb5_verify_user
+function verifies the password supplied by a user. 
+The principal whose
+password will be verified is specified in
+.Fa principal .
+New tickets will be obtained as a side-effect and stored in
+.Fa ccache
+(if NULL, the default ccache is used).
+If the password is not supplied in
+.Fa password
+(and is given as
+.Dv NULL )
+the user will be prompted for it.
+If
+.Fa secure
+the ticket will be verified against the locally stored service key
+.Fa service
+(by default
+.Ql host
+if given as
+.Dv NULL
+).
+.Pp
+The
+.Nm krb5_verify_user_lrealm
+function does the same, except that it ignores the realm in
+.Fa principal
+and tries all the local realms (see
+.Xr krb5.conf 5).
+.Sh EXAMPLE
+Here is a example program that verifies a password. it uses the
+.Ql host/`hostname`
+service principal in
+.Pa krb5.keytab .
+.Bd -literal
+#include <krb5.h>
+
+int
+main(int argc, char **argv)
+{
+    char *user;
+    krb5_error_code error;
+    krb5_principal princ;
+    krb5_context context;
+
+    if (argc != 2)
+	errx(1, "usage: verify_passwd <principal-name>");
+
+    user = argv[1];
+
+    if (krb5_init_context(&context) < 0)
+	errx(1, "krb5_init_context");
+
+    if ((error = krb5_parse_name(context, user, &princ)) != 0)
+	krb5_err(context, 1, error, "krb5_parse_name");
+
+    error = krb5_verify_user(context, princ, NULL, NULL, TRUE, NULL);
+    if (error)
+        krb5_err(context, 1, error, "krb5_verify_user");
+	
+    return 0;
+}
+.Ed
+.Sh SEE ALSO
+.Xr krb5_kt_default 3 ,
+.Xr krb5_init_context 3 ,
+.Xr krb5_err 3 ,
+.Xr krb5.conf 5