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