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