idnits 2.17.1 draft-ietf-secsh-auth-kbdinteract-03.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** The document 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 : ---------------------------------------------------------------------------- ** The document seems to lack a Security Considerations section. ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 121 has weird spacing: '... string use...' == Line 122 has weird spacing: '... string ser...' == Line 124 has weird spacing: '... string lan...' == Line 125 has weird spacing: '... string sub...' == Line 190 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 (April 2, 2002) is 8053 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 279 == Unused Reference: 'RFC-2119' is defined on line 412, but no explicit reference was found in the text == Unused Reference: 'RFC-2279' is defined on line 415, but no explicit reference was found in the text == Unused Reference: 'SSH-CONNECT' is defined on line 426, but no explicit reference was found in the text ** Downref: Normative reference to an Unknown state RFC: RFC 86 (ref. 'PAM') ** Obsolete normative reference: RFC 2279 (Obsoleted by RFC 3629) ** Obsolete normative reference: RFC 3066 (Obsoleted by RFC 4646, RFC 4647) == Outdated reference: A later version (-22) exists of draft-ietf-secsh-architecture-12 == Outdated reference: A later version (-25) exists of draft-ietf-secsh-connect-15 == Outdated reference: A later version (-24) exists of draft-ietf-secsh-transport-14 == Outdated reference: A later version (-27) exists of draft-ietf-secsh-userauth-15 Summary: 9 errors (**), 0 flaws (~~), 14 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 October 2, 2002 M. Forssen 5 Appgate AB 6 April 2, 2002 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 October 2, 2002. 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 is a general-purpose user 48 authentication protocol. It is intended to be run over the SSH 49 transport layer protocol [SSH-TRANS]. The protocol assumes that the 50 underlying protocols provide integrity and confidentiality 51 protection. 53 This document describes a general purpose authentication method for 54 the SSH protocol. This method is suitable for interactive 55 authentication methods which do not need any special software support 56 on the client side. Instead all authentication data should be 57 entered via the keyboard. The major goal of this method is to allow 58 the SSH client to have little or no knowledge of the specifics of the 59 underlying authentication mechanism(s) used by the SSH server. This 60 will allow the server to arbitrarily select or change the underlying 61 authentication mechanism(s) without having to update client code. 63 The name for this authentication method is "keyboard-interactive". 65 This document should be read only after reading the SSH architecture 66 document [SSH-ARCH] and the SSH authentication document 67 [SSH-USERAUTH]. This document freely uses terminology and notation 68 from both documents without reference or further explanation. 70 This document also describes some of the client interaction with the 71 user in obtaining the authentication information. While this is 72 somewhat out of the scope of a protocol specification, it is still 73 described here since some aspects of the protocol are specifically 74 designed based on user interface issues, and omitting this 75 information may lead to incompatible or awkward implementations. 77 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 78 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 79 document are to be interpreted as described in RFC 2119. 81 2. Rationale 83 Currently defined authentication methods for SSH are tightly coupled 84 with the underlying authentication mechanism. This makes it 85 difficult to add new mechanisms for authentication as all clients 86 must be updated to support the new mechanism. With the generic 87 method defined here, clients will not require code changes to support 88 new authentication mechanisms, and if a separate authentication layer 89 is used, such as [PAM], then the server may not need any code changes 90 either. 92 This presents a significant advantage to other methods, such as the 93 "password" method (defined in [SSH-USERAUTH]), as new (presumably 94 stronger) methods may be added "at will" and system security can be 95 transparently enhanced. 97 Challenge-response and One Time Password mechanisms are also easily 98 supported with this authentication method. 100 This authentication method is however limited to authentication 101 mechanisms which do not require any special code, such as hardware 102 drivers or password mangling, on the client. 104 3. Protocol Exchanges 106 The client initiates the authentication with a 107 SSH_MSG_USERAUTH_REQUEST message. The server then requests 108 authentication information from the client with a 109 SSH_MSG_USERAUTH_INFO_REQUEST message. The client obtains the 110 information from the user and then responds with a 111 SSM_MSG_USERAUTH_INFO_RESPONSE message. The server MUST NOT send 112 another SSH_MSG_USERAUTH_INFO_REQUEST before it has received the 113 answer from the client. 115 3.1 Initial Exchange 117 The authentication starts with the client sending the following 118 packet: 120 byte SSH_MSG_USERAUTH_REQUEST 121 string user name (ISO-10646 UTF-8) 122 string service name (US-ASCII) 123 string "keyboard-interactive" (US-ASCII) 124 string language tag (as defined in [RFC-3066]) 125 string submethods (ISO-10646 UTF-8) 127 The language tag is deprecated and SHOULD be the empty string. It 128 may be removed in a future revision of this specification. The 129 server SHOULD instead select the language used based on the tags 130 communicated during key exchange [SSH-TRANS]. 132 If the language tag is not the empty string, the server SHOULD use 133 the specified language for any messages sent to the client as part of 134 this protocol. The language tag SHOULD NOT be used for language 135 selection for messages outside of this protocol. The language to be 136 used if the server does not support the requested language is 137 implementation-dependent. 139 The submethods field is included so the user can give a hint of which 140 actual methods he wants to use. It is a a comma-separated list of 141 authentication submethods (software or hardware) which the user 142 prefers. If the client has knowledge of the submethods preferred by 143 the user, presumably through a configuration setting, it MAY use the 144 submethods field to pass this information to the server. Otherwise 145 it MUST send the empty string. 147 The actual names of the submethods is something which the user and 148 the server needs to agree upon. 150 Server interpretation of the submethods field is implementation- 151 dependent. 153 One possible implementation strategy of the submethods field on the 154 server is that, unless the user may use multiple different 155 submethods, the server ignores this field. If the user may 156 authenticate using one of several different submethods the server 157 should treat the submethods field as a hint on which submethod the 158 user wants to use this time. 160 Note that when this message is sent to the server, the client has not 161 yet prompted the user for a password, and so that information is NOT 162 included with this initial message (unlike the "password" method). 164 The server MUST reply with either a SSH_MSG_USERAUTH_SUCCESS, 165 SSH_MSG_USERAUTH_FAILURE, or SSH_MSG_USERAUTH_INFO_REQUEST message. 167 The server SHOULD NOT reply with the SSH_MSG_USERAUTH_FAILURE message 168 if the failure is based on the user name or service name; instead it 169 SHOULD send SSH_MSG_USERAUTH_INFO_REQUEST message(s) which look just 170 like the one(s) which would have been sent in cases where 171 authentication should proceed, and then send the failure message 172 (after a suitable delay, as described below). The goal is to make it 173 impossible to find valid usernames by just comparing the results when 174 authenticating as different users. 176 3.2 Information Requests 178 Requests are generated from the server using the 179 SSH_MSG_USERAUTH_INFO_REQUEST message. 181 The server may send as many requests as are necessary to authenticate 182 the client; the client MUST be prepared to handle multiple exchanges. 183 However the server MUST NOT ever have more than one 184 SSH_MSG_USERAUTH_INFO_REQUEST message outstanding. That is, it may 185 not send another request before the client has answered. 187 The SSH_MSG_USERAUTH_INFO_REQUEST message is defined as follows: 189 byte SSH_MSG_USERAUTH_INFO_REQUEST 190 string name (ISO-10646 UTF-8) 191 string instruction (ISO-10646 UTF-8) 192 string language tag (as defined in [RFC-3066]) 193 int num-prompts 194 string prompt[1] (ISO-10646 UTF-8) 195 boolean echo[1] 196 ... 197 string prompt[num-prompts] (ISO-10646 UTF-8) 198 boolean echo[num-prompts] 200 The server SHOULD take into consideration that some clients may not 201 be able to properly display a long name or prompt field (see next 202 section), and limit the lengths of those fields if possible. For 203 example, instead of an instruction field of "Enter Password" and a 204 prompt field of "Password for user23@host.domain: ", a better choice 205 might be an instruction field of 206 "Password authentication for user23@host.domain" and a prompt field 207 of "Password: ". It is expected that this authentication method 208 would typically be backended by [PAM] and so such choices would not 209 be possible. 211 The name and instruction fields MAY be empty strings, the client MUST 212 be prepared to handle this correctly. The prompt field(s) MUST NOT 213 be empty strings. 215 The language tag SHOULD describe the language used in the textual 216 fields. If the server does not know the language used, or if 217 multiple languages are used, the language tag MUST be the empty 218 string. 220 The num-prompts field may be `0', in which case there will be no 221 prompt/echo fields in the message, but the client SHOULD still 222 display the name and instruction fields (as described below). 224 3.3 User Interface 226 Upon receiving a request message, the client SHOULD prompt the user 227 as follows: 229 A command line interface (CLI) client SHOULD print the name and 230 instruction (if non-empty), adding newlines. Then for each prompt in 231 turn, the client SHOULD display the prompt and read the user input. 233 A graphical user interface (GUI) client has many choices on how to 234 prompt the user. One possibility is to use the name field (possibly 235 prefixed with the application's name) as the title of a dialog window 236 in which the prompt(s) are presented. In that dialog window, the 237 instruction field would be a text message, and the prompts would be 238 labels for text entry fields. All fields SHOULD be presented to the 239 user, for example an implementation SHOULD NOT discard the name field 240 because its windows lack titles; it SHOULD instead find another way 241 to display this information. If prompts are presented in a dialog 242 window, then the client SHOULD NOT present each prompt in a separate 243 window. 245 All clients MUST properly handle an instruction field with embedded 246 newlines. They SHOULD also be able to display at least 30 characters 247 for the name and prompts. If the server presents names or prompts 248 longer than 30 characters, the client MAY truncate these fields to 249 the length it can display. If the client does truncate any fields, 250 there MUST be an obvious indication that such truncation has occured. 251 The instruction field SHOULD NOT be truncated. 253 Clients SHOULD use control character filtering as discussed in 254 [SSH-ARCH] to avoid attacks by including terminal control characters 255 in the fields to be displayed. 257 For each prompt, the corresponding echo field indicates whether or 258 not the user input should be echoed as characters are typed. Clients 259 SHOULD correctly echo/mask user input for each prompt independently 260 of other prompts in the request message. If a client does not honor 261 the echo field for whatever reason, then the client MUST err on the 262 side of masking input. A GUI client might like to have a checkbox 263 toggling echo/mask. Clients SHOULD NOT add any additional characters 264 to the prompt such as ": " (colon-space); the server is responsible 265 for supplying all text to be displayed to the user. Clients MUST 266 also accept empty responses from the user and pass them on as empty 267 strings. 269 3.4 Information Responses 271 After obtaining the requested information from the user, the client 272 MUST respond with a SSH_MSG_USERAUTH_INFO_RESPONSE message. 274 The format of the SSH_MSG_USERAUTH_INFO_RESPONSE message is as 275 follows: 277 byte SSH_MSG_USERAUTH_INFO_RESPONSE 278 int num-responses 279 string response[1] (ISO-10646 UTF-8) 280 ... 281 string response[num-responses] (ISO-10646 UTF-8) 283 Note that the responses are encoded in ISO-10646 UTF-8. It is up to 284 the server how it interprets the responses and validates them. 285 However, if the client reads the responses in some other encoding 286 (e.g., ISO 8859-1), it MUST convert the responses to ISO-10646 UTF-8 287 before transmitting. 289 If the num-responses field does not match the num-prompts field in 290 the request message, the server MUST send a failure message. 292 In the case that the server sends a `0' num-prompts field in the 293 request message, the client MUST send a response message with a `0' 294 num-responses field. 296 The responses must be ordered as the prompts were ordered. That is, 297 response[n] must be the answer to prompt[n]. 299 After receiving the response, the server MUST send either a 300 SSH_MSG_USERAUTH_SUCCESS, SSH_MSG_USERAUTH_FAILURE, or another 301 SSH_MSG_USERAUTH_INFO_REQUEST message. 303 If the server fails to authenticate the user (through the underlying 304 authentication mechanism(s)), it SHOULD NOT send another request 305 message(s) in an attempt to obtain new authentication data, instead 306 it SHOULD send a failure message. The only time the server should 307 send multiple request messages is if additional authentication data 308 is needed (i.e., because there are multiple underlying authentication 309 mechanisms that must be used to authenticate the user). 311 If the server intends to respond with a failure message, it MAY delay 312 for an implementation-dependent time before sending to the client. 313 It is suspected that implementations are likely to make the time 314 delay a configurable, a suggested default is 2 seconds. 316 4. Authentication Examples 318 Here are two example exchanges between a client and server. The 319 first is an example of a challenge/response implementation. This is 320 an authentication that is not otherwise possible with other 321 authentication methods. 323 C: byte SSH_MSG_USERAUTH_REQUEST 324 C: string "user23" 325 C: string "ssh-userauth" 326 C: string "keyboard-interactive" 327 C: string "" 328 C: string "" 329 S: byte SSH_MSG_USERAUTH_INFO_REQUEST 330 S: string "CRYPTOCard Authentication" 331 S: string "The challenge is '14315716'" 332 S: string "en-US" 333 S: int 1 334 S: string "Response: " 335 S: boolean TRUE 337 [Client prompts user for password] 339 C: byte SSH_MSG_USERAUTH_INFO_RESPONSE 340 C: int 1 341 C: string "6d757575" 343 S: byte SSH_MSG_USERAUTH_SUCCESS 345 The second example is of a standard password authentication, in 346 this case the user's password is expired. 348 C: byte SSH_MSG_USERAUTH_REQUEST 349 C: string "user23" 350 C: string "ssh-userauth" 351 C: string "keyboard-interactive" 352 C: string "en-US" 353 C: string "" 355 S: byte SSH_MSG_USERAUTH_INFO_REQUEST 356 S: string "Password Authentication" 357 S: string "" 358 S: string "en-US" 359 S: int 1 360 S: string "Password: " 361 S: boolean FALSE 363 [Client prompts user for password] 365 C: byte SSH_MSG_USERAUTH_INFO_RESPONSE 366 C: int 1 367 C: string "password" 368 S: byte SSH_MSG_USERAUTH_INFO_REQUEST 369 S: string "Password Expired" 370 S: string "Your password has expired." 371 S: string "en-US" 372 S: int 2 373 S: string "Enter new password: " 374 S: boolean FALSE 375 S: string "Enter it again: " 376 S: boolean FALSE 378 [Client prompts user for new password] 380 C: byte SSH_MSG_USERAUTH_INFO_RESPONSE 381 C: int 2 382 C: string "newpass" 383 C: string "newpass" 385 S: byte SSH_MSG_USERAUTH_INFO_REQUEST 386 S: string "Password changed" 387 S: string "Password successfully changed for user23." 388 S: string "en-US" 389 S: int 0 391 [Client displays message to user] 393 C: byte SSH_MSG_USERAUTH_INFO_RESPONSE 394 C: int 0 396 S: byte SSH_MSG_USERAUTH_SUCCESS 398 5. Protocol constants 400 The following method-specific constants are used with this 401 authentication method: 403 SSH_MSG_USERAUTH_INFO_REQUEST 60 404 SSH_MSG_USERAUTH_INFO_RESPONSE 61 406 6. References 408 [PAM] Samar, V., Schemers, R., "Unified Login With 409 Pluggable Authentication Modules (PAM)", OSF RFC 410 86.0, October 1995 412 [RFC-2119] Bradner, S., "Key words for use in RFCs to Indicate 413 Requirement Level", BCP 14, RFC 2119, March 1997. 415 [RFC-2279] Yergeau, F., "UTF-8, a transformation format of 416 Unicode and ISO 10646", RFC 2279, October 1996. 418 [RFC-3066] Alvestrand, H., "Tags for the Identification of 419 Languages", BCP 47, RFC 3066, January 2001. 421 [SSH-ARCH] Ylonen, T., Kivinen, T, Saarinen, M., Rinne, T., and 422 Lehtinen, S., "SSH Protocol Architecture", work in 423 progress, draft-ietf-secsh-architecture-12.txt, 424 January, 2002. 426 [SSH-CONNECT] Ylonen, T., Kivinen, T, Saarinen, M., Rinne, T., and 427 Lehtinen, S., "SSH Connection Protocol", work in 428 progress, draft-ietf-secsh-connect-15.txt, January, 429 2002. 431 [SSH-TRANS] Ylonen, T., Kivinen, T, Saarinen, M., Rinne, T., and 432 Lehtinen, S., "SSH Transport Layer Protocol", work in 433 progress, draft-ietf-secsh-transport-14.txt, March, 434 2002. 436 [SSH-USERAUTH] Ylonen, T., Kivinen, T, Saarinen, M., Rinne, T., and 437 Lehtinen, S., "SSH Authentication Protocol", work in 438 progress, draft-ietf-secsh-userauth-15.txt, February, 439 2002. 441 7. Author's Addresses 443 Frank Cusack 444 Google, Inc. 445 2400 Bayshore Parkway 446 Mountain View, CA 94043 447 Email: frank@google.com 449 Martin Forssen 450 Appgate AB 451 Stora Badhusgatan 18-20 452 SE-411 21 Gothenburg 453 SWEDEN 454 Email: maf@appgate.com