idnits 2.17.1 draft-ietf-secsh-gsskeyex-03.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: ---------------------------------------------------------------------------- ** The document is more than 15 pages and seems to lack a Table of Contents. == 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 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], [11]), 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 226 has weird spacing: '... string out...' == Line 234 has weird spacing: '... string ser...' == Line 246 has weird spacing: '... string out...' == Line 257 has weird spacing: '... string out...' == Line 271 has weird spacing: '... string per...' == (10 more instances...) -- 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 (January 14, 2002) is 8139 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) -- 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) == Outdated reference: A later version (-22) exists of draft-ietf-secsh-architecture-11 == Outdated reference: A later version (-25) exists of draft-ietf-secsh-connect-14 == Outdated reference: A later version (-24) exists of draft-ietf-secsh-transport-11 == Outdated reference: A later version (-27) exists of draft-ietf-secsh-userauth-13 ** Obsolete normative reference: RFC 2279 (ref. '13') (Obsoleted by RFC 3629) ** Obsolete normative reference: RFC 1766 (ref. '14') (Obsoleted by RFC 3066, RFC 3282) Summary: 11 errors (**), 0 flaws (~~), 12 warnings (==), 4 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: July 15, 2002 J. Salowey 5 Cisco Systems 6 J. Galbraith 7 Van Dyke Technologies, Inc. 8 V. Welch 9 U Chicago / ANL 10 January 14, 2002 12 GSSAPI Authentication and Key Exchange for the Secure Shell Protocol 13 draft-ietf-secsh-gsskeyex-03 15 Status of this Memo 17 This document is an Internet-Draft and is in full conformance with 18 all provisions of Section 10 of RFC2026. 20 Internet-Drafts are working documents of the Internet Engineering 21 Task Force (IETF), its areas, and its working groups. Note that 22 other groups may also distribute working documents as 23 Internet-Drafts. 25 Internet-Drafts are draft documents valid for a maximum of six 26 months and may be updated, replaced, or obsoleted by other documents 27 at any time. It is inappropriate to use Internet-Drafts as reference 28 material or to cite them other than as "work in progress." 30 The list of current Internet-Drafts can be accessed at 31 http://www.ietf.org/ietf/1id-abstracts.txt. 33 The list of Internet-Draft Shadow Directories can be accessed at 34 http://www.ietf.org/shadow.html. 36 This Internet-Draft will expire on July 15, 2002. 38 Copyright Notice 40 Copyright (C) The Internet Society (2002). All Rights Reserved. 42 Abstract 44 The Secure Shell protocol (SSH) is a protocol for secure remote 45 login and other secure network services over an insecure network. 47 The Generic Security Service Application Program Interface (GSS-API) 48 [2] provides security services to callers in a mechanism-independent 49 fashion. 51 This memo describes methods for using the GSS-API for authentication 52 and key exchange in SSH. It defines an SSH user authentication 53 method which uses a specified GSSAPI mechanism to authenticate a 54 user, and a family of SSH key exchange methods which use GSSAPI to 55 authenticate the Diffie-Hellman exchange described in [11]. 57 This memo also defines a new host public key algorithm which can be 58 used when no operations are needed using a host's public key, and a 59 new user authentication method which allows an authorization name to 60 be used in conjunction with any authentication which has already 61 occurred as a side-effect of key exchange. 63 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 64 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 65 document are to be interpreted as described in [7]. 67 1. Introduction 69 This document describes the methods used to perform key exchange and 70 user authentication in the Secure Shell protocol using the GSSAPI. 71 To do this, it defines a family of key exchange methods, two user 72 authentication methods, and a new host key algorithm. These 73 definitions allow any GSSAPI mechanism to be used with the Secure 74 Shell protocol. 76 This document should be read only after reading the documents 77 describing the SSH protocol architecture [9], transport layer 78 protocol [11], and user authentication protocol [12]. This document 79 freely uses terminology and notation from the architecture document 80 without reference or further explanation. 82 1.1 SSH terminology 84 The data types used in the packets are defined in the SSH 85 architecture document [9]. It is particularly important to note the 86 definition of string allows binary content. 88 The SSH_MSG_USERAUTH_REQUEST packet refers to a service; this 89 service name is an SSH service name, and has no relationship to 90 GSSAPI service names. Currently, the only defined service name is 91 "ssh-connection", which refers to the SSH connection protocol [10]. 93 2. GSSAPI Authenticated Diffie-Hellman Key Exchange 95 This section defines a class of key exchange methods which combine 96 the Diffie-Hellman key exchange from section 6 of [11] with mutual 97 authentication using GSSAPI. 99 Since the GSSAPI key exchange methods described in this section do 100 not require the use of public key signature or encryption 101 algorithms, they MAY be used with any host key algorithm, including 102 the "null" algorithm described in Section 5. 104 2.1 Generic GSSAPI Key Exchange 106 The following symbols are used in this description: 108 o C is the client, and S is the server 110 o p is a large safe prime, g is a generator for a subgroup of 111 GF(p), and q is the order of the subgroup 113 o V_S is S's version string, and V_C is C's version string 115 o I_C is C's KEXINIT message, and I_S is S's KEXINIT message 117 1. C generates a random number x (1 < x < q) and computes e = g^x 118 mod p. 120 2. C calls GSS_Init_sec_context, using the most recent reply token 121 received from S during this exchange, if any. For this call, 122 the client MUST set the mutual_req_flag to "true" to request 123 that mutual authentication be performed. It also MUST set the 124 integ_req_flag to "true" to request that per-message integrity 125 protection be supported for this context. In addition, the 126 deleg_req_flag MAY be set to "true" to request access 127 delegation, if requested by the user. Since the key exchange 128 process authenticates only the host, the setting of the 129 anon_req_flag is immaterial to this process. If the client does 130 not support the "external-keyx" user authentication method 131 described in Section 4, or does not intend to use that method, 132 then the anon_req_flag SHOULD be set to "true". Otherwise, this 133 flag MAY be set to true if the client wishes to hide its 134 identity. 136 * If the resulting major_status code is GSS_S_COMPLETE and the 137 mutual_state flag is not true, then mutual authentication has 138 not been established, and the key exchange MUST fail. 140 * If the resulting major_status code is GSS_S_COMPLETE and the 141 integ_avail flag is not true, then per-message integrity 142 protection is not available, and the key exchange MUST fail. 144 * If the resulting major_status code is GSS_S_COMPLETE and both 145 the mutual_state and integ_avail flags are true, the 146 resulting output token is sent to S. 148 * If the resulting major_status code is GSS_S_CONTINUE_NEEDED, 149 the the output_token is sent to S, which will reply with a 150 new token to be provided to GSS_Init_sec_context. 152 * The client MUST also include "e" with the first message it 153 sends to the server during this process; if the server 154 receives more than one "e" or none at all, the key exchange 155 fails. 157 * It is an error if the call does not produce a token of 158 non-zero length to be sent to the server. In this case, the 159 key exchange MUST fail. 161 3. S calls GSS_Accept_sec_context, using the token received from C. 163 * If the resulting major_status code is GSS_S_COMPLETE and the 164 mutual_state flag is not true, then mutual authentication has 165 not been established, and the key exchange MUST fail. 167 * If the resulting major_status code is GSS_S_COMPLETE and the 168 integ_avail flag is not true, then per-message integrity 169 protection is not available, and the key exchange MUST fail. 171 * If the resulting major_status code is GSS_S_COMPLETE and both 172 the mutual_state and integ_avail flags are true, then the 173 security context has been established, and processing 174 continues with step 4. 176 * If the resulting major_status code is GSS_S_CONTINUE_NEEDED, 177 then the output token is sent to C, and processing continues 178 with step 2. 180 * If the resulting major_status code is GSS_S_COMPLETE, but a 181 non-zero-length reply token is returned, then that token is 182 sent to the client. 184 4. S generates a random number y (0 < y < q) and computes f = g^y 185 mod p. It computes K = e ^ y mod p, and H = hash(V_C || V_S || 186 I_C || I_S || K_S || e || f || K). It then calls GSS_GetMIC to 187 obtain a GSSAPI message integrity code for H. S then sends f 188 and the MIC to C. 190 5. This step is performed only if the server's final call to 191 GSS_Accept_sec_context produced a non-zero-length final reply 192 token to be sent to the client _and_ no previous call by the 193 client to GSS_Init_sec_context has resulted in a major_status of 194 GSS_S_COMPLETE. Under these conditions, the client makes an 195 additional call to GSS_Init_sec_context to process the final 196 reply token. This call is made exactly as described above. 197 However, if the resulting major_status is anything other than 198 GSS_S_COMPLETE, or a non-zero-length token is returned, it is an 199 error and the key exchange MUST fail. 201 6. C computes K = f^x mod p, and H = hash(V_C || V_S || I_C || I_S 202 || K_S || e || f || K). It then calls GSS_VerifyMIC to verify 203 that the MIC sent by S matches H. 205 Either side MUST NOT send or accept e or f values that are not in 206 the range [1, p-1]. If this condition is violated, the key exchange 207 fails. 209 If any call to GSS_Init_sec_context or GSS_Accept_sec_context 210 returns a major_status other than GSS_S_COMPLETE or 211 GSS_S_CONTINUE_NEEDED, or any other GSSAPI call returns a 212 major_status other than GSS_S_COMPLETE, the key exchange fails. If 213 the key exchange fails due to a GSSAPI error on the server, the 214 server SHOULD send a message informing the client of the details of 215 the error before terminating the connection as required by [11]. 217 This is implemented with the following messages. The hash algorithm 218 for computing the exchange hash is defined by the method name, and 219 is called HASH. The group used for Diffie-Hellman key exchange and 220 the underlying GSSAPI mechanism are also defined by the method name. 222 After the client's first call to GSS_Init_sec_context, it sends the 223 following: 225 byte SSH_MSG_KEXGSS_INIT 226 string output_token (from GSS_Init_sec_context) 227 mpint e 229 Upon receiving the SSH_MSG_KEXGSS_INIT message, the server MAY send 230 the following message, prior to any other messages, to inform the 231 client of its host key. 233 byte SSH_MSG_KEXGSS_HOSTKEY 234 string server public host key and certificates (K_S) 236 Since this key exchange method does not require the host key to be 237 used for any encryption operations, this message is OPTIONAL. If 238 the "null" host key algorithm described in Section 5 is used, this 239 message MUST NOT be sent. 241 Each time the server's call to GSS_Accept_sec_context returns a 242 major_status code of GSS_S_CONTINUE_NEEDED, it sends the following 243 reply to the client: 245 byte SSH_MSG_KEXGSS_CONTINUE 246 string output_token (from GSS_Accept_sec_context) 248 If the client receives this message after a call to 249 GSS_Init_sec_context has returned a major_status code of 250 GSS_S_COMPLETE, a protocol error has occurred and the key exchange 251 MUST fail. 253 Each time the client receives the message described above, it makes 254 another call to GSS_Init_sec_context. It then sends the following: 256 byte SSH_MSG_KEXGSS_CONTINUE 257 string output_token (from GSS_Init_sec_context) 259 The server and client continue to trade these two messages as long 260 as the server's calls to GSS_Accept_sec_context result in 261 major_status codes of GSS_S_CONTINUE_NEEDED. When a call results in 262 a major_status code of GSS_S_COMPLETE, it sends one of two final 263 messages. 265 If the server's final call to GSS_Accept_sec_context (resulting in a 266 major_status code of GSS_S_COMPLETE) returns a non-zero-length token 267 to be sent to the client, it sends the following: 269 byte SSH_MSG_KEXGSS_COMPLETE 270 mpint f 271 string per_msg_token (MIC of H) 272 boolean TRUE 273 string output_token (from GSS_Accept_sec_context) 275 If the client receives this message after a call to 276 GSS_Init_sec_context has returned a major_status code of 277 GSS_S_COMPLETE, a protocol error has occurred and the key exchange 278 MUST fail. 280 If the server's final call to GSS_Accept_sec_context (resulting in a 281 major_status code of GSS_S_COMPLETE) returns a zero-length token or 282 no token at all, it sends the following: 284 byte SSH_MSG_KEXGSS_COMPLETE 285 mpint f 286 string per_msg_token (MIC of H) 287 boolean FALSE 289 If the client receives this message when no call to 290 GSS_Init_sec_context has yet resulted in a major_status code of 291 GSS_S_COMPLETE, a protocol error has occurred and the key exchange 292 MUST fail. 294 In the event of a GSSAPI error on the server, the server may send 295 the following message before terminating the connection: 297 byte SSH_MSG_KEXGSS_ERROR 298 uint32 major_status 299 uint32 minor_status 300 string message 301 string language tag 303 The message text MUST be encoded in the UTF-8 encoding described in 304 [13]. Language tags are those described in [14]. Note that the 305 message text may contain multiple lines separated by carriage 306 return-line feed (CRLF) sequences. Application developers should 307 take this into account when displaying these messages. 309 The hash H is computed as the HASH hash of the concatenation of the 310 following: 312 string V_C, the client's version string (CR and NL excluded) 313 string V_S, the server's version string (CR and NL excluded) 314 string I_C, the payload of the client's SSH_MSG_KEXINIT 315 string I_S, the payload of the server's SSH_MSG_KEXINIT 316 string K_S, the host key 317 mpint e, exchange value sent by the client 318 mpint f, exchange value sent by the server 319 mpint K, the shared secret 321 This value is called the exchange hash, and it is used to 322 authenticate the key exchange. The exchange hash SHOULD be kept 323 secret. If no SSH_MSG_KEXGSS_HOSTKEY message has been send by the 324 client or received by the server, then the empty string is used in 325 place of K_S when computing the exchange hash. 327 The GSS_GetMIC call MUST be applied over H, not the original data. 329 2.2 gss-group1-sha1-* 331 Each of these methods specifies GSSAPI authenticated Diffie-Hellman 332 key exchange as described in Section 2.1 with SHA-1 as HASH, and the 333 group defined in section 6.1 of [11]. The method name for each 334 method is the concatenation of the string "gss-group1-sha1-" with 335 the Base64 encoding of the MD5 hash [5] of the ASN.1 DER encoding 336 [1] of the underlying GSSAPI mechanism's OID. Base64 encoding is 337 described in section 6.8 of [6]. 339 Each and every such key exchange method is implicitly registered by 340 this specification. The IESG is considered to be the owner of all 341 such key exchange methods; this does NOT imply that the IESG is 342 considered to be the owner of the underlying GSSAPI mechanism. 344 2.3 Other GSSAPI key exchange methods 346 Key exchange method names starting with "gss-" are reserved for key 347 exchange methods which conform to this document; in particular, for 348 those methods which use the GSSAPI authenticated Diffie-Hellman key 349 exchange algorithm described in Section 2.1, including any future 350 methods which use different groups and/or hash functions. The 351 intent is that the names for any such future methods methods be 352 defined in a similar manner to that used in Section 2.2. 354 3. GSSAPI User Authentication 356 This section describes a general-purpose user authentication method 357 based on [2]. It is intended to be run over the SSH user 358 authentication protocol [12]. 360 The authentication method name for this protocol is "gssapi". 362 3.1 GSSAPI Authentication Overview 364 GSSAPI authentication must maintain a context. Authentication 365 begins when the client sends a SSH_MSG_USERAUTH_REQUEST, which 366 specifies the mechanism OIDs the client supports. 368 If the server supports any of the requested mechanism OIDs, the 369 server sends a SSH_MSG_USERAUTH_GSSAPI_RESPONSE message containing 370 the mechanism OID. 372 After the client receives SSH_MSG_USERAUTH_GSSAPI_RESPONSE, the 373 client and server exchange SSH_MSG_USERAUTH_GSSAPI_TOKEN packets 374 until the authentication mechanism either succeeds or fails. 376 If at any time during the exchange, the client sends a new 377 SSH_MSG_USERAUTH_REQUEST packet, the GSSAPI context is completely 378 discarded and destroyed, and any further GSSAPI authentication MUST 379 restart from the beginning. 381 3.2 Initiating GSSAPI authentication 383 The GSSAPI authentication method is initiated when the client sends 384 a SSH_MSG_USERAUTH_REQUEST: 386 byte SSH_MSG_USERAUTH_REQUEST 387 string user name (in ISO-10646 UTF-8 encoding) 388 string service name (in US-ASCII) 389 string "gssapi" (US-ASCII method name) 390 uint32 n, the number of mechanism OIDs client supports 391 string[n] mechanism OIDs 393 Mechanism OIDs are encoded according to the ASN.1 basic encoding 394 rules (BER), as described in [1] and in section 3.1 of [2]. The 395 mechanism OIDs MUST be listed in order of preference, and the server 396 must choose the first mechanism OID on the list that it supports. 398 The client SHOULD NOT send more then one gssapi mechanism OID unless 399 there are no non-GSSAPI authentication methods between the GSSAPI 400 mechanisms in the order of preference, otherwise, authentication 401 methods may be executed out of order. 403 If the server does not support any of the specified OIDs, the server 404 MUST fail the request by sending a SSH_MSG_USERAUTH_FAILURE packet. 406 The user name may be an empty string if it can be deduced from the 407 results of the gssapi authentication. If the user name is not 408 empty, and the requested user does not exist, the server MAY 409 disconnect, or MAY send a bogus list of acceptable authentications 410 but never accept any. This makes it possible for the server to 411 avoid disclosing information about which accounts exist. In any 412 case, if the user does not exist, the authentication request MUST 413 NOT be accepted. 415 The client MAY at any time continue with a new 416 SSH_MSG_USERAUTH_REQUEST message, in which case the server MUST 417 abandon the previous authentication attempt and continue with the 418 new one. 420 3.3 Initial server response 422 The server responds to the SSH_MSG_USERAUTH_REQUEST with either a 423 SSH_MSG_USERAUTH_FAILURE if none of the mechanisms are supported, or 424 with SSH_MSG_USERAUTH_GSSAPI_RESPONSE as follows: 426 byte SSH_MSG_USERAUTH_GSSAPI_RESPONSE 427 string selected mechanism OID 429 The mechanism OID must be one of the OIDs sent by the client in the 430 SSH_MSG_USERAUTH_REQUEST packet. 432 3.4 GSSAPI session 434 Once the mechanism OID has been selected, the client will then 435 initiate an exchange of one or more pairs of 436 SSH_MSG_USERAUTH_GSSAPI_TOKEN packets. These packets contain the 437 tokens produced from the 'GSS_Init_sec_context()' and 438 'GSS_Accept_sec_context()' calls. The actual number of packets 439 exchanged is determined by the underlying GSSAPI mechanism. 441 byte SSH_MSG_USERAUTH_GSSAPI_TOKEN 442 string data returned from either GSS_Init_sec_context() 443 or GSS_Accept_sec_context() 445 If an error occurs during this exchange on server side, the server 446 can terminate the method by sending a SSH_MSG_USERAUTH_FAILURE 447 packet. If an error occurs on client side, the client can terminate 448 the method by sending a new SSH_MSG_USERAUTH_REQUEST packet. 450 The client MAY use the deleg_req_flag in calls to 451 GSS_Init_sec_context() to request credential delegation. 453 Additional SSH_MSG_USERAUTH_GSSAPI_TOKEN messages are sent if and 454 only if the calls to the GSSAPI routines produce send tokens of 455 non-zero length. 457 Any major status code other than GSS_S_COMPLETE or 458 GSS_S_CONTINUE_NEEDED SHOULD be a failure. 460 3.5 Client acknowledgement 462 It is possible for the server to successfully complete the GSSAPI 463 method and the client to fail. If the server simply assumed success 464 on the part of the client and completed the authentication service, 465 it is possible that the client would fail to complete the 466 authentication method, but not be able to retry other methods 467 because the server had already moved on. 469 Therefore, the client MUST send the following message when it has 470 successfully called GSS_Init_sec_context() and gotten GSS_S_COMPLETE: 472 byte SSH_MSG_USERAUTH_GSSAPI_EXCHANGE_COMPLETE 474 This message MUST be sent if and only if GSS_Init_sec_context() 475 returned GSS_S_COMPLETE. If a token is returned then the 476 SSH_MSG_USERAUTH_GSSAPI_TOKEN message MUST be sent before this one. 478 If GSS_Init_sec_context() failed, the client MUST terminate the 479 method by sending a new SSH_MSG_USERAUTH_REQUEST. 481 3.6 Completion 483 As with all SSH authentication methods, successful completion is 484 indicated by a SSH_MSG_USERAUTH_SUCCESS if no other authentication 485 is required, or a SSH_MSG_USERAUTH_FAILURE with the partial success 486 flag set if the server requires further authentication. 488 This packet should be sent immediately following receipt of the the 489 SSH_MSG_USERAUTH_GSSAPI_EXCHANGE_COMPLETE packet. 491 3.7 Error Status 493 In the event a GSSAPI error occurs on the server during context 494 establishment, the server SHOULD send the following message to 495 inform the client of the details of the error before sending a 496 SSH_MSG_USERAUTH_FAILURE message: 498 byte SSH_MSG_USERAUTH_GSSAPI_ERROR 499 uint32 major_status 500 uint32 minor_status 501 string message 502 string language tag 504 The message text MUST be encoded in the UTF-8 encoding described in 505 [13]. Language tags are those described in [14]. Note that the 506 message text may contain multiple lines separated by carriage 507 return-line feed (CRLF) sequences. Application developers should 508 take this into account when displaying these messages. 510 Clients receiving this message MAY log the error details and/or 511 report them to the user. Any server sending this message MUST 512 ignore any SSH_MSG_UNIMPLEMENTED sent by the client in response. 514 4. External Key Exchange User Authentication 516 This section describes a user authentication method building on the 517 framework described in [12]. This method relies upon the key 518 exchange to authenticate both the client and the server. If the key 519 exchange did not successfully perform these functions then the 520 server MUST always respond to this request with 521 SSH_MSG_USERAUTH_FAILURE with partial success set to false. 523 The new mechanism is defined as follows: 525 byte SSH_MSG_USERAUTH_REQUEST 526 string user name (in ISO-10646 UTF-8 encoding) 527 string service name (in US-ASCII) 528 string "external-keyx" (US-ASCII method name) 530 If the authentication performed as part of key exchange can be used 531 to authorize login as the requested user, this method is successful, 532 and the server responds with SSH_MSG_USERAUTH_SUCCESS if no more 533 authentications are needed, or with SSH_MSG_USERAUTH_FAILURE with 534 partial success set to true if more authentications are needed. 536 If the authentication performed as part of key-exchange cannot be 537 used to authorize login as the requested user, then 538 SSH_MSG_USERAUTH_FAILURE is returned with partial success set to 539 false. 541 If the user name is not empty, and the requested user does not 542 exist, the server MAY disconnect, or MAY send a bogus list of 543 acceptable authentications but never accept any. This makes it 544 possible for the server to avoid disclosing information about which 545 accounts exist. In any case, if the user does not exist, the 546 authentication request MUST NOT be accepted. 548 Any implementation supporting at least one key exchange method which 549 conforms to section 1 of this document SHOULD also support the 550 "external-keyx" user authentication method, in order to allow user 551 authentication to be performed at the same time as key exchange, 552 thereby reducing the number of round trips needed for connection 553 setup. 555 5. Null Host Key Algorithm 557 The "null" host key algorithm has no associated host key material, 558 and provides neither signature nor encryption algorithms. Thus, it 559 can be used only with key exchange methods that do not require any 560 public-key operations and do not require the use of host public key 561 material. The key exchange methods described in section 1 of this 562 document are examples of such methods. 564 This algorithm is used when, as a matter of configuration, the host 565 does not have or does not wish to use a public key. For example, it 566 can be used when the administrator has decided as a matter of policy 567 to require that all key exchanges be authenticated using Kerberos 568 [3], and thus the only permitted key exchange method is the 569 GSSAPI-authenticated Diffie-Hellman exchange described above, with 570 Kerberos V5 as the underlying GSSAPI mechanism. In such a 571 configuration, the server implementation supports the "ssh-dss" key 572 algorithm (as required by [11]), but could be prohibited by 573 configuration from using it. In this situation, the server needs 574 some key exchange algorithm to advertise; the "null" algorithm fills 575 this purpose. 577 Note that the use of the "null" algorithm in this way means that the 578 server will not be able to interoperate with clients which do not 579 support this algorithm. This is not a significant problem, since in 580 the configuration described, it will also be unable to interoperate 581 with implementations that do not support the GSSAPI-authenticated 582 key exchange and Kerberos. 584 Any implementation supporting at least one key exchange method which 585 conforms to section 1 of this document MUST also support the "null" 586 host key algorithm. Servers MUST NOT advertise the "null" host key 587 algorithm unless it is the only algorithm advertised. 589 6. Summary of Message Numbers 591 The following message numbers have been defined for use with 592 GSSAPI-based key exchange methods: 594 #define SSH_MSG_KEXGSS_INIT 30 595 #define SSH_MSG_KEXGSS_CONTINUE 31 596 #define SSH_MSG_KEXGSS_COMPLETE 32 597 #define SSH_MSG_KEXGSS_HOSTKEY 33 598 #define SSH_MSG_KEXGSS_ERROR 34 600 The numbers 30-49 are specific to key exchange and may be redefined 601 by other kex methods. 603 The following message numbers have been defined for use with the 604 'gssapi' user authentication method: 606 #define SSH_MSG_USERAUTH_GSSAPI_RESPONSE 60 607 #define SSH_MSG_USERAUTH_GSSAPI_TOKEN 61 608 #define SSH_MSG_USERAUTH_GSSAPI_EXCHANGE_COMPLETE 63 609 #define SSH_MSG_USERAUTH_GSSAPI_ERROR 64 611 The numbers 60-79 are specific to user authentication and may be 612 redefined by other user auth methods. Note that in the method 613 described in this document, message number 62 is unused. 615 7. GSSAPI Considerations 617 7.1 Naming Conventions 619 In order to establish a GSSAPI security context, the SSH client 620 needs to determine the appropriate targ_name to use in identifying 621 the server when calling GSS_Init_sec_context. For this purpose, the 622 GSSAPI mechanism-independent name form for host-based services is 623 used, as described in section 4.1 of [2]. 625 In particular, the targ_name to pass to GSS_Init_sec_context is 626 obtained by calling GSS_Import_name with an input_name_type of 627 GSS_C_NT_HOSTBASED_SERVICE, and an input_name_string consisting of 628 the string "host@" concatenated with the hostname of the SSH server. 630 7.2 Channel Bindings 632 This document recommends that channel bindings SHOULD NOT be 633 specified in the calls during context establishment. This document 634 does not specify any standard data to be used as channel bindings 635 and the use of network addresses as channel bindings may break SSH 636 in environments where it is most useful. 638 7.3 SPNEGO 640 The use of the Simple and Protected GSS-API Negotiation Mechanism 641 [8] in conjunction with the authentication and key exchange methods 642 described in this document is both unnecessary and undesirable. As 643 a result, mechanisms conforming to this document MUST NOT use SPNEGO 644 as the underlying GSSAPI mechanism. 646 Since SSH performs its own negotiation of authentication and key 647 exchange methods, the negotiation capability of SPNEGO alone does 648 not provide any added benefit. In fact, as described below, it has 649 the potential to result in the use of a weaker method than desired. 651 Normally, SPNEGO provides the added benefit of protecting the GSSAPI 652 mechanism negotiation. It does this by having the server compute a 653 MIC of the list of mechanisms proposed by the client, and then 654 checking that value at the client. In the case of key exchange, 655 this protection is not needed because the key exchange methods 656 described here already perform an equivalent operation; namely, they 657 generate a MIC of the SSH exchange hash, which is a hash of several 658 items including the lists of key exchange mechanisms supported by 659 both sides. In the case of user authentication, the protection is 660 not needed because the negotiation occurs over a secure channel, and 661 the host's identity has already been proved to the user. 663 The use of SPNEGO combined with GSSAPI mechanisms used without 664 SPNEGO can lead to interoperability problems. For example, a client 665 which supports key exchange using the Kerberos V5 GSSAPI mechanism 666 [4] only underneath SPNEGO will not interoperate with a server which 667 supports key exchange only using the Kerberos V5 GSSAPI mechanism 668 directly. As a result, allowing GSSAPI mechanisms to be used both 669 with and without SPNEGO is undesirable. 671 If a client's policy is to first prefer GSSAPI-based key exchange 672 method X, then non-GSSAPI method Y, then GSSAPI-based method Z, and 673 if a server supports mechanisms Y and Z but not X, then an attempt 674 to use SPNEGO to negotiate a GSSAPI mechanism might result in the 675 use of method Z when method Y would have been preferable. As a 676 result, the use of SPNEGO could result in the subversion of the 677 negotiation algorithm for key exchange methods as described in 678 section 5.1 of [11] and/or the negotiation algorithm for user 679 authentication methods as described in [12]. 681 8. Security Considerations 683 This document describes authentication and key-exchange protocols. 684 As such, security considerations are discussed throughout. 686 This protocol depends on the SSH protocol itself, the GSSAPI, any 687 underlying GSSAPI mechanisms which are used, and any protocols on 688 which such mechanisms might depend. Each of these components plays 689 a part in the security of the resulting connection, and each will 690 have its own security considerations. 692 The key exchange method described in section 1 of this document 693 depends on the underlying GSSAPI mechanism to provide both mutual 694 authentication and per-message integrity services. If either of 695 these features is not supported by a particular GSSAPI mechanism, or 696 by a particular implementation of a GSSAPI mechanism, then the key 697 exchange is not secure and MUST fail. 699 In order for the "external-keyx" user authentication method to be 700 used, it MUST have access to user authentication information 701 obtained as a side-effect of the key exchange. If this information 702 is unavailable, the authentication MUST fail. 704 Revealing information about the reason for an authentication failure 705 may be considered by some sites to be an unacceptable security risk 706 for a production environment. However, having that information 707 available can be invaluable for debugging purposes. Thus, it is 708 RECOMMENDED that implementations provide a means for controlling, as 709 a matter of policy, whether the SSH_MSG_KEXGSS_ERROR and/or 710 SSH_MGS_USERAUTH_GGSAPI_ERROR messages are sent. 712 9. Acknowledgements 714 The authors would like to thank Sam Hartman and Simon Wilkinson for 715 their invaluable assistance with this document. 717 10. Changes the last version 719 This section lists important changes since the previous version of 720 this internet-draft. This section should be removed at the time of 721 publication of this document as an RFC. 723 o Added the SSH_MSG_KEXGSS_ERROR message to allow reporting of 724 GSSAPI errors during the key exchange process. 726 o Added the SSH_MSG_USERAUTH_GSSAPI_ERROR message to allow 727 reporting of GSSAPI errors during the user authentication process. 729 o Clarified the handling of 730 GSS_MSG_USERAUTH_GSSAPI_EXCHANGE_COMPLETE when the client has a 731 final GSSAPI token to send. 733 o Added references to RFC2279 (UTF-8) and RFC1176 (language tags). 735 o Added a missing paragraph specifying that a server accepting a 736 GSSAPI context for key exchange must verify that message 737 integrity protection is available in that context. 739 References 741 [1] ISO/IEC, "Specification of Abstract Syntax Notation One 742 (ASN.1)", ISO/IEC 8824, November 1998. 744 [2] Linn, J., "Generic Security Service Application Program 745 Interface Version 2, Update 1", RFC 2743, January 2000. 747 [3] Kohl, J. and C. Neuman, "The Kerberos Network Authentication 748 Service (V5)", RFC 1510, September 1993. 750 [4] Linn, J., "The Kerberos Version 5 GSS-API Mechanism", RFC 751 1964, June 1996. 753 [5] Rivest, R., "The MD5 Message-Digest Algorithm", RFC 1321, 754 April 1992. 756 [6] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 757 Extensions (MIME) Part One: Format of Internet Message 758 Bodies", RFC 2045, November 1996. 760 [7] Bradner, S., "Key words for use in RFCs to Indicate 761 Requirement Levels", RFC 2119, BCP 14, March 1997. 763 [8] Baize, E. and D. Pinkas, "The Simple and Protected GSS-API 764 Negotiation Mechanism", RFC 2478, December 1998. 766 [9] Ylonen, T., Kivinen, T., Saarinen, M., Rinne, T. and S. 767 Lehtinen, "SSH Protocol Architecture", 768 draft-ietf-secsh-architecture-11.txt (work in progress), 769 November 2001. 771 [10] Ylonen, T., Kivinen, T., Saarinen, M., Rinne, T. and S. 772 Lehtinen, "SSH Connection Protocol", 773 draft-ietf-secsh-connect-14.txt (work in progress), November 774 2001. 776 [11] Ylonen, T., Kivinen, T., Saarinen, M., Rinne, T. and S. 777 Lehtinen, "SSH Transport Layer Protocol", 778 draft-ietf-secsh-transport-11.txt (work in progress), November 779 2001. 781 [12] Ylonen, T., Kivinen, T., Saarinen, M., Rinne, T. and S. 782 Lehtinen, "SSH Authentication Protocol", 783 draft-ietf-secsh-userauth-13.txt (work in progress), November 784 2001. 786 [13] Yergeau, , "UTF-8, a transformation format of ISO 10646", RFC 787 2279, January 1998. 789 [14] Alvestrand, H., "Tags for the Identification of Languages", 790 RFC 1766, March 1995. 792 Authors' Addresses 794 Jeffrey Hutzelman 795 Carnegie Mellon University 796 5000 Forbes Ave 797 Pittsburgh, PA 15213 798 US 800 Phone: +1 412 268 7225 801 EMail: jhutz+@cmu.edu 802 URI: http://www.cs.cmu.edu/~jhutz/ 804 Joseph Salowey 805 Cisco Systems 806 Bldg 20 807 725 Alder Drive 808 Milpitas, CA 95035 809 US 811 Phone: +1 408 525 6381 812 EMail: jsalowey@cisco.com 814 Joseph Galbraith 815 Van Dyke Technologies, Inc. 816 4848 Tramway Ridge Dr. NE 817 Suite 101 818 Albuquerque, NM 87111 819 US 821 EMail: galb@vandyke.com 823 Vol Welch 824 University of Chicago & Argonne National Laboratory 825 Distributed Systems Laboratory 826 701 E. Washington 827 Urbana, IL 61801 828 US 830 EMail: welch@mcs.anl.gov 832 Full Copyright Statement 834 Copyright (C) The Internet Society (2002). All Rights Reserved. 836 This document and translations of it may be copied and furnished to 837 others, and derivative works that comment on or otherwise explain it 838 or assist in its implementation may be prepared, copied, published 839 and distributed, in whole or in part, without restriction of any 840 kind, provided that the above copyright notice and this paragraph 841 are included on all such copies and derivative works. However, this 842 document itself may not be modified in any way, such as by removing 843 the copyright notice or references to the Internet Society or other 844 Internet organizations, except as needed for the purpose of 845 developing Internet standards in which case the procedures for 846 copyrights defined in the Internet Standards process must be 847 followed, or as required to translate it into languages other than 848 English. 850 The limited permissions granted above are perpetual and will not be 851 revoked by the Internet Society or its successors or assigns. 853 This document and the information contained herein is provided on an 854 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 855 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 856 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 857 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 858 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 860 Acknowledgement 862 Funding for the RFC editor function is currently provided by the 863 Internet Society.