idnits 2.17.1 draft-ietf-secsh-gsskeyex-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by 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 : ---------------------------------------------------------------------------- ** The document seems to lack an Introduction section. ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** There are 2 instances of too long lines in the document, the longest one being 2 characters in excess of 72. ** The abstract seems to contain references ([2], [7], [10]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == Line 182 has weird spacing: '... string out...' == Line 190 has weird spacing: '... string out...' == Line 202 has weird spacing: '... string out...' == Line 216 has weird spacing: '... string per...' == Line 218 has weird spacing: '... string out...' == (1 more instance...) -- 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 (March 2, 2001) is 8455 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: '9' is defined on line 478, but no explicit reference was found in the text -- Possible downref: Non-RFC (?) normative reference: ref. '1' ** Obsolete normative reference: RFC 1510 (ref. '3') (Obsoleted by RFC 4120, RFC 6649) ** Downref: Normative reference to an Informational RFC: RFC 1321 (ref. '5') ** Obsolete normative reference: RFC 2478 (ref. '8') (Obsoleted by RFC 4178) -- Possible downref: Non-RFC (?) normative reference: ref. '9' -- Possible downref: Non-RFC (?) normative reference: ref. '10' -- Possible downref: Non-RFC (?) normative reference: ref. '11' Summary: 9 errors (**), 0 flaws (~~), 9 warnings (==), 7 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group J. Hutzelman 3 Internet-Draft CMU 4 Expires: August 31, 2001 J. Salowey 5 Cisco Systems 6 March 2, 2001 8 Using GSSAPI authentication for key exchange in Secure Shell 9 draft-ietf-secsh-gsskeyex-01 11 Status of this Memo 13 This document is an Internet-Draft and is in full conformance with 14 all provisions of Section 10 of RFC2026. 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 19 Internet-Drafts. 21 Internet-Drafts are draft documents valid for a maximum of six 22 months and may be updated, replaced, or obsoleted by other documents 23 at any 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 August 31, 2001. 34 Copyright Notice 36 Copyright (C) The Internet Society (2001). All Rights Reserved. 38 Abstract 40 This memo describes a method for using the Generic Security Service 41 Application Program Interface [2] for key exchange in the Secure 42 Shell protocol, by defining a class of SSH key exchange methods 43 which use GSSAPI to authenticate the Diffie-Hellman exchange 44 described in [10]. 46 This memo also defines a new host public key algorithm which can be 47 used when no operations are needed using a host's public key, and a 48 new user authentication method which allows an authorization name to 49 be used in conjunction with any authentication which has already 50 occurred as a side-effect of key exchange. 52 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 53 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 54 document are to be interpreted as described in [7]. 56 1. GSSAPI Authenticated Diffie-Hellman Key Exchange 58 This section defines a class of key exchange methods which combine 59 the Diffie-Hellman key exchange from section 6 of [10] with mutual 60 authentication using GSSAPI. 62 Since the GSSAPI key exchange methods described in this section do 63 not require the use of public key signature or encryption 64 algorithms, they MAY be used with any host key algorithm, including 65 the "null" algorithm described in section 2 of this document. 67 1.1 Generic method description 69 The following symbols are used in this description: 71 o C is the client, and S is the server 73 o p is a large safe prime, g is a generator for a subgroup of 74 GF(p), and q is the order of the subgroup 76 o V_S is S's version string, and V_C is C's version string 78 o I_C is C's KEXINIT message, and I_S is S's KEXINIT message 80 1. C generates a random number x (1 < x < q) and computes e = g^x 81 mod p. 83 2. C calls GSS_Init_sec_context, using the most recent reply token 84 received from S during this exchange, if any. For this call, 85 the client MUST set the mutual_req_flag to "true" to request 86 that mutual authentication be performed. It also MUST set the 87 integ_req_flag to "true" to request that per-message integrity 88 protection be supported for this context. In addition, the 89 deleg_req_flag MAY be set to "true" to request access 90 delegation, if requested by the user. Since the key exchange 91 process authenticates only the host, the setting of the 92 anon_req_flag is immaterial to this process. If the client does 93 not support the "external-keyx" user authentication method 94 described in section 3 of this document, or does not intend to 95 use that method, then the anon_req_flag SHOULD be set to "true". 96 Otherwise, this flag MAY be set to true if the client wishes to 97 hide its identity. 99 * If the resulting major_status code is GSS_S_COMPLETE and the 100 mutual_state flag is not true, then mutual authentication has 101 not been established, and the key exchange MUST fail. 103 * If the resulting major_status code is GSS_S_COMPLETE and the 104 integ_avail flag is not true, then per-message integrity 105 protection is not available, and the key exchange MUST fail. 107 * If the resulting major_status code is GSS_S_COMPLETE and the 108 mutual_state flag is true, the resulting output token is sent 109 to S. 111 * If the resulting major_status code is GSS_S_CONTINUE_NEEDED, 112 the the output_token is sent to S, which will reply with a 113 new token to be provided to GSS_Init_sec_context. 115 * The client MUST also include "e" with the first message it 116 sends to the server during this process; if the server 117 receives more than one "e" or none at all, the key exchange 118 fails. 120 * It is an error if the call does not produce a token of 121 non-zero length to be sent to the server. In this case, the 122 key exchange MUST fail. 124 3. S calls GSS_Accept_sec_context, using the token received from C. 126 * If the resulting major_status code is GSS_S_COMPLETE and the 127 mutual_state flag is not true, then mutual authentication has 128 not been established, and the key exchange MUST fail. 130 * If the resulting major_status code is GSS_S_COMPLETE and the 131 mutual_state flag is true, then the security context has been 132 established, and processing continues with step 4. 134 * If the resulting major_status code is GSS_S_CONTINUE_NEEDED, 135 then the output token is sent to C, and processing continues 136 with step 2. 138 * If the resulting major_status code is GSS_S_COMPLETE, but a 139 non-zero-length reply token is returned, then that token is 140 sent to the client. 142 4. S generates a random number y (0 < y < q) and computes f = g^y 143 mod p. It computes K = e ^ y mod p, and H = hash(V_C || V_S || 144 I_C || I_S || e || f || K). It then calls GSS_GetMIC to obtain 145 a GSSAPI message integrity code for H. S then sends f and the 146 MIC to C. 148 5. This step is performed only if the server's final call to 149 GSS_Accept_sec_context produced a non-zero-length final reply 150 token to be sent to the client _and_ no previous call by the 151 client to GSS_Init_sec_context has resulted in a major_status of 152 GSS_S_COMPLETE. Under these conditions, the client makes an 153 additional call to GSS_Init_sec_context to process the final 154 reply token. This call is made exactly as described above. 155 However, if the resulting major_status is anything other than 156 GSS_S_COMPLETE, or a non-zero-length token is returned, it is an 157 error and the key exchange MUST fail. 159 6. C computes K = f^x mod p, and H = hash(V_C || V_S || I_C || I_S 160 || e || f || K). It then calls GSS_VerifyMIC to verify that the 161 MIC sent by S matches H. 163 Either side MUST NOT send or accept e or f values that are not in 164 the range [1, p-1]. If this condition is violated, the key exchange 165 fails. 167 If any call to GSS_Init_sec_context or GSS_Accept_sec_context 168 returns a major_status other than GSS_S_COMPLETE or 169 GSS_S_CONTINUE_NEEDED, or any other GSSAPI call returns a 170 major_status other than GSS_S_COMPLETE, the key exchange fails. 172 This is implemented with the following messages. The hash algorithm 173 for computing the exchange hash is defined by the method name, and 174 is called HASH. The group used for Diffie-Hellman key exchange and 175 the underlying GSSAPI mechanism are also defined by the method name. 177 After the client's first call to GSS_Init_sec_context, it sends the 178 following: 180 byte SSH_MSG_GSSAPI_INIT 181 boolean TRUE 182 string output_token (from GSS_Init_sec_context) 183 mpint e 185 Each time the server's call to GSS_Accept_sec_context returns a 186 major_status code of GSS_S_CONTINUE_NEEDED, it sends the following 187 reply to the client: 189 byte SSH_MSG_GSSAPI_CONTINUE 190 string output_token (from GSS_Accept_sec_context) 192 If the client receives this message appears after a call to 193 GSS_Init_sec_context has returned a major_status code of 194 GSS_S_COMPLETE, a protocol error has occurred and the key exchange 195 MUST fail. 197 Each time the client receives the message described above, it makes 198 another call to GSS_Init_sec_context. It then sends the following: 200 byte SSH_MSG_GSSAPI_INIT 201 boolean FALSE 202 string output_token (from GSS_Init_sec_context) 204 The server and client continue to trade these two messages as long 205 as the server's calls to GSS_Accept_sec_context result in 206 major_status codes of GSS_S_CONTINUE_NEEDED. When a call results in 207 a major_status code of GSS_S_COMPLETE, it sends one of two final 208 messages. 210 If the server's final call to GSS_Accept_sec_contents (resulting in 211 a major_status code of GSS_S_COMPLETE) returns a non-zero-length 212 token to be sent to the client, it sends the following: 214 byte SSH_MSG_GSSAPI_COMPLETE 215 mpint f 216 string per_msg_token (MIC of H) 217 boolean TRUE 218 string output_token (from GSS_Accept_sec_context) 220 If the client receives this message appears after a call to 221 GSS_Init_sec_context has returned a major_status code of 222 GSS_S_COMPLETE, a protocol error has occurred and the key exchange 223 MUST fail. 225 If the server's final call to GSS_Accept_sec_contents (resulting in 226 a major_status code of GSS_S_COMPLETE) returns a zero-length token 227 or no token at all, it sends the following: 229 byte SSH_MSG_GSSAPI_COMPLETE 230 mpint f 231 string per_msg_token (MIC of H) 232 boolean FALSE 234 If the client receives this message when no call to 235 GSS_Init_sec_context has yet resulted in a major_status code of 236 GSS_S_COMPLETE, a protocol error has occurred and the key exchange 237 MUST fail. 239 The hash H is computed as the HASH hash of the concatenation of the 240 following: 242 string V_C, the client's version string (CR and NL excluded) 243 string V_S, the server's version string (CR and NL excluded) 244 string I_C, the payload of the client's SSH_MSG_KEXINIT 245 string I_S, the payload of the server's SSH_MSG_KEXINIT 246 mpint e, exchange value sent by the client 247 mpint f, exchange value sent by the server 248 mpint K, the shared secret 250 This value is called the exchange hash, and it is used to 251 authenticate the key exchange. The exchange hash SHOULD be kept 252 secret. 254 The GSS_GetMIC call MUST be applied over H, not the original data. 256 1.2 gss-group1-sha1-* 258 Each of these methods specifies GSSAPI authenticated Diffie-Hellman 259 key exchange as described in section 1.1 of this document, with 260 SHA-1 as HASH, and the group defined in section 6.1 of [10]. The 261 method name for each method is the concatenation of the string 262 "gss-group1-sha1-" with the Base64 encoding of the MD5 hash [5] of 263 the ASN.1 DER encoding [1] of the underlying GSSAPI mechanism's OID. 264 Base64 encoding is described in section 6.8 of [6]. 266 Each and every such key exchange method is implicitly registered by 267 this specification. The IESG is considered to be the owner of all 268 such key exchange methods; this does NOT imply that the IESG is 269 considered to be the owner of the underlying GSSAPI mechanism. 271 1.3 Other GSSAPI key exchange methods 273 Key exchange method names starting with "gss-" are reserved for key 274 exchange methods which conform to this document; in particular, for 275 those methods which use the GSSAPI authenticated Diffie-Hellman key 276 exchange algorithm described in section 1.1 of this document, 277 including any future methods which use different groups and/or hash 278 functions. The intent is that the names for any such future methods 279 methods be defined in a similar manner to that used in section 1.2 280 of this document. 282 1.4 SPNEGO 284 The use of the Simple and Protected GSS-API Negotiation Mechanism 285 [8] in conjunction with the key exchange methods described in this 286 document is both unnecessary and undesirable. As a result, key 287 exchange mechanisms conforming to this document MUST NOT use SPNEGO 288 as the underlying GSSAPI mechanism. 290 Since SSH performs its own negotiation of key exchange methods, and 291 there exists a separate method name corresponding to every possible 292 underlying GSSAPI mechanism, the negotiation capability of SPNEGO 293 alone does not provide any added benefit. In fact, as described 294 below, it has the potential to result in the use of a weaker method 295 than desired. 297 Normally, SPNEGO provides the added benefit of protecting the GSSAPI 298 mechanism negotiation. It does this by having the server compute a 299 MIC of the list of mechanisms proposed by the client, and then 300 checking that value at the client. The key exchange methods 301 described in this document already perform an equivalent operation; 302 namely, they generate a MIC of the SSH exchange hash, which is a 303 hash of several items including the lists of key exchange mechanisms 304 supported by both sides. Thus, the extra level of protection 305 offered by SPNEGO is unnecessary in this case. 307 The use of SPNEGO combined with GSSAPI mechanisms used without 308 SPNEGO can lead to interoperability problems. For example, a client 309 which supports key exchange using the Kerberos V5 GSSAPI mechanism 310 [4] only underneath SPNEGO will not interoperate with a server which 311 supports key exchange only using the Kerberos V5 GSSAPI mechanism 312 directly. As a result, allowing GSSAPI mechanisms to be used both 313 with and without SPNEGO is undesirable. 315 If a client's policy is to first prefer GSSAPI-based key exchange 316 method X, then non-GSSAPI method Y, then GSSAPI-based method Z, and 317 if a server supports mechanisms Y and Z but not X, then an attempt 318 to use SPNEGO to negotiate a GSSAPI mechanism might result in the 319 use of method Z when method Y would have been preferable. As a 320 result, the use of SPNEGO could result in the subversion of the 321 negotiation algorithm for key exchange methods as described in 322 section 5.1 of [10]. 324 1.5 Naming Conventions 326 In order to establish a GSSAPI security context, the SSH client 327 needs to determine the appropriate targ_name to use in identifying 328 the server when calling GSS_Init_sec_context. For this purpose, the 329 GSSAPI mechanism-independent name form for host-based services is 330 used, as described in section 4.1 of [2]. 332 In particular, the targ_name to pass to GSS_Init_sec_context is 333 obtained by calling GSS_Import_name with an input_name_type of 334 GSS_C_NT_HOSTBASED_SERVICE, and an input_name_string consisting of 335 the string "host@" concatenated with the hostname of the SSH server. 337 1.6 Channel Bindings 339 This document recommends that channel bindings SHOULD NOT be 340 specified in the calls during context establishment. This document 341 does not specify any standard data to be used as channel bindings 342 and the use of network addresses as channel bindings may break SSH 343 in environments where it is most useful. 345 2. Null Host Key Algorithm 347 The "null" host key algorithm has no associated host key material, 348 and provides neither signature nor encryption algorithms. Thus, it 349 can be used only with key exchange methods that do not require any 350 public-key operations and do not require the use of host public key 351 material. The key exchange methods described in section 1 of this 352 document are examples of such methods. 354 This algorithm is used when, as a matter of configuration, the host 355 does not have or does not wish to use a public key. For example, it 356 can be used when the administrator has decided as a matter of policy 357 to require that all key exchanges be authenticated using Kerberos 358 [3], and thus the only permitted key exchange method is the 359 GSSAPI-authenticated Diffie-Hellman exchange described above, with 360 Kerberos V5 as the underlying GSSAPI mechanism. In such a 361 configuration, the server implementation supports the "ssh-dss" key 362 algorithm (as required by [10], but could be prohibited by 363 configuration from using it. In this situation, the server needs 364 some key exchange algorithm to advertise; the "null" algorithm fills 365 this purpose. 367 Note that the use of the "null" algorithm in this way means that the 368 server will not be able to interoperate with clients which do not 369 support this algorithm. This is not a significant problem, since in 370 the configuration described, it will also be unable to interoperate 371 with implementations that do not support the GSSAPI-authenticated 372 key exchange and Kerberos. 374 Any implementation supporting at least one key exchange method which 375 conforms to section 1 of this document MUST also support the "null" 376 host key algorithm. Servers MUST NOT advertise the "null" host key 377 algorithm unless it is the only algorithm advertised. 379 3. External Key Exchange user authentication 381 This section describes a user authentication method building on the 382 framework described in [11]. This method relies upon the key 383 exchange to authenticate both the client and the server. If the key 384 exchange did not successfully perform these functions then the 385 server MUST always respond to this request with 386 SSH_MSG_USERAUTH_FAILURE with partial success set to false. 388 The new mechanism is defined as follows: 390 byte SSH_MSG_USERAUTH_REQUEST 391 string authorization-ID 392 string service 393 string "external-keyx" 395 If the user authenticated in the key-exchange is allowed to assume 396 the authorization identity, this method is successful, and the 397 server responds with SSH_MSG_USERAUTH_SUCCESS if no more 398 authentications are needed, or with SSH_MSG_USERAUTH_FAILURE with 399 partial success set to true if more authentications are needed. 401 If the user authenticated in the key-exchange is not allowed to 402 assume the authorization identity, then SSH_MSG_USERAUTH_FAILURE is 403 returned with partial success set to false. 405 Any implementation supporting at least one key exchange method which 406 conforms to section 1 of this document SHOULD also support the 407 "external-keyx" user authentication method, in order to allow user 408 authentication to be performed at the same time as key exchange, 409 thereby reducing the number of round trips needed for connection 410 setup. 412 4. Summary of Message Numbers 414 The following message numbers have been defined in this document: 416 #define SSH_MSG_GSSAPI_INIT 30 417 #define SSH_MSG_GSSAPI_CONTINUE 31 418 #define SSH_MSG_GSSAPI_COMPLETE 32 420 The numbers 30-49 are key exchange specific and may be redefined by 421 other kex methods. 423 5. Security Considerations 425 This document describes an authentication and key-exchange protocol. 426 As such, security considerations are discussed throughout. 428 This protocol depends on the SSH protocol itself, the GSSAPI, any 429 underlying GSSAPI mechanisms which are used, and any protocols on 430 which such mechanisms might depend. Each of these components plays 431 a part in the security of the resulting connection, and each will 432 have its own security considerations. 434 The key exchange method described in section 1 of this document 435 depends on the underlying GSSAPI mechanism to provide both mutual 436 authentication and per-message integrity services. If either of 437 these features is not supported by a particular GSSAPI mechanism, or 438 by a particular implementation of a GSSAPI mechanism, then the key 439 exchange is not secure and MUST fail. 441 In order for the "external-keyx" user authentication method to be 442 used, it MUST have access to user authentication information 443 obtained as a side-effect of the key exchange. If this information 444 is unavailable, the authentication MUST fail. 446 6. Acknowledgements 448 The authors would like to thank Sam Hartman and Simon Wilkinson for 449 their invaluable assistance with this document. 451 References 453 [1] ISO/IEC, "Specification of Abstract Syntax Notation One 454 (ASN.1)", ISO/IEC 8824, November 1998. 456 [2] Linn, J., "Generic Security Service Application Program 457 Interface Version 2, Update 1", RFC 2743, January 2000. 459 [3] Kohl, J. and C. Neuman, "The Kerberos Network Authentication 460 Service (V5)", RFC 1510, September 1993. 462 [4] Linn, J., "The Kerberos Version 5 GSS-API Mechanism", RFC 463 1964, June 1996. 465 [5] Rivest, R., "The MD5 Message-Digest Algorithm", RFC 1321, 466 April 1992. 468 [6] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 469 Extensions (MIME) Part One: Format of Internet Message 470 Bodies", RFC 2045, November 1996. 472 [7] Bradner, S., "Key words for use in RFCs to Indicate 473 Requirement Levels", RFC 2119, BCP 14, March 1997. 475 [8] Baize, E. and D. Pinkas, "The Simple and Protected GSS-API 476 Negotiation Mechanism", RFC 2478, December 1998. 478 [9] Ylonen, T., Kivinen, T., Saarinen, M., Rinne, T. and S. 479 Lehtinen, "SSH Protocol Architecture", November 2000. 481 [10] Ylonen, T., Kivinen, T., Saarinen, M., Rinne, T. and S. 482 Lehtinen, "SSH Transport Layer Protocol", November 2000. 484 [11] Ylonen, T., Kivinen, T., Saarinen, M., Rinne, T. and S. 485 Lehtinen, "SSH Authentication Protocol", November 2000. 487 Authors' Addresses 489 Jeffrey Hutzelman 490 Carnegie Mellon University 491 5000 Forbes Ave 492 Pittsburgh, PA 15213 493 US 495 Phone: +1 412 268 7225 496 EMail: jhutz+@cmu.edu 497 URI: http://www.cs.cmu.edu/~jhutz/ 498 Joseph Salowey 499 Cisco Systems 500 Bldg 20 501 725 Alder Drive 502 Milpitas, CA 95035 503 US 505 Phone: +1 408 525 6381 506 EMail: jsalowey@cisco.com 508 Full Copyright Statement 510 Copyright (C) The Internet Society (2001). All Rights Reserved. 512 This document and translations of it may be copied and furnished to 513 others, and derivative works that comment on or otherwise explain it 514 or assist in its implementation may be prepared, copied, published 515 and distributed, in whole or in part, without restriction of any 516 kind, provided that the above copyright notice and this paragraph 517 are included on all such copies and derivative works. However, this 518 document itself may not be modified in any way, such as by removing 519 the copyright notice or references to the Internet Society or other 520 Internet organizations, except as needed for the purpose of 521 developing Internet standards in which case the procedures for 522 copyrights defined in the Internet Standards process must be 523 followed, or as required to translate it into languages other than 524 English. 526 The limited permissions granted above are perpetual and will not be 527 revoked by the Internet Society or its successors or assigns. 529 This document and the information contained herein is provided on an 530 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 531 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 532 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 533 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 534 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 536 Acknowledgement 538 Funding for the RFC editor function is currently provided by the 539 Internet Society.