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