doc/standardisation/rfc4401.txt

   1
   2
   3
   4
   5
   6
   7 Network Working Group                                        N. Williams
   8 Request for Comments: 4401                              Sun Microsystems
   9 Category: Standards Track                                  February 2006
  10
  11
  12          A Pseudo-Random Function (PRF) API Extension for the
  13     Generic Security Service Application Program Interface (GSS-API)
  14
  15 Status of This Memo
  16
  17    This document specifies an Internet standards track protocol for the
  18    Internet community, and requests discussion and suggestions for
  19    improvements.  Please refer to the current edition of the "Internet
  20    Official Protocol Standards" (STD 1) for the standardization state
  21    and status of this protocol.  Distribution of this memo is unlimited.
  22
  23 Copyright Notice
  24
  25    Copyright (C) The Internet Society (2006).
  26
  27 Abstract
  28
  29    This document defines a Pseudo-Random Function (PRF) extension to the
  30    Generic Security Service Application Program Interface (GSS-API) for
  31    keying application protocols given an established GSS-API security
  32    context.  The primary intended use of this function is to key secure
  33    session layers that do not or cannot use GSS-API per-message message
  34    integrity check (MIC) and wrap tokens for session protection.
  35
  36 Table of Contents
  37
  38    1. Introduction ....................................................2
  39       1.1. Conventions Used in This Document ..........................2
  40    2. GSS_Pseudo_random() .............................................2
  41       2.1. C-Bindings .................................................5
  42    3. IANA Considerations .............................................5
  43    4. Security Considerations .........................................5
  44    5. References ......................................................7
  45       5.1. Normative References .......................................7
  46       5.2. Informative References .....................................7
  47
  48
  49
  50
  51
  52
  53
  54
  55
  56
  57
  58 Williams                    Standards Track                     [Page 1]
  59 \f
  60 RFC 4401            A PRF Extension for the GSS-API        February 2006
  61
  62
  63 1.  Introduction
  64
  65    A need has arisen for users of the GSS-API to key applications'
  66    cryptographic protocols using established GSS-API security contexts.
  67    Such applications can use the GSS-API [RFC2743] for authentication,
  68    but not for transport security (for whatever reasons), and since the
  69    GSS-API does not provide a method for obtaining keying material from
  70    established security contexts, such applications cannot make
  71    effective use of the GSS-API.
  72
  73    To address this need, we define a pseudo-random function (PRF)
  74    extension to the GSS-API.
  75
  76    Though this document specifies an abstract API as an extension to the
  77    GSS-API version 2, update 1, and though it specifies the bindings of
  78    this extension for the C programming language, it does not specify a
  79    revision of the GSS-API and so does not address the matter of how
  80    portable applications detect support for and ensure access to this
  81    extension.  We defer this matter to an expected, comprehensive update
  82    to the GSS-API.
  83
  84 1.1.  Conventions Used in This Document
  85
  86    The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
  87    "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
  88    document are to be interpreted as described in [RFC2119].
  89
  90 2.  GSS_Pseudo_random()
  91
  92    Inputs:
  93
  94    o  context CONTEXT handle,
  95
  96    o  prf_key INTEGER,
  97
  98    o  prf_in OCTET STRING,
  99
 100    o  desired_output_len INTEGER
 101
 102
 103    Outputs:
 104
 105    o  major_status INTEGER,
 106
 107    o  minor_status INTEGER,
 108
 109    o  prf_out OCTET STRING
 110
 111
 112
 113
 114 Williams                    Standards Track                     [Page 2]
 115 \f
 116 RFC 4401            A PRF Extension for the GSS-API        February 2006
 117
 118
 119    Return major_status codes:
 120
 121    o  GSS_S_COMPLETE indicates no error.
 122
 123    o  GSS_S_NO_CONTEXT indicates that a null context has been provided
 124       as input.
 125
 126    o  GSS_S_CONTEXT_EXPIRED indicates that an expired context has been
 127       provided as input.
 128
 129    o  GSS_S_UNAVAILABLE indicates that the mechanism lacks support for
 130       this function or, if the security context is not fully
 131       established, that the context is not ready to compute the PRF with
 132       the given prf_key, or that the given prf_key is not available.
 133
 134    o  GSS_S_FAILURE indicates general failure, possibly due to the given
 135       input data being too large or of zero length, or due to the
 136       desired_output_len being zero; the minor status code may provide
 137       additional information.
 138
 139    This function applies the established context's mechanism's keyed
 140    pseudo-random function (PRF) to the input data ('prf_in'), keyed with
 141    key material associated with the given security context and
 142    identified by 'prf_key', and outputs the resulting octet string
 143    ('prf_out') of desired_output_len length.
 144
 145    The minimum input data length is one octet.
 146
 147    Mechanisms MUST be able to consume all the provided prf_in input data
 148    that is 2^14 or fewer octets.
 149
 150    If a mechanism cannot consume as much input data as provided by the
 151    caller, then GSS_Pseudo_random() MUST return GSS_S_FAILURE.
 152
 153    The minimum desired_output_len is one.
 154
 155    Mechanisms MUST be able to output at least up to 2^14 octets.
 156
 157    If the implementation cannot produce the desired output due to lack
 158    of resources, then it MUST return GSS_S_FAILURE and MUST set a
 159    suitable minor status code.
 160
 161    The prf_key can take on the following values: GSS_C_PRF_KEY_FULL,
 162    GSS_C_PRF_KEY_PARTIAL, or mechanism-specific values, if any.  This
 163    parameter is intended to distinguish between the best cryptographic
 164    keys that may be available only after full security context
 165    establishment and keys that may be available prior to full security
 166    context establishment.  For some mechanisms, or contexts, those two
 167
 168
 169
 170 Williams                    Standards Track                     [Page 3]
 171 \f
 172 RFC 4401            A PRF Extension for the GSS-API        February 2006
 173
 174
 175    prf_key values MAY refer to the same cryptographic keys; for
 176    mechanisms like the Kerberos V GSS-API mechanism [RFC1964] where one
 177    peer may assert a key that may be considered better than the others
 178    they MAY be different keys.
 179
 180    GSS_C_PRF_KEY_PARTIAL corresponds to a key that would have been used
 181    while the security context was partially established, even if it is
 182    fully established when GSS_Pseudo_random() is actually called.
 183    Mechanism-specific prf_key values are intended to refer to any other
 184    keys that may be available.
 185
 186    The GSS_C_PRF_KEY_FULL value corresponds to the best key available
 187    for fully-established security contexts.
 188
 189    GSS_Pseudo_random() has the following properties:
 190
 191    o  its output string MUST be a pseudo-random function [GGM1] [GGM2]
 192       of the input keyed with key material from the given security
 193       context -- the chances of getting the same output given different
 194       input parameters should be exponentially small.
 195
 196    o  when successfully applied to the same inputs by an initiator and
 197       acceptor using the same security context, it MUST produce the
 198       _same results_ for both, the initiator and acceptor, even if
 199       called multiple times (as long as the security context is not
 200       expired).
 201
 202    o  upon full establishment of a security context, all cryptographic
 203       keys and/or negotiations used for computing the PRF with any
 204       prf_key MUST be authenticated (mutually, if mutual authentication
 205       is in effect for the given security context).
 206
 207    o  the outputs of the mechanism's GSS_Pseudo_random() (for different
 208       inputs) and its per-message tokens for the given security context
 209       MUST be "cryptographically separate"; in other words, it must not
 210       be feasible to recover key material for one mechanism operation or
 211       transform its tokens and PRF outputs from one to the other given
 212       only said tokens and PRF outputs.  (This is a fancy way of saying
 213       that key derivation and strong cryptographic operations and
 214       constructions must be used.)
 215
 216    o  as implied by the above requirement, it MUST NOT be possible to
 217       access any raw keys of a security context through
 218       GSS_Pseudo_random(), no matter what inputs are given.
 219
 220
 221
 222
 223
 224
 225
 226 Williams                    Standards Track                     [Page 4]
 227 \f
 228 RFC 4401            A PRF Extension for the GSS-API        February 2006
 229
 230
 231 2.1.  C-Bindings
 232
 233    #define GSS_C_PRF_KEY_FULL 0
 234    #define GSS_C_PRF_KEY_PARTIAL 1
 235
 236    OM_uint32 gss_pseudo_random(
 237      OM_uint32                     *minor_status,
 238      gss_ctx_id_t                  context,
 239      int                           prf_key,
 240      const gss_buffer_t            prf_in,
 241      ssize_t                       desired_output_len,
 242      gss_buffer_t                  prf_out
 243    );
 244
 245    Additional major status codes for the C-bindings:
 246
 247    o  GSS_S_CALL_INACCESSIBLE_READ
 248
 249    o  GSS_S_CALL_INACCESSIBLE_WRITE
 250
 251    See [RFC2744].
 252
 253 3.  IANA Considerations
 254
 255    This document has no IANA considerations currently.  If and when a
 256    relevant IANA registry of GSS-API symbols is created, then the
 257    generic and language-specific function names, constant names, and
 258    constant values described above should be added to such a registry.
 259
 260 4.  Security Considerations
 261
 262    Care should be taken in properly designing a mechanism's PRF
 263    function.
 264
 265    GSS mechanisms' PRF functions should use a key derived from contexts'
 266    authenticated session keys and should preserve the forward security
 267    properties of the mechanisms' key exchanges.
 268
 269    Some mechanisms may support the GSS PRF function with security
 270    contexts that are not fully established, but applications MUST assume
 271    that authentication, mutual or otherwise, has not completed until the
 272    security context is fully established.
 273
 274    Callers of GSS_Pseudo_random() should avoid accidentally calling it
 275    with the same inputs.  One useful technique is to prepend to the
 276    prf_in input string, by convention, a string indicating the intended
 277    purpose of the PRF output in such a way that unique contexts in which
 278    the function is called yield unique inputs to it.
 279
 280
 281
 282 Williams                    Standards Track                     [Page 5]
 283 \f
 284 RFC 4401            A PRF Extension for the GSS-API        February 2006
 285
 286
 287    Pseudo-random functions are, by their nature, capable of producing
 288    only limited amounts of cryptographically secure output.  The exact
 289    amount of output that one can safely use, unfortunately, varies from
 290    one PRF to another (which prevents us from recommending specific
 291    numbers).  Because of this, we recommend that unless you really know
 292    what you are doing (i.e., you are a cryptographer and are qualified
 293    to pass judgement on cryptographic functions in areas of period,
 294    presence of short cycles, etc.), you limit the amount of the PRF
 295    output used to the necessary minimum.  See [RFC4086] for more
 296    information about "Randomness Requirements for Security".
 297
 298    For some mechanisms, the computational cost of computing
 299    GSS_Pseudo_random() may increase significantly as the length of the
 300    prf_in data and/or the desired_output_length increase.  This means
 301    that if an application can be tricked into providing very large input
 302    octet strings and requesting very long output octet strings, then
 303    that may constitute a denial of service attack on the application;
 304    therefore, applications SHOULD place appropriate limits on the size
 305    of any input octet strings received from their peers without
 306    integrity protection.
 307
 308
 309
 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
 335
 336
 337
 338 Williams                    Standards Track                     [Page 6]
 339 \f
 340 RFC 4401            A PRF Extension for the GSS-API        February 2006
 341
 342
 343 5.  References
 344
 345 5.1.  Normative References
 346
 347    [GGM1]     Goldreich, O., Goldwasser, S., and S. Micali, "How to
 348               Construct Random Functions", Journal of the ACM, October
 349               1986.
 350
 351    [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
 352               Requirement Levels", BCP 14, RFC 2119, March 1997.
 353
 354    [RFC2743]  Linn, J., "Generic Security Service Application Program
 355               Interface Version 2, Update 1", RFC 2743, January 2000.
 356
 357    [RFC2744]  Wray, J., "Generic Security Service API Version 2 :
 358               C-bindings", RFC 2744, January 2000.
 359
 360 5.2.  Informative References
 361
 362    [GGM2]     Goldreich, O., Goldwasser, S., and S. Micali, "On the
 363               Cryptographic Applications of Random Functions",
 364               Proceedings of CRYPTO 84 on Advances in cryptology, 1985.
 365
 366    [RFC4086]  Eastlake, D., 3rd, Schiller, J., and S. Crocker,
 367               "Randomness Requirements for Security", BCP 106, RFC 4086,
 368               June 2005.
 369
 370    [RFC1964]  Linn, J., "The Kerberos Version 5 GSS-API Mechanism", RFC
 371               1964, June 1996.
 372
 373 Author's Address
 374
 375    Nicolas Williams
 376    Sun Microsystems
 377    5300 Riata Trace Ct
 378    Austin, TX  78727
 379    US
 380
 381    EMail: Nicolas.Williams@sun.com
 382
 383
 384
 385
 386
 387
 388
 389
 390
 391
 392
 393
 394 Williams                    Standards Track                     [Page 7]
 395 \f
 396 RFC 4401            A PRF Extension for the GSS-API        February 2006
 397
 398
 399 Full Copyright Statement
 400
 401    Copyright (C) The Internet Society (2006).
 402
 403    This document is subject to the rights, licenses and restrictions
 404    contained in BCP 78, and except as set forth therein, the authors
 405    retain all their rights.
 406
 407    This document and the information contained herein are provided on an
 408    "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
 409    OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
 410    ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
 411    INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
 412    INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
 413    WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
 414
 415 Intellectual Property
 416
 417    The IETF takes no position regarding the validity or scope of any
 418    Intellectual Property Rights or other rights that might be claimed to
 419    pertain to the implementation or use of the technology described in
 420    this document or the extent to which any license under such rights
 421    might or might not be available; nor does it represent that it has
 422    made any independent effort to identify any such rights.  Information
 423    on the procedures with respect to rights in RFC documents can be
 424    found in BCP 78 and BCP 79.
 425
 426    Copies of IPR disclosures made to the IETF Secretariat and any
 427    assurances of licenses to be made available, or the result of an
 428    attempt made to obtain a general license or permission for the use of
 429    such proprietary rights by implementers or users of this
 430    specification can be obtained from the IETF on-line IPR repository at
 431    http://www.ietf.org/ipr.
 432
 433    The IETF invites any interested party to bring to its attention any
 434    copyrights, patents or patent applications, or other proprietary
 435    rights that may cover technology that may be required to implement
 436    this standard.  Please address the information to the IETF at
 437    ietf-ipr@ietf.org.
 438
 439 Acknowledgement
 440
 441    Funding for the RFC Editor function is provided by the IETF
 442    Administrative Support Activity (IASA).
 443
 444
 445
 446
 447
 448
 449
 450 Williams                    Standards Track                     [Page 8]
 451 \f