idnits 2.17.1 draft-ietf-secsh-auth-kbdinteract-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 seems to lack a 1id_guidelines paragraph about the list of current Internet-Drafts -- however, there's a paragraph with a matching beginning. Boilerplate error? ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories -- however, there's a paragraph with a matching beginning. Boilerplate error? == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == Line 122 has weird spacing: '... string use...' == Line 123 has weird spacing: '... string ser...' == Line 125 has weird spacing: '... string lan...' == Line 126 has weird spacing: '... string sub...' == Line 197 has weird spacing: '... string nam...' == (8 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 (May 1, 2004) is 7272 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Looks like a reference, but probably isn't: '1' on line 293 == Unused Reference: 'SSH-CONNECT' is defined on line 458, but no explicit reference was found in the text ** Obsolete normative reference: RFC 3066 (Obsoleted by RFC 4646, RFC 4647) == Outdated reference: A later version (-22) exists of draft-ietf-secsh-architecture-15 == Outdated reference: A later version (-25) exists of draft-ietf-secsh-connect-18 == Outdated reference: A later version (-24) exists of draft-ietf-secsh-transport-17 == Outdated reference: A later version (-27) exists of draft-ietf-secsh-userauth-18 Summary: 4 errors (**), 0 flaws (~~), 13 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group F. Cusack 3 INTERNET-DRAFT Google, Inc. 4 Expires November 1, 2004 M. Forssen 5 Appgate AB 6 May 1, 2004 8 Generic Message Exchange Authentication For SSH 9 11 Status of this Memo 13 This document is an Internet-Draft and is subject to all provisions 14 of Section 10 of RFC2026. 16 Internet-Drafts are working documents of the Internet Engineering 17 Task Force (IETF), its areas, and its working groups. Note that 18 other groups may also distribute working documents as 19 Internet-Drafts. 21 Internet-Drafts are draft documents valid for a maximum of six months 22 and may be updated, replaced, or obsoleted by other documents at any 23 time. It is inappropriate to use Internet-Drafts as reference 24 material or to cite them other than as "work in progress." 26 The list of current Internet-Drafts can be accessed at 27 . 29 The list of Internet-Draft Shadow Directories can be accessed at 30 . 32 This Internet-Draft will expire on November 1, 2004. 34 Abstract 36 SSH is a protocol for secure remote login and other secure network 37 services over an insecure network. This document describes a general 38 purpose authentication method for the SSH protocol, suitable for 39 interactive authentications where the authentication data should be 40 entered via a keyboard. The major goal of this method is to allow 41 the SSH client to support a whole class of authentication 42 mechanism(s) without knowing the specifics of the actual 43 authentication mechanism(s). 45 1. Introduction 47 The SSH authentication protocol [SSH-USERAUTH] is a general-purpose 48 user authentication protocol. It is intended to be run over the SSH 49 transport layer protocol [SSH-TRANS]. The authentication protocol 50 assumes that the underlying protocols provide integrity and 51 confidentiality protection. 53 This document describes a general purpose authentication method for 54 the SSH authentication protocol. This method is suitable for 55 interactive authentication methods which do not need any special 56 software support on the client side. Instead all authentication data 57 should be entered via the keyboard. The major goal of this method is 58 to allow the SSH client to have little or no knowledge of the 59 specifics of the underlying authentication mechanism(s) used by the 60 SSH server. This will allow the server to arbitrarily select or 61 change the underlying authentication mechanism(s) without having to 62 update client code. 64 The name for this authentication method is "keyboard-interactive". 66 This document should be read only after reading the SSH architecture 67 document [SSH-ARCH] and the SSH authentication document 68 [SSH-USERAUTH]. This document freely uses terminology and notation 69 from both documents without reference or further explanation. 71 This document also describes some of the client interaction with the 72 user in obtaining the authentication information. While this is 73 somewhat out of the scope of a protocol specification, it is 74 described here anyway since some aspects of the protocol are 75 specifically designed based on user interface issues, and omitting 76 this information may lead to incompatible or awkward implementations. 78 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 79 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 80 document are to be interpreted as described in [RFC-2119]. 82 2. Rationale 84 Currently defined authentication methods for SSH are tightly coupled 85 with the underlying authentication mechanism. This makes it 86 difficult to add new mechanisms for authentication as all clients 87 must be updated to support the new mechanism. With the generic 88 method defined here, clients will not require code changes to support 89 new authentication mechanisms, and if a separate authentication layer 90 is used, such as [PAM], then the server may not need any code changes 91 either. 93 This presents a significant advantage to other methods, such as the 94 "password" method (defined in [SSH-USERAUTH]), as new (presumably 95 stronger) methods may be added "at will" and system security can be 96 transparently enhanced. 98 Challenge-response and One Time Password mechanisms are also easily 99 supported with this authentication method. 101 This authentication method is however limited to authentication 102 mechanisms which do not require any special code, such as hardware 103 drivers or password mangling, on the client. 105 3. Protocol Exchanges 107 The client initiates the authentication with a 108 SSH_MSG_USERAUTH_REQUEST message. The server then requests 109 authentication information from the client with a 110 SSH_MSG_USERAUTH_INFO_REQUEST message. The client obtains the 111 information from the user and then responds with a 112 SSM_MSG_USERAUTH_INFO_RESPONSE message. The server MUST NOT send 113 another SSH_MSG_USERAUTH_INFO_REQUEST before it has received the 114 answer from the client. 116 3.1 Initial Exchange 118 The authentication starts with the client sending the following 119 packet: 121 byte SSH_MSG_USERAUTH_REQUEST 122 string user name (ISO-10646 UTF-8, as defined in [RFC-3629]) 123 string service name (US-ASCII) 124 string "keyboard-interactive" (US-ASCII) 125 string language tag (as defined in [RFC-3066]) 126 string submethods (ISO-10646 UTF-8) 128 The language tag is deprecated and SHOULD be the empty string. It 129 may be removed in a future revision of this specification. The 130 server SHOULD instead select the language used based on the tags 131 communicated during key exchange [SSH-TRANS]. 133 If the language tag is not the empty string, the server SHOULD use 134 the specified language for any messages sent to the client as part of 135 this protocol. The language tag SHOULD NOT be used for language 136 selection for messages outside of this protocol. The language to be 137 used if the server does not support the requested language is 138 implementation-dependent. 140 The submethods field is included so the user can give a hint of which 141 actual methods he wants to use. It is a comma-separated list of 142 authentication submethods (software or hardware) which the user 143 prefers. If the client has knowledge of the submethods preferred by 144 the user, presumably through a configuration setting, it MAY use the 145 submethods field to pass this information to the server. Otherwise 146 it MUST send the empty string. 148 The actual names of the submethods is something which the user and 149 the server need to agree upon. 151 Server interpretation of the submethods field is implementation- 152 dependent. 154 One possible implementation strategy of the submethods field on the 155 server is that, unless the user may use multiple different 156 submethods, the server ignores this field. If the user may 157 authenticate using one of several different submethods the server 158 should treat the submethods field as a hint on which submethod the 159 user wants to use this time. 161 Note that when this message is sent to the server, the client has not 162 yet prompted the user for a password, and so that information is NOT 163 included with this initial message (unlike the "password" method). 165 The server MUST reply with either a SSH_MSG_USERAUTH_SUCCESS, 166 SSH_MSG_USERAUTH_FAILURE, or SSH_MSG_USERAUTH_INFO_REQUEST message. 168 The server SHOULD NOT reply with the SSH_MSG_USERAUTH_FAILURE message 169 if the failure is based on the user name or service name; instead it 170 SHOULD send SSH_MSG_USERAUTH_INFO_REQUEST message(s) which look just 171 like the one(s) which would have been sent in cases where 172 authentication should proceed, and then send the failure message 173 (after a suitable delay, as described below). The goal is to make it 174 impossible to find valid usernames by just comparing the results when 175 authenticating as different users. 177 The server MAY reply with a SSH_MSG_USERAUTH_SUCCESS message if no 178 authentication is required for the user in question, however a better 179 approach, for reasons discussed above, might be to reply with a 180 SSH_MSG_USERAUTH_INFO_REQUEST message and ignore (don't validate) the 181 response. 183 3.2 Information Requests 185 Requests are generated from the server using the 186 SSH_MSG_USERAUTH_INFO_REQUEST message. 188 The server may send as many requests as are necessary to authenticate 189 the client; the client MUST be prepared to handle multiple exchanges. 190 However the server MUST NOT ever have more than one 191 SSH_MSG_USERAUTH_INFO_REQUEST message outstanding. That is, it may 192 not send another request before the client has answered. 194 The SSH_MSG_USERAUTH_INFO_REQUEST message is defined as follows: 196 byte SSH_MSG_USERAUTH_INFO_REQUEST 197 string name (ISO-10646 UTF-8) 198 string instruction (ISO-10646 UTF-8) 199 string language tag (as defined in [RFC-3066]) 200 int num-prompts 201 string prompt[1] (ISO-10646 UTF-8) 202 boolean echo[1] 203 ... 204 string prompt[num-prompts] (ISO-10646 UTF-8) 205 boolean echo[num-prompts] 207 The language tag is deprecated and SHOULD be the empty string. It 208 may be removed in a future revision of this specification. The 209 server SHOULD instead select the language used based on the tags 210 communicated during key exchange [SSH-TRANS]. 212 If the language tag is not the empty string, the server SHOULD use 213 the specified language for any messages sent to the client as part of 214 this protocol. The language tag SHOULD NOT be used for language 215 selection for messages outside of this protocol. The language to be 216 used if the server does not support the requested language is 217 implementation-dependent. 219 The server SHOULD take into consideration that some clients may not 220 be able to properly display a long name or prompt field (see next 221 section), and limit the lengths of those fields if possible. For 222 example, instead of an instruction field of "Enter Password" and a 223 prompt field of "Password for user23@host.domain: ", a better choice 224 might be an instruction field of 225 "Password authentication for user23@host.domain" and a prompt field 226 of "Password: ". It is expected that this authentication method 227 would typically be backended by [PAM] and so such choices would not 228 be possible. 230 The name and instruction fields MAY be empty strings, the client MUST 231 be prepared to handle this correctly. The prompt field(s) MUST NOT 232 be empty strings. 234 The num-prompts field may be `0', in which case there will be no 235 prompt/echo fields in the message, but the client SHOULD still 236 display the name and instruction fields (as described below). 238 3.3 User Interface 240 Upon receiving a request message, the client SHOULD prompt the user 241 as follows: 243 A command line interface (CLI) client SHOULD print the name and 244 instruction (if non-empty), adding newlines. Then for each prompt in 245 turn, the client SHOULD display the prompt and read the user input. 247 A graphical user interface (GUI) client has many choices on how to 248 prompt the user. One possibility is to use the name field (possibly 249 prefixed with the application's name) as the title of a dialog window 250 in which the prompt(s) are presented. In that dialog window, the 251 instruction field would be a text message, and the prompts would be 252 labels for text entry fields. All fields SHOULD be presented to the 253 user, for example an implementation SHOULD NOT discard the name field 254 because its windows lack titles; it SHOULD instead find another way 255 to display this information. If prompts are presented in a dialog 256 window, then the client SHOULD NOT present each prompt in a separate 257 window. 259 All clients MUST properly handle an instruction field with embedded 260 newlines. They SHOULD also be able to display at least 30 characters 261 for the name and prompts. If the server presents names or prompts 262 longer than 30 characters, the client MAY truncate these fields to 263 the length it can display. If the client does truncate any fields, 264 there MUST be an obvious indication that such truncation has 265 occurred. The instruction field SHOULD NOT be truncated. 267 Clients SHOULD use control character filtering as discussed in 268 [SSH-ARCH] to avoid attacks by including terminal control characters 269 in the fields to be displayed. 271 For each prompt, the corresponding echo field indicates whether or 272 not the user input should be echoed as characters are typed. Clients 273 SHOULD correctly echo/mask user input for each prompt independently 274 of other prompts in the request message. If a client does not honor 275 the echo field for whatever reason, then the client MUST err on the 276 side of masking input. A GUI client might like to have a checkbox 277 toggling echo/mask. Clients SHOULD NOT add any additional characters 278 to the prompt such as ": " (colon-space); the server is responsible 279 for supplying all text to be displayed to the user. Clients MUST 280 also accept empty responses from the user and pass them on as empty 281 strings. 283 3.4 Information Responses 285 After obtaining the requested information from the user, the client 286 MUST respond with a SSH_MSG_USERAUTH_INFO_RESPONSE message. 288 The format of the SSH_MSG_USERAUTH_INFO_RESPONSE message is as 289 follows: 291 byte SSH_MSG_USERAUTH_INFO_RESPONSE 292 int num-responses 293 string response[1] (ISO-10646 UTF-8) 294 ... 295 string response[num-responses] (ISO-10646 UTF-8) 297 Note that the responses are encoded in ISO-10646 UTF-8. It is up to 298 the server how it interprets the responses and validates them. 299 However, if the client reads the responses in some other encoding 300 (e.g., ISO 8859-1), it MUST convert the responses to ISO-10646 UTF-8 301 before transmitting. 303 If the num-responses field does not match the num-prompts field in 304 the request message, the server MUST send a failure message. 306 In the case that the server sends a `0' num-prompts field in the 307 request message, the client MUST send a response message with a `0' 308 num-responses field. 310 The responses MUST be ordered as the prompts were ordered. That is, 311 response[n] MUST be the answer to prompt[n]. 313 After receiving the response, the server MUST send either a 314 SSH_MSG_USERAUTH_SUCCESS, SSH_MSG_USERAUTH_FAILURE, or another 315 SSH_MSG_USERAUTH_INFO_REQUEST message. 317 If the server fails to authenticate the user (through the underlying 318 authentication mechanism(s)), it SHOULD NOT send another request 319 message(s) in an attempt to obtain new authentication data, instead 320 it SHOULD send a failure message. The only time the server should 321 send multiple request messages is if additional authentication data 322 is needed (i.e., because there are multiple underlying authentication 323 mechanisms that must be used to authenticate the user). 325 If the server intends to respond with a failure message, it MAY delay 326 for an implementation-dependent time before sending to the client. 327 It is suspected that implementations are likely to make the time 328 delay configurable; a suggested default is 2 seconds. 330 4. Authentication Examples 332 Here are two example exchanges between a client and server. The 333 first is an example of challenge/response with a handheld token. 335 This is an authentication that is not otherwise possible with other 336 authentication methods. 338 C: byte SSH_MSG_USERAUTH_REQUEST 339 C: string "user23" 340 C: string "ssh-userauth" 341 C: string "keyboard-interactive" 342 C: string "" 343 C: string "" 345 S: byte SSH_MSG_USERAUTH_INFO_REQUEST 346 S: string "CRYPTOCard Authentication" 347 S: string "The challenge is '14315716'" 348 S: string "en-US" 349 S: int 1 350 S: string "Response: " 351 S: boolean TRUE 353 [Client prompts user for password] 355 C: byte SSH_MSG_USERAUTH_INFO_RESPONSE 356 C: int 1 357 C: string "6d757575" 359 S: byte SSH_MSG_USERAUTH_SUCCESS 361 The second example is of a standard password authentication, in 362 this case the user's password is expired. 364 C: byte SSH_MSG_USERAUTH_REQUEST 365 C: string "user23" 366 C: string "ssh-userauth" 367 C: string "keyboard-interactive" 368 C: string "en-US" 369 C: string "" 371 S: byte SSH_MSG_USERAUTH_INFO_REQUEST 372 S: string "Password Authentication" 373 S: string "" 374 S: string "en-US" 375 S: int 1 376 S: string "Password: " 377 S: boolean FALSE 379 [Client prompts user for password] 380 C: byte SSH_MSG_USERAUTH_INFO_RESPONSE 381 C: int 1 382 C: string "password" 384 S: byte SSH_MSG_USERAUTH_INFO_REQUEST 385 S: string "Password Expired" 386 S: string "Your password has expired." 387 S: string "en-US" 388 S: int 2 389 S: string "Enter new password: " 390 S: boolean FALSE 391 S: string "Enter it again: " 392 S: boolean FALSE 394 [Client prompts user for new password] 396 C: byte SSH_MSG_USERAUTH_INFO_RESPONSE 397 C: int 2 398 C: string "newpass" 399 C: string "newpass" 401 S: byte SSH_MSG_USERAUTH_INFO_REQUEST 402 S: string "Password changed" 403 S: string "Password successfully changed for user23." 404 S: string "en-US" 405 S: int 0 407 [Client displays message to user] 409 C: byte SSH_MSG_USERAUTH_INFO_RESPONSE 410 C: int 0 412 S: byte SSH_MSG_USERAUTH_SUCCESS 414 5. IANA Considerations 416 The userauth type "keyboard-interactive" is used for this 417 authentication method. 419 The following method-specific constants are used with this 420 authentication method: 422 SSH_MSG_USERAUTH_INFO_REQUEST 60 423 SSH_MSG_USERAUTH_INFO_RESPONSE 61 425 6. Security Considerations 427 The authentication protocol, and this authentication method, depend 428 on the security of the underlying SSH transport layer. Without the 429 confidentiality provided therein, any authentication data passed with 430 this method is subject to interception. 432 The number of client-server exchanges required to complete an 433 authentication using this method may be variable. It is possible 434 that an observer may gain valuable information simply by counting 435 that number. For example, an observer may guess that a user's 436 password has expired, and with further observation may be able to 437 determine the password lifetime imposed by a site's password 438 expiration policy. 440 7. References 442 7.1 Normative References 444 [RFC-2119] Bradner, S., "Key words for use in RFCs to Indicate 445 Requirement Level", BCP 14, RFC 2119, March 1997. 447 [RFC-3629] Yergeau, F., "UTF-8, a transformation format of 448 Unicode and ISO 10646", RFC 3629, November 2003. 450 [RFC-3066] Alvestrand, H., "Tags for the Identification of 451 Languages", BCP 47, RFC 3066, January 2001. 453 [SSH-ARCH] Ylonen, T., Kivinen, T, Saarinen, M., Rinne, T., and 454 Lehtinen, S., "SSH Protocol Architecture", work in 455 progress, draft-ietf-secsh-architecture-15.txt, 456 October, 2003. 458 [SSH-CONNECT] Ylonen, T., Kivinen, T, Saarinen, M., Rinne, T., and 459 Lehtinen, S., "SSH Connection Protocol", work in 460 progress, draft-ietf-secsh-connect-18.txt, October, 461 2003. 463 [SSH-TRANS] Ylonen, T., Kivinen, T, Saarinen, M., Rinne, T., and 464 Lehtinen, S., "SSH Transport Layer Protocol", work in 465 progress, draft-ietf-secsh-transport-17.txt, October, 466 2003. 468 [SSH-USERAUTH] Ylonen, T., Kivinen, T, Saarinen, M., Rinne, T., and 469 Lehtinen, S., "SSH Authentication Protocol", work in 470 progress, draft-ietf-secsh-userauth-18.txt, 471 September, 2002. 473 7.2 Informative References 475 [PAM] Samar, V., Schemers, R., "Unified Login With 476 Pluggable Authentication Modules (PAM)", OSF RFC 477 86.0, October 1995 479 8. Authors' Addresses 481 Frank Cusack 482 Google, Inc. 483 2400 Bayshore Parkway 484 Mountain View, CA 94043 485 Email: frank@google.com 487 Martin Forssen 488 Appgate AB 489 Stora Badhusgatan 18-20 490 SE-411 21 Gothenburg 491 SWEDEN 492 Email: maf@appgate.com 494 9. Intellectual Property and Copyright Statements 496 9.1. Intellectual Property Statement 498 The IETF takes no position regarding the validity or scope of any 499 intellectual property or other rights that might be claimed to 500 pertain to the implementation or use of the technology described in 501 this document or the extent to which any license under such rights 502 might or might not be available; neither does it represent that it 503 has made any effort to identify any such rights. Information on the 504 IETF's procedures with respect to rights in standards-track and 505 standards-related documentation can be found in BCP-11. Copies of 506 claims of rights made available for publication and any assurances of 507 licenses to be made available, or the result of an attempt made to 508 obtain a general license or permission for the use of such 509 proprietary rights by implementors or users of this specification can 510 be obtained from the IETF Secretariat. 512 The IETF invites any interested party to bring to its attention any 513 copyrights, patents or patent applications, or other proprietary 514 rights which may cover technology that may be required to practice 515 this standard. Please address the information to the IETF Executive 516 Director. 518 The IETF has been notified of intellectual property rights claimed in 519 regard to some or all of the specification contained in this 520 document. For more information consult the online list of claimed 521 rights. 523 9.2 Full Copyright Statement 525 Copyright (C) The Internet Society (2003). All Rights Reserved. 527 This document and translations of it may be copied and furnished to 528 others, and derivative works that comment on or otherwise explain it 529 or assist in its implementation may be prepared, copied, published 530 and distributed, in whole or in part, without restriction of any 531 kind, provided that the above copyright notice and this paragraph are 532 included on all such copies and derivative works. However, this 533 document itself may not be modified in any way, such as by removing 534 the copyright notice or references to the Internet Society or other 535 Internet organizations, except as needed for the purpose of 536 developing Internet standards in which case the procedures for 537 copyrights defined in the Internet Standards process must be 538 followed, or as required to translate it into languages other than 539 English. 541 The limited permissions granted above are perpetual and will not be 542 revoked by the Internet Society or its successors or assignees. 544 This document and the information contained herein is provided on an 545 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 546 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 547 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 548 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 549 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 551 Acknowledgement 553 Funding for the RFC Editor function is currently provided by the 554 Internet Society.