1.\" Copyright (c) 2004 - 2005 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_get_credentials.3 22071 2007-11-14 20:04:50Z lha $
33.\"
34.Dd July 26, 2004
35.Dt KRB5_GET_CREDENTIALS 3
36.Os HEIMDAL
37.Sh NAME
38.Nm krb5_get_credentials ,
39.Nm krb5_get_credentials_with_flags ,
40.Nm krb5_get_cred_from_kdc ,
41.Nm krb5_get_cred_from_kdc_opt ,
42.Nm krb5_get_kdc_cred ,
43.Nm krb5_get_renewed_creds
44.Nd get credentials from the KDC using krbtgt
45.Sh LIBRARY
46Kerberos 5 Library (libkrb5, -lkrb5)
47.Sh SYNOPSIS
48.In krb5.h
49.Ft krb5_error_code
50.Fo krb5_get_credentials
51.Fa "krb5_context context"
52.Fa "krb5_flags options"
53.Fa "krb5_ccache ccache"
54.Fa "krb5_creds *in_creds"
55.Fa "krb5_creds **out_creds"
56.Fc
57.Ft krb5_error_code
58.Fo krb5_get_credentials_with_flags
59.Fa "krb5_context context"
60.Fa "krb5_flags options"
61.Fa "krb5_kdc_flags flags"
62.Fa "krb5_ccache ccache"
63.Fa "krb5_creds *in_creds"
64.Fa "krb5_creds **out_creds"
65.Fc
66.Ft krb5_error_code
67.Fo krb5_get_cred_from_kdc
68.Fa "krb5_context context"
69.Fa "krb5_ccache ccache"
70.Fa "krb5_creds *in_creds"
71.Fa "krb5_creds **out_creds"
72.Fa "krb5_creds ***ret_tgts"
73.Fc
74.Ft krb5_error_code
75.Fo krb5_get_cred_from_kdc_opt
76.Fa "krb5_context context"
77.Fa "krb5_ccache ccache"
78.Fa "krb5_creds *in_creds"
79.Fa "krb5_creds **out_creds"
80.Fa "krb5_creds ***ret_tgts"
81.Fa "krb5_flags flags"
82.Fc
83.Ft krb5_error_code
84.Fo krb5_get_kdc_cred
85.Fa "krb5_context context"
86.Fa "krb5_ccache id"
87.Fa "krb5_kdc_flags flags"
88.Fa "krb5_addresses *addresses"
89.Fa "Ticket  *second_ticket"
90.Fa "krb5_creds *in_creds"
91.Fa "krb5_creds **out_creds"
92.Fc
93.Ft krb5_error_code
94.Fo krb5_get_renewed_creds
95.Fa "krb5_context context"
96.Fa "krb5_creds *creds"
97.Fa "krb5_const_principal client"
98.Fa "krb5_ccache ccache"
99.Fa "const char *in_tkt_service"
100.Fc
101.Sh DESCRIPTION
102.Fn krb5_get_credentials_with_flags
103get credentials specified by
104.Fa in_creds->server
105and
106.Fa in_creds->client
107(the rest of the
108.Fa in_creds
109structure is ignored)
110by first looking in the
111.Fa ccache
112and if doesn't exists or is expired, fetch the credential from the KDC
113using the krbtgt in
114.Fa ccache .
115The credential is returned in
116.Fa out_creds
117and should be freed using the function
118.Fn krb5_free_creds .
119.Pp
120Valid flags to pass into
121.Fa options
122argument are:
123.Pp
124.Bl -tag -width "KRB5_GC_USER_USER" -compact
125.It KRB5_GC_CACHED
126Only check the
127.Fa ccache ,
128don't got out on network to fetch credential.
129.It KRB5_GC_USER_USER
130Request a user to user ticket.
131This option doesn't store the resulting user to user credential in
132the
133.Fa ccache .
134.It KRB5_GC_EXPIRED_OK
135returns the credential even if it is expired, default behavior is trying
136to refetch the credential from the KDC.
137.El
138.Pp
139.Fa Flags
140are KDCOptions, note the caller must fill in the bit-field and not
141use the integer associated structure.
142.Pp
143.Fn krb5_get_credentials
144works the same way as
145.Fn krb5_get_credentials_with_flags
146except that the
147.Fa flags
148field is missing.
149.Pp
150.Fn krb5_get_cred_from_kdc
151and
152.Fn krb5_get_cred_from_kdc_opt
153fetches the credential from the KDC very much like
154.Fn krb5_get_credentials, but doesn't look in the
155.Fa ccache
156if the credential exists there first.
157.Pp
158.Fn krb5_get_kdc_cred
159does the same as the functions above, but the caller must fill in all
160the information andits closer to the wire protocol.
161.Pp
162.Fn krb5_get_renewed_creds
163renews a credential given by
164.Fa in_tkt_service
165(if
166.Dv NULL
167the default
168.Li krbtgt )
169using the credential cache
170.Fa ccache .
171The result is stored in
172.Fa creds
173and should be freed using
174.Fa krb5_free_creds .
175.Sh EXAMPLES
176Here is a example function that get a credential from a credential cache
177.Fa id
178or the KDC and returns it to the caller.
179.Bd -literal
180#include <krb5.h>
181
182int
183getcred(krb5_context context, krb5_ccache id, krb5_creds **creds)
184{
185    krb5_error_code ret;
186    krb5_creds in;
187
188    ret = krb5_parse_name(context, "client@EXAMPLE.COM",
189			  &in.client);
190    if (ret)
191	krb5_err(context, 1, ret, "krb5_parse_name");
192
193    ret = krb5_parse_name(context, "host/server.example.com@EXAMPLE.COM",
194			  &in.server);
195    if (ret)
196	krb5_err(context, 1, ret, "krb5_parse_name");
197
198    ret = krb5_get_credentials(context, 0, id, &in, creds);
199    if (ret)
200	krb5_err(context, 1, ret, "krb5_get_credentials");
201
202    return 0;
203}
204.Ed
205.Sh SEE ALSO
206.Xr krb5 3 ,
207.Xr krb5_get_forwarded_creds 3 ,
208.Xr krb5.conf 5
209