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