| blob | 9412f15a1c140c9018f55d86525621e2ec9498a7 |
1 .\" $NetBSD: krb5_get_creds.3,v 1.1.1.2 2011/04/14 14:09:23 elric Exp $
2 .\"
3 .\" Copyright (c) 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 June 15, 2006
37 .Dt KRB5_GET_CREDS 3
38 .Os
39 .Sh NAME
40 .Nm krb5_get_creds ,
41 .Nm krb5_get_creds_opt_add_options ,
42 .Nm krb5_get_creds_opt_alloc ,
43 .Nm krb5_get_creds_opt_free ,
44 .Nm krb5_get_creds_opt_set_enctype ,
45 .Nm krb5_get_creds_opt_set_impersonate ,
46 .Nm krb5_get_creds_opt_set_options ,
47 .Nm krb5_get_creds_opt_set_ticket
48 .Nd get credentials from the KDC
49 .Sh LIBRARY
50 Kerberos 5 Library (libkrb5, -lkrb5)
51 .Sh SYNOPSIS
52 .In krb5/krb5.h
53 .Ft krb5_error_code
54 .Fo krb5_get_creds
55 .Fa "krb5_context context"
56 .Fa "krb5_get_creds_opt opt"
57 .Fa "krb5_ccache ccache"
58 .Fa "krb5_const_principal inprinc"
59 .Fa "krb5_creds **out_creds"
60 .Fc
61 .Ft void
62 .Fo krb5_get_creds_opt_add_options
63 .Fa "krb5_context context"
64 .Fa "krb5_get_creds_opt opt"
65 .Fa "krb5_flags options"
66 .Fc
67 .Ft krb5_error_code
68 .Fo krb5_get_creds_opt_alloc
69 .Fa "krb5_context context"
70 .Fa "krb5_get_creds_opt *opt"
71 .Fc
72 .Ft void
73 .Fo krb5_get_creds_opt_free
74 .Fa "krb5_context context"
75 .Fa "krb5_get_creds_opt opt"
76 .Fc
77 .Ft void
78 .Fo krb5_get_creds_opt_set_enctype
79 .Fa "krb5_context context"
80 .Fa "krb5_get_creds_opt opt"
81 .Fa "krb5_enctype enctype"
82 .Fc
83 .Ft krb5_error_code
84 .Fo krb5_get_creds_opt_set_impersonate
85 .Fa "krb5_context context"
86 .Fa "krb5_get_creds_opt opt"
87 .Fa "krb5_const_principal self"
88 .Fc
89 .Ft void
90 .Fo krb5_get_creds_opt_set_options
91 .Fa "krb5_context context"
92 .Fa "krb5_get_creds_opt opt"
93 .Fa "krb5_flags options"
94 .Fc
95 .Ft krb5_error_code
96 .Fo krb5_get_creds_opt_set_ticket
97 .Fa "krb5_context context"
98 .Fa "krb5_get_creds_opt opt"
99 .Fa "const Ticket *ticket"
100 .Fc
101 .Sh DESCRIPTION
102 .Fn krb5_get_creds
103 fetches credentials specified by
104 .Fa opt
105 by first looking in the
106 .Fa ccache ,
107 and then it doesn't exists, fetch the credential from the KDC
108 using the krbtgts in
109 .Fa ccache .
110 The credential is returned in
111 .Fa out_creds
112 and should be freed using the function
113 .Fn krb5_free_creds .
114 .Pp
115 The structure
116 .Li krb5_get_creds_opt
117 controls the behavior of
118 .Fn krb5_get_creds .
119 The structure is opaque to consumers that can set the content of the
120 structure with accessors functions. All accessor functions make copies
121 of the data that is passed into accessor functions, so external
122 consumers free the memory before calling
123 .Fn krb5_get_creds .
124 .Pp
125 The structure
126 .Li krb5_get_creds_opt
127 is allocated with
128 .Fn krb5_get_creds_opt_alloc
129 and freed with
130 .Fn krb5_get_creds_opt_free .
131 The free function also frees the content of the structure set by the
132 accessor functions.
133 .Pp
134 .Fn krb5_get_creds_opt_add_options
135 and
136 .Fn krb5_get_creds_opt_set_options
137 adds and sets options to the
138 .Fi krb5_get_creds_opt
139 structure .
140 The possible options to set are
141 .Bl -tag -width "KRB5_GC_USER_USER" -compact
142 .It KRB5_GC_CACHED
143 Only check the
144 .Fa ccache ,
145 don't got out on network to fetch credential.
146 .It KRB5_GC_USER_USER
147 request a user to user ticket.
148 This options doesn't store the resulting user to user credential in
149 the
150 .Fa ccache .
151 .It KRB5_GC_EXPIRED_OK
152 returns the credential even if it is expired, default behavior is trying
153 to refetch the credential from the KDC.
154 .It KRB5_GC_NO_STORE
155 Do not store the resulting credentials in the
156 .Fa ccache .
157 .El
158 .Pp
159 .Fn krb5_get_creds_opt_set_enctype
160 sets the preferred encryption type of the application. Don't set this
161 unless you have to since if there is no match in the KDC, the function
162 call will fail.
163 .Pp
164 .Fn krb5_get_creds_opt_set_impersonate
165 sets the principal to impersonate., Returns a ticket that have the
166 impersonation principal as a client and the requestor as the
167 service. Note that the requested principal have to be the same as the
168 client principal in the krbtgt.
169 .Pp
170 .Fn krb5_get_creds_opt_set_ticket
171 sets the extra ticket used in user-to-user or contrained delegation use case.
172 .Sh SEE ALSO
173 .Xr krb5 3 ,
174 .Xr krb5_get_credentials 3 ,
175 .Xr krb5.conf 5