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