idnits 2.17.1 draft-ietf-secsh-gsskeyex-04.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 249 has weird spacing: '... string out...' == Line 260 has weird spacing: '... string out...' == Line 274 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 (July 5, 2002) is 7938 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: January 3, 2003 J. Salowey 5 Cisco Systems 6 J. Galbraith 7 Van Dyke Technologies, Inc. 8 V. Welch 9 U Chicago / ANL 10 July 5, 2002 12 GSSAPI Authentication and Key Exchange for the Secure Shell Protocol 13 draft-ietf-secsh-gsskeyex-04 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 January 3, 2003. 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. If this message is sent, the server 240 public host key(s) and/or certificate(s) in this message are encoded 241 as a single string, in the format specified by the public key type 242 in use (see [11], section 4.6). 244 Each time the server's call to GSS_Accept_sec_context returns a 245 major_status code of GSS_S_CONTINUE_NEEDED, it sends the following 246 reply to the client: 248 byte SSH_MSG_KEXGSS_CONTINUE 249 string output_token (from GSS_Accept_sec_context) 251 If the client receives this message after a call to 252 GSS_Init_sec_context has returned a major_status code of 253 GSS_S_COMPLETE, a protocol error has occurred and the key exchange 254 MUST fail. 256 Each time the client receives the message described above, it makes 257 another call to GSS_Init_sec_context. It then sends the following: 259 byte SSH_MSG_KEXGSS_CONTINUE 260 string output_token (from GSS_Init_sec_context) 262 The server and client continue to trade these two messages as long 263 as the server's calls to GSS_Accept_sec_context result in 264 major_status codes of GSS_S_CONTINUE_NEEDED. When a call results in 265 a major_status code of GSS_S_COMPLETE, it sends one of two final 266 messages. 268 If the server's final call to GSS_Accept_sec_context (resulting in a 269 major_status code of GSS_S_COMPLETE) returns a non-zero-length token 270 to be sent to the client, it sends the following: 272 byte SSH_MSG_KEXGSS_COMPLETE 273 mpint f 274 string per_msg_token (MIC of H) 275 boolean TRUE 276 string output_token (from GSS_Accept_sec_context) 278 If the client receives this message after a call to 279 GSS_Init_sec_context has returned a major_status code of 280 GSS_S_COMPLETE, a protocol error has occurred and the key exchange 281 MUST fail. 283 If the server's final call to GSS_Accept_sec_context (resulting in a 284 major_status code of GSS_S_COMPLETE) returns a zero-length token or 285 no token at all, it sends the following: 287 byte SSH_MSG_KEXGSS_COMPLETE 288 mpint f 289 string per_msg_token (MIC of H) 290 boolean FALSE 292 If the client receives this message when no call to 293 GSS_Init_sec_context has yet resulted in a major_status code of 294 GSS_S_COMPLETE, a protocol error has occurred and the key exchange 295 MUST fail. 297 In the event of a GSSAPI error on the server, the server may send 298 the following message before terminating the connection: 300 byte SSH_MSG_KEXGSS_ERROR 301 uint32 major_status 302 uint32 minor_status 303 string message 304 string language tag 306 The message text MUST be encoded in the UTF-8 encoding described in 307 [13]. Language tags are those described in [14]. Note that the 308 message text may contain multiple lines separated by carriage 309 return-line feed (CRLF) sequences. Application developers should 310 take this into account when displaying these messages. 312 The hash H is computed as the HASH hash of the concatenation of the 313 following: 315 string V_C, the client's version string (CR and NL excluded) 316 string V_S, the server's version string (CR and NL excluded) 317 string I_C, the payload of the client's SSH_MSG_KEXINIT 318 string I_S, the payload of the server's SSH_MSG_KEXINIT 319 string K_S, the host key 320 mpint e, exchange value sent by the client 321 mpint f, exchange value sent by the server 322 mpint K, the shared secret 324 This value is called the exchange hash, and it is used to 325 authenticate the key exchange. The exchange hash SHOULD be kept 326 secret. If no SSH_MSG_KEXGSS_HOSTKEY message has been sent by the 327 server or received by the client, then the empty string is used in 328 place of K_S when computing the exchange hash. 330 The GSS_GetMIC call MUST be applied over H, not the original data. 332 2.2 gss-group1-sha1-* 334 Each of these methods specifies GSSAPI authenticated Diffie-Hellman 335 key exchange as described in Section 2.1 with SHA-1 as HASH, and the 336 group defined in section 6.1 of [11]. The method name for each 337 method is the concatenation of the string "gss-group1-sha1-" with 338 the Base64 encoding of the MD5 hash [5] of the ASN.1 DER encoding 339 [1] of the underlying GSSAPI mechanism's OID. Base64 encoding is 340 described in section 6.8 of [6]. 342 Each and every such key exchange method is implicitly registered by 343 this specification. The IESG is considered to be the owner of all 344 such key exchange methods; this does NOT imply that the IESG is 345 considered to be the owner of the underlying GSSAPI mechanism. 347 2.3 Other GSSAPI key exchange methods 349 Key exchange method names starting with "gss-" are reserved for key 350 exchange methods which conform to this document; in particular, for 351 those methods which use the GSSAPI authenticated Diffie-Hellman key 352 exchange algorithm described in Section 2.1, including any future 353 methods which use different groups and/or hash functions. The 354 intent is that the names for any such future methods methods be 355 defined in a similar manner to that used in Section 2.2. 357 3. GSSAPI User Authentication 359 This section describes a general-purpose user authentication method 360 based on [2]. It is intended to be run over the SSH user 361 authentication protocol [12]. 363 The authentication method name for this protocol is "gssapi". 365 3.1 GSSAPI Authentication Overview 367 GSSAPI authentication must maintain a context. Authentication 368 begins when the client sends a SSH_MSG_USERAUTH_REQUEST, which 369 specifies the mechanism OIDs the client supports. 371 If the server supports any of the requested mechanism OIDs, the 372 server sends a SSH_MSG_USERAUTH_GSSAPI_RESPONSE message containing 373 the mechanism OID. 375 After the client receives SSH_MSG_USERAUTH_GSSAPI_RESPONSE, the 376 client and server exchange SSH_MSG_USERAUTH_GSSAPI_TOKEN packets 377 until the authentication mechanism either succeeds or fails. 379 If at any time during the exchange, the client sends a new 380 SSH_MSG_USERAUTH_REQUEST packet, the GSSAPI context is completely 381 discarded and destroyed, and any further GSSAPI authentication MUST 382 restart from the beginning. 384 3.2 Initiating GSSAPI authentication 386 The GSSAPI authentication method is initiated when the client sends 387 a SSH_MSG_USERAUTH_REQUEST: 389 byte SSH_MSG_USERAUTH_REQUEST 390 string user name (in ISO-10646 UTF-8 encoding) 391 string service name (in US-ASCII) 392 string "gssapi" (US-ASCII method name) 393 uint32 n, the number of mechanism OIDs client supports 394 string[n] mechanism OIDs 396 Mechanism OIDs are encoded according to the ASN.1 basic encoding 397 rules (BER), as described in [1] and in section 3.1 of [2]. The 398 mechanism OIDs MUST be listed in order of preference, and the server 399 must choose the first mechanism OID on the list that it supports. 401 The client SHOULD NOT send more then one gssapi mechanism OID unless 402 there are no non-GSSAPI authentication methods between the GSSAPI 403 mechanisms in the order of preference, otherwise, authentication 404 methods may be executed out of order. 406 If the server does not support any of the specified OIDs, the server 407 MUST fail the request by sending a SSH_MSG_USERAUTH_FAILURE packet. 409 The user name may be an empty string if it can be deduced from the 410 results of the gssapi authentication. If the user name is not 411 empty, and the requested user does not exist, the server MAY 412 disconnect, or MAY send a bogus list of acceptable authentications 413 but never accept any. This makes it possible for the server to 414 avoid disclosing information about which accounts exist. In any 415 case, if the user does not exist, the authentication request MUST 416 NOT be accepted. 418 The client MAY at any time continue with a new 419 SSH_MSG_USERAUTH_REQUEST message, in which case the server MUST 420 abandon the previous authentication attempt and continue with the 421 new one. 423 3.3 Initial server response 425 The server responds to the SSH_MSG_USERAUTH_REQUEST with either a 426 SSH_MSG_USERAUTH_FAILURE if none of the mechanisms are supported, or 427 with SSH_MSG_USERAUTH_GSSAPI_RESPONSE as follows: 429 byte SSH_MSG_USERAUTH_GSSAPI_RESPONSE 430 string selected mechanism OID 432 The mechanism OID must be one of the OIDs sent by the client in the 433 SSH_MSG_USERAUTH_REQUEST packet. 435 3.4 GSSAPI session 437 Once the mechanism OID has been selected, the client will then 438 initiate an exchange of one or more pairs of 439 SSH_MSG_USERAUTH_GSSAPI_TOKEN packets. These packets contain the 440 tokens produced from the 'GSS_Init_sec_context()' and 441 'GSS_Accept_sec_context()' calls. The actual number of packets 442 exchanged is determined by the underlying GSSAPI mechanism. 444 byte SSH_MSG_USERAUTH_GSSAPI_TOKEN 445 string data returned from either GSS_Init_sec_context() 446 or GSS_Accept_sec_context() 448 If an error occurs during this exchange on server side, the server 449 can terminate the method by sending a SSH_MSG_USERAUTH_FAILURE 450 packet. If an error occurs on client side, the client can terminate 451 the method by sending a new SSH_MSG_USERAUTH_REQUEST packet. 453 The client MAY use the deleg_req_flag in calls to 454 GSS_Init_sec_context() to request credential delegation. 456 Additional SSH_MSG_USERAUTH_GSSAPI_TOKEN messages are sent if and 457 only if the calls to the GSSAPI routines produce send tokens of 458 non-zero length. 460 Any major status code other than GSS_S_COMPLETE or 461 GSS_S_CONTINUE_NEEDED SHOULD be a failure. 463 3.5 Client acknowledgement 465 It is possible for the server to successfully complete the GSSAPI 466 method and the client to fail. If the server simply assumed success 467 on the part of the client and completed the authentication service, 468 it is possible that the client would fail to complete the 469 authentication method, but not be able to retry other methods 470 because the server had already moved on. 472 Therefore, the client MUST send the following message when it has 473 successfully called GSS_Init_sec_context() and gotten GSS_S_COMPLETE: 475 byte SSH_MSG_USERAUTH_GSSAPI_EXCHANGE_COMPLETE 477 This message MUST be sent if and only if GSS_Init_sec_context() 478 returned GSS_S_COMPLETE. If a token is returned then the 479 SSH_MSG_USERAUTH_GSSAPI_TOKEN message MUST be sent before this one. 481 If GSS_Init_sec_context() failed, the client MUST terminate the 482 method by sending a new SSH_MSG_USERAUTH_REQUEST. 484 3.6 Completion 486 As with all SSH authentication methods, successful completion is 487 indicated by a SSH_MSG_USERAUTH_SUCCESS if no other authentication 488 is required, or a SSH_MSG_USERAUTH_FAILURE with the partial success 489 flag set if the server requires further authentication. 491 This packet should be sent immediately following receipt of the the 492 SSH_MSG_USERAUTH_GSSAPI_EXCHANGE_COMPLETE packet. 494 3.7 Error Status 496 In the event a GSSAPI error occurs on the server during context 497 establishment, the server SHOULD send the following message to 498 inform the client of the details of the error before sending a 499 SSH_MSG_USERAUTH_FAILURE message: 501 byte SSH_MSG_USERAUTH_GSSAPI_ERROR 502 uint32 major_status 503 uint32 minor_status 504 string message 505 string language tag 507 The message text MUST be encoded in the UTF-8 encoding described in 508 [13]. Language tags are those described in [14]. Note that the 509 message text may contain multiple lines separated by carriage 510 return-line feed (CRLF) sequences. Application developers should 511 take this into account when displaying these messages. 513 Clients receiving this message MAY log the error details and/or 514 report them to the user. Any server sending this message MUST 515 ignore any SSH_MSG_UNIMPLEMENTED sent by the client in response. 517 4. External Key Exchange User Authentication 519 This section describes a user authentication method building on the 520 framework described in [12]. This method relies upon the key 521 exchange to authenticate both the client and the server. If the key 522 exchange did not successfully perform these functions then the 523 server MUST always respond to this request with 524 SSH_MSG_USERAUTH_FAILURE with partial success set to false. 526 The new mechanism is defined as follows: 528 byte SSH_MSG_USERAUTH_REQUEST 529 string user name (in ISO-10646 UTF-8 encoding) 530 string service name (in US-ASCII) 531 string "external-keyx" (US-ASCII method name) 533 If the authentication performed as part of key exchange can be used 534 to authorize login as the requested user, this method is successful, 535 and the server responds with SSH_MSG_USERAUTH_SUCCESS if no more 536 authentications are needed, or with SSH_MSG_USERAUTH_FAILURE with 537 partial success set to true if more authentications are needed. 539 If the authentication performed as part of key-exchange cannot be 540 used to authorize login as the requested user, then 541 SSH_MSG_USERAUTH_FAILURE is returned with partial success set to 542 false. 544 If the user name is not empty, and the requested user does not 545 exist, the server MAY disconnect, or MAY send a bogus list of 546 acceptable authentications but never accept any. This makes it 547 possible for the server to avoid disclosing information about which 548 accounts exist. In any case, if the user does not exist, the 549 authentication request MUST NOT be accepted. 551 Any implementation supporting at least one key exchange method which 552 conforms to section 1 of this document SHOULD also support the 553 "external-keyx" user authentication method, in order to allow user 554 authentication to be performed at the same time as key exchange, 555 thereby reducing the number of round trips needed for connection 556 setup. 558 5. Null Host Key Algorithm 560 The "null" host key algorithm has no associated host key material, 561 and provides neither signature nor encryption algorithms. Thus, it 562 can be used only with key exchange methods that do not require any 563 public-key operations and do not require the use of host public key 564 material. The key exchange methods described in section 1 of this 565 document are examples of such methods. 567 This algorithm is used when, as a matter of configuration, the host 568 does not have or does not wish to use a public key. For example, it 569 can be used when the administrator has decided as a matter of policy 570 to require that all key exchanges be authenticated using Kerberos 571 [3], and thus the only permitted key exchange method is the 572 GSSAPI-authenticated Diffie-Hellman exchange described above, with 573 Kerberos V5 as the underlying GSSAPI mechanism. In such a 574 configuration, the server implementation supports the "ssh-dss" key 575 algorithm (as required by [11]), but could be prohibited by 576 configuration from using it. In this situation, the server needs 577 some key exchange algorithm to advertise; the "null" algorithm fills 578 this purpose. 580 Note that the use of the "null" algorithm in this way means that the 581 server will not be able to interoperate with clients which do not 582 support this algorithm. This is not a significant problem, since in 583 the configuration described, it will also be unable to interoperate 584 with implementations that do not support the GSSAPI-authenticated 585 key exchange and Kerberos. 587 Any implementation supporting at least one key exchange method which 588 conforms to section 1 of this document MUST also support the "null" 589 host key algorithm. Servers MUST NOT advertise the "null" host key 590 algorithm unless it is the only algorithm advertised. 592 6. Summary of Message Numbers 594 The following message numbers have been defined for use with 595 GSSAPI-based key exchange methods: 597 #define SSH_MSG_KEXGSS_INIT 30 598 #define SSH_MSG_KEXGSS_CONTINUE 31 599 #define SSH_MSG_KEXGSS_COMPLETE 32 600 #define SSH_MSG_KEXGSS_HOSTKEY 33 601 #define SSH_MSG_KEXGSS_ERROR 34 603 The numbers 30-49 are specific to key exchange and may be redefined 604 by other kex methods. 606 The following message numbers have been defined for use with the 607 'gssapi' user authentication method: 609 #define SSH_MSG_USERAUTH_GSSAPI_RESPONSE 60 610 #define SSH_MSG_USERAUTH_GSSAPI_TOKEN 61 611 #define SSH_MSG_USERAUTH_GSSAPI_EXCHANGE_COMPLETE 63 612 #define SSH_MSG_USERAUTH_GSSAPI_ERROR 64 614 The numbers 60-79 are specific to user authentication and may be 615 redefined by other user auth methods. Note that in the method 616 described in this document, message number 62 is unused. 618 7. GSSAPI Considerations 620 7.1 Naming Conventions 622 In order to establish a GSSAPI security context, the SSH client 623 needs to determine the appropriate targ_name to use in identifying 624 the server when calling GSS_Init_sec_context. For this purpose, the 625 GSSAPI mechanism-independent name form for host-based services is 626 used, as described in section 4.1 of [2]. 628 In particular, the targ_name to pass to GSS_Init_sec_context is 629 obtained by calling GSS_Import_name with an input_name_type of 630 GSS_C_NT_HOSTBASED_SERVICE, and an input_name_string consisting of 631 the string "host@" concatenated with the hostname of the SSH server. 633 7.2 Channel Bindings 635 This document recommends that channel bindings SHOULD NOT be 636 specified in the calls during context establishment. This document 637 does not specify any standard data to be used as channel bindings 638 and the use of network addresses as channel bindings may break SSH 639 in environments where it is most useful. 641 7.3 SPNEGO 643 The use of the Simple and Protected GSS-API Negotiation Mechanism 644 [8] in conjunction with the authentication and key exchange methods 645 described in this document is both unnecessary and undesirable. As 646 a result, mechanisms conforming to this document MUST NOT use SPNEGO 647 as the underlying GSSAPI mechanism. 649 Since SSH performs its own negotiation of authentication and key 650 exchange methods, the negotiation capability of SPNEGO alone does 651 not provide any added benefit. In fact, as described below, it has 652 the potential to result in the use of a weaker method than desired. 654 Normally, SPNEGO provides the added benefit of protecting the GSSAPI 655 mechanism negotiation. It does this by having the server compute a 656 MIC of the list of mechanisms proposed by the client, and then 657 checking that value at the client. In the case of key exchange, 658 this protection is not needed because the key exchange methods 659 described here already perform an equivalent operation; namely, they 660 generate a MIC of the SSH exchange hash, which is a hash of several 661 items including the lists of key exchange mechanisms supported by 662 both sides. In the case of user authentication, the protection is 663 not needed because the negotiation occurs over a secure channel, and 664 the host's identity has already been proved to the user. 666 The use of SPNEGO combined with GSSAPI mechanisms used without 667 SPNEGO can lead to interoperability problems. For example, a client 668 which supports key exchange using the Kerberos V5 GSSAPI mechanism 669 [4] only underneath SPNEGO will not interoperate with a server which 670 supports key exchange only using the Kerberos V5 GSSAPI mechanism 671 directly. As a result, allowing GSSAPI mechanisms to be used both 672 with and without SPNEGO is undesirable. 674 If a client's policy is to first prefer GSSAPI-based key exchange 675 method X, then non-GSSAPI method Y, then GSSAPI-based method Z, and 676 if a server supports mechanisms Y and Z but not X, then an attempt 677 to use SPNEGO to negotiate a GSSAPI mechanism might result in the 678 use of method Z when method Y would have been preferable. As a 679 result, the use of SPNEGO could result in the subversion of the 680 negotiation algorithm for key exchange methods as described in 681 section 5.1 of [11] and/or the negotiation algorithm for user 682 authentication methods as described in [12]. 684 8. Security Considerations 686 This document describes authentication and key-exchange protocols. 687 As such, security considerations are discussed throughout. 689 This protocol depends on the SSH protocol itself, the GSSAPI, any 690 underlying GSSAPI mechanisms which are used, and any protocols on 691 which such mechanisms might depend. Each of these components plays 692 a part in the security of the resulting connection, and each will 693 have its own security considerations. 695 The key exchange method described in section 1 of this document 696 depends on the underlying GSSAPI mechanism to provide both mutual 697 authentication and per-message integrity services. If either of 698 these features is not supported by a particular GSSAPI mechanism, or 699 by a particular implementation of a GSSAPI mechanism, then the key 700 exchange is not secure and MUST fail. 702 In order for the "external-keyx" user authentication method to be 703 used, it MUST have access to user authentication information 704 obtained as a side-effect of the key exchange. If this information 705 is unavailable, the authentication MUST fail. 707 Revealing information about the reason for an authentication failure 708 may be considered by some sites to be an unacceptable security risk 709 for a production environment. However, having that information 710 available can be invaluable for debugging purposes. Thus, it is 711 RECOMMENDED that implementations provide a means for controlling, as 712 a matter of policy, whether the SSH_MSG_KEXGSS_ERROR and/or 713 SSH_MGS_USERAUTH_GGSAPI_ERROR messages are sent. 715 9. Acknowledgements 717 The authors would like to thank Sam Hartman and Simon Wilkinson for 718 their invaluable assistance with this document. 720 10. Changes the last version 722 This section lists important changes since the previous version of 723 this internet-draft. This section should be removed at the time of 724 publication of this document as an RFC. 726 o Clarified the encoding of host keys in SSH_MSG_KEXGSS_HOSTKEY. 728 o Fixed a wording error in the description of the exchange hash; 729 the use of the empty string as the host key is dependent on the 730 SSH_MSG_KEXGSS_HOSTKEY message, which is sent by the server and 731 received by the client, not the other way around. 733 References 735 [1] ISO/IEC, "Specification of Abstract Syntax Notation One 736 (ASN.1)", ISO/IEC 8824, November 1998. 738 [2] Linn, J., "Generic Security Service Application Program 739 Interface Version 2, Update 1", RFC 2743, January 2000. 741 [3] Kohl, J. and C. Neuman, "The Kerberos Network Authentication 742 Service (V5)", RFC 1510, September 1993. 744 [4] Linn, J., "The Kerberos Version 5 GSS-API Mechanism", RFC 745 1964, June 1996. 747 [5] Rivest, R., "The MD5 Message-Digest Algorithm", RFC 1321, 748 April 1992. 750 [6] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 751 Extensions (MIME) Part One: Format of Internet Message 752 Bodies", RFC 2045, November 1996. 754 [7] Bradner, S., "Key words for use in RFCs to Indicate 755 Requirement Levels", RFC 2119, BCP 14, March 1997. 757 [8] Baize, E. and D. Pinkas, "The Simple and Protected GSS-API 758 Negotiation Mechanism", RFC 2478, December 1998. 760 [9] Ylonen, T., Kivinen, T., Saarinen, M., Rinne, T. and S. 761 Lehtinen, "SSH Protocol Architecture", 762 draft-ietf-secsh-architecture-11.txt (work in progress), 763 November 2001. 765 [10] Ylonen, T., Kivinen, T., Saarinen, M., Rinne, T. and S. 766 Lehtinen, "SSH Connection Protocol", 767 draft-ietf-secsh-connect-14.txt (work in progress), November 768 2001. 770 [11] Ylonen, T., Kivinen, T., Saarinen, M., Rinne, T. and S. 771 Lehtinen, "SSH Transport Layer Protocol", 772 draft-ietf-secsh-transport-11.txt (work in progress), November 773 2001. 775 [12] Ylonen, T., Kivinen, T., Saarinen, M., Rinne, T. and S. 776 Lehtinen, "SSH Authentication Protocol", 777 draft-ietf-secsh-userauth-13.txt (work in progress), November 778 2001. 780 [13] Yergeau, , "UTF-8, a transformation format of ISO 10646", RFC 781 2279, January 1998. 783 [14] Alvestrand, H., "Tags for the Identification of Languages", 784 RFC 1766, March 1995. 786 Authors' Addresses 788 Jeffrey Hutzelman 789 Carnegie Mellon University 790 5000 Forbes Ave 791 Pittsburgh, PA 15213 792 US 794 Phone: +1 412 268 7225 795 EMail: jhutz+@cmu.edu 796 URI: http://www.cs.cmu.edu/~jhutz/ 798 Joseph Salowey 799 Cisco Systems 800 Bldg 20 801 725 Alder Drive 802 Milpitas, CA 95035 803 US 805 Phone: +1 408 525 6381 806 EMail: jsalowey@cisco.com 808 Joseph Galbraith 809 Van Dyke Technologies, Inc. 810 4848 Tramway Ridge Dr. NE 811 Suite 101 812 Albuquerque, NM 87111 813 US 815 EMail: galb@vandyke.com 817 Von Welch 818 University of Chicago & Argonne National Laboratory 819 Distributed Systems Laboratory 820 701 E. Washington 821 Urbana, IL 61801 822 US 824 EMail: welch@mcs.anl.gov 826 Full Copyright Statement 828 Copyright (C) The Internet Society (2002). All Rights Reserved. 830 This document and translations of it may be copied and furnished to 831 others, and derivative works that comment on or otherwise explain it 832 or assist in its implementation may be prepared, copied, published 833 and distributed, in whole or in part, without restriction of any 834 kind, provided that the above copyright notice and this paragraph 835 are included on all such copies and derivative works. However, this 836 document itself may not be modified in any way, such as by removing 837 the copyright notice or references to the Internet Society or other 838 Internet organizations, except as needed for the purpose of 839 developing Internet standards in which case the procedures for 840 copyrights defined in the Internet Standards process must be 841 followed, or as required to translate it into languages other than 842 English. 844 The limited permissions granted above are perpetual and will not be 845 revoked by the Internet Society or its successors or assigns. 847 This document and the information contained herein is provided on an 848 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 849 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 850 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 851 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 852 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 854 Acknowledgement 856 Funding for the RFC editor function is currently provided by the 857 Internet Society.