lib/krb5/krb5_verify_user.3

   1 .\" Copyright (c) 2001 - 2006 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$
  33 .\"
  34 .Dd May  1, 2006
  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_alloc ,
  43 .Nm krb5_verify_opt_free ,
  44 .Nm krb5_verify_opt_set_ccache ,
  45 .Nm krb5_verify_opt_set_flags ,
  46 .Nm krb5_verify_opt_set_service ,
  47 .Nm krb5_verify_opt_set_secure ,
  48 .Nm krb5_verify_opt_set_keytab
  49 .Nd Heimdal password verifying functions
  50 .Sh LIBRARY
  51 Kerberos 5 Library (libkrb5, -lkrb5)
  52 .Sh SYNOPSIS
  53 .In krb5.h
  54 .Ft krb5_error_code
  55 .Fn "krb5_verify_user" "krb5_context context" " krb5_principal principal" "krb5_ccache ccache" "const char *password" "krb5_boolean secure" "const char *service"
  56 .Ft krb5_error_code
  57 .Fn "krb5_verify_user_lrealm" "krb5_context context" "krb5_principal principal" "krb5_ccache ccache" "const char *password" "krb5_boolean secure" "const char *service"
  58 .Ft void
  59 .Fn krb5_verify_opt_init "krb5_verify_opt *opt"
  60 .Ft void
  61 .Fn krb5_verify_opt_alloc "krb5_verify_opt **opt"
  62 .Ft void
  63 .Fn krb5_verify_opt_free "krb5_verify_opt *opt"
  64 .Ft void
  65 .Fn krb5_verify_opt_set_ccache "krb5_verify_opt *opt" "krb5_ccache ccache"
  66 .Ft void
  67 .Fn krb5_verify_opt_set_keytab "krb5_verify_opt *opt" "krb5_keytab keytab"
  68 .Ft void
  69 .Fn krb5_verify_opt_set_secure "krb5_verify_opt *opt" "krb5_boolean secure"
  70 .Ft void
  71 .Fn krb5_verify_opt_set_service "krb5_verify_opt *opt" "const char *service"
  72 .Ft void
  73 .Fn krb5_verify_opt_set_flags "krb5_verify_opt *opt" "unsigned int flags"
  74 .Ft krb5_error_code
  75 .Fo krb5_verify_user_opt
  76 .Fa "krb5_context context"
  77 .Fa "krb5_principal principal"
  78 .Fa "const char *password"
  79 .Fa "krb5_verify_opt *opt"
  80 .Fc
  81 .Sh DESCRIPTION
  82 The
  83 .Nm krb5_verify_user
  84 function verifies the password supplied by a user.
  85 The principal whose password will be verified is specified in
  86 .Fa principal .
  87 New tickets will be obtained as a side-effect and stored in
  88 .Fa ccache
  89 (if
  90 .Dv NULL ,
  91 the default ccache is used).
  92 .Fn krb5_verify_user
  93 will call
  94 .Fn krb5_cc_initialize
  95 on the given
  96 .Fa ccache ,
  97 so
  98 .Fa ccache
  99 must only initialized with
 100 .Fn krb5_cc_resolve
 101 or
 102 .Fn krb5_cc_gen_new .
 103 If the password is not supplied in
 104 .Fa password
 105 (and is given as
 106 .Dv NULL )
 107 the user will be prompted for it.
 108 If
 109 .Fa secure
 110 the ticket will be verified against the locally stored service key
 111 .Fa service
 112 (by default
 113 .Ql host
 114 if given as
 115 .Dv NULL
 116 ).
 117 .Pp
 118 The
 119 .Fn krb5_verify_user_lrealm
 120 function does the same, except that it ignores the realm in
 121 .Fa principal
 122 and tries all the local realms (see
 123 .Xr krb5.conf 5 ) .
 124 After a successful return, the principal is set to the authenticated
 125 realm. If the call fails, the principal will not be meaningful, and
 126 should only be freed with
 127 .Xr krb5_free_principal 3 .
 128 .Pp
 129 .Fn krb5_verify_opt_alloc
 130 and
 131 .Fn krb5_verify_opt_free
 132 allocates and frees a
 133 .Li krb5_verify_opt .
 134 You should use the the alloc and free function instead of allocation
 135 the structure yourself, this is because in a future release the
 136 structure wont be exported.
 137 .Pp
 138 .Fn krb5_verify_opt_init
 139 resets all opt to default values.
 140 .Pp
 141 None of the krb5_verify_opt_set function makes a copy of the data
 142 structure that they are called with. It's up the caller to free them
 143 after the
 144 .Fn krb5_verify_user_opt
 145 is called.
 146 .Pp
 147 .Fn krb5_verify_opt_set_ccache
 148 sets the
 149 .Fa ccache
 150 that user of
 151 .Fa opt
 152 will use. If not set, the default credential cache will be used.
 153 .Pp
 154 .Fn krb5_verify_opt_set_keytab
 155 sets the
 156 .Fa keytab
 157 that user of
 158 .Fa opt
 159 will use. If not set, the default keytab will be used.
 160 .Pp
 161 .Fn krb5_verify_opt_set_secure
 162 if
 163 .Fa secure
 164 if true, the password verification will require that the ticket will
 165 be verified against the locally stored service key. If not set,
 166 default value is true.
 167 .Pp
 168 .Fn krb5_verify_opt_set_service
 169 sets the
 170 .Fa service
 171 principal that user of
 172 .Fa opt
 173 will use. If not set, the
 174 .Ql host
 175 service will be used.
 176 .Pp
 177 .Fn krb5_verify_opt_set_flags
 178 sets
 179 .Fa flags
 180 that user of
 181 .Fa opt
 182 will use.
 183 If the flag
 184 .Dv KRB5_VERIFY_LREALMS
 185 is used, the
 186 .Fa principal
 187 will be modified like
 188 .Fn krb5_verify_user_lrealm
 189 modifies it.
 190 .Pp
 191 .Fn krb5_verify_user_opt
 192 function verifies the
 193 .Fa password
 194 supplied by a user.
 195 The principal whose password will be verified is specified in
 196 .Fa principal .
 197 Options the to the verification process is pass in in
 198 .Fa opt .
 199 .Sh EXAMPLES
 200 Here is a example program that verifies a password. it uses the
 201 .Ql host/`hostname`
 202 service principal in
 203 .Pa krb5.keytab .
 204 .Bd -literal
 205 #include <krb5.h>
 206
 207 int
 208 main(int argc, char **argv)
 209 {
 210     char *user;
 211     krb5_error_code error;
 212     krb5_principal princ;
 213     krb5_context context;
 214
 215     if (argc != 2)
 216         errx(1, "usage: verify_passwd <principal-name>");
 217
 218     user = argv[1];
 219
 220     if (krb5_init_context(&context) < 0)
 221         errx(1, "krb5_init_context");
 222
 223     if ((error = krb5_parse_name(context, user, &princ)) != 0)
 224         krb5_err(context, 1, error, "krb5_parse_name");
 225
 226     error = krb5_verify_user(context, princ, NULL, NULL, TRUE, NULL);
 227     if (error)
 228         krb5_err(context, 1, error, "krb5_verify_user");
 229
 230     return 0;
 231 }
 232 .Ed
 233 .Sh SEE ALSO
 234 .Xr krb5_cc_gen_new 3 ,
 235 .Xr krb5_cc_initialize 3 ,
 236 .Xr krb5_cc_resolve 3 ,
 237 .Xr krb5_err 3 ,
 238 .Xr krb5_free_principal 3 ,
 239 .Xr krb5_init_context 3 ,
 240 .Xr krb5_kt_default 3 ,
 241 .Xr krb5.conf 5