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 51Kerberos 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 82The 83.Nm krb5_verify_user 84function verifies the password supplied by a user. 85The principal whose password will be verified is specified in 86.Fa principal . 87New tickets will be obtained as a side-effect and stored in 88.Fa ccache 89(if 90.Dv NULL , 91the default ccache is used). 92.Fn krb5_verify_user 93will call 94.Fn krb5_cc_initialize 95on the given 96.Fa ccache , 97so 98.Fa ccache 99must only initialized with 100.Fn krb5_cc_resolve 101or 102.Fn krb5_cc_gen_new . 103If the password is not supplied in 104.Fa password 105(and is given as 106.Dv NULL ) 107the user will be prompted for it. 108If 109.Fa secure 110the ticket will be verified against the locally stored service key 111.Fa service 112(by default 113.Ql host 114if given as 115.Dv NULL 116). 117.Pp 118The 119.Fn krb5_verify_user_lrealm 120function does the same, except that it ignores the realm in 121.Fa principal 122and tries all the local realms (see 123.Xr krb5.conf 5 ) . 124After a successful return, the principal is set to the authenticated 125realm. If the call fails, the principal will not be meaningful, and 126should only be freed with 127.Xr krb5_free_principal 3 . 128.Pp 129.Fn krb5_verify_opt_alloc 130and 131.Fn krb5_verify_opt_free 132allocates and frees a 133.Li krb5_verify_opt . 134You should use the the alloc and free function instead of allocation 135the structure yourself, this is because in a future release the 136structure wont be exported. 137.Pp 138.Fn krb5_verify_opt_init 139resets all opt to default values. 140.Pp 141None of the krb5_verify_opt_set function makes a copy of the data 142structure that they are called with. It's up the caller to free them 143after the 144.Fn krb5_verify_user_opt 145is called. 146.Pp 147.Fn krb5_verify_opt_set_ccache 148sets the 149.Fa ccache 150that user of 151.Fa opt 152will use. If not set, the default credential cache will be used. 153.Pp 154.Fn krb5_verify_opt_set_keytab 155sets the 156.Fa keytab 157that user of 158.Fa opt 159will use. If not set, the default keytab will be used. 160.Pp 161.Fn krb5_verify_opt_set_secure 162if 163.Fa secure 164if true, the password verification will require that the ticket will 165be verified against the locally stored service key. If not set, 166default value is true. 167.Pp 168.Fn krb5_verify_opt_set_service 169sets the 170.Fa service 171principal that user of 172.Fa opt 173will use. If not set, the 174.Ql host 175service will be used. 176.Pp 177.Fn krb5_verify_opt_set_flags 178sets 179.Fa flags 180that user of 181.Fa opt 182will use. 183If the flag 184.Dv KRB5_VERIFY_LREALMS 185is used, the 186.Fa principal 187will be modified like 188.Fn krb5_verify_user_lrealm 189modifies it. 190.Pp 191.Fn krb5_verify_user_opt 192function verifies the 193.Fa password 194supplied by a user. 195The principal whose password will be verified is specified in 196.Fa principal . 197Options the to the verification process is pass in in 198.Fa opt . 199.Sh EXAMPLES 200Here is a example program that verifies a password. it uses the 201.Ql host/`hostname` 202service principal in 203.Pa krb5.keytab . 204.Bd -literal 205#include <krb5.h> 206 207int 208main(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 242