crypto/heimdal/lib/krb5/krb5_verify_user.3

   1 .\" Copyright (c) 2001 Kungliga Tekniska Högskolan
   2 .\" $Id: krb5_verify_user.3,v 1.5 2002/08/28 15:30:58 joda Exp $
   3 .Dd June 27, 2001
   4 .Dt KRB5_VERIFY_USER 3
   5 .Os HEIMDAL
   6 .Sh NAME
   7 .Nm krb5_verify_user ,
   8 .Nm krb5_verify_user_lrealm
   9 .Nd Heimdal password verifying functions
  10 .Sh LIBRARY
  11 Kerberos 5 Library (libkrb5, -lkrb5)
  12 .Sh SYNOPSIS
  13 .Fd #include <krb5.h>
  14 .Ft krb5_error_code
  15 .Fn "krb5_verify_user" "krb5_context context" " krb5_principal principal" "krb5_ccache ccache" "const char *password" "krb5_boolean secure" "const char *service"
  16 .Ft krb5_error_code
  17 .Fn "krb5_verify_user_lrealm" "krb5_context context" "krb5_principal principal" "krb5_ccache ccache" "const char *password" "krb5_boolean secure" "const char *service"
  18 .Sh DESCRIPTION
  19 The
  20 .Nm krb5_verify_user
  21 function verifies the password supplied by a user.
  22 The principal whose
  23 password will be verified is specified in
  24 .Fa principal .
  25 New tickets will be obtained as a side-effect and stored in
  26 .Fa ccache
  27 (if NULL, the default ccache is used).
  28 If the password is not supplied in
  29 .Fa password
  30 (and is given as
  31 .Dv NULL )
  32 the user will be prompted for it.
  33 If
  34 .Fa secure
  35 the ticket will be verified against the locally stored service key
  36 .Fa service
  37 (by default
  38 .Ql host
  39 if given as
  40 .Dv NULL
  41 ).
  42 .Pp
  43 The
  44 .Nm krb5_verify_user_lrealm
  45 function does the same, except that it ignores the realm in
  46 .Fa principal
  47 and tries all the local realms (see
  48 .Xr krb5.conf 5 ) .
  49 After a successful return, the principal is set to the authenticated
  50 realm. If the call fails, the principal will not be meaningful, and
  51 should only be freed with
  52 .Xr krb5_free_principal 3 .
  53 .Sh EXAMPLE
  54 Here is a example program that verifies a password. it uses the
  55 .Ql host/`hostname`
  56 service principal in
  57 .Pa krb5.keytab .
  58 .Bd -literal
  59 #include <krb5.h>
  60
  61 int
  62 main(int argc, char **argv)
  63 {
  64     char *user;
  65     krb5_error_code error;
  66     krb5_principal princ;
  67     krb5_context context;
  68
  69     if (argc != 2)
  70         errx(1, "usage: verify_passwd <principal-name>");
  71
  72     user = argv[1];
  73
  74     if (krb5_init_context(&context) < 0)
  75         errx(1, "krb5_init_context");
  76
  77     if ((error = krb5_parse_name(context, user, &princ)) != 0)
  78         krb5_err(context, 1, error, "krb5_parse_name");
  79
  80     error = krb5_verify_user(context, princ, NULL, NULL, TRUE, NULL);
  81     if (error)
  82         krb5_err(context, 1, error, "krb5_verify_user");
  83
  84     return 0;
  85 }
  86 .Ed
  87 .Sh SEE ALSO
  88 .Xr krb5_err 3 ,
  89 .Xr krb5_free_principal 3 ,
  90 .Xr krb5_init_context 3 ,
  91 .Xr krb5_kt_default 3 ,
  92 .Xr krb5.conf 5