NAME

       krb5_verify_user,        krb5_verify_user_lrealm,       krb5_verify_user_opt,       krb5_verify_opt_init,
       krb5_verify_opt_alloc,   krb5_verify_opt_free,   krb5_verify_opt_set_ccache,   krb5_verify_opt_set_flags,
       krb5_verify_opt_set_service,  krb5_verify_opt_set_secure,  krb5_verify_opt_set_keytab  — Heimdal password
       verifying functions

LIBRARY

       Kerberos 5 Library (libkrb5, -lkrb5)

SYNOPSIS

       #include <krb5.h>

       krb5_error_code
       krb5_verify_user(krb5_context     context,     krb5_principal     principal,     krb5_ccache      ccache,
           const char *password, krb5_boolean secure, const char *service);

       krb5_error_code
       krb5_verify_user_lrealm(krb5_context    context,    krb5_principal    principal,    krb5_ccache   ccache,
           const char *password, krb5_boolean secure, const char *service);

       void
       krb5_verify_opt_init(krb5_verify_opt *opt);

       void
       krb5_verify_opt_alloc(krb5_verify_opt **opt);

       void
       krb5_verify_opt_free(krb5_verify_opt *opt);

       void
       krb5_verify_opt_set_ccache(krb5_verify_opt *opt, krb5_ccache ccache);

       void
       krb5_verify_opt_set_keytab(krb5_verify_opt *opt, krb5_keytab keytab);

       void
       krb5_verify_opt_set_secure(krb5_verify_opt *opt, krb5_boolean secure);

       void
       krb5_verify_opt_set_service(krb5_verify_opt *opt, const char *service);

       void
       krb5_verify_opt_set_flags(krb5_verify_opt *opt, unsigned int flags);

       krb5_error_code
       krb5_verify_user_opt(krb5_context context,        krb5_principal principal,         const char *password,
           krb5_verify_opt *opt);

DESCRIPTION

       The  krb5_verify_user  function  verifies  the password supplied by a user.  The principal whose password
       will be verified is specified in principal.  New tickets will be obtained as a side-effect and stored  in
       ccache  (if  NULL, the default ccache is used).  krb5_verify_user() will call krb5_cc_initialize() on the
       given ccache, so ccache must only  initialized  with  krb5_cc_resolve()  or  krb5_cc_gen_new().   If  the
       password  is not supplied in password (and is given as NULL) the user will be prompted for it.  If secure
       the ticket will be verified against the locally stored service key service (by default ‘host’ if given as
       NULL ).

       The krb5_verify_user_lrealm() function does the same, except that it ignores the realm in  principal  and
       tries  all  the  local realms (see krb5.conf(5)).  After a successful return, the principal is set to the
       authenticated realm. If the call fails, the principal will not be meaningful, and should  only  be  freed
       with krb5_free_principal(3).

       krb5_verify_opt_alloc() and krb5_verify_opt_free() allocates and frees a krb5_verify_opt.  You should use
       the the alloc and free function instead of allocation the structure yourself, this is because in a future
       release the structure wont be exported.

       krb5_verify_opt_init() resets all opt to default values.

       None  of  the  krb5_verify_opt_set function makes a copy of the data structure that they are called with.
       It's up the caller to free them after the krb5_verify_user_opt() is called.

       krb5_verify_opt_set_ccache() sets the ccache that  user  of  opt  will  use.  If  not  set,  the  default
       credential cache will be used.

       krb5_verify_opt_set_keytab()  sets  the  keytab that user of opt will use. If not set, the default keytab
       will be used.

       krb5_verify_opt_set_secure() if secure if true, the password verification will require  that  the  ticket
       will be verified against the locally stored service key. If not set, default value is true.

       krb5_verify_opt_set_service()  sets  the  service  principal  that  user of opt will use. If not set, the
       ‘host’ service will be used.

       krb5_verify_opt_set_flags() sets flags that user of opt will use.  If  the  flag  KRB5_VERIFY_LREALMS  is
       used, the principal will be modified like krb5_verify_user_lrealm() modifies it.

       krb5_verify_user_opt()  function  verifies the password supplied by a user.  The principal whose password
       will be verified is specified in principal.  Options the to the verification process is pass in in opt.

EXAMPLES

       Here is a example program that verifies a password. it uses the ‘host/`hostname`’  service  principal  in
       krb5.keytab.

       #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;
       }

SEE ALSO

       krb5_cc_gen_new(3),   krb5_cc_initialize(3),   krb5_cc_resolve(3),  krb5_err(3),  krb5_free_principal(3),
       krb5_init_context(3), krb5_kt_default(3), krb5.conf(5)

HEIMDAL                                            May 1, 2006                               KRB5_VERIFY_USER(3)