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