idnits 2.17.1 draft-ietf-secsh-auth-kbdinteract-00.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. ** 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 113: '... server SHOULD use this language for...' RFC 2119 keyword, line 122: '... available to the user, it MAY use the...' RFC 2119 keyword, line 124: '... MUST send the empty string....' RFC 2119 keyword, line 136: '... The server MUST reply with either a...' RFC 2119 keyword, line 139: '... The server SHOULD NOT reply with th...' (27 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 106 has weird spacing: '... string user ...' == Line 107 has weird spacing: '... string servi...' == Line 109 has weird spacing: '... string langu...' == Line 110 has weird spacing: '... string devic...' == Line 159 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 (7 March 1999) is 9182 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 225 == Unused Reference: 'RFC-2044' is defined on line 318, but no explicit reference was found in the text == Unused Reference: 'SSH-CONNECT' is defined on line 324, 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 2044 (Obsoleted by RFC 2279) == Outdated reference: A later version (-22) exists of draft-ietf-secsh-architecture-03 == Outdated reference: A later version (-25) exists of draft-ietf-secsh-connect-05 == Outdated reference: A later version (-24) exists of draft-ietf-secsh-transport-05 == Outdated reference: A later version (-27) exists of draft-ietf-secsh-userauth-05 Summary: 9 errors (**), 0 flaws (~~), 13 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 Network Working Group F. Cusack 2 INTERNET-DRAFT Qwest Internet Solutions 3 draft-ietf-secsh-auth-kbdinteract-00.txt M. Forssen 4 Expires September 7, 1999 Firedoor Network Security AB 5 7 March 1999 7 Generic Message Exchange Authentication For SSH 9 Status of this Memo 11 This document is an Internet-Draft and is in full conformance with 12 all provisions of Section 10 of RFC2026. 14 Internet-Drafts are working documents of the Internet Engineering 15 Task Force (IETF), its areas, and its working groups. Note that 16 other groups may also distribute working documents as Internet- 17 Drafts. 19 Internet-Drafts are draft documents valid for a maximum of six months 20 and may be updated, replaced, or obsoleted by other documents at any 21 time. It is inappropriate to use Internet-Drafts as reference 22 material or to cite them other than as "work in progress." 24 The list of current Internet-Drafts can be accessed at 25 http://www.ietf.org/ietf/1id-abstracts.txt. 27 The list of Internet-Draft Shadow Directories can be accessed at 28 http://www.ietf.org/shadow.html. 30 Abstract 32 SSH is a protocol for secure remote login and other secure network 33 services over an insecure network. This document describes a general 34 purpose authentication method for the SSH protocol, suitable for 35 interactive authentications where the authentication data should be 36 entered via a keyboard. The major goal of this method is to allow 37 the SSH client to have little or no knowledge of the underlying 38 authentication mechanism(s) used by the SSH server. 40 1. Introduction 42 The SSH authentication protocol is a general-purpose user 43 authentication protocol. It is intended to be run over the SSH 44 transport layer protocol [SSH-TRANS]. The protocol assumes that the 45 underlying protocols provide integrity and confidentiality 46 protection. 48 This document describes a general purpose authentication method for 49 the SSH protocol, suitable for interactive authentications where the 50 authentication data should be entered via a keyboard. The major goal 51 of this method is to allow the SSH client to have little or no 52 knowledge of the underlying authentication mechanism(s) used by the 53 SSH server. This will allow the server to arbitrarily select or 54 change the underlying authentication mechanism(s) without having to 55 update client code. 57 The method name for this authentication method is "keyboard- 58 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 3. Protocol Exchanges 93 The client initiates the authentication with a 94 SSH_MSG_USERAUTH_REQUEST message. The server then requests 95 authentication information from the client with a 96 SSH_MSG_USERAUTH_INFO_REQUEST message. The client obtains the 97 information from the user and then responds with a 98 SSM_MSG_USERAUTH_INFO_RESPONSE message. 100 3.1 Initial Exchange 102 The authentication starts with the client sending the following 103 packet: 105 byte SSH_MSG_USERAUTH_REQUEST 106 string user name (ISO-10646 UTF-8) 107 string service name (US-ASCII) 108 string "keyboard-interactive" (US-ASCII) 109 string language tag (as defined in [RFC-1766]) 110 string devices (ISO-10646 UTF-8) 112 The language tag indicates the client's preferred language. The 113 server SHOULD use this language for all text that is to be presented 114 to the user in the subsequent exchanges. 116 If the server cannot support the requested language, the language to 117 be used is implementation-defined. 119 The devices field is a comma-separated list of authentication devices 120 (software or hardware) that are available to authenticate the user 121 using the keyboard-interactive authentication method. If the client 122 has knowledge of the devices available to the user, it MAY use the 123 devices field to pass this information to the server. Otherwise it 124 MUST send the empty string. 126 Server interpretation of the devices is implementation-defined. 128 Device names should be registered with IANA (Internet Assigned 129 Numbers Authority), or a locally defined name containing an at-sign 130 (@). See section 5 of [SSH-ARCH] for more discussion on name syntax. 132 Note that when this message is sent to the server, the client has not 133 yet prompted the user for a password, and so that information is NOT 134 included with this initial message (unlike the "password" method). 136 The server MUST reply with either a SSH_MSG_USERAUTH_SUCCESS, 137 SSH_MSG_USERAUTH_FAILURE, or SSH_MSG_USERAUTH_INFO_REQUEST message. 139 The server SHOULD NOT reply with the SSH_MSG_USERAUTH_FAILURE message 140 if the failure is based on the user name or service name; instead it 141 SHOULD send SSH_MSG_USERAUTH_INFO_REQUEST message(s) which look just 142 like the one(s) which would have been sent in cases where 143 authentication should proceed, and then send the failure message 144 (after a suitable delay, as described below). The goal is to make it 145 impossible to find valid usernames by just comparing the results when 146 authenticating as different users. 148 3.2 Information Requests 150 Requests are generated from the server using the 151 SSH_MSG_USERAUTH_INFO_REQUEST message. 153 The server may send as many requests as are necessary to authenticate 154 the client; the client MUST be prepared to handle multiple exchanges. 156 The SSH_MSG_USERAUTH_INFO_REQUEST message is defined as follows: 158 byte SSH_MSG_USERAUTH_INFO_REQUEST 159 string name (ISO-10646 UTF-8) 160 string instruction (ISO-10646 UTF-8) 161 string language tag (as defined in [RFC-1766]) 162 int num-prompts 163 string prompt[1] (ISO-10646 UTF-8) 164 boolean echo[1] 165 ... 166 string prompt[num-prompts] (ISO-10646 UTF-8) 167 boolean echo[num-prompts] 169 The server SHOULD limit the length of the name and prompt fields to 170 30 characters. No restrictions are placed on the instruction field. 172 The name and instruction fields MAY be empty strings, the client MUST 173 be prepared to handle this correctly. 175 The num-prompts field may be `0', in which case there will be no 176 prompt/echo fields in the message, but the client MUST still display 177 the name and instruction fields (as described below). 179 3.3 User Interface 181 Upon receiving a request message, the client SHOULD prompt the user 182 as follows: 184 A command line interface (CLI) client SHOULD print the name and 185 instruction (if non-empty), adding newlines. Then for each prompt in 186 turn, the client MUST display the prompt and read the user input. 188 A graphical user interface (GUI) client SHOULD present a dialog 189 window, using the name (if non-empty) as the title of the window, the 190 instruction (if non-empty) as a text message inside the dialog, and 191 the appropriate number of entry fields with the prompts as labels. A 192 GUI client SHOULD NOT present each prompt in a separate window. 194 All clients MUST properly handle an instruction field with embedded 195 newlines. They MUST also be able to display at least 30 characters 196 for the name and prompts. If the server presents names/prompts 197 longer than 30 characters, the client MAY truncate these fields to 198 the length it can display. If the client does truncate any fields, 199 there SHOULD be an obvious indication that such truncation has 200 occured. 202 Clients SHOULD use control character filtering as discussed in [SSH- 203 ARCH] to avoid attacks by including terminal control characters in 204 the fields to be displayed. 206 For each prompt, the corresponding echo field indicates whether or 207 not the user input should be echoed as characters are typed. Clients 208 MUST correctly echo/mask user input for each prompt independently of 209 other prompts in the request message. Clients MUST NOT add any 210 additional characters to the prompt such as ": "; the server is 211 reponsible for supplying all text to be displayed to the user. 212 Clients MUST also accept empty responses from the user and pass them 213 on as empty strings. 215 3.4 Information Responses 217 After obtaining the requested information from the user, the client 218 MUST respond with a SSH_MSG_USERAUTH_INFO_RESPONSE message. 220 The format of the SSH_MSG_USERAUTH_INFO_RESPONSE message is as 221 follows: 223 byte SSH_MSG_USERAUTH_INFO_RESPONSE 224 int num-responses 225 string response[1] (ISO-10646 UTF-8) 226 ... 227 string response[num-responses] (ISO-10646 UTF-8) 229 Note that the responses are encoded in ISO-10646 UTF-8. It is up to 230 the server how it interprets the responses and validates them. 231 However, if the client reads the responses in some other encoding 232 (e.g., ISO 8859-1), it MUST convert the responses to ISO-10646 UTF-8 233 before transmitting, and the server MUST convert the responses to the 234 encoding used on that system that is needed to verify them. 236 If the num-responses field does not match the num-prompts field in 237 the request message, the server MUST send a failure message. 239 In the case that the server sends a `0' num-prompts field in the 240 request message, the client MUST send a response message with a `0' 241 num-responses field. 243 After receiving the response, the server MUST send either a 244 SSH_MSG_USERAUTH_SUCCESS, SSH_MSG_USERAUTH_FAILURE, or another 245 SSH_MSG_USERAUTH_INFO_REQUEST message. 247 If the server fails to authenticate the user (through the underlying 248 authentication mechanism(s)), it SHOULD NOT send another request 249 message(s) in an attempt to obtain new authentication data, instead 250 it SHOULD send a failure message. The only time the server should 251 send multiple request messages is if additional authentication data 252 is needed (i.e., because there are multiple underlying authentication 253 mechanisms that must be used to authenticate the user). 255 If the server responds with a failure message, it SHOULD delay a 256 minimum of 2 seconds before sending the failure message, to limit 257 certain types of attacks. 259 4. Authentication Example 261 Here is an example exchange between a client and server: 263 C: byte SSH_MSG_USERAUTH_REQUEST 264 C: string "foo" 265 C: string "ssh-userauth" 266 C: string "keyboard-interactive" 267 C: string "en-US" 268 C: string "password" 270 S: byte SSH_MSG_USERAUTH_INFO_REQUEST 271 S: string "Password Authentication" 272 S: string "Enter password for foo" 273 S: int 1 274 S: string "Password: " 275 S: boolean FALSE 276 S: string "en-US" 278 [Client prompts user for password] 279 C: byte SSH_MSG_USERAUTH_INFO_RESPONSE 280 C: int 1 281 C: string "bar" 283 S: byte SSH_MSG_USERAUTH_INFO_REQUEST 284 S: string "Password Expired" 285 S: string "Your password has expired." 286 S: int 2 287 S: string "Enter new password: " 288 S: boolean FALSE 289 S: string "Enter it again: " 290 S: boolean FALSE 291 S: string "en-US" 293 [Client prompts user for new password] 295 C: byte SSH_MSG_USERAUTH_INFO_RESPONSE 296 C: int 2 297 C: string "baz" 298 C: string "baz" 300 S: byte SSH_MSG_USERAUTH_SUCCESS 302 5. Protocol constants 304 The following method-specific constants are used with this 305 authentication method: 307 SSH_MSG_USERAUTH_INFO_REQUEST 60 308 SSH_MSG_USERAUTH_INFO_RESPONSE 61 310 6. References 312 [PAM] Samar, V., Schemers, R., "Unified Login With Pluggable 313 Authentication Modules (PAM)", OSF RFC 86.0, October 1995 315 [RFC-1766] Alvestrand, H., "Tags for the Identification of 316 Languages", March 1995. 318 [RFC-2044] Yergeau, F., "UTF-8, a Transformation Format of Unicode 319 and ISO 10646", October 1996. 321 [SSH-ARCH] Ylonen, T., Kivinen, T, and Saarinen, M., "SSH Protocol 322 Architecture", Internet Draft, draft-ietf-secsh-architecture-03.txt 324 [SSH-CONNECT] Ylonen, T., Kivinen, T, and Saarinen, M., "SSH 325 Connection Protocol", Internet Draft, draft-ietf-secsh-connect-05.txt 327 [SSH-TRANS] Ylonen, T., Kivinen, T, and Saarinen, M., "SSH Transport 328 Layer Protocol", Internet Draft, draft-ietf-secsh-transport-05.txt 330 [SSH-USERAUTH] Ylonen, T., Kivinen, T, and Saarinen, M., "SSH 331 Authentication Protocol", Internet Draft, draft-ietf-secsh-userauth- 332 05.txt 334 7. Author's Addresses 336 Frank Cusack 337 Qwest Internet Solutions 338 1200 Harbor Blvd, 8th Fl. 339 Weehawken, NJ 07087 340 Email: fcusack@iconnet.net 342 Martin Forssen 343 Firedoor Network Security AB 344 Stora Badhusgatan 18-20 345 SE-411 21 Gothenburg 346 SWEDEN 347 Email: maf@firedoor.se