third_party/heimdal/doc/standardisation/draft-ietf-kitten-gssapi-prf-03.txt

   1 NETWORK WORKING GROUP                                        N. Williams
   2 Internet-Draft                                                       Sun
   3 Expires: November 13, 2005                                  May 12, 2005
   4
   5
   6                   A PRF API extension for the GSS-API
   7                   draft-ietf-kitten-gssapi-prf-03.txt
   8
   9 Status of this Memo
  10
  11    By submitting this Internet-Draft, each author represents that any
  12    applicable patent or other IPR claims of which he or she is aware
  13    have been or will be disclosed, and any of which he or she becomes
  14    aware will be disclosed, in accordance with Section 6 of BCP 79.
  15
  16    Internet-Drafts are working documents of the Internet Engineering
  17    Task Force (IETF), its areas, and its working groups.  Note that
  18    other groups may also distribute working documents as Internet-
  19    Drafts.
  20
  21    Internet-Drafts are draft documents valid for a maximum of six months
  22    and may be updated, replaced, or obsoleted by other documents at any
  23    time.  It is inappropriate to use Internet-Drafts as reference
  24    material or to cite them other than as "work in progress."
  25
  26    The list of current Internet-Drafts can be accessed at
  27    http://www.ietf.org/ietf/1id-abstracts.txt.
  28
  29    The list of Internet-Draft Shadow Directories can be accessed at
  30    http://www.ietf.org/shadow.html.
  31
  32    This Internet-Draft will expire on November 13, 2005.
  33
  34 Copyright Notice
  35
  36    Copyright (C) The Internet Society (2005).
  37
  38 Abstract
  39
  40    This document defines a Pseudo-Random Function (PRF) extension to the
  41    Generic Security Service Application Programming Interface (GSS-API)
  42    for keying application protocols given an established GSS-API
  43    security context.  The primary intended use of this function is to
  44    key secure session layers that don't or cannot use GSS-API per-
  45    message MIC (message integrity check) and wrap tokens for session
  46    protection.
  47
  48
  49
  50
  51
  52 Williams                Expires November 13, 2005               [Page 1]
  53 \f
  54 Internet-Draft       A PRF Extension for the GSS-API            May 2005
  55
  56
  57 Table of Contents
  58
  59    1.  Introduction . . . . . . . . . . . . . . . . . . . . . . . . .  3
  60    1.1 Conventions used in this document  . . . . . . . . . . . . . .  3
  61    2.  GSS_Pseudo_random()  . . . . . . . . . . . . . . . . . . . . .  3
  62    2.1 C-Bindings . . . . . . . . . . . . . . . . . . . . . . . . . .  5
  63    2.2 Java Bindings  . . . . . . . . . . . . . . . . . . . . . . . .  6
  64    3.  IANA Considerations  . . . . . . . . . . . . . . . . . . . . .  6
  65    4.  Security Considerations  . . . . . . . . . . . . . . . . . . .  6
  66    5.  References . . . . . . . . . . . . . . . . . . . . . . . . . .  7
  67    5.1 Normative References . . . . . . . . . . . . . . . . . . . . .  7
  68    5.2 Informative References . . . . . . . . . . . . . . . . . . . .  7
  69        Author's Address . . . . . . . . . . . . . . . . . . . . . . .  7
  70        Intellectual Property and Copyright Statements . . . . . . . .  8
  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 Williams                Expires November 13, 2005               [Page 2]
 109 \f
 110 Internet-Draft       A PRF Extension for the GSS-API            May 2005
 111
 112
 113 1.  Introduction
 114
 115    A need has arisen for users of the GSS-API to key applications'
 116    cryptographic protocols using established GSS-API security contexts.
 117    Such applications can use the GSS-API for authentication, but not for
 118    transport security (for whatever reasons), and since the GSS-API does
 119    not provide a method for obtaining keying material from established
 120    security contexts such applications cannot make effective use of the
 121    GSS-API.
 122
 123    To address this need we define a pseudo-random function (PRF)
 124    extension to the GSS-API.
 125
 126 1.1  Conventions used in this document
 127
 128    The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
 129    "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
 130    document are to be interpreted as described in [RFC2119].
 131
 132 2.  GSS_Pseudo_random()
 133
 134    Inputs:
 135
 136
 137    o  context CONTEXT handle,
 138
 139    o  prf_key INTEGER,
 140
 141    o  prf_in OCTET STRING,
 142
 143    o  desired_output_len INTEGER
 144
 145    Outputs:
 146
 147
 148    o  major_status INTEGER,
 149
 150    o  minor_status INTEGER,
 151
 152    o  prf_out OCTET STRING
 153
 154    Return major_status codes:
 155
 156    o  GSS_S_COMPLETE indicates no error.
 157
 158    o  GSS_S_NO_CONTEXT indicates that a null context has been provided
 159       as input.
 160
 161
 162
 163
 164 Williams                Expires November 13, 2005               [Page 3]
 165 \f
 166 Internet-Draft       A PRF Extension for the GSS-API            May 2005
 167
 168
 169    o  GSS_S_CONTEXT_EXPIRED indicates that an expired context has been
 170       provided as input.
 171
 172    o  GSS_S_UNAVAILABLE indicates that the mechanism lacks support for
 173       this function or, if the security context is not fully
 174       established, that the context is not ready to compute the PRF with
 175       the given prf_key, or that the given prf_key is not available.
 176
 177    o  GSS_S_FAILURE indicates general failure, possibly due to the given
 178       input data being too large or of zero length, or due to the
 179       desired_output_len being zero; the minor status code may provide
 180       additional information.
 181
 182    This function applies the established context's mechanism's keyed
 183    pseudo-random function (PRF) to the input data ('prf_in'), keyed with
 184    key material associated with the given security context and
 185    identified by 'prf_key', and outputs the resulting octet string
 186    ('prf_out') of desired_output_len length.
 187
 188    The minimum input data length is one octet.
 189
 190    Mechanisms MUST be able to consume all the provided prf_in input data
 191    that is 2^14 or fewer octets.
 192
 193    If a mechanism cannot consume as much input data as provided by the
 194    caller, then GSS_Pseudo_random() MUST return GSS_S_FAILURE.
 195
 196    The minimum desired_output_len is one.
 197
 198    Mechanisms MUST be able to output at least up to 2^14 octets.
 199
 200    If the implementation cannot produce the desired output due to lack
 201    of resources then it MUST output what it can and still return
 202    GSS_S_COMPLETE.
 203
 204    The prf_key can take on the following values: GSS_C_PRF_KEY_FULL,
 205    GSS_C_PRF_KEY_PARTIAL or mechanism-specific values, if any.  This
 206    parameter is intended to distinguish between the best cryptographic
 207    keys that may be available only after full security context
 208    establishment and keys that may be available prior to full security
 209    context establishment.  For some mechanisms, or contexts, those two
 210    prf_key values MAY refer to the same cryptographic keys; for
 211    mechanisms like the Kerberos V GSS-API mechanism [RFC1964] where one
 212    peer may assert a key that may be considered better than the others
 213    they MAY be different keys.
 214
 215    GSS_C_PRF_KEY_PARTIAL corresponds to a key that would be have been
 216    used while the security context was partially established, even if it
 217
 218
 219
 220 Williams                Expires November 13, 2005               [Page 4]
 221 \f
 222 Internet-Draft       A PRF Extension for the GSS-API            May 2005
 223
 224
 225    is fully established when GSS_Pseudo_random() is actually called.
 226    Mechanism-specific prf_key values are intended to refer to any other
 227    keys that may be available.
 228
 229    The GSS_C_PRF_KEY_FULL value corresponds to the best key available
 230    for fully-established security contexts.
 231
 232    GSS_Pseudo_random() has the following properties:
 233
 234    o  its output string MUST be a pseudo-random function [GGM1] [GGM2]
 235       of the input keyed with key material from the given security
 236       context -- the chances of getting the same output given different
 237       input parameters should be exponentially small.
 238
 239    o  when successfully applied to the same inputs by an initiator and
 240       acceptor using the same security context, it MUST produce the
 241       _same results_ for both, the initiator and acceptor, even if
 242       called multiple times (as long as the security context is not
 243       expired).
 244
 245    o  upon full establishment of a security context all cryptographic
 246       keys and/or negotiations used for computing the PRF with any
 247       prf_key MUST be authenticated (mutually, if mutual authentication
 248       is in effect for the given security context).
 249
 250    o  the outputs of the mechanism's GSS_Pseudo_random() (for different
 251       inputs) and its per-message tokens for the given security context
 252       MUST be "cryptographically separate;" in other words, it must not
 253       be feasible to recover key material for one mechanism operation or
 254       transform its tokens and PRF outputs from one to the other given
 255       only said tokens and PRF outputs.  [This is a fancy way of saying
 256       that key derivation and strong cryptographic operations and
 257       constructions must be used.]
 258
 259    o  as implied by the above requirement, it MUST NOT be possible to
 260       access any raw keys of a security context through
 261       GSS_Pseudo_random(), no matter what inputs are given.
 262
 263    Mechanisms MAY limit the output of the PRF, possibly in ways related
 264    to the types of cryptographic keys available for the PRF function,
 265    thus the prf_out output of GSS_Pseudo_random() MAY be smaller than
 266    requested.
 267
 268 2.1  C-Bindings
 269
 270    #define GSS_C_PRF_KEY_FULL 0
 271    #define GSS_C_PRF_KEY_PARTIAL 1
 272
 273
 274
 275
 276 Williams                Expires November 13, 2005               [Page 5]
 277 \f
 278 Internet-Draft       A PRF Extension for the GSS-API            May 2005
 279
 280
 281    OM_uint32 gss_pseudo_random(
 282      OM_uint32                     *minor_status,
 283      gss_ctx_id_t                  context,
 284      int                           prf_key,
 285      const gss_buffer_t            prf_in,
 286      ssize_t                       desired_output_len,
 287      gss_buffer_t                  prf_out
 288    );
 289
 290    Additional major status codes for the C-bindings:
 291
 292    o  GSS_S_CALL_INACCESSIBLE_READ
 293
 294    o  GSS_S_CALL_INACCESSIBLE_WRITE
 295
 296    See [RFC2744].
 297
 298 2.2  Java Bindings
 299
 300    For Java GSS_Pseudo_random() maps to a GSSContext method, 'prf':
 301
 302    public static final int GSS_C_PRF_KEY_FULL = 0
 303    public static final int GSS_C_PRF_KEY_PARTIAL = 1
 304
 305    public byte[] prf(int prf_key, byte inBuf[], int outlen)
 306       throws GSSException
 307
 308    See [RFC2853].
 309
 310 3.  IANA Considerations
 311
 312    This document has no IANA considerations currently.  If and when a
 313    relevant IANA registry of GSS-API symbols is created then the generic
 314    and language-specific function names, constant names and constant
 315    values described above should be added to such a registry.
 316
 317 4.  Security Considerations
 318
 319    Care should be taken in properly designing a mechanism's PRF
 320    function.
 321
 322    GSS mechanisms' PRF functions should use a key derived from contexts'
 323    authenticated session keys and should preserve the forward security
 324    properties of the mechanisms' key exchanges.
 325
 326    Some mechanisms may support the GSS PRF function with security
 327    contexts that are not fully established, but applications MUST assume
 328    that authentication, mutual or otherwise, has not completed until the
 329
 330
 331
 332 Williams                Expires November 13, 2005               [Page 6]
 333 \f
 334 Internet-Draft       A PRF Extension for the GSS-API            May 2005
 335
 336
 337    security context is fully established.
 338
 339    Callers of GSS_Pseudo_random() should avoid accidentally calling it
 340    with the same inputs.  One useful technique is to prepend to the
 341    prf_in input string, by convention, a string indicating the intended
 342    purpose of the PRF output in such a way that unique contexts in which
 343    the function is called yield unique inputs to it.
 344
 345 5.  References
 346
 347 5.1  Normative References
 348
 349    [GGM1]     Goldreich, O., Goldwasser, S., and S. Micali, "How to
 350               Construct Random Functions", October 1986.
 351
 352    [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
 353               Requirement Levels", BCP 14, RFC 2119, March 1997.
 354
 355    [RFC2743]  Linn, J., "Generic Security Service Application Program
 356               Interface Version 2, Update 1", RFC 2743, January 2000.
 357
 358    [RFC2744]  Wray, J., "Generic Security Service API Version 2 :
 359               C-bindings", RFC 2744, January 2000.
 360
 361    [RFC2853]  Kabat, J. and M. Upadhyay, "Generic Security Service API
 362               Version 2 : Java Bindings", RFC 2853, June 2000.
 363
 364 5.2  Informative References
 365
 366    [GGM2]     Goldreich, O., Goldwasser, S., and S. Micali, "On the
 367               Cryptographic Applications of Random Functions", 1985.
 368
 369    [RFC1750]  Eastlake, D., Crocker, S., and J. Schiller, "Randomness
 370               Recommendations for Security", RFC 1750, December 1994.
 371
 372    [RFC1964]  Linn, J., "The Kerberos Version 5 GSS-API Mechanism",
 373               RFC 1964, June 1996.
 374
 375
 376 Author's Address
 377
 378    Nicolas Williams
 379    Sun Microsystems
 380    5300 Riata Trace Ct
 381    Austin, TX  78727
 382    US
 383
 384    Email: Nicolas.Williams@sun.com
 385
 386
 387
 388 Williams                Expires November 13, 2005               [Page 7]
 389 \f
 390 Internet-Draft       A PRF Extension for the GSS-API            May 2005
 391
 392
 393 Intellectual Property Statement
 394
 395    The IETF takes no position regarding the validity or scope of any
 396    Intellectual Property Rights or other rights that might be claimed to
 397    pertain to the implementation or use of the technology described in
 398    this document or the extent to which any license under such rights
 399    might or might not be available; nor does it represent that it has
 400    made any independent effort to identify any such rights.  Information
 401    on the procedures with respect to rights in RFC documents can be
 402    found in BCP 78 and BCP 79.
 403
 404    Copies of IPR disclosures made to the IETF Secretariat and any
 405    assurances of licenses to be made available, or the result of an
 406    attempt made to obtain a general license or permission for the use of
 407    such proprietary rights by implementers or users of this
 408    specification can be obtained from the IETF on-line IPR repository at
 409    http://www.ietf.org/ipr.
 410
 411    The IETF invites any interested party to bring to its attention any
 412    copyrights, patents or patent applications, or other proprietary
 413    rights that may cover technology that may be required to implement
 414    this standard.  Please address the information to the IETF at
 415    ietf-ipr@ietf.org.
 416
 417
 418 Disclaimer of Validity
 419
 420    This document and the information contained herein are provided on an
 421    "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
 422    OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
 423    ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
 424    INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
 425    INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
 426    WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
 427
 428
 429 Copyright Statement
 430
 431    Copyright (C) The Internet Society (2005).  This document is subject
 432    to the rights, licenses and restrictions contained in BCP 78, and
 433    except as set forth therein, the authors retain all their rights.
 434
 435
 436 Acknowledgment
 437
 438    Funding for the RFC Editor function is currently provided by the
 439    Internet Society.
 440
 441
 442
 443
 444 Williams                Expires November 13, 2005               [Page 8]
 445 \f
 446