GSS_S_PROMPTING_NEEDED is a bit
[cyrus-sasl.git] / doc / draft-ietf-sasl-gssapi-xx.txt
1
2
3 SASL Working Group                                           A. Melnikov
4 Internet-Draft                                                     Isode
5 Expires: May 22, 2004                                  November 22, 2003
6
7
8                          SASL GSSAPI mechanisms
9                        draft-ietf-sasl-gssapi-00
10
11 Status of this Memo
12
13    This document is an Internet-Draft and is in full conformance with
14    all provisions of Section 10 of RFC2026.
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 http://
27    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 May 22, 2004.
33
34 Copyright Notice
35
36    Copyright (C) The Internet Society (2003).  All Rights Reserved.
37
38 Abstract
39
40    The Simple Authentication and Security Layer [SASL] is a method for
41    adding authentication support to connection-based protocols.  This
42    document describes the method for using the Generic Security Service
43    Application Program Interface [GSSAPI] in the Simple Authentication
44    and Security Layer [SASL].
45
46    This document replaces section 7.2 of RFC 2222 [SASL], the definition
47    of the "GSSAPI" SASL mechanism.
48
49
50
51
52
53
54
55 Melnikov                  Expires May 22, 2004                  [Page 1]
56 \f
57 Internet-Draft           SASL GSSAPI mechanisms            November 2003
58
59
60 Table of Contents
61
62    1.  Conventions Used in this Document  . . . . . . . . . . . . . .  3
63    2.  Introduction and Overview  . . . . . . . . . . . . . . . . . .  4
64    2.1 Example  . . . . . . . . . . . . . . . . . . . . . . . . . . .  4
65    3.  SPNEGO . . . . . . . . . . . . . . . . . . . . . . . . . . . .  5
66    4.  Specification common to all GSSAPI mechanisms  . . . . . . . .  6
67    4.1 Client side of authentication protocol exchange  . . . . . . .  6
68    4.2 Server side of authentication protocol exchange  . . . . . . .  7
69    4.3 Security layer . . . . . . . . . . . . . . . . . . . . . . . .  8
70    5.  IANA Considerations  . . . . . . . . . . . . . . . . . . . . .  9
71    6.  Security Considerations  . . . . . . . . . . . . . . . . . . . 11
72    7.  Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 12
73        Normative References . . . . . . . . . . . . . . . . . . . . . 13
74        Informative References . . . . . . . . . . . . . . . . . . . . 14
75        Author's Address . . . . . . . . . . . . . . . . . . . . . . . 14
76        Full Copyright Statement . . . . . . . . . . . . . . . . . . . 15
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 Melnikov                  Expires May 22, 2004                  [Page 2]
112 \f
113 Internet-Draft           SASL GSSAPI mechanisms            November 2003
114
115
116 1. Conventions Used in this Document
117
118    The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY"
119    in this document are to be interpreted as defined in "Key words for
120    use in RFCs to Indicate Requirement Levels" [KEYWORDS].
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 Melnikov                  Expires May 22, 2004                  [Page 3]
168 \f
169 Internet-Draft           SASL GSSAPI mechanisms            November 2003
170
171
172 2. Introduction and Overview
173
174    Each and every GSSAPI mechanism used within SASL is implicitly
175    registered by this specification.
176
177    For backwards compatibility with existing implementations of Kerberos
178    V5 and SPNEGO under SASL, the SASL mechanism name for the Kerberos V5
179    GSSAPI mechanism [KRB5GSS] is "GSSAPI" and the SASL mechanism for the
180    SPNEGO GSSAPI mechanism [SPNEGO] is "GSS-SPNEGO".  The SASL mechanism
181    name for any other GSSAPI mechanism is the concatenation of "GSS-"
182    and the Base32 [BASE-ENCODING] encoding of the first ten bytes of the
183    MD5 hash [MD5] of the ASN.1 DER encoding [ASN1] of the GSSAPI
184    mechanism's OID.  The Base32 rules on padding characters and
185    characters outside of the base32 alphabet are not relevant to this
186    use of Base32.
187
188    SASL mechanism names starting with "GSS-" are reserved for SASL
189    mechanisms which conform to this document.
190
191    The specification of all SASL mechanisms conforming to this document
192    is in the "Specification common to all GSSAPI mechanisms" section of
193    this document.
194
195    The IESG is considered to be the owner of all SASL mechanisms which
196    conform to this document.  This does NOT necessarily imply that the
197    IESG is considered to be the owner of the underlying GSSAPI
198    mechanism.
199
200 2.1 Example
201
202    The OID for the SPKM-1 mechanism [SPKM1] is 1.3.6.1.5.5.1.  The ASN.1
203    DER encoding of this OID is 06 06 2b 06 01 05 05 01.  The MD5 hash of
204    the ASN.1 DER encoding is 57 ee 81 82 4e ac 4d b0 e6 50 9f 60 1f 46
205    8a 30.  The Base32 encoding of the first ten bytes of this is
206    "K7XIDASOVRG3BZSQ".  Thus the SASL mechanism name for the SPKM-1
207    GSSAPI mechanism is "GSS-K7XIDASOVRG3BZSQ".
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223 Melnikov                  Expires May 22, 2004                  [Page 4]
224 \f
225 Internet-Draft           SASL GSSAPI mechanisms            November 2003
226
227
228 3. SPNEGO
229
230    Use of the Simple and Protected GSS-API Negotiation Mechanism
231    [SPNEGO] underneath SASL introduces subtle interoperability problems
232    and security considerations.  To address these, this section places
233    additional requirements on implementations which support SPNEGO
234    underneath SASL.
235
236    A client which supports, for example, the Kerberos V5 GSSAPI
237    mechanism only underneath SPNEGO underneath the "GSS-SPNEGO" SASL
238    mechanism will not interoperate with a server which supports the
239    Kerberos V5 GSSAPI mechanism only underneath the "GSSAPI" SASL
240    mechanism.
241
242    Since SASL is capable of negotiating amongst GSSAPI mechanisms, the
243    only reason for a server or client to support the "GSS-SPNEGO"
244    mechanism is to allow a policy of only using mechanisms below a
245    certain strength if those mechanism's negotiation is protected.  In
246    such a case, a client or server would only want to negotiate those
247    weaker mechanisms through SPNEGO.  In any case, there is no down-
248    negotiation security consideration with using the strongest mechanism
249    and set of options the implementation supports, so for
250    interoperability that mechanism and set of options MUST be negotiable
251    without using the "GSS-SPNEGO" mechanism.
252
253    If a client's policy is to first prefer GSSAPI mechanism X, then non-
254    GSSAPI mechanism Y, then GSSAPI mechanism Z, and if a server supports
255    mechanisms Y and Z but not X, then if the client attempts to
256    negotiate mechanism X by using the "GSS-SPNEGO" SASL mechanism, it
257    may end up using mechanism Z when it should have used mechanism Y.
258    For this reason, implementations MUST exclude from SPNEGO those
259    GSSAPI mechanisms which are weaker than the strongest non-GSSAPI SASL
260    mechanism advertised by the server.
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279 Melnikov                  Expires May 22, 2004                  [Page 5]
280 \f
281 Internet-Draft           SASL GSSAPI mechanisms            November 2003
282
283
284 4. Specification common to all GSSAPI mechanisms
285
286    Each SASL mechanism which uses a GSSAPI mechanism uses the following
287    specification.
288
289    The implementation MAY set any GSSAPI flags or arguments not
290    mentioned in this specification as is necessary for the
291    implementation to enforce its security policy.
292
293 4.1 Client side of authentication protocol exchange
294
295    The client calls GSS_Init_sec_context, passing in
296    input_context_handle of 0 (initially), mech_type of the GSSAPI
297    mechanism for which this SASL mechanism is registered, chan_binding
298    of NULL, and targ_name equal to output_name from GSS_Import_Name
299    called with input_name_type of GSS_C_NT_HOSTBASED_SERVICE and
300    input_name_string of "service@hostname" where "service" is the
301    service name specified in the protocol's profile, and "hostname" is
302    the fully qualified host name of the server.  If the client will be
303    requesting a security layer, it MUST also supply to the
304    GSS_Init_sec_context a mutual_req_flag of TRUE, a sequence_req_flag
305    of TRUE, and an integ_req_flag of TRUE.  If the client will be
306    requesting a security layer providing confidentiality protection, it
307    MUST also supply to the GSS_Init_sec_context a conf_req_flag of TRUE.
308    The client then responds with the resulting output_token.  If
309    GSS_Init_sec_context returns GSS_S_CONTINUE_NEEDED, then the client
310    should expect the server to issue a token in a subsequent challenge.
311    The client must pass the token to another call to
312    GSS_Init_sec_context, repeating the actions in this paragraph.
313
314    When GSS_Init_sec_context returns GSS_S_COMPLETE, the client examines
315    the context to ensure that it provides a level of protection
316    permitted by the client's security policy.  If the context is
317    acceptable, the client takes the following actions: If the last call
318    to GSS_Init_sec_context returned an output_token, then the client
319    responds with the output_token, otherwise the client responds with no
320    data.  The client should then expect the server to issue a token in a
321    subsequent challenge.  The client passes this token to GSS_Unwrap and
322    interprets the first octet of resulting cleartext as a bit-mask
323    specifying the security layers supported by the server and the second
324    through fourth octets as the network byte order maximum size
325    output_message to send to the server (if the resulting cleartext is
326    not 4 octets long, the client fails the negotiation).  The client
327    then constructs data, with the first octet containing the bit-mask
328    specifying the selected security layer, the second through fourth
329    octets containing in network byte order the maximum size
330    output_message the client is able to receive, and the remaining
331    octets containing the authorization identity, encoded according to
332
333
334
335 Melnikov                  Expires May 22, 2004                  [Page 6]
336 \f
337 Internet-Draft           SASL GSSAPI mechanisms            November 2003
338
339
340    the application profile specification.  The authorization identity is
341    not NUL-terminated.  The client passes the data to GSS_Wrap with
342    conf_flag set to FALSE, and responds with the generated
343    output_message.  The client can then consider the server
344    authenticated.
345
346 4.2 Server side of authentication protocol exchange
347
348    The server passes the initial client response to
349    GSS_Accept_sec_context as input_token, setting input_context_handle
350    to 0 (initially), mech_type of the GSSAPI mechanism for which this
351    SASL mechanism is registered, chan_binding of NULL, and
352    acceptor_cred_handle equal to output_cred_handle from
353    GSS_Acquire_cred called with desired_name equal to output_name from
354    GSS_Import_name with input_name_type of GSS_C_NT_HOSTBASED_SERVICE
355    and input_name_string of "service@hostname" where "service" is the
356    service name specified in the protocol's profile, and "hostname" is
357    the fully qualified host name of the server.  If
358    GSS_Accept_sec_context returns GSS_S_CONTINUE_NEEDED, the server
359    returns the generated output_token to the client in challenge and
360    passes the resulting response to another call to
361    GSS_Accept_sec_context, repeating the actions in this paragraph.
362
363    When GSS_Accept_sec_context returns GSS_S_COMPLETE, the server
364    examines the context to ensure that it provides a level of protection
365    permitted by the server's security policy.  If the context is
366    acceptable, the server takes the following actions: If the last call
367    to GSS_Accept_sec_context returned an output_token, the server
368    returns it to the client in a challenge and expects a reply from the
369    client with no data.  Whether or not an output_token was returned
370    (and after receipt of any response from the client to such an
371    output_token), the server then constructs 4 octets of data, with the
372    first octet containing a bit-mask specifying the security layers
373    supported by the server and the second through fourth octets
374    containing in network byte order the maximum size output_token the
375    server is able to receive.  The server must then pass the plaintext
376    to GSS_Wrap with conf_flag set to FALSE and issue the generated
377    output_message to the client in a challenge.  The server must then
378    pass the resulting response to GSS_Unwrap and interpret the first
379    octet of resulting cleartext as the bit-mask for the selected
380    security layer, the second through fourth octets as the network byte
381    order maximum size output_message to send to the client, and the
382    remaining octets as the authorization identity.  The server must
383    verify that the src_name is authorized to authenticate as the
384    authorization identity.  After these verifications, the
385    authentication process is complete.
386
387
388
389
390
391 Melnikov                  Expires May 22, 2004                  [Page 7]
392 \f
393 Internet-Draft           SASL GSSAPI mechanisms            November 2003
394
395
396 4.3 Security layer
397
398    The security layers and their corresponding bit-masks are as follows:
399
400          1 No security layer
401          2 Integrity protection.
402            Sender calls GSS_Wrap with conf_flag set to FALSE
403          4 Confidentiality protection.
404            Sender calls GSS_Wrap with conf_flag set to TRUE
405
406    Other bit-masks may be defined in the future; bits which are not
407    understood must be negotiated off.
408
409    Note that SASL negotiates the maximum size of the output_message to
410    send.  Implementations can use the GSS_Wrap_size_limit call to
411    determine the corresponding maximum size input_message.
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
446
447 Melnikov                  Expires May 22, 2004                  [Page 8]
448 \f
449 Internet-Draft           SASL GSSAPI mechanisms            November 2003
450
451
452 5. IANA Considerations
453
454    The IANA is advised that SASL mechanism names starting with "GSS-"
455    are reserved for SASL mechanisms which conform to this document.  The
456    IANA is directed to place a statement to that effect in the sasl-
457    mechanisms registry.
458
459    Family of SASL mechanisms: YES
460
461    Prefix: GSS-
462
463    Security considerations: RFC [THIS-DOC]
464
465    Published Specification: RFC [THIS-DOC]
466
467    Person & email address to contact for further information: Alexey
468       Melnikov <Alexey.Melnikov@isode.com>
469
470    Intended usage: COMMON
471
472    Author/Change controller: iesg@ietf.org
473
474    The IANA is directed to modify the existing registration for "GSSAPI"
475    as follows.
476
477    Family of SASL mechanisms: NO
478
479    SASL mechanism name: GSSAPI
480
481    Security considerations: ?
482
483    Published Specification: RFC [THIS-DOC]
484
485    Person & email address to contact for further information: Alexey
486       Melnikov <Alexey.Melnikov@isode.com>
487
488    Intended usage: COMMON
489
490    Author/Change controller: iesg@ietf.org
491
492    Additional Information: This mechanism is for the Kerberos V5
493       mechanism of GSSAPI.  Other GSSAPI mechanisms use other SASL
494       mechanism names, as described in this mechanism's published
495       specification.
496
497    The IANA is directed to modify the existing registration for "GSS-
498    SPNEGO" as follows.
499
500
501
502
503 Melnikov                  Expires May 22, 2004                  [Page 9]
504 \f
505 Internet-Draft           SASL GSSAPI mechanisms            November 2003
506
507
508    Family of SASL mechanisms: NO
509
510    SASL mechanism name: GSS-SPNEGO
511
512    Security considerations: See the "SPNEGO" section of RFC [THIS-DOC].
513
514    Published Specification: RFC [THIS-DOC]
515
516    Person & email address to contact for further information: Alexey
517       Melnikov <Alexey.Melnikov@isode.com>
518
519    Intended usage: LIMITED USE
520
521    Author/Change controller: iesg@ietf.org
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559 Melnikov                  Expires May 22, 2004                 [Page 10]
560 \f
561 Internet-Draft           SASL GSSAPI mechanisms            November 2003
562
563
564 6. Security Considerations
565
566    Security issues are discussed throughout this memo.
567
568    When a server or client supports multiple authentication mechanisms,
569    each of which has a different security strength, it is possible for
570    an active attacker to cause a party to use the least secure mechanism
571    supported.  To protect against this sort of attack, a client or
572    server which supports mechanisms of different strengths should have a
573    configurable minimum strength that it will use.  It is not sufficient
574    for this minimum strength check to only be on the server, since an
575    active attacker can change which mechanisms the client sees as being
576    supported, causing the client to send authentication credentials for
577    its weakest supported mechanism.
578
579    The client's selection of a SASL mechanism is done in the clear and
580    may be modified by an active attacker.  It is important for any new
581    SASL mechanisms to be designed such that an active attacker cannot
582    obtain an authentication with weaker security properties by modifying
583    the SASL mechanism name and/or the challenges and responses.
584
585    [SPNEGO] has protection against many of these down-negotiation
586    attacks, SASL does not itself have such protection.  The section
587    titled "SPNEGO" mentions considerations of choosing negotiation
588    through SASL versus SPNEGO.
589
590    The integrity protection provided by the security layer is useless to
591    the client unless the client also requests mutual authentication.
592    Therefore, a client wishing to benefit from the integrity protection
593    of a security layer MUST pass to the GSS_Init_sec_context call a
594    mutual_req_flag of TRUE.
595
596    When constructing the input_name_string, the client should not
597    canonicalize the server's fully qualified domain name using an
598    insecure or untrusted directory service.
599
600    Additional security considerations are in the [SASL] and [GSSAPI]
601    specifications.
602
603
604
605
606
607
608
609
610
611
612
613
614
615 Melnikov                  Expires May 22, 2004                 [Page 11]
616 \f
617 Internet-Draft           SASL GSSAPI mechanisms            November 2003
618
619
620 7. Acknowledgements
621
622    This document is a revision of RFC 2222 written by John G.  Myers.
623    He also contributed significantly to this revision.
624
625    Thank you to Lawrence Greenfield for converting text of this draft to
626    XML format.
627
628    Contributions of many members of the SASL mailing list are gratefully
629    acknowledged.
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671 Melnikov                  Expires May 22, 2004                 [Page 12]
672 \f
673 Internet-Draft           SASL GSSAPI mechanisms            November 2003
674
675
676 Normative References
677
678    [ASN1]           International Organization for Standardization,
679                     "Information Processing Systems - Open Systems
680                     Interconnection - Specification of Abstract Syntax
681                     Notation One (ASN.1)", ISO Standard 8824, December
682                     1990.
683
684    [BASE-ENCODING]  Josefsson, S., "The Base16, Base32, and Base64 Data
685                     Encodings", RFC 3548, July 2003.
686
687    [GSSAPI]         Linn, J., "Generic Security Service Application
688                     Program Interface Version 2, Update 1", RFC 2743,
689                     January 2000.
690
691    [KEYWORDS]       Bradner, S., "Key words for use in RFCs to Indicate
692                     Requirement Levels", BCP 14, RFC 2119, March 1997.
693
694    [KRB5GSS]        Linn, J., "The Kerberos Version 5 GSS-API
695                     Mechanism", RFC 1964, June 1996.
696
697    [MD5]            Rivest, R., "The MD5 Message-Digest Algorithm", RFC
698                     1321, April 1992.
699
700    [SASL]           Myers, J., "Simple Authentication and Security Layer
701                     (SASL)", RFC 2222, October 1997.
702
703    [SASL(rev)]      Melnikov, A., "Simple Authentication and Security
704                     Layer (SASL)", draft-ietf-sasl-rfc2222bis (work in
705                     progress), October 2003.
706
707    [SPNEGO]         Baize, E. and D. Pinkas, "The Simple and Protected
708                     GSS-API Negotiation Mechanism", RFC 2478, December
709                     1998.
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727 Melnikov                  Expires May 22, 2004                 [Page 13]
728 \f
729 Internet-Draft           SASL GSSAPI mechanisms            November 2003
730
731
732 Informative References
733
734    [SPKM1]  Adams, C., "The Simple Public-Key GSS-API Mechanism (SPKM)",
735             RFC 2025, October 1996.
736
737    [UTF8]   Yergeau, F., "UTF-8, a transformation format of ISO 10646",
738             RFC 2279, January 1998.
739
740
741 Author's Address
742
743    Alexey Melnikov (Ed.)
744    Isode Limited
745    5 Castle Business Village
746    36 Station Road
747    Hampton, Middlesex  TW12 2BX
748    UK
749
750    EMail: Alexey.Melnikov@isode.com
751    URI:   http://www.melnikov.ca/
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783 Melnikov                  Expires May 22, 2004                 [Page 14]
784 \f
785 Internet-Draft           SASL GSSAPI mechanisms            November 2003
786
787
788 Full Copyright Statement
789
790    Copyright (C) The Internet Society (2003).  All Rights Reserved.
791
792    This document and translations of it may be copied and furnished to
793    others, and derivative works that comment on or otherwise explain it
794    or assist in its implementation may be prepared, copied, published
795    and distributed, in whole or in part, without restriction of any
796    kind, provided that the above copyright notice and this paragraph are
797    included on all such copies and derivative works.  However, this
798    document itself may not be modified in any way, such as by removing
799    the copyright notice or references to the Internet Society or other
800    Internet organizations, except as needed for the purpose of
801    developing Internet standards in which case the procedures for
802    copyrights defined in the Internet Standards process must be
803    followed, or as required to translate it into languages other than
804    English.
805
806    The limited permissions granted above are perpetual and will not be
807    revoked by the Internet Society or its successors or assigns.
808
809    This document and the information contained herein is provided on an
810    "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
811    TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
812    BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
813    HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
814    MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
815
816 Acknowledgement
817
818    Funding for the RFC Editor function is currently provided by the
819    Internet Society.
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839 Melnikov                  Expires May 22, 2004                 [Page 15]
840 \f
841