idnits 2.17.1 draft-ietf-secsh-gsskeyex-06.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 == The page length should not exceed 58 lines per page, but there was 1 longer page, the longest (page 26) being 60 lines Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** 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], [5], [8]), 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 247 has weird spacing: '... string out...' == Line 255 has weird spacing: '... string ser...' == Line 270 has weird spacing: '... string out...' == Line 281 has weird spacing: '... string out...' == Line 295 has weird spacing: '... string per...' == (11 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 (March 2, 2003) is 7720 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' ** Downref: Normative reference to an Informational RFC: RFC 1321 (ref. '3') == 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. '10') (Obsoleted by RFC 3629) ** Obsolete normative reference: RFC 1766 (ref. '11') (Obsoleted by RFC 3066, RFC 3282) -- Obsolete informational reference (is this intentional?): RFC 1510 (ref. '12') (Obsoleted by RFC 4120, RFC 6649) -- Obsolete informational reference (is this intentional?): RFC 2478 (ref. '14') (Obsoleted by RFC 4178) Summary: 7 errors (**), 0 flaws (~~), 13 warnings (==), 6 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, 2003 J. Salowey 5 Cisco Systems 6 J. Galbraith 7 Van Dyke Technologies, Inc. 8 V. Welch 9 U Chicago / ANL 10 March 2, 2003 12 GSSAPI Authentication and Key Exchange for the Secure Shell Protocol 13 draft-ietf-secsh-gsskeyex-06 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 August 31, 2003. 38 Copyright Notice 40 Copyright (C) The Internet Society (2003). 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 [8]. 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 [5]. 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 [6], transport layer 78 protocol [8], and user authentication protocol [9]. 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 [6]. 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 [7]. 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 [8] 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. In 213 this case, several mechanisms are available for communicating error 214 information to the peer before terminating the connection as 215 required by [8]: 217 o If the key exchange fails due to any GSSAPI error on the server 218 (including errors returned by GSS_Accept_sec_context), the server 219 MAY send a message informing the client of the details of the 220 error. In this case, if an error token is also sent (see below), 221 then this message MUST be sent before the error token. 223 o If the key exchange fails due to a GSSAPI error returned from the 224 server's call to GSS_Accept_sec_context, and an "error token" is 225 also returned, then the server SHOULD send the error token to the 226 client to allow completion of the GSS security exchange. 228 o If the key exchange fails due to a GSSAPI error returned from the 229 client's call to GSS_Init_sec_context, and an "error token" is 230 also returned, then the client SHOULD send the error token to the 231 server to allow completion of the GSS security exchange. 233 As noted in Section 9, it may be desirable under site security 234 policy to obscure information about the precise nature of the error; 235 thus, it is RECOMMENDED that implementations provide a method to 236 suppress these messages as a matter of policy. 238 This is implemented with the following messages. The hash algorithm 239 for computing the exchange hash is defined by the method name, and 240 is called HASH. The group used for Diffie-Hellman key exchange and 241 the underlying GSSAPI mechanism are also defined by the method name. 243 After the client's first call to GSS_Init_sec_context, it sends the 244 following: 246 byte SSH_MSG_KEXGSS_INIT 247 string output_token (from GSS_Init_sec_context) 248 mpint e 250 Upon receiving the SSH_MSG_KEXGSS_INIT message, the server MAY send 251 the following message, prior to any other messages, to inform the 252 client of its host key. 254 byte SSH_MSG_KEXGSS_HOSTKEY 255 string server public host key and certificates (K_S) 257 Since this key exchange method does not require the host key to be 258 used for any encryption operations, this message is OPTIONAL. If 259 the "null" host key algorithm described in Section 5 is used, this 260 message MUST NOT be sent. If this message is sent, the server 261 public host key(s) and/or certificate(s) in this message are encoded 262 as a single string, in the format specified by the public key type 263 in use (see [8], section 4.6). 265 Each time the server's call to GSS_Accept_sec_context returns a 266 major_status code of GSS_S_CONTINUE_NEEDED, it sends the following 267 reply to the client: 269 byte SSH_MSG_KEXGSS_CONTINUE 270 string output_token (from GSS_Accept_sec_context) 272 If the client receives this message after a call to 273 GSS_Init_sec_context has returned a major_status code of 274 GSS_S_COMPLETE, a protocol error has occurred and the key exchange 275 MUST fail. 277 Each time the client receives the message described above, it makes 278 another call to GSS_Init_sec_context. It then sends the following: 280 byte SSH_MSG_KEXGSS_CONTINUE 281 string output_token (from GSS_Init_sec_context) 283 The server and client continue to trade these two messages as long 284 as the server's calls to GSS_Accept_sec_context result in 285 major_status codes of GSS_S_CONTINUE_NEEDED. When a call results in 286 a major_status code of GSS_S_COMPLETE, it sends one of two final 287 messages. 289 If the server's final call to GSS_Accept_sec_context (resulting in a 290 major_status code of GSS_S_COMPLETE) returns a non-zero-length token 291 to be sent to the client, it sends the following: 293 byte SSH_MSG_KEXGSS_COMPLETE 294 mpint f 295 string per_msg_token (MIC of H) 296 boolean TRUE 297 string output_token (from GSS_Accept_sec_context) 299 If the client receives this message after a call to 300 GSS_Init_sec_context has returned a major_status code of 301 GSS_S_COMPLETE, a protocol error has occurred and the key exchange 302 MUST fail. 304 If the server's final call to GSS_Accept_sec_context (resulting in a 305 major_status code of GSS_S_COMPLETE) returns a zero-length token or 306 no token at all, it sends the following: 308 byte SSH_MSG_KEXGSS_COMPLETE 309 mpint f 310 string per_msg_token (MIC of H) 311 boolean FALSE 313 If the client receives this message when no call to 314 GSS_Init_sec_context has yet resulted in a major_status code of 315 GSS_S_COMPLETE, a protocol error has occurred and the key exchange 316 MUST fail. 318 If either the client's call to GSS_Init_sec_context or the server's 319 call to GSS_Accept_sec_context returns an error status and produces 320 an output token (called an "error token"), then the following SHOULD 321 be sent to convey the error information to the peer: 323 byte SSH_MSG_KEXGSS_CONTINUE 324 string error_token 326 If a server sends both this message and an SSH_MSG_KEXGSS_ERROR 327 message, the SSH_MSG_KEXGSS_ERROR message MUST be sent first, to 328 allow clients to record and/or display the error information before 329 processing the error token. This is important because a client 330 processing an error token will likely disconnect without reading any 331 further messages. 333 In the event of a GSSAPI error on the server, the server MAY send 334 the following message before terminating the connection: 336 byte SSH_MSG_KEXGSS_ERROR 337 uint32 major_status 338 uint32 minor_status 339 string message 340 string language tag 342 The message text MUST be encoded in the UTF-8 encoding described in 343 [10]. Language tags are those described in [11]. Note that the 344 message text may contain multiple lines separated by carriage 345 return-line feed (CRLF) sequences. Application developers should 346 take this into account when displaying these messages. 348 The hash H is computed as the HASH hash of the concatenation of the 349 following: 351 string V_C, the client's version string (CR and NL excluded) 352 string V_S, the server's version string (CR and NL excluded) 353 string I_C, the payload of the client's SSH_MSG_KEXINIT 354 string I_S, the payload of the server's SSH_MSG_KEXINIT 355 string K_S, the host key 356 mpint e, exchange value sent by the client 357 mpint f, exchange value sent by the server 358 mpint K, the shared secret 360 This value is called the exchange hash, and it is used to 361 authenticate the key exchange. The exchange hash SHOULD be kept 362 secret. If no SSH_MSG_KEXGSS_HOSTKEY message has been sent by the 363 server or received by the client, then the empty string is used in 364 place of K_S when computing the exchange hash. 366 The GSS_GetMIC call MUST be applied over H, not the original data. 368 2.2 gss-group1-sha1-* 370 Each of these methods specifies GSSAPI authenticated Diffie-Hellman 371 key exchange as described in Section 2.1 with SHA-1 as HASH, and the 372 group defined in section 6.1 of [8]. The method name for each 373 method is the concatenation of the string "gss-group1-sha1-" with 374 the Base64 encoding of the MD5 hash [3] of the ASN.1 DER encoding 375 [1] of the underlying GSSAPI mechanism's OID. Base64 encoding is 376 described in section 6.8 of [4]. 378 Each and every such key exchange method is implicitly registered by 379 this specification. The IESG is considered to be the owner of all 380 such key exchange methods; this does NOT imply that the IESG is 381 considered to be the owner of the underlying GSSAPI mechanism. 383 2.3 Other GSSAPI key exchange methods 385 Key exchange method names starting with "gss-" are reserved for key 386 exchange methods which conform to this document; in particular, for 387 those methods which use the GSSAPI authenticated Diffie-Hellman key 388 exchange algorithm described in Section 2.1, including any future 389 methods which use different groups and/or hash functions. The 390 intent is that the names for any such future methods methods be 391 defined in a similar manner to that used in Section 2.2. 393 3. GSSAPI User Authentication 395 This section describes a general-purpose user authentication method 396 based on [2]. It is intended to be run over the SSH user 397 authentication protocol [9]. 399 The authentication method name for this protocol is "gssapi". 401 3.1 GSSAPI Authentication Overview 403 GSSAPI authentication must maintain a context. Authentication 404 begins when the client sends a SSH_MSG_USERAUTH_REQUEST, which 405 specifies the mechanism OIDs the client supports. 407 If the server supports any of the requested mechanism OIDs, the 408 server sends a SSH_MSG_USERAUTH_GSSAPI_RESPONSE message containing 409 the mechanism OID. 411 After the client receives SSH_MSG_USERAUTH_GSSAPI_RESPONSE, the 412 client and server exchange SSH_MSG_USERAUTH_GSSAPI_TOKEN packets 413 until the authentication mechanism either succeeds or fails. 415 If at any time during the exchange, the client sends a new 416 SSH_MSG_USERAUTH_REQUEST packet, the GSSAPI context is completely 417 discarded and destroyed, and any further GSSAPI authentication MUST 418 restart from the beginning. 420 3.2 Initiating GSSAPI authentication 422 The GSSAPI authentication method is initiated when the client sends 423 a SSH_MSG_USERAUTH_REQUEST: 425 byte SSH_MSG_USERAUTH_REQUEST 426 string user name (in ISO-10646 UTF-8 encoding) 427 string service name (in US-ASCII) 428 string "gssapi" (US-ASCII method name) 429 uint32 n, the number of mechanism OIDs client supports 430 string[n] mechanism OIDs 432 Mechanism OIDs are encoded according to the ASN.1 distinguished 433 encoding rules (DER), as described in [1] and in section 3.1 of [2]. 434 The mechanism OIDs MUST be listed in order of preference, and the 435 server must choose the first mechanism OID on the list that it 436 supports. 438 The client SHOULD NOT send more then one gssapi mechanism OID unless 439 there are no non-GSSAPI authentication methods between the GSSAPI 440 mechanisms in the order of preference, otherwise, authentication 441 methods may be executed out of order. 443 If the server does not support any of the specified OIDs, the server 444 MUST fail the request by sending a SSH_MSG_USERAUTH_FAILURE packet. 446 The user name may be an empty string if it can be deduced from the 447 results of the gssapi authentication. If the user name is not 448 empty, and the requested user does not exist, the server MAY 449 disconnect, or MAY send a bogus list of acceptable authentications 450 but never accept any. This makes it possible for the server to 451 avoid disclosing information about which accounts exist. In any 452 case, if the user does not exist, the authentication request MUST 453 NOT be accepted. 455 The client MAY at any time continue with a new 456 SSH_MSG_USERAUTH_REQUEST message, in which case the server MUST 457 abandon the previous authentication attempt and continue with the 458 new one. 460 3.3 Initial server response 462 The server responds to the SSH_MSG_USERAUTH_REQUEST with either a 463 SSH_MSG_USERAUTH_FAILURE if none of the mechanisms are supported, or 464 with SSH_MSG_USERAUTH_GSSAPI_RESPONSE as follows: 466 byte SSH_MSG_USERAUTH_GSSAPI_RESPONSE 467 string selected mechanism OID 469 The mechanism OID must be one of the OIDs sent by the client in the 470 SSH_MSG_USERAUTH_REQUEST packet. 472 3.4 GSSAPI session 474 Once the mechanism OID has been selected, the client will then 475 initiate an exchange of one or more pairs of 476 SSH_MSG_USERAUTH_GSSAPI_TOKEN packets. These packets contain the 477 tokens produced from the 'GSS_Init_sec_context()' and 478 'GSS_Accept_sec_context()' calls. The actual number of packets 479 exchanged is determined by the underlying GSSAPI mechanism. 481 byte SSH_MSG_USERAUTH_GSSAPI_TOKEN 482 string data returned from either GSS_Init_sec_context() 483 or GSS_Accept_sec_context() 485 If an error occurs during this exchange on server side, the server 486 can terminate the method by sending a SSH_MSG_USERAUTH_FAILURE 487 packet. If an error occurs on client side, the client can terminate 488 the method by sending a new SSH_MSG_USERAUTH_REQUEST packet. 490 The client MAY use the deleg_req_flag in calls to 491 GSS_Init_sec_context() to request credential delegation. 493 Additional SSH_MSG_USERAUTH_GSSAPI_TOKEN messages are sent if and 494 only if the calls to the GSSAPI routines produce send tokens of 495 non-zero length. 497 Any major status code other than GSS_S_COMPLETE or 498 GSS_S_CONTINUE_NEEDED SHOULD be a failure. 500 3.5 Client acknowledgement 502 It is possible for the server to successfully complete the GSSAPI 503 method and the client to fail. If the server simply assumed success 504 on the part of the client and completed the authentication service, 505 it is possible that the client would fail to complete the 506 authentication method, but not be able to retry other methods 507 because the server had already moved on. 509 Therefore, the client MUST send the following message when it has 510 successfully called GSS_Init_sec_context() and gotten GSS_S_COMPLETE: 512 byte SSH_MSG_USERAUTH_GSSAPI_EXCHANGE_COMPLETE 514 This message MUST be sent if and only if GSS_Init_sec_context() 515 returned GSS_S_COMPLETE. If a token is returned then the 516 SSH_MSG_USERAUTH_GSSAPI_TOKEN message MUST be sent before this one. 518 If GSS_Init_sec_context() failed, the client MUST terminate the 519 method by sending a new SSH_MSG_USERAUTH_REQUEST. or by closing the 520 connection 522 3.6 Completion 524 As with all SSH authentication methods, successful completion is 525 indicated by a SSH_MSG_USERAUTH_SUCCESS if no other authentication 526 is required, or a SSH_MSG_USERAUTH_FAILURE with the partial success 527 flag set if the server requires further authentication. 529 This packet should be sent immediately following receipt of the the 530 SSH_MSG_USERAUTH_GSSAPI_EXCHANGE_COMPLETE packet. 532 3.7 Error Status 534 In the event a GSSAPI error occurs on the server during context 535 establishment, the server MAY send the following message to inform 536 the client of the details of the error before sending a 537 SSH_MSG_USERAUTH_FAILURE message: 539 byte SSH_MSG_USERAUTH_GSSAPI_ERROR 540 uint32 major_status 541 uint32 minor_status 542 string message 543 string language tag 545 The message text MUST be encoded in the UTF-8 encoding described in 546 [10]. Language tags are those described in [11]. Note that the 547 message text may contain multiple lines separated by carriage 548 return-line feed (CRLF) sequences. Application developers should 549 take this into account when displaying these messages. 551 Clients receiving this message MAY log the error details and/or 552 report them to the user. Any server sending this message MUST 553 ignore any SSH_MSG_UNIMPLEMENTED sent by the client in response. 555 3.8 Error Token 557 In the event that, during context establishment, a client's call to 558 GSS_Init_sec_context or a server's call to GSS_Accept_sec_context 559 returns a token along with an error status, the resulting "error 560 token" SHOULD be sent to the peer using the following message: 562 byte SSH_MSG_USERAUTH_GSSAPI_ERRTOK 563 string error token 565 This message implies that the authentication is about to fail, and 566 is defined to allow the error token to be communicated without 567 losing synchronization. 569 When a server sends this message, it MUST be followed by a 570 SSH_MSG_USERAUTH_FAILURE message, which is to be interpreted as 571 applying to the same authentication request. A client receiving 572 this message SHOULD wait for the following SSH_MSG_USERAUTH_FAILURE 573 message before beginning another authentication attempt. 575 When a client sends this message, it MUST be followed by a new 576 authentication request or by terminating the connection. A server 577 receiving this message MUST NOT send a SSH_MSG_USERAUTH_FAILURE in 578 reply, since such a message might otherwise be interpreted by a 579 client as a response to the following authentication sequence. 581 Any server sending this message MUST ignore any 582 SSH_MSG_UNIMPLEMENTED sent by the client in response. If a server 583 sends both this message and an SSH_MSG_USERAUTH_GSSAPI_ERROR 584 message, the SSH_MSG_USERAUTH_GSSAPI_ERROR message MUST be sent 585 first, to allow the client to store and/or display the error status 586 before processing the error token. 588 4. External Key Exchange User Authentication 590 This section describes a user authentication method building on the 591 framework described in [9]. This method relies upon the key 592 exchange to authenticate both the client and the server. If the key 593 exchange did not successfully perform these functions then the 594 server MUST always respond to this request with 595 SSH_MSG_USERAUTH_FAILURE with partial success set to false. 597 The new mechanism is defined as follows: 599 byte SSH_MSG_USERAUTH_REQUEST 600 string user name (in ISO-10646 UTF-8 encoding) 601 string service name (in US-ASCII) 602 string "external-keyx" (US-ASCII method name) 604 If the authentication performed as part of key exchange can be used 605 to authorize login as the requested user, this method is successful, 606 and the server responds with SSH_MSG_USERAUTH_SUCCESS if no more 607 authentications are needed, or with SSH_MSG_USERAUTH_FAILURE with 608 partial success set to true if more authentications are needed. 610 If the authentication performed as part of key-exchange cannot be 611 used to authorize login as the requested user, then 612 SSH_MSG_USERAUTH_FAILURE is returned with partial success set to 613 false. 615 If the user name is not empty, and the requested user does not 616 exist, the server MAY disconnect, or MAY send a bogus list of 617 acceptable authentications but never accept any. This makes it 618 possible for the server to avoid disclosing information about which 619 accounts exist. In any case, if the user does not exist, the 620 authentication request MUST NOT be accepted. 622 Any implementation supporting at least one key exchange method which 623 conforms to section 1 of this document SHOULD also support the 624 "external-keyx" user authentication method, in order to allow user 625 authentication to be performed at the same time as key exchange, 626 thereby reducing the number of round trips needed for connection 627 setup. 629 5. Null Host Key Algorithm 631 The "null" host key algorithm has no associated host key material, 632 and provides neither signature nor encryption algorithms. Thus, it 633 can be used only with key exchange methods that do not require any 634 public-key operations and do not require the use of host public key 635 material. The key exchange methods described in section 1 of this 636 document are examples of such methods. 638 This algorithm is used when, as a matter of configuration, the host 639 does not have or does not wish to use a public key. For example, it 640 can be used when the administrator has decided as a matter of policy 641 to require that all key exchanges be authenticated using Kerberos 642 [12], and thus the only permitted key exchange method is the 643 GSSAPI-authenticated Diffie-Hellman exchange described above, with 644 Kerberos V5 as the underlying GSSAPI mechanism. In such a 645 configuration, the server implementation supports the "ssh-dss" key 646 algorithm (as required by [8]), but could be prohibited by 647 configuration from using it. In this situation, the server needs 648 some key exchange algorithm to advertise; the "null" algorithm fills 649 this purpose. 651 Note that the use of the "null" algorithm in this way means that the 652 server will not be able to interoperate with clients which do not 653 support this algorithm. This is not a significant problem, since in 654 the configuration described, it will also be unable to interoperate 655 with implementations that do not support the GSSAPI-authenticated 656 key exchange and Kerberos. 658 Any implementation supporting at least one key exchange method which 659 conforms to section 1 of this document MUST also support the "null" 660 host key algorithm. Servers MUST NOT advertise the "null" host key 661 algorithm unless it is the only algorithm advertised. 663 6. Summary of Message Numbers 665 The following message numbers have been defined for use with 666 GSSAPI-based key exchange methods: 668 #define SSH_MSG_KEXGSS_INIT 30 669 #define SSH_MSG_KEXGSS_CONTINUE 31 670 #define SSH_MSG_KEXGSS_COMPLETE 32 671 #define SSH_MSG_KEXGSS_HOSTKEY 33 672 #define SSH_MSG_KEXGSS_ERROR 34 674 The numbers 30-49 are specific to key exchange and may be redefined 675 by other kex methods. 677 The following message numbers have been defined for use with the 678 'gssapi' user authentication method: 680 #define SSH_MSG_USERAUTH_GSSAPI_RESPONSE 60 681 #define SSH_MSG_USERAUTH_GSSAPI_TOKEN 61 682 #define SSH_MSG_USERAUTH_GSSAPI_EXCHANGE_COMPLETE 63 683 #define SSH_MSG_USERAUTH_GSSAPI_ERROR 64 685 The numbers 60-79 are specific to user authentication and may be 686 redefined by other user auth methods. Note that in the method 687 described in this document, message number 62 is unused. 689 7. GSSAPI Considerations 691 7.1 Naming Conventions 693 In order to establish a GSSAPI security context, the SSH client 694 needs to determine the appropriate targ_name to use in identifying 695 the server when calling GSS_Init_sec_context. For this purpose, the 696 GSSAPI mechanism-independent name form for host-based services is 697 used, as described in section 4.1 of [2]. 699 In particular, the targ_name to pass to GSS_Init_sec_context is 700 obtained by calling GSS_Import_name with an input_name_type of 701 GSS_C_NT_HOSTBASED_SERVICE, and an input_name_string consisting of 702 the string "host@" concatenated with the hostname of the SSH server. 704 7.2 Channel Bindings 706 This document recommends that channel bindings SHOULD NOT be 707 specified in the calls during context establishment. This document 708 does not specify any standard data to be used as channel bindings 709 and the use of network addresses as channel bindings may break SSH 710 in environments where it is most useful. 712 7.3 SPNEGO 714 The use of the Simple and Protected GSS-API Negotiation Mechanism 715 [14] in conjunction with the authentication and key exchange methods 716 described in this document is both unnecessary and undesirable. As 717 a result, mechanisms conforming to this document MUST NOT use SPNEGO 718 as the underlying GSSAPI mechanism. 720 Since SSH performs its own negotiation of authentication and key 721 exchange methods, the negotiation capability of SPNEGO alone does 722 not provide any added benefit. In fact, as described below, it has 723 the potential to result in the use of a weaker method than desired. 725 Normally, SPNEGO provides the added benefit of protecting the GSSAPI 726 mechanism negotiation. It does this by having the server compute a 727 MIC of the list of mechanisms proposed by the client, and then 728 checking that value at the client. In the case of key exchange, 729 this protection is not needed because the key exchange methods 730 described here already perform an equivalent operation; namely, they 731 generate a MIC of the SSH exchange hash, which is a hash of several 732 items including the lists of key exchange mechanisms supported by 733 both sides. In the case of user authentication, the protection is 734 not needed because the negotiation occurs over a secure channel, and 735 the host's identity has already been proved to the user. 737 The use of SPNEGO combined with GSSAPI mechanisms used without 738 SPNEGO can lead to interoperability problems. For example, a client 739 which supports key exchange using the Kerberos V5 GSSAPI mechanism 740 [13] only underneath SPNEGO will not interoperate with a server 741 which supports key exchange only using the Kerberos V5 GSSAPI 742 mechanism directly. As a result, allowing GSSAPI mechanisms to be 743 used both with and without SPNEGO is undesirable. 745 If a client's policy is to first prefer GSSAPI-based key exchange 746 method X, then non-GSSAPI method Y, then GSSAPI-based method Z, and 747 if a server supports mechanisms Y and Z but not X, then an attempt 748 to use SPNEGO to negotiate a GSSAPI mechanism might result in the 749 use of method Z when method Y would have been preferable. As a 750 result, the use of SPNEGO could result in the subversion of the 751 negotiation algorithm for key exchange methods as described in 752 section 5.1 of [8] and/or the negotiation algorithm for user 753 authentication methods as described in [9]. 755 8. IANA Considerations 757 Consistent with section 7 of [6], the IANA is directed to make the 758 following registrations: 760 The family of SSH key exchange method names beginning with 761 "gss-group1-sha1-" and not containing the at-sign ('@'), to name 762 the key exchange methods defined in Section 2.2. 764 All other SSH key exchange method names beginning with "gss-" and 765 not containing the at-sign ('@'), to be reserved for future key 766 exchange methods defined in conformance with this document, as 767 noted in Section 2.3. 769 The SSH host public key algorithm name "null", to name the NULL 770 host key algorithm defined in Section 5. 772 The SSH user authentication method name "gssapi", to name the 773 GSSAPI user authentication method defined in Section 3. 775 The SSH user authentication method name "external-keyx", to name 776 the "external key-exchange" user authentication method defined in 777 Section 4. 779 This document creates no new registries. 781 9. Security Considerations 783 This document describes authentication and key-exchange protocols. 784 As such, security considerations are discussed throughout. 786 This protocol depends on the SSH protocol itself, the GSSAPI, any 787 underlying GSSAPI mechanisms which are used, and any protocols on 788 which such mechanisms might depend. Each of these components plays 789 a part in the security of the resulting connection, and each will 790 have its own security considerations. 792 The key exchange method described in section 1 of this document 793 depends on the underlying GSSAPI mechanism to provide both mutual 794 authentication and per-message integrity services. If either of 795 these features is not supported by a particular GSSAPI mechanism, or 796 by a particular implementation of a GSSAPI mechanism, then the key 797 exchange is not secure and MUST fail. 799 In order for the "external-keyx" user authentication method to be 800 used, it MUST have access to user authentication information 801 obtained as a side-effect of the key exchange. If this information 802 is unavailable, the authentication MUST fail. 804 Revealing information about the reason for an authentication failure 805 may be considered by some sites to be an unacceptable security risk 806 for a production environment. However, having that information 807 available can be invaluable for debugging purposes. Thus, it is 808 RECOMMENDED that implementations provide a means for controlling, as 809 a matter of policy, whether to send SSH_MSG_USERAUTH_GSSAPI_ERROR, 810 SSH_MSG_USERAUTH_GSSAPI_ERRTOK, and SSH_MSG_KEXGSS_ERROR messages, 811 and SSH_MSG_KEXGEE_CONTINUE messages containing a GSSAPI error token. 813 10. Acknowledgements 815 The authors would like to thank Sam Hartman, Simon Wilkinson, and 816 Nicolas Williams for their invaluable assistance with this document. 818 11. Changes the last version 820 This section lists important changes since the previous version of 821 this internet-draft. This section should be removed at the time of 822 publication of this document as an RFC. 824 o Improved the description of error handling during key exchange. 826 o Specified that SSH_MSG_GSSKEX_CONTINUE SHOULD be used to send 827 error tokens in the event of a failure of GSS_Init_sec_context or 828 GSS_Accept_sec_context during key exchange. 830 o Made SSH_MSG_GSSKEX_ERROR be OPTIONAL instead of RECOMMENDED. 832 o Specified a new SSH_MSG_USERAUTH_GSSAPI_ERRTOK message which 833 SHOULD be used to send error tokens in the event of a failure of 834 GSS_Init_sec_context or GSS_Accept_sec_context during user 835 authentication. 837 o Made SSH_MSG_USERAUTH_GSSAPI_ERROR be OPTIONAL instead of 838 RECOMMENDED. 840 o Added IANA considerations section. 842 Normative References 844 [1] ISO/IEC, "ASN.1 Encoding Rules: Specification of Basic 845 Encoding Rules (BER), Canonical Encoding Rules (CER) and 846 Distinguished Encoding Rules (DER)", ITU-T Recommendation 847 X.690 (1997), ISO/IEC 8825-1:1998, November 1998. 849 [2] Linn, J., "Generic Security Service Application Program 850 Interface Version 2, Update 1", RFC 2743, January 2000. 852 [3] Rivest, R., "The MD5 Message-Digest Algorithm", RFC 1321, 853 April 1992. 855 [4] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 856 Extensions (MIME) Part One: Format of Internet Message 857 Bodies", RFC 2045, November 1996. 859 [5] Bradner, S., "Key words for use in RFCs to Indicate 860 Requirement Levels", RFC 2119, BCP 14, March 1997. 862 [6] Ylonen, T., Kivinen, T., Saarinen, M., Rinne, T. and S. 863 Lehtinen, "SSH Protocol Architecture", 864 draft-ietf-secsh-architecture-11.txt (work in progress), 865 November 2001. 867 [7] Ylonen, T., Kivinen, T., Saarinen, M., Rinne, T. and S. 868 Lehtinen, "SSH Connection Protocol", 869 draft-ietf-secsh-connect-14.txt (work in progress), November 870 2001. 872 [8] Ylonen, T., Kivinen, T., Saarinen, M., Rinne, T. and S. 873 Lehtinen, "SSH Transport Layer Protocol", 874 draft-ietf-secsh-transport-11.txt (work in progress), November 875 2001. 877 [9] Ylonen, T., Kivinen, T., Saarinen, M., Rinne, T. and S. 878 Lehtinen, "SSH Authentication Protocol", 879 draft-ietf-secsh-userauth-13.txt (work in progress), November 880 2001. 882 [10] Yergeau, F., "UTF-8, a transformation format of ISO 10646", 883 RFC 2279, January 1998. 885 [11] Alvestrand, H., "Tags for the Identification of Languages", 886 RFC 1766, March 1995. 888 Non-normative References 890 [12] Kohl, J. and C. Neuman, "The Kerberos Network Authentication 891 Service (V5)", RFC 1510, September 1993. 893 [13] Linn, J., "The Kerberos Version 5 GSS-API Mechanism", RFC 894 1964, June 1996. 896 [14] Baize, E. and D. Pinkas, "The Simple and Protected GSS-API 897 Negotiation Mechanism", RFC 2478, December 1998. 899 Authors' Addresses 901 Jeffrey Hutzelman 902 Carnegie Mellon University 903 5000 Forbes Ave 904 Pittsburgh, PA 15213 905 US 907 Phone: +1 412 268 7225 908 EMail: jhutz+@cmu.edu 909 URI: http://www.cs.cmu.edu/~jhutz/ 911 Joseph Salowey 912 Cisco Systems 913 2901 Third Avenue 914 Seattle, WA 98121 915 US 917 Phone: +1 206 256 3380 918 EMail: jsalowey@cisco.com 920 Joseph Galbraith 921 Van Dyke Technologies, Inc. 922 4848 Tramway Ridge Dr. NE 923 Suite 101 924 Albuquerque, NM 87111 925 US 927 EMail: galb@vandyke.com 929 Von Welch 930 University of Chicago & Argonne National Laboratory 931 Distributed Systems Laboratory 932 701 E. Washington 933 Urbana, IL 61801 934 US 936 EMail: welch@mcs.anl.gov 938 Full Copyright Statement 940 Copyright (C) The Internet Society (2003). All Rights Reserved. 942 This document and translations of it may be copied and furnished to 943 others, and derivative works that comment on or otherwise explain it 944 or assist in its implementation may be prepared, copied, published 945 and distributed, in whole or in part, without restriction of any 946 kind, provided that the above copyright notice and this paragraph 947 are included on all such copies and derivative works. However, this 948 document itself may not be modified in any way, such as by removing 949 the copyright notice or references to the Internet Society or other 950 Internet organizations, except as needed for the purpose of 951 developing Internet standards in which case the procedures for 952 copyrights defined in the Internet Standards process must be 953 followed, or as required to translate it into languages other than 954 English. 956 The limited permissions granted above are perpetual and will not be 957 revoked by the Internet Society or its successors or assigns. 959 This document and the information contained herein is provided on an 960 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 961 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 962 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 963 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 964 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 966 Acknowledgement 968 Funding for the RFC editor function is currently provided by the 969 Internet Society.