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