1 2 3 4NETWORK WORKING GROUP N. Williams 5Internet-Draft Sun 6Intended status: Informational October 19, 2006 7Expires: April 22, 2007 8 9 10 GSS-API Extension for Storing Delegated Credentials 11 draft-ietf-kitten-gssapi-store-cred-02.txt 12 13Status of this Memo 14 15 By submitting this Internet-Draft, each author represents that any 16 applicable patent or other IPR claims of which he or she is aware 17 have been or will be disclosed, and any of which he or she becomes 18 aware will be disclosed, in accordance with Section 6 of BCP 79. 19 20 Internet-Drafts are working documents of the Internet Engineering 21 Task Force (IETF), its areas, and its working groups. Note that 22 other groups may also distribute working documents as Internet- 23 Drafts. 24 25 Internet-Drafts are draft documents valid for a maximum of six months 26 and may be updated, replaced, or obsoleted by other documents at any 27 time. It is inappropriate to use Internet-Drafts as reference 28 material or to cite them other than as "work in progress." 29 30 The list of current Internet-Drafts can be accessed at 31 http://www.ietf.org/ietf/1id-abstracts.txt. 32 33 The list of Internet-Draft Shadow Directories can be accessed at 34 http://www.ietf.org/shadow.html. 35 36 This Internet-Draft will expire on April 22, 2007. 37 38Copyright Notice 39 40 Copyright (C) The Internet Society (2006). 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55Williams Expires April 22, 2007 [Page 1] 56 57Internet-Draft GSS_Store_cred() October 2006 58 59 60Abstract 61 62 This document defines a new function for the GSS-API which allows 63 applications to store delegated (and other) credentials in the 64 implicit GSS-API credential store. This is needed for GSS-API 65 applications to use delegated credentials as they would use other 66 credentials. 67 68 69Table of Contents 70 71 1. Conventions used in this document . . . . . . . . . . . . . . 3 72 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 73 3. GSS_Store_cred() . . . . . . . . . . . . . . . . . . . . . . . 5 74 4. C-Bindings . . . . . . . . . . . . . . . . . . . . . . . . . . 7 75 5. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 76 6. Security considerations . . . . . . . . . . . . . . . . . . . 9 77 7. Normative References . . . . . . . . . . . . . . . . . . . . . 10 78 Author's Address . . . . . . . . . . . . . . . . . . . . . . . 11 79 Intellectual Property and Copyright Statements . . . . . . . . 12 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 22, 2007 [Page 2] 112 113Internet-Draft GSS_Store_cred() October 2006 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 22, 2007 [Page 3] 168 169Internet-Draft GSS_Store_cred() October 2006 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 Applications may be able to change the credential store from which 185 credentials can be acquired, either by changing user contexts (where 186 the applications have the privilege to do so) or by other means 187 (where a user may have multiple credential stores). 188 189 Some GSS-API acceptor applications always change user contexts, after 190 accepting a GSS-API security context and making appropriate 191 authorization checks, to the user context corresponding to the 192 initiator principal name or to a context requested by the initiator. 193 The means by which credential stores are managed are generally beyond 194 the scope of the GSS-API. 195 196 In the case of delegated credential handles however, such credentials 197 do not exist in the acceptor's credential store or in the credential 198 stores of the user contexts to which the acceptor application might 199 change. The GSS-API provides no mechanism by which delegated 200 credential handles can be made available for acquisition through 201 GSS_Acquire_cred()/GSS_Add_cred(). The GSS-API also does not provide 202 any credential import/export interfaces like the GSS-API context 203 import/export interfaces. 204 205 Thus acceptors are limited to making only direct use of delegated 206 credential handles and only with GSS_Init_sec_context(), 207 GSS_Inquire_cred*() and GSS_Release_cred(). This limitation is 208 particularly onerous on Unix systems where a call to exec() to 209 replace the process image obliterates any delegated credentials 210 handle that may exist in that process. 211 212 In order to make delegated credentials generally as useful as 213 credentials that can be acquired with GSS_Acquire_cred() and 214 GSS_Add_cred() a primitive is needed which allows storing of 215 credentials in the implicit credential store. This primitive we call 216 "GSS_Store_cred()." 217 218 219 220 221 222 223Williams Expires April 22, 2007 [Page 4] 224 225Internet-Draft GSS_Store_cred() October 2006 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 22, 2007 [Page 5] 280 281Internet-Draft GSS_Store_cred() October 2006 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 22, 2007 [Page 6] 336 337Internet-Draft GSS_Store_cred() October 2006 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_handle, 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 22, 2007 [Page 7] 392 393Internet-Draft GSS_Store_cred() October 2006 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 -- all 419 * OS-specific details. 420 */ 421 if (change_user_context(requested_username)) 422 (void) gss_store_creds(&minor_status, deleg_cred, 423 GSS_C_INITIATE, actual_mech, 424 0, 1, NULL, NULL); 425 } 426 else ... 427 } 428 else ... 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447Williams Expires April 22, 2007 [Page 8] 448 449Internet-Draft GSS_Store_cred() October 2006 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 463 464 465 466 467 468 469 470 471 472 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 22, 2007 [Page 9] 504 505Internet-Draft GSS_Store_cred() October 2006 506 507 5087. Normative References 509 510 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 511 Requirement Levels", BCP 14, RFC 2119, March 1997. 512 513 [RFC2743] Linn, J., "Generic Security Service Application Program 514 Interface Version 2, Update 1", RFC 2743, January 2000. 515 516 [RFC2744] Wray, J., "Generic Security Service API Version 2 : 517 C-bindings", RFC 2744, January 2000. 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 22, 2007 [Page 10] 560 561Internet-Draft GSS_Store_cred() October 2006 562 563 564Author's Address 565 566 Nicolas Williams 567 Sun Microsystems 568 5300 Riata Trace Ct 569 Austin, TX 78727 570 US 571 572 Email: Nicolas.Williams@sun.com 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615Williams Expires April 22, 2007 [Page 11] 616 617Internet-Draft GSS_Store_cred() October 2006 618 619 620Full Copyright Statement 621 622 Copyright (C) The Internet Society (2006). 623 624 This document is subject to the rights, licenses and restrictions 625 contained in BCP 78, and except as set forth therein, the authors 626 retain all their rights. 627 628 This document and the information contained herein are provided on an 629 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 630 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET 631 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, 632 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE 633 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 634 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 635 636 637Intellectual Property 638 639 The IETF takes no position regarding the validity or scope of any 640 Intellectual Property Rights or other rights that might be claimed to 641 pertain to the implementation or use of the technology described in 642 this document or the extent to which any license under such rights 643 might or might not be available; nor does it represent that it has 644 made any independent effort to identify any such rights. Information 645 on the procedures with respect to rights in RFC documents can be 646 found in BCP 78 and BCP 79. 647 648 Copies of IPR disclosures made to the IETF Secretariat and any 649 assurances of licenses to be made available, or the result of an 650 attempt made to obtain a general license or permission for the use of 651 such proprietary rights by implementers or users of this 652 specification can be obtained from the IETF on-line IPR repository at 653 http://www.ietf.org/ipr. 654 655 The IETF invites any interested party to bring to its attention any 656 copyrights, patents or patent applications, or other proprietary 657 rights that may cover technology that may be required to implement 658 this standard. Please address the information to the IETF at 659 ietf-ipr@ietf.org. 660 661 662Acknowledgment 663 664 Funding for the RFC Editor function is provided by the IETF 665 Administrative Support Activity (IASA). 666 667 668 669 670 671Williams Expires April 22, 2007 [Page 12] 672 673 674