1
2
3
4
5
6
7Network Working Group                                        N. Williams
8Request for Comments: 5588                                           Sun
9Category: Standards Track                                      July 2009
10
11
12   Generic Security Service Application Program Interface (GSS-API)
13              Extension for Storing Delegated Credentials
14
15Abstract
16
17   This document defines a new function for the Generic Security Service
18   Application Program Interface (GSS-API), which allows applications to
19   store delegated (and other) credentials in the implicit GSS-API
20   credential store.  This is needed for GSS-API applications to use
21   delegated credentials as they would use other credentials.
22
23Status of This Memo
24
25   This document specifies an Internet standards track protocol for the
26   Internet community, and requests discussion and suggestions for
27   improvements.  Please refer to the current edition of the "Internet
28   Official Protocol Standards" (STD 1) for the standardization state
29   and status of this protocol.  Distribution of this memo is unlimited.
30
31Copyright Notice
32
33   Copyright (c) 2009 IETF Trust and the persons identified as the
34   document authors.  All rights reserved.
35
36   This document is subject to BCP 78 and the IETF Trust's Legal
37   Provisions Relating to IETF Documents in effect on the date of
38   publication of this document (http://trustee.ietf.org/license-info).
39   Please review these documents carefully, as they describe your rights
40   and restrictions with respect to this document.
41
42Table of Contents
43
44   1. Introduction ....................................................2
45   2. Conventions Used in This Document ...............................3
46   3. GSS_Store_cred() ................................................3
47   4. C-Bindings ......................................................5
48   5. Examples ........................................................6
49   6. Security Considerations .........................................6
50   7. Normative References ............................................7
51
52
53
54
55
56
57
58Williams                    Standards Track                     [Page 1]
59
60RFC 5588                    GSS_Store_cred()                   July 2009
61
62
631.  Introduction
64
65   The GSS-API [RFC2743] clearly assumes that credentials exist in an
66   implicit store whence they can be acquired using GSS_Acquire_cred()
67   and GSS_Add_cred() or through use of the default credential.
68   Multiple credential stores may exist on a given host, but only one
69   store may be accessed by GSS_Acquire_cred() and GSS_Add_cred() at any
70   given time.
71
72   This assumption can be seen in Sections 1.1.1.2 and 1.1.1.3 of
73   [RFC2743] as well as in Section 3.5 of [RFC2744].
74
75   Applications may be able to change the credential store from which
76   credentials can be acquired, either by changing user contexts (where
77   the applications have the privilege to do so) or by other means
78   (where a user may have multiple credential stores).
79
80   Some GSS-API acceptor applications always change user contexts, after
81   accepting a GSS-API security context and making appropriate
82   authorization checks, to the user context corresponding to the
83   initiator principal name or to a context requested by the initiator.
84   The means by which credential stores are managed are generally beyond
85   the scope of the GSS-API.
86
87   In the case of delegated credential handles however, such credentials
88   do not exist in the acceptor's credential store or in the credential
89   stores of the user contexts to which the acceptor application might
90   change.  The GSS-API provides no mechanism by which delegated
91   credential handles can be made available for acquisition through
92   GSS_Acquire_cred()/GSS_Add_cred().  The GSS-API also does not provide
93   any credential import/export interfaces like the GSS-API context
94   import/export interfaces.
95
96   Thus, acceptors are limited to making only direct use of delegated
97   credential handles and only with GSS_Init_sec_context(),
98   GSS_Inquire_cred*(), and GSS_Release_cred().  This limitation is
99   particularly onerous on Unix systems where a call to exec() to
100   replace the process image obliterates any delegated credentials
101   handle that may exist in that process.
102
103   In order to make delegated credentials generally as useful as
104   credentials that can be acquired with GSS_Acquire_cred() and
105   GSS_Add_cred(), a primitive is needed that allows storing of
106   credentials in the implicit credential store.  We call this primitive
107   "GSS_Store_cred()".
108
109
110
111
112
113
114Williams                    Standards Track                     [Page 2]
115
116RFC 5588                    GSS_Store_cred()                   July 2009
117
118
1192.  Conventions Used in This Document
120
121   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
122   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
123   document are to be interpreted as described in [RFC2119].
124
1253.  GSS_Store_cred()
126
127   Inputs:
128
129   o  input_cred_handle CREDENTIAL HANDLE, -- credential to store; MUST
130      NOT be GSS_C_NO_CREDENTIAL.
131
132   o  cred_usage INTEGER -- 0=INITIATE-AND-ACCEPT, 1=INITIATE-ONLY,
133      2=ACCEPT-ONLY.
134
135   o  desired_mech_element OBJECT IDENTIFIER, -- if GSS_C_NULL_OID, then
136      store all the elements of the input_cred_handle, otherwise, store
137      only the element of the corresponding mechanism.
138
139   o  overwrite_cred BOOLEAN, -- if TRUE, replace any credential for the
140      same principal in the credential store.
141
142   o  default_cred BOOLEAN -- advisory input; if TRUE, make the stored
143      credential available as the default credential (for acquisition
144      with GSS_C_NO_NAME as the desired name or for use as
145      GSS_C_NO_CREDENTIAL).
146
147   Outputs:
148
149   o  major_status INTEGER.
150
151   o  minor_status INTEGER.
152
153   o  mech_elements_stored SET OF OBJECT IDENTIFIER, -- the set of
154      mechanism OIDs for which credential elements were successfully
155      stored.
156
157   o  cred_usage_stored INTEGER -- like cred_usage, but indicates what
158      kind of credential was stored (useful when the cred_usage input
159      parameter is set to INITIATE-AND-ACCEPT).
160
161   Return major_status codes:
162
163   o  GSS_S_COMPLETE indicates that the credentials were successfully
164      stored.
165
166
167
168
169
170Williams                    Standards Track                     [Page 3]
171
172RFC 5588                    GSS_Store_cred()                   July 2009
173
174
175   o  GSS_S_CREDENTIALS_EXPIRED indicates that the input credentials had
176      expired or expired before they could be stored.
177
178   o  GSS_S_NO_CRED indicates that no input credentials were given.
179
180   o  GSS_S_UNAVAILABLE indicates that the credential store is not
181      available.
182
183   o  GSS_S_DUPLICATE_ELEMENT indicates that an element of the input
184      credential could not be stored because a credential for the same
185      principal exists in the current credential store and the
186      overwrite_cred input argument was FALSE.
187
188   o  GSS_S_FAILURE indicates that the credential could not be stored
189      for some other reason.  The minor status code may provide more
190      information if a non-GSS_C_NULL_OID desired_mech_element was
191      given.
192
193   GSS_Store_cred() is used to store, in the current credential store, a
194   given credential that has either been acquired from a different
195   credential store or been accepted as a delegated credential.
196
197   Specific mechanism elements of a credential can be stored one at a
198   time by specifying a non-GSS_C_NULL_OID mechanism OID as the
199   desired_mech_element input argument; in which case, the minor status
200   output SHOULD have a mechanism-specific value when the major status
201   is not GSS_S_COMPLETE.
202
203   The initiator, acceptor, or both usages of the input credential may
204   be stored as per the cred_usage input argument.
205
206   The credential elements that were actually stored, when the major
207   status is GSS_S_COMPLETE, are indicated through the cred_usage_stored
208   and mech_elements_stored function outputs.
209
210   If credentials already exist in the current store for the principal
211   of the input_cred_handle, then those credentials are not replaced
212   with the input credentials unless the overwrite_cred input argument
213   is TRUE.
214
215   In the GSS-API, the default credential can be used by using
216   GSS_C_NO_CREDENTIAL or a CREDENTIAL handle acquired by calling
217   GSS_Acquire_cred() or GSS_Add_cred() with the desired_name input set
218   to GSS_C_NO_NAME.
219
220   If the default_cred input argument is TRUE, and the input credential
221   can be successfully stored, then the input credential SHOULD be
222   stored as the default credential (see above).
223
224
225
226Williams                    Standards Track                     [Page 4]
227
228RFC 5588                    GSS_Store_cred()                   July 2009
229
230
231   If the current credential store has no default credential (see
232   above), then the implementation MAY make the stored credentials
233   available as the default credential regardless of the value of the
234   default_cred input argument.
235
2364.  C-Bindings
237
238   The C-Bindings for GSS_Store_cred() make use of types from and are
239   designed based on the style of the GSS-APIv2 C-Bindings [RFC2744].
240
241         OM_uint32 gss_store_cred(
242            OM_uint32         *minor_status,
243            gss_cred_id_t     input_cred_handle,
244            gss_cred_usage_t  cred_usage,
245            const gss_OID     desired_mech,
246            OM_uint32         overwrite_cred,
247            OM_uint32         default_cred,
248            gss_OID_set       *elements_stored,
249            gss_cred_usage_t  *cred_usage_stored)
250
251                        Figure 1
252
253   The two boolean arguments, 'overwrite_cred' and 'default_cred', are
254   typed as OM_uint32; 0 corresponds to FALSE, non-zero values
255   correspond to TRUE.
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282Williams                    Standards Track                     [Page 5]
283
284RFC 5588                    GSS_Store_cred()                   July 2009
285
286
2875.  Examples
288
289   The intended usage of GSS_Store_cred() is to make delegated
290   credentials available to child processes of GSS-API acceptor
291   applications.  Example pseudo-code:
292
293      /*
294       * <GSS_Accept_sec_context() loop resulting in GSS_S_COMPLETE,
295       * an initiator name (hereafter, "src_name") and a delegated
296       * credential handle (hereafter "deleg_cred").>
297       *
298       * <"requested_username" is a username derived from the
299       * initiator name or explicitly requested by the initiator
300       * application.>
301       */
302      ...
303
304      if (authorize_gss_client(src_name, requested_username)) {
305         /*
306          * For Unix-type platforms this may mean calling setuid() and
307          * it may or may not also mean setting/unsetting such
308          * environment variables as KRB5CCNAME and what not -- all
309          * OS-specific details.
310          */
311         if (change_user_context(requested_username))
312            (void) gss_store_cred(&minor_status, deleg_cred,
313                                  GSS_C_INITIATE, actual_mech,
314                                  0, 1, NULL, NULL);
315         }
316         else ...
317      }
318      else ...
319
3206.  Security Considerations
321
322   Acceptor applications MUST only store delegated credentials into
323   appropriate credential stores and only after proper authorization of
324   the authenticated initiator principal to the requested service(s).
325
326   Acceptor applications that have no use for delegated credentials MUST
327   release them (such acceptor applications that use the GSS-API C-
328   Bindings may simply provide a NULL value for the
329   delegated_cred_handle argument to gss_accept_sec_context()).
330
331
332
333
334
335
336
337
338Williams                    Standards Track                     [Page 6]
339
340RFC 5588                    GSS_Store_cred()                   July 2009
341
342
3437.  Normative References
344
345   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
346              Requirement Levels", BCP 14, RFC 2119, March 1997.
347
348   [RFC2743]  Linn, J., "Generic Security Service Application Program
349              Interface Version 2, Update 1", RFC 2743, January 2000.
350
351   [RFC2744]  Wray, J., "Generic Security Service API Version 2 :
352              C-bindings", RFC 2744, January 2000.
353
354Author's Address
355
356   Nicolas Williams
357   Sun Microsystems
358   5300 Riata Trace Ct
359   Austin, TX  78727
360   US
361
362   EMail: Nicolas.Williams@sun.com
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394Williams                    Standards Track                     [Page 7]
395
396