third_party/heimdal/doc/standardisation/draft-ietf-kitten-gssapi-store-cred-00.txt

   1
   2 NETWORK WORKING GROUP                                        N. Williams
   3 Internet-Draft                                                       Sun
   4 Expires: 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
  10 Status 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
  35 Copyright Notice
  36
  37    Copyright (C) The Internet Society (2005).  All Rights Reserved.
  38
  39 Abstract
  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
  54 Williams                Expires August 15, 2005                 [Page 1]
  55 \f
  56 Internet-Draft              GSS_Store_cred()               February 2005
  57
  58
  59 Table 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
 110 Williams                Expires August 15, 2005                 [Page 2]
 111 \f
 112 Internet-Draft              GSS_Store_cred()               February 2005
 113
 114
 115 1.  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
 166 Williams                Expires August 15, 2005                 [Page 3]
 167 \f
 168 Internet-Draft              GSS_Store_cred()               February 2005
 169
 170
 171 2.  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
 222 Williams                Expires August 15, 2005                 [Page 4]
 223 \f
 224 Internet-Draft              GSS_Store_cred()               February 2005
 225
 226
 227 3.  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
 278 Williams                Expires August 15, 2005                 [Page 5]
 279 \f
 280 Internet-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
 334 Williams                Expires August 15, 2005                 [Page 6]
 335 \f
 336 Internet-Draft              GSS_Store_cred()               February 2005
 337
 338
 339 4.  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
 390 Williams                Expires August 15, 2005                 [Page 7]
 391 \f
 392 Internet-Draft              GSS_Store_cred()               February 2005
 393
 394
 395 5.   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
 446 Williams                Expires August 15, 2005                 [Page 8]
 447 \f
 448 Internet-Draft              GSS_Store_cred()               February 2005
 449
 450
 451 6.  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
 462 7  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
 474 Author'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
 502 Williams                Expires August 15, 2005                 [Page 9]
 503 \f
 504 Internet-Draft              GSS_Store_cred()               February 2005
 505
 506
 507 Intellectual 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
 532 Disclaimer 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
 543 Copyright 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
 550 Acknowledgment
 551
 552    Funding for the RFC Editor function is currently provided by the
 553    Internet Society.
 554
 555
 556
 557
 558 Williams                Expires August 15, 2005                [Page 10]
 559 \f
 560