crypto/heimdal-0.6.3/lib/krb5/krb5_verify_user.3

   1 .\" Copyright (c) 2001 - 2003 Kungliga Tekniska Högskolan
   2 .\" (Royal Institute of Technology, Stockholm, Sweden).
   3 .\" All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\"
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\"
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in the
  14 .\"    documentation and/or other materials provided with the distribution.
  15 .\"
  16 .\" 3. Neither the name of the Institute nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\" $Id: krb5_verify_user.3,v 1.10 2003/04/16 13:58:11 lha Exp $
  33 .\"
  34 .Dd March 25, 2003
  35 .Dt KRB5_VERIFY_USER 3
  36 .Os HEIMDAL
  37 .Sh NAME
  38 .Nm krb5_verify_user ,
  39 .Nm krb5_verify_user_lrealm ,
  40 .Nm krb5_verify_user_opt ,
  41 .Nm krb5_verify_opt_init
  42 .Nm krb5_verify_opt_set_flags ,
  43 .Nm krb5_verify_opt_set_service ,
  44 .Nm krb5_verify_opt_set_secure ,
  45 .Nm krb5_verify_opt_set_keytab
  46 .Nd Heimdal password verifying functions.
  47 .Sh LIBRARY
  48 Kerberos 5 Library (libkrb5, -lkrb5)
  49 .Sh SYNOPSIS
  50 .In krb5.h
  51 .Ft krb5_error_code
  52 .Fn "krb5_verify_user" "krb5_context context" " krb5_principal principal" "krb5_ccache ccache" "const char *password" "krb5_boolean secure" "const char *service"
  53 .Ft krb5_error_code
  54 .Fn "krb5_verify_user_lrealm" "krb5_context context" "krb5_principal principal" "krb5_ccache ccache" "const char *password" "krb5_boolean secure" "const char *service"
  55 .Ft void
  56 .Fn krb5_verify_opt_init "krb5_verify_opt *opt"
  57 .Ft void
  58 .Fn krb5_verify_opt_set_ccache "krb5_verify_opt *opt" "krb5_ccache ccache"
  59 .Ft void
  60 .Fn krb5_verify_opt_set_keytab "krb5_verify_opt *opt" "krb5_keytab keytab"
  61 .Ft void
  62 .Fn krb5_verify_opt_set_secure "krb5_verify_opt *opt" "krb5_boolean secure"
  63 .Ft void
  64 .Fn krb5_verify_opt_set_service "krb5_verify_opt *opt" "const char *service"
  65 .Ft void
  66 .Fn krb5_verify_opt_set_flags "krb5_verify_opt *opt" "unsigned int flags"
  67 .Ft krb5_error_code
  68 .Fo krb5_verify_user_opt
  69 .Fa "krb5_context context"
  70 .Fa "krb5_principal principal"
  71 .Fa "const char *password"
  72 .Fa "krb5_verify_opt *opt"
  73 .Fc
  74 .Sh DESCRIPTION
  75 The
  76 .Nm krb5_verify_user
  77 function verifies the password supplied by a user.
  78 The principal whose password will be verified is specified in
  79 .Fa principal .
  80 New tickets will be obtained as a side-effect and stored in
  81 .Fa ccache
  82 (if
  83 .Dv NULL ,
  84 the default ccache is used).
  85 .Fn krb5_verify_user
  86 will call
  87 .Fn krb5_cc_initialize
  88 on the given
  89 .Fa ccache ,
  90 so
  91 .Fa ccache
  92 must only initialized with
  93 .Fn krb5_cc_resolve
  94 or
  95 .Fn krb5_cc_gen_new .
  96 If the password is not supplied in
  97 .Fa password
  98 (and is given as
  99 .Dv NULL )
 100 the user will be prompted for it.
 101 If
 102 .Fa secure
 103 the ticket will be verified against the locally stored service key
 104 .Fa service
 105 (by default
 106 .Ql host
 107 if given as
 108 .Dv NULL
 109 ).
 110 .Pp
 111 The
 112 .Nm krb5_verify_user_lrealm
 113 function does the same, except that it ignores the realm in
 114 .Fa principal
 115 and tries all the local realms (see
 116 .Xr krb5.conf 5 ) .
 117 After a successful return, the principal is set to the authenticated
 118 realm. If the call fails, the principal will not be meaningful, and
 119 should only be freed with
 120 .Xr krb5_free_principal 3 .
 121 .Pp
 122 .Fn krb5_verify_opt_init
 123 resets all opt to default values.
 124 .Pp
 125 None of the krb5_verify_opt_set function makes a copy of the data
 126 structure that they are called with. Its up the caller to free them
 127 after the
 128 .Fn krb5_verify_user_opt
 129 is called.
 130 .Pp
 131 .Fn krb5_verify_opt_set_ccache
 132 sets the
 133 .Fa ccache
 134 that user of
 135 .Fa opt
 136 will use. If not set, the default credential cache will be used.
 137 .Pp
 138 .Fn krb5_verify_opt_set_keytab
 139 sets the
 140 .Fa keytab
 141 that user of
 142 .Fa opt
 143 will use. If not set, the default keytab will be used.
 144 .Pp
 145 .Fn krb5_verify_opt_set_secure
 146 if
 147 .Fa secure
 148 if true, the password verification will require that the ticket will
 149 be verified against the locally stored service key. If not set,
 150 default value is true.
 151 .Pp
 152 .Fn krb5_verify_opt_set_service
 153 sets the
 154 .Fa service
 155 principal that user of
 156 .Fa opt
 157 will use. If not set, the
 158 .Ql host
 159 service will be used.
 160 .Pp
 161 .Fn krb5_verify_opt_set_flags
 162 sets
 163 .Fa flags
 164 that user of
 165 .Fa opt
 166 will use.
 167 If the flag
 168 .Dv KRB5_VERIFY_LREALMS
 169 is used, the
 170 .Fa principal
 171 will be modified like
 172 .Fn krb5_verify_user_lrealm
 173 modifies it.
 174 .Pp
 175 .Fn krb5_verify_user_opt
 176 function verifies the
 177 .Fa password
 178 supplied by a user.
 179 The principal whose password will be verified is specified in
 180 .Fa principal .
 181 Options the to the verification process is pass in in
 182 .Fa opt .
 183 .Sh EXAMPLE
 184 Here is a example program that verifies a password. it uses the
 185 .Ql host/`hostname`
 186 service principal in
 187 .Pa krb5.keytab .
 188 .Bd -literal
 189 #include <krb5.h>
 190
 191 int
 192 main(int argc, char **argv)
 193 {
 194     char *user;
 195     krb5_error_code error;
 196     krb5_principal princ;
 197     krb5_context context;
 198
 199     if (argc != 2)
 200         errx(1, "usage: verify_passwd <principal-name>");
 201
 202     user = argv[1];
 203
 204     if (krb5_init_context(&context) < 0)
 205         errx(1, "krb5_init_context");
 206
 207     if ((error = krb5_parse_name(context, user, &princ)) != 0)
 208         krb5_err(context, 1, error, "krb5_parse_name");
 209
 210     error = krb5_verify_user(context, princ, NULL, NULL, TRUE, NULL);
 211     if (error)
 212         krb5_err(context, 1, error, "krb5_verify_user");
 213
 214     return 0;
 215 }
 216 .Ed
 217 .Sh SEE ALSO
 218 .Xr krb5_err 3 ,
 219 .Xr krb5_cc_gen_new 3 ,
 220 .Xr krb5_cc_resolve 3 ,
 221 .Xr krb5_cc_initialize 3 ,
 222 .Xr krb5_free_principal 3 ,
 223 .Xr krb5_init_context 3 ,
 224 .Xr krb5_kt_default 3 ,
 225 .Xr krb5.conf 5