idnits 2.17.1 draft-ietf-kitten-gssapi-prf-04.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** It looks like you're using RFC 3978 boilerplate. You should update this to the boilerplate described in the IETF Trust License Policy document (see https://trustee.ietf.org/license-info), which is required now. -- Found old boilerplate from RFC 3978, Section 5.1 on line 14. -- Found old boilerplate from RFC 3978, Section 5.5 on line 342. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 319. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 326. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 332. ** This document has an original RFC 3978 Section 5.4 Copyright Line, instead of the newer IETF Trust Copyright according to RFC 4748. ** This document has an original RFC 3978 Section 5.5 Disclaimer, instead of the newer disclaimer which includes the IETF Trust according to RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (June 13, 2005) is 6892 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Unused Reference: 'RFC2743' is defined on line 280, but no explicit reference was found in the text == Unused Reference: 'RFC1750' is defined on line 294, but no explicit reference was found in the text -- Possible downref: Non-RFC (?) normative reference: ref. 'GGM1' ** Obsolete normative reference: RFC 2853 (Obsoleted by RFC 5653) -- Obsolete informational reference (is this intentional?): RFC 1750 (Obsoleted by RFC 4086) Summary: 4 errors (**), 0 flaws (~~), 4 warnings (==), 10 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 NETWORK WORKING GROUP N. Williams 3 Internet-Draft Sun 4 Expires: December 15, 2005 June 13, 2005 6 A PRF API extension for the GSS-API 7 draft-ietf-kitten-gssapi-prf-04.txt 9 Status of this Memo 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. 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. 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." 26 The list of current Internet-Drafts can be accessed at 27 http://www.ietf.org/ietf/1id-abstracts.txt. 29 The list of Internet-Draft Shadow Directories can be accessed at 30 http://www.ietf.org/shadow.html. 32 This Internet-Draft will expire on December 15, 2005. 34 Copyright Notice 36 Copyright (C) The Internet Society (2005). 38 Abstract 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. 48 Table of Contents 50 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 51 1.1 Conventions used in this document . . . . . . . . . . . . . . 3 52 2. GSS_Pseudo_random() . . . . . . . . . . . . . . . . . . . . . 3 53 2.1 C-Bindings . . . . . . . . . . . . . . . . . . . . . . . . . . 5 54 2.2 Java Bindings . . . . . . . . . . . . . . . . . . . . . . . . 6 55 3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6 56 4. Security Considerations . . . . . . . . . . . . . . . . . . . 6 57 5. References . . . . . . . . . . . . . . . . . . . . . . . . . . 7 58 5.1 Normative References . . . . . . . . . . . . . . . . . . . . . 7 59 5.2 Informative References . . . . . . . . . . . . . . . . . . . . 7 60 Author's Address . . . . . . . . . . . . . . . . . . . . . . . 8 61 Intellectual Property and Copyright Statements . . . . . . . . 9 63 1. Introduction 65 A need has arisen for users of the GSS-API to key applications' 66 cryptographic protocols using established GSS-API security contexts. 67 Such applications can use the GSS-API for authentication, but not for 68 transport security (for whatever reasons), and since the GSS-API does 69 not provide a method for obtaining keying material from established 70 security contexts such applications cannot make effective use of the 71 GSS-API. 73 To address this need we define a pseudo-random function (PRF) 74 extension to the GSS-API. 76 1.1 Conventions used in this document 78 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 79 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 80 document are to be interpreted as described in [RFC2119]. 82 2. GSS_Pseudo_random() 84 Inputs: 86 o context CONTEXT handle, 88 o prf_key INTEGER, 90 o prf_in OCTET STRING, 92 o desired_output_len INTEGER 94 Outputs: 96 o major_status INTEGER, 98 o minor_status INTEGER, 100 o prf_out OCTET STRING 102 Return major_status codes: 104 o GSS_S_COMPLETE indicates no error. 106 o GSS_S_NO_CONTEXT indicates that a null context has been provided 107 as input. 109 o GSS_S_CONTEXT_EXPIRED indicates that an expired context has been 110 provided as input. 112 o GSS_S_UNAVAILABLE indicates that the mechanism lacks support for 113 this function or, if the security context is not fully 114 established, that the context is not ready to compute the PRF with 115 the given prf_key, or that the given prf_key is not available. 117 o GSS_S_FAILURE indicates general failure, possibly due to the given 118 input data being too large or of zero length, or due to the 119 desired_output_len being zero; the minor status code may provide 120 additional information. 122 This function applies the established context's mechanism's keyed 123 pseudo-random function (PRF) to the input data ('prf_in'), keyed with 124 key material associated with the given security context and 125 identified by 'prf_key', and outputs the resulting octet string 126 ('prf_out') of desired_output_len length. 128 The minimum input data length is one octet. 130 Mechanisms MUST be able to consume all the provided prf_in input data 131 that is 2^14 or fewer octets. 133 If a mechanism cannot consume as much input data as provided by the 134 caller, then GSS_Pseudo_random() MUST return GSS_S_FAILURE. 136 The minimum desired_output_len is one. 138 Mechanisms MUST be able to output at least up to 2^14 octets. 140 If the implementation cannot produce the desired output due to lack 141 of resources then it MUST output what it can and still return 142 GSS_S_COMPLETE. 144 The prf_key can take on the following values: GSS_C_PRF_KEY_FULL, 145 GSS_C_PRF_KEY_PARTIAL or mechanism-specific values, if any. This 146 parameter is intended to distinguish between the best cryptographic 147 keys that may be available only after full security context 148 establishment and keys that may be available prior to full security 149 context establishment. For some mechanisms, or contexts, those two 150 prf_key values MAY refer to the same cryptographic keys; for 151 mechanisms like the Kerberos V GSS-API mechanism [RFC1964] where one 152 peer may assert a key that may be considered better than the others 153 they MAY be different keys. 155 GSS_C_PRF_KEY_PARTIAL corresponds to a key that would be have been 156 used while the security context was partially established, even if it 157 is fully established when GSS_Pseudo_random() is actually called. 158 Mechanism-specific prf_key values are intended to refer to any other 159 keys that may be available. 161 The GSS_C_PRF_KEY_FULL value corresponds to the best key available 162 for fully-established security contexts. 164 GSS_Pseudo_random() has the following properties: 166 o its output string MUST be a pseudo-random function [GGM1] [GGM2] 167 of the input keyed with key material from the given security 168 context -- the chances of getting the same output given different 169 input parameters should be exponentially small. 171 o when successfully applied to the same inputs by an initiator and 172 acceptor using the same security context, it MUST produce the 173 _same results_ for both, the initiator and acceptor, even if 174 called multiple times (as long as the security context is not 175 expired). 177 o upon full establishment of a security context all cryptographic 178 keys and/or negotiations used for computing the PRF with any 179 prf_key MUST be authenticated (mutually, if mutual authentication 180 is in effect for the given security context). 182 o the outputs of the mechanism's GSS_Pseudo_random() (for different 183 inputs) and its per-message tokens for the given security context 184 MUST be "cryptographically separate;" in other words, it must not 185 be feasible to recover key material for one mechanism operation or 186 transform its tokens and PRF outputs from one to the other given 187 only said tokens and PRF outputs. [This is a fancy way of saying 188 that key derivation and strong cryptographic operations and 189 constructions must be used.] 191 o as implied by the above requirement, it MUST NOT be possible to 192 access any raw keys of a security context through 193 GSS_Pseudo_random(), no matter what inputs are given. 195 Mechanisms MAY limit the output of the PRF, possibly in ways related 196 to the types of cryptographic keys available for the PRF function, 197 thus the prf_out output of GSS_Pseudo_random() MAY be smaller than 198 requested. 200 2.1 C-Bindings 202 #define GSS_C_PRF_KEY_FULL 0 203 #define GSS_C_PRF_KEY_PARTIAL 1 204 OM_uint32 gss_pseudo_random( 205 OM_uint32 *minor_status, 206 gss_ctx_id_t context, 207 int prf_key, 208 const gss_buffer_t prf_in, 209 ssize_t desired_output_len, 210 gss_buffer_t prf_out 211 ); 213 Additional major status codes for the C-bindings: 215 o GSS_S_CALL_INACCESSIBLE_READ 217 o GSS_S_CALL_INACCESSIBLE_WRITE 219 See [RFC2744]. 221 2.2 Java Bindings 223 For Java GSS_Pseudo_random() maps to a GSSContext method, 'prf': 225 public static final int GSS_C_PRF_KEY_FULL = 0 226 public static final int GSS_C_PRF_KEY_PARTIAL = 1 228 public byte[] prf(int prf_key, byte inBuf[], int outlen) 229 throws GSSException 231 See [RFC2853]. 233 3. IANA Considerations 235 This document has no IANA considerations currently. If and when a 236 relevant IANA registry of GSS-API symbols is created then the generic 237 and language-specific function names, constant names and constant 238 values described above should be added to such a registry. 240 4. Security Considerations 242 Care should be taken in properly designing a mechanism's PRF 243 function. 245 GSS mechanisms' PRF functions should use a key derived from contexts' 246 authenticated session keys and should preserve the forward security 247 properties of the mechanisms' key exchanges. 249 Some mechanisms may support the GSS PRF function with security 250 contexts that are not fully established, but applications MUST assume 251 that authentication, mutual or otherwise, has not completed until the 252 security context is fully established. 254 Callers of GSS_Pseudo_random() should avoid accidentally calling it 255 with the same inputs. One useful technique is to prepend to the 256 prf_in input string, by convention, a string indicating the intended 257 purpose of the PRF output in such a way that unique contexts in which 258 the function is called yield unique inputs to it. 260 Pseudo-random functions are, by their nature, capable of producing 261 only limited amounts of cryptographically secure output. The exact 262 amount of output that one can safely use, unfortunately, varies from 263 one PRF to another (which prevents us from recommending specific 264 numbers). Because of this we recommend that unless you really know 265 what you are doing (i.e. you are a cryptographer and are qualified to 266 pass judgement on cryptographic functions in areas of period, 267 presence of short cycles, etc), you limit the amount of the PRF 268 output used to the necessary minimum. 270 5. References 272 5.1 Normative References 274 [GGM1] Goldreich, O., Goldwasser, S., and S. Micali, "How to 275 Construct Random Functions", October 1986. 277 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 278 Requirement Levels", BCP 14, RFC 2119, March 1997. 280 [RFC2743] Linn, J., "Generic Security Service Application Program 281 Interface Version 2, Update 1", RFC 2743, January 2000. 283 [RFC2744] Wray, J., "Generic Security Service API Version 2 : 284 C-bindings", RFC 2744, January 2000. 286 [RFC2853] Kabat, J. and M. Upadhyay, "Generic Security Service API 287 Version 2 : Java Bindings", RFC 2853, June 2000. 289 5.2 Informative References 291 [GGM2] Goldreich, O., Goldwasser, S., and S. Micali, "On the 292 Cryptographic Applications of Random Functions", 1985. 294 [RFC1750] Eastlake, D., Crocker, S., and J. Schiller, "Randomness 295 Recommendations for Security", RFC 1750, December 1994. 297 [RFC1964] Linn, J., "The Kerberos Version 5 GSS-API Mechanism", 298 RFC 1964, June 1996. 300 Author's Address 302 Nicolas Williams 303 Sun Microsystems 304 5300 Riata Trace Ct 305 Austin, TX 78727 306 US 308 Email: Nicolas.Williams@sun.com 310 Intellectual Property Statement 312 The IETF takes no position regarding the validity or scope of any 313 Intellectual Property Rights or other rights that might be claimed to 314 pertain to the implementation or use of the technology described in 315 this document or the extent to which any license under such rights 316 might or might not be available; nor does it represent that it has 317 made any independent effort to identify any such rights. Information 318 on the procedures with respect to rights in RFC documents can be 319 found in BCP 78 and BCP 79. 321 Copies of IPR disclosures made to the IETF Secretariat and any 322 assurances of licenses to be made available, or the result of an 323 attempt made to obtain a general license or permission for the use of 324 such proprietary rights by implementers or users of this 325 specification can be obtained from the IETF on-line IPR repository at 326 http://www.ietf.org/ipr. 328 The IETF invites any interested party to bring to its attention any 329 copyrights, patents or patent applications, or other proprietary 330 rights that may cover technology that may be required to implement 331 this standard. Please address the information to the IETF at 332 ietf-ipr@ietf.org. 334 Disclaimer of Validity 336 This document and the information contained herein are provided on an 337 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 338 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET 339 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, 340 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE 341 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 342 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 344 Copyright Statement 346 Copyright (C) The Internet Society (2005). This document is subject 347 to the rights, licenses and restrictions contained in BCP 78, and 348 except as set forth therein, the authors retain all their rights. 350 Acknowledgment 352 Funding for the RFC Editor function is currently provided by the 353 Internet Society.