idnits 2.17.1 draft-ietf-secsh-auth-kbdinteract-01.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: ---------------------------------------------------------------------------- ** Missing expiration date. The document expiration date should appear on the first and last page. == 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. ** There is 1 instance of too long lines in the document, the longest one being 3 characters in excess of 72. ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 117: '... server SHOULD use this language for...' RFC 2119 keyword, line 126: '... available to the user, it MAY use the...' RFC 2119 keyword, line 128: '... MUST send the empty string....' RFC 2119 keyword, line 146: '... The server MUST reply with either a...' RFC 2119 keyword, line 149: '... The server SHOULD NOT reply with th...' (26 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 110 has weird spacing: '... string user ...' == Line 111 has weird spacing: '... string servi...' == Line 113 has weird spacing: '... string langu...' == Line 114 has weird spacing: '... string devic...' == Line 169 has weird spacing: '... string name ...' == (6 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 (12 October 2000) is 8596 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 234 == Unused Reference: 'RFC-2279' is defined on line 326, but no explicit reference was found in the text == Unused Reference: 'SSH-CONNECT' is defined on line 333, 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 1766 (Obsoleted by RFC 3066, RFC 3282) ** Obsolete normative reference: RFC 2279 (Obsoleted by RFC 3629) == Outdated reference: A later version (-22) exists of draft-ietf-secsh-architecture-05 == Outdated reference: A later version (-25) exists of draft-ietf-secsh-connect-07 == Outdated reference: A later version (-24) exists of draft-ietf-secsh-transport-07 == Outdated reference: A later version (-27) exists of draft-ietf-secsh-userauth-07 Summary: 10 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 M. Forssen 3 INTERNET-DRAFT Appgate AB 4 draft-ietf-secsh-auth-kbdinteract-01.txt F. Cusack 5 Expires in six months Qwest Internet Solutions 6 12 October 2000 8 Generic Message Exchange Authentication For SSH 10 Status of this Memo 12 This document is an Internet-Draft and is in full conformance with 13 all provisions of Section 10 of RFC2026. 15 Internet-Drafts are working documents of the Internet Engineering 16 Task Force (IETF), its areas, and its working groups. Note that 17 other groups may also distribute working documents as Internet- 18 Drafts. 20 Internet-Drafts are draft documents valid for a maximum of six months 21 and may be updated, replaced, or obsoleted by other documents at any 22 time. It is inappropriate to use Internet-Drafts as reference 23 material or to cite them other than as "work in progress." 25 The list of current Internet-Drafts can be accessed at 26 http://www.ietf.org/ietf/1id-abstracts.txt. 28 The list of Internet-Draft Shadow Directories can be accessed at 29 http://www.ietf.org/shadow.html. 31 Abstract 33 SSH is a protocol for secure remote login and other secure network 34 services over an insecure network. This document describes a general 35 purpose authentication method for the SSH protocol, suitable for 36 interactive authentications where the authentication data should be 37 entered via a keyboard. The major goal of this method is to allow 38 the SSH client to have little or no knowledge of the underlying 39 authentication mechanism(s) used by the SSH server. 41 1. Introduction 43 The SSH authentication protocol is a general-purpose user 44 authentication protocol. It is intended to be run over the SSH 45 transport layer protocol [SSH-TRANS]. The protocol assumes that the 46 underlying protocols provide integrity and confidentiality 47 protection. 49 This document describes a general purpose authentication method for 50 the SSH protocol, suitable for interactive authentications where the 51 authentication data should be entered via a keyboard. The major goal 52 of this method is to allow the SSH client to have little or no 53 knowledge of the underlying authentication mechanism(s) used by the 54 SSH server. This will allow the server to arbitrarily select or 55 change the underlying authentication mechanism(s) without having to 56 update client code. 58 The name for this authentication method is "keyboard-interactive". 60 This document should be read only after reading the SSH architecture 61 document [SSH-ARCH] and the SSH authentication document [SSH- 62 USERAUTH]. This document freely uses terminology and notation from 63 both documents without reference or further explanation. 65 This document also describes some of the client interaction with the 66 user in obtaining the authentication information. While this is 67 somewhat out of the scope of a protocol specification, it is still 68 described here since some aspects of the protocol are specifically 69 designed based on user interface issues, and omitting this 70 information may lead to incompatible or awkward implementations. 72 2. Rationale 74 Currently defined authentication methods for SSH are tightly coupled 75 with the underlying authentication mechanism. This makes it 76 difficult to add new mechanisms for authentication as all clients 77 must be updated to support the new mechanism. With the generic 78 method defined here, clients will not require code changes to support 79 new authentication mechanisms, and if a separate authentication layer 80 is used, such as [PAM], then the server may not need any code changes 81 either. 83 This presents a significant advantage to other methods, such as the 84 "password" method (defined in [SSH-USERAUTH]), as new (presumably 85 stronger) methods may be added "at will" and system security can be 86 transparently enhanced. 88 Challenge-response and One Time Password mechanisms are also easily 89 supported with this authentication method. 91 This authentication method is however limited to authentication 92 mechanisms which do not require any special code, such as hardware 93 drivers or password mangling, on the client. 95 3. Protocol Exchanges 97 The client initiates the authentication with a 98 SSH_MSG_USERAUTH_REQUEST message. The server then requests 99 authentication information from the client with a 100 SSH_MSG_USERAUTH_INFO_REQUEST message. The client obtains the 101 information from the user and then responds with a 102 SSM_MSG_USERAUTH_INFO_RESPONSE message. 104 3.1 Initial Exchange 106 The authentication starts with the client sending the following 107 packet: 109 byte SSH_MSG_USERAUTH_REQUEST 110 string user name (ISO-10646 UTF-8) 111 string service name (US-ASCII) 112 string "keyboard-interactive" (US-ASCII) 113 string language tag (as defined in [RFC-1766]) 114 string devices (ISO-10646 UTF-8) 116 The language tag indicates the client's preferred language. The 117 server SHOULD use this language for all text that is to be presented 118 to the user in the subsequent exchanges. 120 If the server cannot support the requested language, the language to 121 be used is implementation-dependent. 123 The devices field is a comma-separated list of authentication devices 124 (software or hardware) that are available to authenticate the user 125 using the keyboard-interactive authentication method. If the client 126 has knowledge of the devices available to the user, it MAY use the 127 devices field to pass this information to the server. Otherwise it 128 MUST send the empty string. 130 Server interpretation of the devices is implementation-dependent. 132 One possible implementation strategy of the devices field on the 133 server is that, unless the user may use multiple different devices, 134 the server ignores this field. If the user may authenticate using one 135 of several different devices the server should treat the devices 136 field as a hint on which device the user wants to use this time. 138 Device names should be registered with IANA (Internet Assigned 139 Numbers Authority), or a locally defined name containing an at-sign 140 (@). See section 5 of [SSH-ARCH] for more discussion on name syntax. 142 Note that when this message is sent to the server, the client has not 143 yet prompted the user for a password, and so that information is NOT 144 included with this initial message (unlike the "password" method). 146 The server MUST reply with either a SSH_MSG_USERAUTH_SUCCESS, 147 SSH_MSG_USERAUTH_FAILURE, or SSH_MSG_USERAUTH_INFO_REQUEST message. 149 The server SHOULD NOT reply with the SSH_MSG_USERAUTH_FAILURE message 150 if the failure is based on the user name or service name; instead it 151 SHOULD send SSH_MSG_USERAUTH_INFO_REQUEST message(s) which look just 152 like the one(s) which would have been sent in cases where 153 authentication should proceed, and then send the failure message 154 (after a suitable delay, as described below). The goal is to make it 155 impossible to find valid user names by just comparing the results 156 when authenticating as different users. 158 3.2 Information Requests 160 Requests are generated from the server using the 161 SSH_MSG_USERAUTH_INFO_REQUEST message. 163 The server may send as many requests as are necessary to authenticate 164 the client; the client MUST be prepared to handle multiple exchanges. 166 The SSH_MSG_USERAUTH_INFO_REQUEST message is defined as follows: 168 byte SSH_MSG_USERAUTH_INFO_REQUEST 169 string name (ISO-10646 UTF-8) 170 string instruction (ISO-10646 UTF-8) 171 string language tag (as defined in [RFC-1766]) 172 int num-prompts 173 string prompt[1] (ISO-10646 UTF-8) 174 boolean echo[1] 175 ... 176 string prompt[num-prompts] (ISO-10646 UTF-8) 177 boolean echo[num-prompts] 179 The server SHOULD limit the length of the name and prompt fields to 180 30 characters. No restrictions are placed on the instruction field. 182 The name and instruction fields MAY be empty strings, the client MUST 183 be prepared to handle this correctly. 185 The num-prompts field may be `0', in which case there will be no 186 prompt/echo fields in the message, but the client MUST still display 187 the name and instruction fields (as described below). 189 3.3 User Interface 191 Upon receiving a request message, the client SHOULD prompt the user 192 as follows: 194 A command line interface (CLI) client SHOULD print the name and 195 instruction (if non-empty), adding newlines. Then for each prompt in 196 turn, the client MUST display the prompt and read the user input. 198 A graphical user interface (GUI) client SHOULD present a dialog 199 window, using the name (if non-empty) as the title of the window, the 200 instruction (if non-empty) as a text message inside the dialog, and 201 the appropriate number of entry fields with the prompts as labels. A 202 GUI client SHOULD NOT present each prompt in a separate window. 204 All clients MUST properly handle an instruction field with embedded 205 newlines. They MUST also be able to display at least 30 characters 206 for the name and prompts. If the server presents names/prompts 207 longer than 30 characters, the client MAY truncate these fields to 208 the length it can display. If the client does truncate any fields, 209 there SHOULD be an obvious indication that such truncation has 210 occurred. 212 Clients SHOULD use control character filtering as discussed in [SSH- 213 ARCH] to avoid attacks by including terminal control characters in 214 the fields to be displayed. 216 For each prompt, the corresponding echo field indicates whether or 217 not the user input should be echoed or not. Clients SHOULD correctly 218 handle echo for each prompt independently of other prompts in the 219 request message. Clients SHOULD NOT add any additional characters to 220 the prompt such as ": "; the server is responsible for supplying all 221 text to be displayed to the user. Clients MUST also accept empty 222 responses from the user and pass them on as empty strings. 224 3.4 Information Responses 226 After obtaining the requested information from the user, the client 227 MUST respond with a SSH_MSG_USERAUTH_INFO_RESPONSE message. 229 The format of the SSH_MSG_USERAUTH_INFO_RESPONSE message is as 230 follows: 232 byte SSH_MSG_USERAUTH_INFO_RESPONSE 233 int num-responses 234 string response[1] (ISO-10646 UTF-8) 235 ... 236 string response[num-responses] (ISO-10646 UTF-8) 238 Note that the responses are encoded in ISO-10646 UTF-8. It is up to 239 the server how it interprets the responses and validates them. 240 However, if the client reads the responses in some other encoding 241 (e.g., ISO 8859-1), it MUST convert the responses to ISO-10646 UTF-8 242 before transmitting. 244 If the num-responses field does not match the num-prompts field in 245 the request message, the server MUST send a failure message. 247 In the case that the server sends a `0' num-prompts field in the 248 request message, the client MUST send a response message with a `0' 249 num-responses field. 251 After receiving the response, the server MUST send either a 252 SSH_MSG_USERAUTH_SUCCESS, SSH_MSG_USERAUTH_FAILURE, or another 253 SSH_MSG_USERAUTH_INFO_REQUEST message. 255 If the server fails to authenticate the user (through the underlying 256 authentication mechanism(s)), it SHOULD NOT send another request 257 message(s) in an attempt to obtain new authentication data, instead 258 it SHOULD send a failure message. The only time the server should 259 send multiple request messages is if additional authentication data 260 is needed (i.e., because there are multiple underlying authentication 261 mechanisms that must be used to authenticate the user). 263 If the server responds with a failure message, it SHOULD delay a 264 minimum of 2 seconds before sending the failure message, to limit 265 certain types of attacks. 267 4. Authentication Example 269 Here is an example exchange between a client and server: 271 C: byte SSH_MSG_USERAUTH_REQUEST 272 C: string "user23" 273 C: string "ssh-userauth" 274 C: string "keyboard-interactive" 275 C: string "en-US" 276 C: string "" 277 S: byte SSH_MSG_USERAUTH_INFO_REQUEST 278 S: string "Password Authentication" 279 S: string "Enter password for user23@server" 280 S: string "en-US" 281 S: int 1 282 S: string "Password: " 283 S: boolean FALSE 285 [Client prompts user for password] 287 C: byte SSH_MSG_USERAUTH_INFO_RESPONSE 288 C: int 1 289 C: string "bar" 291 S: byte SSH_MSG_USERAUTH_INFO_REQUEST 292 S: string "Password Expired" 293 S: string "Your password has expired, you must enter a new one" 294 S: string "en-US" 295 S: int 2 296 S: string "New password: " 297 S: boolean FALSE 298 S: string "Enter it again: " 299 S: boolean FALSE 301 [Client prompts user for new password] 303 C: byte SSH_MSG_USERAUTH_INFO_RESPONSE 304 C: int 2 305 C: string "baz" 306 C: string "baz" 308 S: byte SSH_MSG_USERAUTH_SUCCESS 310 5. Protocol constants 312 The following method-specific constants are used with this 313 authentication method: 315 SSH_MSG_USERAUTH_INFO_REQUEST 60 316 SSH_MSG_USERAUTH_INFO_RESPONSE 61 318 6. References 320 [PAM] Samar, V., Schemers, R., "Unified Login With Pluggable 321 Authentication Modules (PAM)", OSF RFC 86.0, October 1995 323 [RFC-1766] Alvestrand, H., "Tags for the Identification of 324 Languages", March 1995. 326 [RFC-2279] Yergeau, F., "UTF-8, a Transformation Format of Unicode 327 and ISO 10646", October 1996. 329 [SSH-ARCH] T. Ylonen, T. Kivinen, M. Saarinen, T. Rinne and S. 330 Lehtinen, "SSH Protocol Architecture", Internet Draft, draft-ietf- 331 secsh-architecture-05.txt 333 [SSH-CONNECT] T. Ylonen, T. Kivinen, M. Saarinen, T. Rinne and S. 334 Lehtinen, "SSH Connection Protocol", Internet Draft, draft-ietf- 335 secsh-connect-07.txt 337 [SSH-TRANS] T. Ylonen, T. Kivinen, M. Saarinen, T. Rinne and S. 338 Lehtinen, "SSH Transport Layer Protocol", Internet Draft, draft- 339 ietf-secsh-transport-07.txt 341 [SSH-USERAUTH] T. Ylonen, T. Kivinen, M. Saarinen, T. Rinne and S. 342 Lehtinen, "SSH Authentication Protocol", Internet Draft, draft-ietf- 343 secsh-userauth-07.txt 345 7. Author's Addresses 347 Frank Cusack 348 Qwest Internet Solutions 349 1200 Harbor Blvd, 8th Fl. 350 Weehawken, NJ 07087 351 Email: fcusack@iconnet.net 353 Martin Forssen 354 Appgate AB 355 Stora Badhusgatan 18-20 356 SE-411 21 Gothenburg 357 SWEDEN 358 Email: maf@appgate.com