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