doc/standardisation/rfc5588.txt

   1
   2
   3
   4
   5
   6
   7 Network Working Group                                        N. Williams
   8 Request for Comments: 5588                                           Sun
   9 Category: Standards Track                                      July 2009
  10
  11
  12    Generic Security Service Application Program Interface (GSS-API)
  13               Extension for Storing Delegated Credentials
  14
  15 Abstract
  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
  23 Status 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
  31 Copyright 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
  42 Table 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
  58 Williams                    Standards Track                     [Page 1]
  59 \f
  60 RFC 5588                    GSS_Store_cred()                   July 2009
  61
  62
  63 1.  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
 114 Williams                    Standards Track                     [Page 2]
 115 \f
 116 RFC 5588                    GSS_Store_cred()                   July 2009
 117
 118
 119 2.  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
 125 3.  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
 170 Williams                    Standards Track                     [Page 3]
 171 \f
 172 RFC 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
 226 Williams                    Standards Track                     [Page 4]
 227 \f
 228 RFC 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
 236 4.  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
 282 Williams                    Standards Track                     [Page 5]
 283 \f
 284 RFC 5588                    GSS_Store_cred()                   July 2009
 285
 286
 287 5.  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
 320 6.  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
 338 Williams                    Standards Track                     [Page 6]
 339 \f
 340 RFC 5588                    GSS_Store_cred()                   July 2009
 341
 342
 343 7.  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
 354 Author'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
 394 Williams                    Standards Track                     [Page 7]
 395 \f