1 2NETWORK WORKING GROUP N. Williams 3Internet-Draft Sun 4Expires: August 15, 2005 February 14, 2005 5 6 7 GSS-API Extension for Storing Delegated Credentials 8 draft-ietf-kitten-gssapi-store-cred-00.txt 9 10Status of this Memo 11 12 By submitting this Internet-Draft, I certify that any applicable 13 patent or other IPR claims of which I am aware have been disclosed, 14 and any of which I become aware will be disclosed, in accordance with 15 RFC 3668. 16 17 Internet-Drafts are working documents of the Internet Engineering 18 Task Force (IETF), its areas, and its working groups. Note that 19 other groups may also distribute working documents as 20 Internet-Drafts. 21 22 Internet-Drafts are draft documents valid for a maximum of six months 23 and may be updated, replaced, or obsoleted by other documents at any 24 time. It is inappropriate to use Internet-Drafts as reference 25 material or to cite them other than as "work in progress." 26 27 The list of current Internet-Drafts can be accessed at 28 http://www.ietf.org/ietf/1id-abstracts.txt. 29 30 The list of Internet-Draft Shadow Directories can be accessed at 31 http://www.ietf.org/shadow.html. 32 33 This Internet-Draft will expire on August 15, 2005. 34 35Copyright Notice 36 37 Copyright (C) The Internet Society (2005). All Rights Reserved. 38 39Abstract 40 41 This document defines a new function for the GSS-API which allows 42 applications to store delegated (and other) credentials in the 43 implicit GSS-API credential store. This is needed for GSS-API 44 applications to use delegated credentials as they would use other 45 credentials. 46 47 48 49 50 51 52 53 54Williams Expires August 15, 2005 [Page 1] 55 56Internet-Draft GSS_Store_cred() February 2005 57 58 59Table of Contents 60 61 1. Conventions used in this document . . . . . . . . . . . . . . 3 62 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 63 3. GSS_Store_cred() . . . . . . . . . . . . . . . . . . . . . . . 5 64 4. C-Bindings . . . . . . . . . . . . . . . . . . . . . . . . . . 7 65 5. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 66 6. Security considerations . . . . . . . . . . . . . . . . . . . 9 67 7. Normative . . . . . . . . . . . . . . . . . . . . . . . . . . 9 68 Author's Address . . . . . . . . . . . . . . . . . . . . . . . 9 69 Intellectual Property and Copyright Statements . . . . . . . . 10 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110Williams Expires August 15, 2005 [Page 2] 111 112Internet-Draft GSS_Store_cred() February 2005 113 114 1151. Conventions used in this document 116 117 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 118 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 119 document are to be interpreted as described in [RFC2119]. 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166Williams Expires August 15, 2005 [Page 3] 167 168Internet-Draft GSS_Store_cred() February 2005 169 170 1712. Introduction 172 173 The GSS-API [RFC2743] clearly assumes that credentials exist in an 174 implicit store whence they can be acquired using GSS_Acquire_cred() 175 and GSS_Add_cred() or through use of the default credential. 176 Multiple credential stores may exist on a given host, but only one 177 store may be accessed by GSS_Acquire_cred() and GSS_Add_cred() at any 178 given time. 179 180 This assumption can be seen in sections 1.1.1.2 and 1.1.1.3 of 181 [RFC2743] as well as in section 3.5 of [RFC2744]. 182 183 Note to the RFC editor: please remove this note before publication.] 184 185 Applications may be able to change the credential store from which 186 credentials can be acquired, either by changing user contexts (where 187 the applications have the privilege to do so) or by other means 188 (where a user may have multiple credential stores). 189 190 Some GSS-API acceptor applications always change user contexts, after 191 accepting a GSS-API security context and making appropriate 192 authorization checks, to the user context corresponding to the 193 initiator principal name or to a context requested by the initiator. 194 The means by which credential stores are managed are generally beyond 195 the scope of the GSS-API. 196 197 In the case of delegated credential handles however, such credentials 198 do not exist in the acceptor's credential store or in the credential 199 stores of the user contexts to which the acceptor application might 200 change - which is precisely the raison d'etre of credential 201 delegation. But the GSS-API provides no mechanism by which delegated 202 credential handles can be made available for acquisition through 203 GSS_Acquire_cred()/GSS_Add_cred(). The GSS-API also does not provide 204 any credential import/export interfaces like the GSS-API context 205 import/export interfaces. 206 207 Thus acceptors are limited to making only direct use of delegated 208 credential handles and only with GSS_Init_sec_context(), 209 GSS_Inquire_cred*() and GSS_Release_cred(). This limitation is 210 particularly onerous on Unix systems where a call to exec() to 211 replace the process image obliterates the delegated credentials 212 handle. 213 214 In order to make delegated credentials generally as useful as 215 credentials that can be acquired with GSS_Acquire_cred() and 216 GSS_Add_cred() a primitive is needed which allows storing of 217 credentials in the implicit credential store. This primitive we call 218 "GSS_Store_cred()." 219 220 221 222Williams Expires August 15, 2005 [Page 4] 223 224Internet-Draft GSS_Store_cred() February 2005 225 226 2273. GSS_Store_cred() 228 229 Inputs: 230 o input_cred_handle CREDENTIAL HANDLE, -- credential to store; MUST 231 NOT be GSS_C_NO_CREDENTIAL 232 o cred_usage INTEGER -- 0=INITIATE-AND-ACCEPT, 1=INITIATE-ONLY, 233 2=ACCEPT-ONLY 234 o desired_mech_element OBJECT IDENTIFIER, -- if GSS_C_NULL_OID then 235 store all the elements of the input_cred_handle, otherwise store 236 only the element of the corresponding mechanism 237 o overwrite_cred BOOLEAN, -- if TRUE replace any credential for the 238 same principal in the credential store 239 o default_cred BOOLEAN -- if TRUE make the stored credential 240 available as the default credential (for acquisition with 241 GSS_C_NO_NAME as the desired name or for use as 242 GSS_C_NO_CREDENTIAL) 243 244 Outputs: 245 o major_status INTEGER, 246 o minor_status INTEGER, 247 o mech_elements_stored SET OF OBJECT IDENTIFIER, -- the set of 248 mechanism OIDs for which credential elements were successfully 249 stored 250 o cred_usage_stored INTEGER -- like cred_usage, but indicates what 251 kind of credential was stored (useful when the cred_usage input 252 parameter is set to INITIATE-AND-ACCEPT) 253 254 Return major_status codes: 255 o GSS_S_COMPLETE indicates that the credentials were successfully 256 stored. 257 o GSS_S_CREDENTIALS_EXPIRED indicates that the input credentials had 258 expired or expired before they could be stored. 259 o GSS_S_NO_CRED indicates that no input credentials were given. 260 o GSS_S_UNAVAILABLE indicates that the credential store is not 261 available. 262 o GSS_S_DUPLICATE_ELEMENT indicates that an element of the input 263 credential could not be stored because a credential for the same 264 principal exists in the current credential store and the 265 overwrite_cred input argument was FALSE. 266 o GSS_S_FAILURE indicates that the credential could not be stored 267 for some other reason. The minor status code may provide more 268 information if a non-GSS_C_NULL_OID desired_mech_element was 269 given. 270 271 GSS_Store_cred() is used to store, in the current credential store, a 272 given credential that has either been acquired from a different 273 credential store or been accepted as a delegated credential. 274 275 276 277 278Williams Expires August 15, 2005 [Page 5] 279 280Internet-Draft GSS_Store_cred() February 2005 281 282 283 Specific mechanism elements of a credential can be stored one at a 284 time by specifying a non-GSS_C_NULL_OID mechanism OID as the 285 desired_mech_element input argument, in which case the minor status 286 output SHOULD have a mechanism-specific value when the major status 287 is not GSS_S_COMPLETE. 288 289 The initiator, acceptor or both usages of the input credential may be 290 stored as per the cred_usage input argument. 291 292 The credential elements that were actually stored, when the major 293 status is GSS_S_COMPLETE, are indicated through the cred_usage_stored 294 and mech_elements_stored function outputs. 295 296 If credentials already exist in the current store for the principal 297 of the input_cred_handle, then those credentials are not replaced 298 with the input credentials unless the overwrite_cred input argument 299 is TRUE. 300 301 Finally, if the current credential store has no default credential 302 (that is, no credential that could be acquired for GSS_C_NO_NAME) or 303 if the default_cred input argument is TRUE, and the input credential 304 can be successfully stored, then the input credential will be 305 available for acquisition with GSS_C_NO_NAME as the desired name 306 input to GSS_Acquire_cred() or GSS_Add_cred() as well as for use as 307 GSS_C_NO_CREDENTIAL for the cred_handle inputs to GSS_Inquire_cred(), 308 GSS_Inquire_cred_by_mech(), GSS_Init_sec_context() and 309 GSS_Accept_sec_context(). 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334Williams Expires August 15, 2005 [Page 6] 335 336Internet-Draft GSS_Store_cred() February 2005 337 338 3394. C-Bindings 340 341 The C-bindings for GSS_Store_cred() make use of types from and are 342 designed based on the style of the GSS-APIv2 C-Bindings [RFC2744]. 343 344 345 OM_uint32 gss_store_cred( 346 OM_uint32 *minor_status, 347 gss_cred_id_t input_cred, 348 gss_cred_usage_t cred_usage, 349 const gss_OID desired_mech, 350 OM_uint32 overwrite_cred, 351 OM_uint32 default_cred, 352 gss_OID_set *elements_stored, 353 gss_cred_usage_t *cred_usage_stored) 354 355 356 Figure 1 357 358 The two boolean arguments, 'overwrite_cred' and 'default_cred' are 359 typed as OM_uint32; 0 corresponds to FALSE, non-zero values 360 correspond to TRUE. 361 362 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 390Williams Expires August 15, 2005 [Page 7] 391 392Internet-Draft GSS_Store_cred() February 2005 393 394 3955. Examples 396 397 The intended usage of GSS_Store_cred() is to make delegated 398 credentials available to child processes of GSS-API acceptor 399 applications. Example pseudo-code: 400 401 402 /* 403 * <GSS_Accept_sec_context() loop resulting in GSS_S_COMPLETE, 404 * an initiator name (hereafter, "src_name") and a delegated 405 * credential handle (hereafter "deleg_cred").> 406 * 407 * <"requested_username" is a username derived from the 408 * initiator name or explicitly requested by the initiator 409 * application.> 410 */ 411 ... 412 413 if (authorize_gss_client(src_name, requested_username)) { 414 /* 415 * For Unix-type platforms this may mean calling setuid() and 416 * it may or may not also mean setting/unsetting such 417 * environment variables as KRB5CCNAME and what not. 418 */ 419 if (change_user_context(requested_username)) 420 (void) gss_store_creds(&minor_status, deleg_cred, 421 GSS_C_INITIATE, actual_mech, 422 0, 1, NULL, NULL); 423 } 424 else ... 425 } 426 else ... 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446Williams Expires August 15, 2005 [Page 8] 447 448Internet-Draft GSS_Store_cred() February 2005 449 450 4516. Security considerations 452 453 Acceptor applications MUST only store delegated credentials into 454 appropriate credential stores and only after proper authorization of 455 the authenticated initiator principal to the requested service(s). 456 457 Acceptor applications that have no use for delegated credentials MUST 458 release them (such acceptor applications that use the GSS-API 459 C-Bindings may simply provide a NULL value for the 460 delegated_cred_handle argument to gss_accept_sec_context()). 461 4627 Normative 463 464 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 465 Requirement Levels", BCP 14, RFC 2119, March 1997. 466 467 [RFC2743] Linn, J., "Generic Security Service Application Program 468 Interface Version 2, Update 1", RFC 2743, January 2000. 469 470 [RFC2744] Wray, J., "Generic Security Service API Version 2 : 471 C-bindings", RFC 2744, January 2000. 472 473 474Author's Address 475 476 Nicolas Williams 477 Sun Microsystems 478 5300 Riata Trace Ct 479 Austin, TX 78727 480 US 481 482 EMail: Nicolas.Williams@sun.com 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502Williams Expires August 15, 2005 [Page 9] 503 504Internet-Draft GSS_Store_cred() February 2005 505 506 507Intellectual Property Statement 508 509 The IETF takes no position regarding the validity or scope of any 510 Intellectual Property Rights or other rights that might be claimed to 511 pertain to the implementation or use of the technology described in 512 this document or the extent to which any license under such rights 513 might or might not be available; nor does it represent that it has 514 made any independent effort to identify any such rights. Information 515 on the procedures with respect to rights in RFC documents can be 516 found in BCP 78 and BCP 79. 517 518 Copies of IPR disclosures made to the IETF Secretariat and any 519 assurances of licenses to be made available, or the result of an 520 attempt made to obtain a general license or permission for the use of 521 such proprietary rights by implementers or users of this 522 specification can be obtained from the IETF on-line IPR repository at 523 http://www.ietf.org/ipr. 524 525 The IETF invites any interested party to bring to its attention any 526 copyrights, patents or patent applications, or other proprietary 527 rights that may cover technology that may be required to implement 528 this standard. Please address the information to the IETF at 529 ietf-ipr@ietf.org. 530 531 532Disclaimer of Validity 533 534 This document and the information contained herein are provided on an 535 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 536 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET 537 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, 538 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE 539 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 540 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 541 542 543Copyright Statement 544 545 Copyright (C) The Internet Society (2005). This document is subject 546 to the rights, licenses and restrictions contained in BCP 78, and 547 except as set forth therein, the authors retain all their rights. 548 549 550Acknowledgment 551 552 Funding for the RFC Editor function is currently provided by the 553 Internet Society. 554 555 556 557 558Williams Expires August 15, 2005 [Page 10] 559 560 561