1NETWORK WORKING GROUP                                        N. Williams
2Internet-Draft                                                       Sun
3Expires: 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
9Status 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
34Copyright Notice
35
36   Copyright (C) The Internet Society (2005).
37
38Abstract
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
52Williams                Expires November 13, 2005               [Page 1]
53
54Internet-Draft       A PRF Extension for the GSS-API            May 2005
55
56
57Table 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
108Williams                Expires November 13, 2005               [Page 2]
109
110Internet-Draft       A PRF Extension for the GSS-API            May 2005
111
112
1131.  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
1261.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
1322.  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
164Williams                Expires November 13, 2005               [Page 3]
165
166Internet-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
220Williams                Expires November 13, 2005               [Page 4]
221
222Internet-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
2682.1  C-Bindings
269
270   #define GSS_C_PRF_KEY_FULL 0
271   #define GSS_C_PRF_KEY_PARTIAL 1
272
273
274
275
276Williams                Expires November 13, 2005               [Page 5]
277
278Internet-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
2982.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
3103.  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
3174.  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
332Williams                Expires November 13, 2005               [Page 6]
333
334Internet-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
3455.  References
346
3475.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
3645.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
376Author'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
388Williams                Expires November 13, 2005               [Page 7]
389
390Internet-Draft       A PRF Extension for the GSS-API            May 2005
391
392
393Intellectual 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
418Disclaimer 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
429Copyright 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
436Acknowledgment
437
438   Funding for the RFC Editor function is currently provided by the
439   Internet Society.
440
441
442
443
444Williams                Expires November 13, 2005               [Page 8]
445
446
447