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