idnits 2.17.1 draft-josefsson-gss-capsulate-05.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (May 18, 2011) is 4720 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) No issues found here. Summary: 0 errors (**), 0 flaws (~~), 1 warning (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group S. Josefsson 3 Internet-Draft SJD AB 4 Intended status: Standards Track L. Hornquist Astrand 5 Expires: November 19, 2011 Apple, Inc. 6 May 18, 2011 8 Context Token Encapsulate/Decapsulate and OID Comparison Functions for 9 the Generic Security Service Application Program Interface (GSS-API) 10 draft-josefsson-gss-capsulate-05 12 Abstract 14 This document describes three abstract Generic Security Service 15 Application Program Interface (GSS-API) interfaces used to 16 encapsulate/decapsulate context tokens and compare OIDs. The 17 document also specifies C bindings for the abstract interfaces. 19 Status of this Memo 21 This Internet-Draft is submitted in full conformance with the 22 provisions of BCP 78 and BCP 79. 24 Internet-Drafts are working documents of the Internet Engineering 25 Task Force (IETF). Note that other groups may also distribute 26 working documents as Internet-Drafts. The list of current Internet- 27 Drafts is at http://datatracker.ietf.org/drafts/current/. 29 Internet-Drafts are draft documents valid for a maximum of six months 30 and may be updated, replaced, or obsoleted by other documents at any 31 time. It is inappropriate to use Internet-Drafts as reference 32 material or to cite them other than as "work in progress." 34 This Internet-Draft will expire on November 19, 2011. 36 Copyright Notice 38 Copyright (c) 2011 IETF Trust and the persons identified as the 39 document authors. All rights reserved. 41 This document is subject to BCP 78 and the IETF Trust's Legal 42 Provisions Relating to IETF Documents 43 (http://trustee.ietf.org/license-info) in effect on the date of 44 publication of this document. Please review these documents 45 carefully, as they describe your rights and restrictions with respect 46 to this document. Code Components extracted from this document must 47 include Simplified BSD License text as described in Section 4.e of 48 the Trust Legal Provisions and are provided without warranty as 49 described in the Simplified BSD License. 51 Table of Contents 53 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 54 2. Conventions used in this document . . . . . . . . . . . . . . 4 55 3. GSS_Encapsulate_token call . . . . . . . . . . . . . . . . . . 5 56 3.1. gss_encapsulate_token . . . . . . . . . . . . . . . . . . 6 57 4. GSS_Decapsulate_token call . . . . . . . . . . . . . . . . . . 7 58 4.1. gss_decapsulate_token . . . . . . . . . . . . . . . . . . 8 59 5. GSS_OID_equal call . . . . . . . . . . . . . . . . . . . . . . 9 60 5.1. gss_oid_equal . . . . . . . . . . . . . . . . . . . . . . 10 61 6. Test vector . . . . . . . . . . . . . . . . . . . . . . . . . 11 62 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 12 63 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13 64 9. Security Considerations . . . . . . . . . . . . . . . . . . . 14 65 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 15 66 10.1. Normative References . . . . . . . . . . . . . . . . . . . 15 67 10.2. Informative References . . . . . . . . . . . . . . . . . . 15 68 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 16 70 1. Introduction 72 The Generic Security Service Application Program Interface (GSS-API) 73 [RFC2743] is a framework that provides security services to 74 applications using a variety of authentication mechanisms. There are 75 widely implemented C bindings [RFC2744] for the abstract interface. 77 For initial context tokens a mechanism-independent token format may 78 be used, see section 3.1 of [RFC2743]. Some protocols, e.g., SASL 79 GS2 [RFC5801], need the ability to add and remove this token header 80 which contains some ASN.1 tags, a length and the mechanism OID to and 81 from context tokens. This document adds two GSS-API interfaces 82 (GSS_Encapsulate_token and GSS_Decapsulate_token) so that GSS-API 83 libraries can provide this functionality. 85 Being able to compare OIDs is useful, for example when validating 86 that a negotiated mechanism matched the requested one. This document 87 adds one GSS-API interface (GSS_OID_equal) for this purpose. 89 The intention is that text from this specification should be possible 90 to use for implementation documentation, and for this reason this 91 entire document should be considered a code component. 93 2. Conventions used in this document 95 The document uses terms from, and is structured in a similar way as, 96 [RFC2743] and [RFC2744]. The normative reference to [RFC5587] is for 97 the C types "gss_const_buffer_t" and "gss_const_OID", nothing else 98 from that document is required to implement this document. 100 3. GSS_Encapsulate_token call 102 Inputs: 104 o input_token OCTET STRING -- buffer with token data to 105 encapsulate 107 o token_oid OBJECT IDENTIFIER -- object identifier of mechanism 108 for the token 110 Outputs: 112 o major_status INTEGER 114 o output_token OCTET STRING -- Encapsulated token data; caller 115 must release with GSS_Release_buffer() 117 Return major_status codes: 119 o GSS_S_COMPLETE indicates successful completion, and that 120 output parameters holds correct information. 122 o GSS_S_FAILURE indicates that encapsulation failed for 123 reasons unspecified at the GSS-API level. 125 GSS_Encapsulate_token() is used to add the mechanism-independent 126 token header to GSS-API context token data. 128 3.1. gss_encapsulate_token 130 OM_uint32 gss_encapsulate_token ( 131 gss_const_buffer_t input_token, 132 gss_const_OID token_oid, 133 gss_buffer_t output_token) 135 Purpose: 137 Add the mechanism-independent token header to GSS-API context 138 token data. 140 Parameters: 142 input_token buffer, opaque, read 143 Buffer with GSS-API context token data. 145 token_oid Object ID, read 146 Object identifier of token. 148 output_token buffer, opaque, modify 149 Encapsulated token data; caller must 150 release with gss_release_buffer(). 152 Function value: GSS status code 154 GSS_S_COMPLETE Indicates successful completion, and 155 that output parameters holds correct 156 information. 158 GSS_S_FAILURE Indicates that encapsulation failed for 159 reasons unspecified at the GSS-API level. 161 4. GSS_Decapsulate_token call 163 Inputs: 165 o input_token OCTET STRING -- buffer with token to decapsulate 167 o token_oid OBJECT IDENTIFIER -- expected object identifier 168 of token 170 Outputs: 172 o major_status INTEGER 174 o output_token OCTET STRING -- Decapsulated token data; caller 175 must release with GSS_Release_buffer() 177 Return major_status codes: 179 o GSS_S_COMPLETE indicates successful completion, and that 180 output parameters holds correct information. 182 o GSS_S_DEFECTIVE_TOKEN means that the token failed 183 consistency checks (e.g., OID mismatch or ASN.1 DER length 184 errors). 186 o GSS_S_FAILURE indicates that decapsulation failed for 187 reasons unspecified at the GSS-API level. 189 GSS_Decapsulate_token() is used to remove the mechanism- 190 independent token header from an initial GSS-API context token. 192 4.1. gss_decapsulate_token 194 OM_uint32 195 gss_decapsulate_token ( 196 gss_const_buffer_t input_token, 197 gss_const_OID token_oid, 198 gss_buffer_t output_token) 200 Purpose: 202 Remove the mechanism-independent token header from an initial 203 GSS-API context token. 205 Parameters: 207 input_token buffer, opaque, read 208 Buffer with GSS-API context token. 210 token_oid Object ID, read 211 Expected object identifier of token. 213 output_token buffer, opaque, modify 214 Decapsulated token data; caller must 215 release with gss_release_buffer(). 217 Function value: GSS status code 219 GSS_S_COMPLETE Indicates successful completion, and 220 that output parameters holds correct 221 information. 223 GSS_S_DEFECTIVE_TOKEN Means that the token failed consistency 224 checks (e.g., OID mismatch or ASN.1 DER 225 length errors). 227 GSS_S_FAILURE Indicates that decapsulation failed for 228 reasons unspecified at the GSS-API level. 230 5. GSS_OID_equal call 232 Inputs: 234 o first_oid OBJECT IDENTIFIER -- first object identifier 235 to compare 237 o second_oid OBJECT IDENTIFIER -- second object identifier 238 to compare 240 Return codes: 242 o non-0 when neither OID is GSS_C_NO_OID and the two OIDs 243 are equal. 245 o 0 when the two OIDs are not identical or either OID is 246 equal to GSS_C_NO_OID. 248 GSS_OID_equal() is used to add compare two OIDs for equality. The 249 value GSS_C_NO_OID will not match any OID, including GSS_C_NO_OID 250 itself. 252 5.1. gss_oid_equal 254 extern int 255 gss_oid_equal ( 256 gss_const_OID first_oid, 257 gss_const_OID second_oid 258 ) 260 Purpose: 262 Compare two OIDs for equality. The value GSS_C_NO_OID will not 263 match any OID, including GSS_C_NO_OID itself. 265 Parameters: 267 first_oid Object ID, read 268 First object identifier to compare. 270 second_oid Object ID, read 271 Second object identifier to compare. 273 Function value: GSS status code 275 non-0 Neither OID is GSS_C_NO_OID and the 276 two OIDs are equal. 278 0 When the two OIDs are not identical or 279 either OID is equal to GSS_C_NO_OID. 281 6. Test vector 283 For the GSS_Encapsulate_token function, if the "input_token" buffer 284 is the 3 bytes octet sequence "foo" and the "token_oid" OID is 285 1.2.840.113554.1.2.2, which encoded corresponds to the 9 bytes long 286 octet sequence (using C notation) 287 "\x2a\x86\x48\x86\xf7\x12\x01\x02\x02", the output should be the 16 288 byte long octet sequence (again in C notation) 289 "\x60\x0e\x06\x09\x2a\x86\x48\x86\xf7\x12\x01\x02\x02\x66\x6f\x6f". 290 These values may be used to also test the GSS_Decapsulate_token 291 interface. 293 7. Acknowledgements 295 Greg Hudson pointed out the 'const' problem with the C bindings in 296 earlier versions of this document, and Luke Howard suggested to 297 resolve it by using the RFC 5587 types. Stephen Farrell suggested 298 several editorial improvements and the security consideration 299 regarding absent security features of the encapsulation function. 300 Chris Lonvick suggested some improvements. 302 8. IANA Considerations 304 None. 306 9. Security Considerations 308 The security considerations of the base GSS-API specification 309 ([RFC2743]) and the base C bindings ([RFC2744]) are inherited. 311 Encapsulation of data does not provide any kind of integrity or 312 confidentiality. 314 Implementations needs to treat input as potentially untrustworthy for 315 purposes of dereferencing memory objects to avoid security 316 vulnerabilities. In particular, ASN.1 DER length fields is a common 317 source of mistakes. 319 10. References 321 10.1. Normative References 323 [RFC2743] Linn, J., "Generic Security Service Application Program 324 Interface Version 2, Update 1", RFC 2743, January 2000. 326 [RFC2744] Wray, J., "Generic Security Service API Version 2 : 327 C-bindings", RFC 2744, January 2000. 329 [RFC5587] Williams, N., "Extended Generic Security Service Mechanism 330 Inquiry APIs", RFC 5587, July 2009. 332 10.2. Informative References 334 [RFC5801] Josefsson, S. and N. Williams, "Using Generic Security 335 Service Application Program Interface (GSS-API) Mechanisms 336 in Simple Authentication and Security Layer (SASL): The 337 GS2 Mechanism Family", RFC 5801, July 2010. 339 Authors' Addresses 341 Simon Josefsson 342 SJD AB 343 Hagagatan 24 344 Stockholm 113 47 345 SE 347 Email: simon@josefsson.org 348 URI: http://josefsson.org/ 350 Love Hornquist Astrand 351 Apple, Inc. 353 Email: lha@apple.com