idnits 2.17.1 draft-ietf-kitten-gssapi-prf-06.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 347. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 324. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 331. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 337. ** 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 (August 25, 2005) is 6816 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 285, but no explicit reference was found in the text == Unused Reference: 'RFC2853' is defined on line 291, but no explicit reference was found in the text == Unused Reference: 'RFC1750' is defined on line 299, 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 (~~), 5 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: February 26, 2006 August 25, 2005 6 A PRF API extension for the GSS-API 7 draft-ietf-kitten-gssapi-prf-06.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 February 26, 2006. 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 . . . . . . . . . . . . . . . . . . . . . . . . . . 6 54 3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6 55 4. Security Considerations . . . . . . . . . . . . . . . . . . . 6 56 5. References . . . . . . . . . . . . . . . . . . . . . . . . . . 7 57 5.1 Normative References . . . . . . . . . . . . . . . . . . . . . 7 58 5.2 Informative References . . . . . . . . . . . . . . . . . . . . 7 59 Author's Address . . . . . . . . . . . . . . . . . . . . . . . 8 60 Intellectual Property and Copyright Statements . . . . . . . . 9 62 1. Introduction 64 A need has arisen for users of the GSS-API to key applications' 65 cryptographic protocols using established GSS-API security contexts. 66 Such applications can use the GSS-API for authentication, but not for 67 transport security (for whatever reasons), and since the GSS-API does 68 not provide a method for obtaining keying material from established 69 security contexts such applications cannot make effective use of the 70 GSS-API. 72 To address this need we define a pseudo-random function (PRF) 73 extension to the GSS-API. 75 Though this document specifies an abstract API as an extension to the 76 GSS-API version 2, update 1, and though it specifies the bindings of 77 this extension for the C programming language, it does not specify a 78 revision of the GSS-API and so does not address the matter of how 79 portable applications detect support for and ensure access to this 80 extension. We defer this matter to an expected, comprehensive update 81 to the GSS-API. 83 1.1 Conventions used in this document 85 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 86 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 87 document are to be interpreted as described in [RFC2119]. 89 2. GSS_Pseudo_random() 91 Inputs: 93 o context CONTEXT handle, 95 o prf_key INTEGER, 97 o prf_in OCTET STRING, 99 o desired_output_len INTEGER 101 Outputs: 103 o major_status INTEGER, 105 o minor_status INTEGER, 107 o prf_out OCTET STRING 108 Return major_status codes: 110 o GSS_S_COMPLETE indicates no error. 112 o GSS_S_NO_CONTEXT indicates that a null context has been provided 113 as input. 115 o GSS_S_CONTEXT_EXPIRED indicates that an expired context has been 116 provided as input. 118 o GSS_S_UNAVAILABLE indicates that the mechanism lacks support for 119 this function or, if the security context is not fully 120 established, that the context is not ready to compute the PRF with 121 the given prf_key, or that the given prf_key is not available. 123 o GSS_S_FAILURE indicates general failure, possibly due to the given 124 input data being too large or of zero length, or due to the 125 desired_output_len being zero; the minor status code may provide 126 additional information. 128 This function applies the established context's mechanism's keyed 129 pseudo-random function (PRF) to the input data ('prf_in'), keyed with 130 key material associated with the given security context and 131 identified by 'prf_key', and outputs the resulting octet string 132 ('prf_out') of desired_output_len length. 134 The minimum input data length is one octet. 136 Mechanisms MUST be able to consume all the provided prf_in input data 137 that is 2^14 or fewer octets. 139 If a mechanism cannot consume as much input data as provided by the 140 caller, then GSS_Pseudo_random() MUST return GSS_S_FAILURE. 142 The minimum desired_output_len is one. 144 Mechanisms MUST be able to output at least up to 2^14 octets. 146 If the implementation cannot produce the desired output due to lack 147 of resources then it MUST return GSS_S_FAILURE and MUST set a 148 suitable minor status code. 150 The prf_key can take on the following values: GSS_C_PRF_KEY_FULL, 151 GSS_C_PRF_KEY_PARTIAL or mechanism-specific values, if any. This 152 parameter is intended to distinguish between the best cryptographic 153 keys that may be available only after full security context 154 establishment and keys that may be available prior to full security 155 context establishment. For some mechanisms, or contexts, those two 156 prf_key values MAY refer to the same cryptographic keys; for 157 mechanisms like the Kerberos V GSS-API mechanism [RFC1964] where one 158 peer may assert a key that may be considered better than the others 159 they MAY be different keys. 161 GSS_C_PRF_KEY_PARTIAL corresponds to a key that would be have been 162 used while the security context was partially established, even if it 163 is fully established when GSS_Pseudo_random() is actually called. 164 Mechanism-specific prf_key values are intended to refer to any other 165 keys that may be available. 167 The GSS_C_PRF_KEY_FULL value corresponds to the best key available 168 for fully-established security contexts. 170 GSS_Pseudo_random() has the following properties: 172 o its output string MUST be a pseudo-random function [GGM1] [GGM2] 173 of the input keyed with key material from the given security 174 context -- the chances of getting the same output given different 175 input parameters should be exponentially small. 177 o when successfully applied to the same inputs by an initiator and 178 acceptor using the same security context, it MUST produce the 179 _same results_ for both, the initiator and acceptor, even if 180 called multiple times (as long as the security context is not 181 expired). 183 o upon full establishment of a security context all cryptographic 184 keys and/or negotiations used for computing the PRF with any 185 prf_key MUST be authenticated (mutually, if mutual authentication 186 is in effect for the given security context). 188 o the outputs of the mechanism's GSS_Pseudo_random() (for different 189 inputs) and its per-message tokens for the given security context 190 MUST be "cryptographically separate;" in other words, it must not 191 be feasible to recover key material for one mechanism operation or 192 transform its tokens and PRF outputs from one to the other given 193 only said tokens and PRF outputs. [This is a fancy way of saying 194 that key derivation and strong cryptographic operations and 195 constructions must be used.] 197 o as implied by the above requirement, it MUST NOT be possible to 198 access any raw keys of a security context through 199 GSS_Pseudo_random(), no matter what inputs are given. 201 Mechanisms MAY limit the output of the PRF, possibly in ways related 202 to the types of cryptographic keys available for the PRF function, 203 thus the prf_out output of GSS_Pseudo_random() MAY be smaller than 204 requested. 206 2.1 C-Bindings 208 #define GSS_C_PRF_KEY_FULL 0 209 #define GSS_C_PRF_KEY_PARTIAL 1 211 OM_uint32 gss_pseudo_random( 212 OM_uint32 *minor_status, 213 gss_ctx_id_t context, 214 int prf_key, 215 const gss_buffer_t prf_in, 216 ssize_t desired_output_len, 217 gss_buffer_t prf_out 218 ); 220 Additional major status codes for the C-bindings: 222 o GSS_S_CALL_INACCESSIBLE_READ 224 o GSS_S_CALL_INACCESSIBLE_WRITE 226 See [RFC2744]. 228 3. IANA Considerations 230 This document has no IANA considerations currently. If and when a 231 relevant IANA registry of GSS-API symbols is created then the generic 232 and language-specific function names, constant names and constant 233 values described above should be added to such a registry. 235 4. Security Considerations 237 Care should be taken in properly designing a mechanism's PRF 238 function. 240 GSS mechanisms' PRF functions should use a key derived from contexts' 241 authenticated session keys and should preserve the forward security 242 properties of the mechanisms' key exchanges. 244 Some mechanisms may support the GSS PRF function with security 245 contexts that are not fully established, but applications MUST assume 246 that authentication, mutual or otherwise, has not completed until the 247 security context is fully established. 249 Callers of GSS_Pseudo_random() should avoid accidentally calling it 250 with the same inputs. One useful technique is to prepend to the 251 prf_in input string, by convention, a string indicating the intended 252 purpose of the PRF output in such a way that unique contexts in which 253 the function is called yield unique inputs to it. 255 Pseudo-random functions are, by their nature, capable of producing 256 only limited amounts of cryptographically secure output. The exact 257 amount of output that one can safely use, unfortunately, varies from 258 one PRF to another (which prevents us from recommending specific 259 numbers). Because of this we recommend that unless you really know 260 what you are doing (i.e. you are a cryptographer and are qualified to 261 pass judgement on cryptographic functions in areas of period, 262 presence of short cycles, etc), you limit the amount of the PRF 263 output used to the necessary minimum. 265 For some mechanisms the computational cost of computing 266 GSS_Pseudo_random() may increase significantly as the length of the 267 prf_in data and/or the desired_output_length increase. This means 268 that if an application can be tricked into providing very large input 269 octet strings and requesting very long output octet strings then that 270 may constitute a denial of service attack on the application; 271 therefore applications SHOULD place appropriate limits on the size of 272 any input octet strings received from their peers without integrity 273 protection. 275 5. References 277 5.1 Normative References 279 [GGM1] Goldreich, O., Goldwasser, S., and S. Micali, "How to 280 Construct Random Functions", October 1986. 282 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 283 Requirement Levels", BCP 14, RFC 2119, March 1997. 285 [RFC2743] Linn, J., "Generic Security Service Application Program 286 Interface Version 2, Update 1", RFC 2743, January 2000. 288 [RFC2744] Wray, J., "Generic Security Service API Version 2 : 289 C-bindings", RFC 2744, January 2000. 291 [RFC2853] Kabat, J. and M. Upadhyay, "Generic Security Service API 292 Version 2 : Java Bindings", RFC 2853, June 2000. 294 5.2 Informative References 296 [GGM2] Goldreich, O., Goldwasser, S., and S. Micali, "On the 297 Cryptographic Applications of Random Functions", 1985. 299 [RFC1750] Eastlake, D., Crocker, S., and J. Schiller, "Randomness 300 Recommendations for Security", RFC 1750, December 1994. 302 [RFC1964] Linn, J., "The Kerberos Version 5 GSS-API Mechanism", 303 RFC 1964, June 1996. 305 Author's Address 307 Nicolas Williams 308 Sun Microsystems 309 5300 Riata Trace Ct 310 Austin, TX 78727 311 US 313 Email: Nicolas.Williams@sun.com 315 Intellectual Property Statement 317 The IETF takes no position regarding the validity or scope of any 318 Intellectual Property Rights or other rights that might be claimed to 319 pertain to the implementation or use of the technology described in 320 this document or the extent to which any license under such rights 321 might or might not be available; nor does it represent that it has 322 made any independent effort to identify any such rights. Information 323 on the procedures with respect to rights in RFC documents can be 324 found in BCP 78 and BCP 79. 326 Copies of IPR disclosures made to the IETF Secretariat and any 327 assurances of licenses to be made available, or the result of an 328 attempt made to obtain a general license or permission for the use of 329 such proprietary rights by implementers or users of this 330 specification can be obtained from the IETF on-line IPR repository at 331 http://www.ietf.org/ipr. 333 The IETF invites any interested party to bring to its attention any 334 copyrights, patents or patent applications, or other proprietary 335 rights that may cover technology that may be required to implement 336 this standard. Please address the information to the IETF at 337 ietf-ipr@ietf.org. 339 Disclaimer of Validity 341 This document and the information contained herein are provided on an 342 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 343 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET 344 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, 345 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE 346 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 347 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 349 Copyright Statement 351 Copyright (C) The Internet Society (2005). This document is subject 352 to the rights, licenses and restrictions contained in BCP 78, and 353 except as set forth therein, the authors retain all their rights. 355 Acknowledgment 357 Funding for the RFC Editor function is currently provided by the 358 Internet Society.