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