1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
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
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
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
|
<pre>Internet Engineering Task Force (IETF) S. Josefsson
Request for Comments: 6339 SJD AB
Category: Standards Track L. Hornquist Astrand
ISSN: 2070-1721 Apple, Inc.
August 2011
<span class="h1">Context Token Encapsulate/Decapsulate and OID Comparison Functions for</span>
<span class="h1">the Generic Security Service Application Program Interface (GSS-API)</span>
Abstract
This document describes three abstract Generic Security Service
Application Program Interface (GSS-API) interfaces used to
encapsulate/decapsulate context tokens and compare OIDs. This
document also specifies C bindings for the abstract interfaces.
Status of This Memo
This is an Internet Standards Track document.
This document is a product of the Internet Engineering Task Force
(IETF). It represents the consensus of the IETF community. It has
received public review and has been approved for publication by the
Internet Engineering Steering Group (IESG). Further information on
Internet Standards is available in <a href="./rfc5741#section-2">Section 2 of RFC 5741</a>.
Information about the current status of this document, any errata,
and how to provide feedback on it may be obtained at
<a href="http://www.rfc-editor.org/info/rfc6339">http://www.rfc-editor.org/info/rfc6339</a>.
Copyright Notice
Copyright (c) 2011 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to <a href="https://www.rfc-editor.org/bcp/bcp78">BCP 78</a> and the IETF Trust's Legal
Provisions Relating to IETF Documents
(<a href="http://trustee.ietf.org/license-info">http://trustee.ietf.org/license-info</a>) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
<span class="grey">Josefsson & Hornquist Astrand Standards Track [Page 1]</span></pre>
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-2" ></span>
<span class="grey"><a href="./rfc6339">RFC 6339</a> GSS-API Capsulate and OID Comparison August 2011</span>
Table of Contents
<a href="#section-1">1</a>. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . <a href="#page-2">2</a>
<a href="#section-2">2</a>. Conventions Used in This Document . . . . . . . . . . . . . . . <a href="#page-2">2</a>
<a href="#section-3">3</a>. GSS_Encapsulate_token Call . . . . . . . . . . . . . . . . . . <a href="#page-3">3</a>
<a href="#section-3.1">3.1</a>. gss_encapsulate_token . . . . . . . . . . . . . . . . . . . <a href="#page-3">3</a>
<a href="#section-4">4</a>. GSS_Decapsulate_token Call . . . . . . . . . . . . . . . . . . <a href="#page-4">4</a>
<a href="#section-4.1">4.1</a>. gss_decapsulate_token . . . . . . . . . . . . . . . . . . . <a href="#page-5">5</a>
<a href="#section-5">5</a>. GSS_OID_equal Call . . . . . . . . . . . . . . . . . . . . . . <a href="#page-6">6</a>
<a href="#section-5.1">5.1</a>. gss_oid_equal . . . . . . . . . . . . . . . . . . . . . . . <a href="#page-6">6</a>
<a href="#section-6">6</a>. Test Vector . . . . . . . . . . . . . . . . . . . . . . . . . . <a href="#page-7">7</a>
<a href="#section-7">7</a>. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . <a href="#page-7">7</a>
<a href="#section-8">8</a>. Security Considerations . . . . . . . . . . . . . . . . . . . . <a href="#page-7">7</a>
<a href="#section-9">9</a>. References . . . . . . . . . . . . . . . . . . . . . . . . . . <a href="#page-7">7</a>
<a href="#section-9.1">9.1</a>. Normative References . . . . . . . . . . . . . . . . . . . <a href="#page-7">7</a>
<a href="#section-9.2">9.2</a>. Informative Reference . . . . . . . . . . . . . . . . . . . <a href="#page-8">8</a>
<span class="h2"><a class="selflink" id="section-1" href="#section-1">1</a>. Introduction</span>
The Generic Security Service Application Program Interface (GSS-API)
[<a href="./rfc2743" title=""Generic Security Service Application Program Interface Version 2, Update 1"">RFC2743</a>] is a framework that provides security services to
applications using a variety of authentication mechanisms. There are
widely implemented C bindings [<a href="./rfc2744" title=""Generic Security Service API Version 2 : C-bindings"">RFC2744</a>] for the abstract interface.
For initial context tokens, a mechanism-independent token format may
be used (see <a href="./rfc2743#section-3.1">Section 3.1 of [RFC2743]</a>). Some protocols, e.g., Simple
Authentication and Security Layer (SASL) GS2 [<a href="./rfc5801" title=""Using Generic Security Service Application Program Interface (GSS-API) Mechanisms in Simple Authentication and Security Layer (SASL): The GS2 Mechanism Family"">RFC5801</a>], need the
ability to add and remove this token header, which contains some
ASN.1 tags, a length, and the mechanism OID to and from context
tokens. This document adds two GSS-API interfaces
(GSS_Encapsulate_token and GSS_Decapsulate_token) so that GSS-API
libraries can provide this functionality.
Being able to compare OIDs is useful, for example, when validating
that a negotiated mechanism matches the requested one. This document
adds one GSS-API interface (GSS_OID_equal) for this purpose.
Text from this specification can be used as implementation
documentation, and for this reason, Sections <a href="#section-3">3</a>, <a href="#section-4">4</a>, <a href="#section-5">5</a>, <a href="#section-6">6</a>, and <a href="#section-8">8</a> should
be considered code components.
<span class="h2"><a class="selflink" id="section-2" href="#section-2">2</a>. Conventions Used in This Document</span>
The document uses terms from, and is structured in a similar way as,
[<a href="./rfc2743" title=""Generic Security Service Application Program Interface Version 2, Update 1"">RFC2743</a>] and [<a href="./rfc2744" title=""Generic Security Service API Version 2 : C-bindings"">RFC2744</a>]. The normative reference to [<a href="./rfc5587" title=""Extended Generic Security Service Mechanism Inquiry APIs"">RFC5587</a>] is for
the C types "gss_const_buffer_t" and "gss_const_OID"; nothing else
from that document is required to implement this document.
<span class="grey">Josefsson & Hornquist Astrand Standards Track [Page 2]</span></pre>
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-3" ></span>
<span class="grey"><a href="./rfc6339">RFC 6339</a> GSS-API Capsulate and OID Comparison August 2011</span>
<span class="h2"><a class="selflink" id="section-3" href="#section-3">3</a>. GSS_Encapsulate_token Call</span>
Inputs:
o input_token OCTET STRING -- buffer with token data to encapsulate
o token_oid OBJECT IDENTIFIER -- object identifier of mechanism for
the token
Outputs:
o major_status INTEGER
o output_token OCTET STRING -- Encapsulated token data; caller must
release with GSS_Release_buffer()
Return major_status codes:
o GSS_S_COMPLETE indicates that completion was successful and that
output parameters hold correct information.
o GSS_S_FAILURE indicates that encapsulation failed for reasons
unspecified at the GSS-API level.
GSS_Encapsulate_token() is used to add the mechanism-independent
token header to GSS-API context token data.
<span class="h3"><a class="selflink" id="section-3.1" href="#section-3.1">3.1</a>. gss_encapsulate_token</span>
OM_uint32 gss_encapsulate_token (
gss_const_buffer_t input_token,
gss_const_OID token_oid,
gss_buffer_t output_token)
Purpose:
Add the mechanism-independent token header to GSS-API context token
data.
Parameters:
input_token buffer, opaque, read
Buffer with GSS-API context token data.
token_oid Object ID, read
Object identifier of token.
<span class="grey">Josefsson & Hornquist Astrand Standards Track [Page 3]</span></pre>
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-4" ></span>
<span class="grey"><a href="./rfc6339">RFC 6339</a> GSS-API Capsulate and OID Comparison August 2011</span>
output_token buffer, opaque, modify
Encapsulated token data; caller must release
with gss_release_buffer().
Function values: GSS status codes
GSS_S_COMPLETE Indicates that completion was successful and
that output parameters hold correct
information.
GSS_S_FAILURE Indicates that encapsulation failed for
reasons unspecified at the GSS-API level.
<span class="h2"><a class="selflink" id="section-4" href="#section-4">4</a>. GSS_Decapsulate_token Call</span>
Inputs:
o input_token OCTET STRING -- buffer with token to decapsulate
o token_oid OBJECT IDENTIFIER -- expected object identifier of token
Outputs:
o major_status INTEGER
o output_token OCTET STRING -- Decapsulated token data; caller must
release with GSS_Release_buffer()
Return major_status codes:
o GSS_S_COMPLETE indicates that completion was successful and that
output parameters hold correct information.
o GSS_S_DEFECTIVE_TOKEN means that the token failed consistency
checks (e.g., OID mismatch or ASN.1 DER length errors).
o GSS_S_FAILURE indicates that decapsulation failed for reasons
unspecified at the GSS-API level.
GSS_Decapsulate_token() is used to remove the mechanism-independent
token header from an initial GSS-API context token.
<span class="grey">Josefsson & Hornquist Astrand Standards Track [Page 4]</span></pre>
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-5" ></span>
<span class="grey"><a href="./rfc6339">RFC 6339</a> GSS-API Capsulate and OID Comparison August 2011</span>
<span class="h3"><a class="selflink" id="section-4.1" href="#section-4.1">4.1</a>. gss_decapsulate_token</span>
OM_uint32
gss_decapsulate_token (
gss_const_buffer_t input_token,
gss_const_OID token_oid,
gss_buffer_t output_token)
Purpose:
Remove the mechanism-independent token header from an initial GSS-API
context token.
Parameters:
input_token buffer, opaque, read
Buffer with GSS-API context token.
token_oid Object ID, read
Expected object identifier of token.
output_token buffer, opaque, modify
Decapsulated token data; caller must release
with gss_release_buffer().
Function values: GSS status codes
GSS_S_COMPLETE Indicates that completion was successful and
that output parameters hold correct
information.
GSS_S_DEFECTIVE_TOKEN Means that the token failed consistency checks
(e.g., OID mismatch or ASN.1 DER length
errors).
GSS_S_FAILURE Indicates that decapsulation failed for
reasons unspecified at the GSS-API level.
<span class="grey">Josefsson & Hornquist Astrand Standards Track [Page 5]</span></pre>
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-6" ></span>
<span class="grey"><a href="./rfc6339">RFC 6339</a> GSS-API Capsulate and OID Comparison August 2011</span>
<span class="h2"><a class="selflink" id="section-5" href="#section-5">5</a>. GSS_OID_equal Call</span>
Inputs:
o first_oid OBJECT IDENTIFIER -- first object identifier to compare
o second_oid OBJECT IDENTIFIER -- second object identifier to
compare
Return codes:
o non-0 when neither OID is GSS_C_NO_OID and the two OIDs are equal.
o 0 when the two OIDs are not identical or either OID is equal to
GSS_C_NO_OID.
GSS_OID_equal() is used to add compare two OIDs for equality. The
value GSS_C_NO_OID will not match any OID, including GSS_C_NO_OID
itself.
<span class="h3"><a class="selflink" id="section-5.1" href="#section-5.1">5.1</a>. gss_oid_equal</span>
extern int
gss_oid_equal (
gss_const_OID first_oid,
gss_const_OID second_oid
)
Purpose:
Compare two OIDs for equality. The value GSS_C_NO_OID will not match
any OID, including GSS_C_NO_OID itself.
Parameters:
first_oid Object ID, read
First object identifier to compare.
second_oid Object ID, read
Second object identifier to compare.
Function values: GSS status codes
non-0 Neither OID is GSS_C_NO_OID, and the two OIDs
are equal.
0 The two OIDs are not identical, or either OID
is equal to GSS_C_NO_OID.
<span class="grey">Josefsson & Hornquist Astrand Standards Track [Page 6]</span></pre>
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-7" ></span>
<span class="grey"><a href="./rfc6339">RFC 6339</a> GSS-API Capsulate and OID Comparison August 2011</span>
<span class="h2"><a class="selflink" id="section-6" href="#section-6">6</a>. Test Vector</span>
For the GSS_Encapsulate_token function, if the "input_token" buffer
is the 3-byte octet sequence "foo" and the "token_oid" OID is
1.2.840.113554.1.2.2, which encoded corresponds to the 9-byte-long
octet sequence (using C notation)
"\x2a\x86\x48\x86\xf7\x12\x01\x02\x02", the output should be the
16-byte-long octet sequence (again in C notation)
"\x60\x0e\x06\x09\x2a\x86\x48\x86\xf7\x12\x01\x02\x02\x66\x6f\x6f".
These values may also be used to test the GSS_Decapsulate_token
interface.
<span class="h2"><a class="selflink" id="section-7" href="#section-7">7</a>. Acknowledgements</span>
Greg Hudson pointed out the 'const' problem with the C bindings in
earlier versions of this document, and Luke Howard suggested to
resolve it by using the [<a href="./rfc5587" title=""Extended Generic Security Service Mechanism Inquiry APIs"">RFC5587</a>] types. Stephen Farrell suggested
several editorial improvements and the security consideration
regarding absent security features of the encapsulation function.
Chris Lonvick suggested some improvements.
<span class="h2"><a class="selflink" id="section-8" href="#section-8">8</a>. Security Considerations</span>
The security considerations of the base GSS-API specification
([<a href="./rfc2743" title=""Generic Security Service Application Program Interface Version 2, Update 1"">RFC2743</a>]) and the base C bindings ([<a href="./rfc2744" title=""Generic Security Service API Version 2 : C-bindings"">RFC2744</a>]) are inherited.
Encapsulation of data does not provide any kind of integrity or
confidentiality.
Implementations need to treat input as potentially untrustworthy for
purposes of dereferencing memory objects to avoid security
vulnerabilities. In particular, ASN.1 DER length fields are a common
source of mistakes.
<span class="h2"><a class="selflink" id="section-9" href="#section-9">9</a>. References</span>
<span class="h3"><a class="selflink" id="section-9.1" href="#section-9.1">9.1</a>. Normative References</span>
[<a id="ref-RFC2743">RFC2743</a>] Linn, J., "Generic Security Service Application Program
Interface Version 2, Update 1", <a href="./rfc2743">RFC 2743</a>, January 2000.
[<a id="ref-RFC2744">RFC2744</a>] Wray, J., "Generic Security Service API Version 2 :
C-bindings", <a href="./rfc2744">RFC 2744</a>, January 2000.
[<a id="ref-RFC5587">RFC5587</a>] Williams, N., "Extended Generic Security Service Mechanism
Inquiry APIs", <a href="./rfc5587">RFC 5587</a>, July 2009.
<span class="grey">Josefsson & Hornquist Astrand Standards Track [Page 7]</span></pre>
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-8" ></span>
<span class="grey"><a href="./rfc6339">RFC 6339</a> GSS-API Capsulate and OID Comparison August 2011</span>
<span class="h3"><a class="selflink" id="section-9.2" href="#section-9.2">9.2</a>. Informative Reference</span>
[<a id="ref-RFC5801">RFC5801</a>] Josefsson, S. and N. Williams, "Using Generic Security
Service Application Program Interface (GSS-API) Mechanisms
in Simple Authentication and Security Layer (SASL): The
GS2 Mechanism Family", <a href="./rfc5801">RFC 5801</a>, July 2010.
Authors' Addresses
Simon Josefsson
SJD AB
Hagagatan 24
Stockholm 113 47
SE
EMail: simon@josefsson.org
URI: <a href="http://josefsson.org/">http://josefsson.org/</a>
Love Hornquist Astrand
Apple, Inc.
EMail: lha@apple.com
Josefsson & Hornquist Astrand Standards Track [Page 8]
</pre>
|
