aboutsummaryrefslogtreecommitdiff
path: root/doc/draft-ietf-secsh-auth-kbdinteract-05.txt
blob: 99504dbfa5b41b77b94c66398dd8b4bd87526289 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
Network Working Group                                          F. Cusack
INTERNET-DRAFT                                              Google, Inc.
Expires November 1, 2003                                      M. Forssen
                                                              Appgate AB
                                                             May 1, 2003




            Generic Message Exchange Authentication For SSH
               <draft-ietf-secsh-auth-kbdinteract-05.txt>

Status of this Memo

   This document is an Internet-Draft and is subject to all provisions
   of Section 10 of RFC2026.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF), its areas, and its working groups.  Note that
   other groups may also distribute working documents as
   Internet-Drafts.

   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is inappropriate to use Internet-Drafts as reference
   material or to cite them other than as "work in progress."

   The list of current Internet-Drafts can be accessed at
   <http://www.ietf.org/ietf/1id-abstracts.txt>.

   The list of Internet-Draft Shadow Directories can be accessed at
   <http://www.ietf.org/shadow.html>.

   This Internet-Draft will expire on November 1, 2003.

Abstract

   SSH is a protocol for secure remote login and other secure network
   services over an insecure network.  This document describes a general
   purpose authentication method for the SSH protocol, suitable for
   interactive authentications where the authentication data should be
   entered via a keyboard.  The major goal of this method is to allow
   the SSH client to support a whole class of authentication
   mechanism(s) without knowing the specifics of the actual
   authentication mechanism(s).









F. Cusack, M. Forssen   Expires November 1, 2003                [Page 1]

Internet Draft   SSH Generic Interactive Authentication      May 1, 2003


1. Introduction

   The SSH authentication protocol [SSH-USERAUTH] is a general-purpose
   user authentication protocol. It is intended to be run over the SSH
   transport layer protocol [SSH-TRANS].  The authentication protocol
   assumes that the underlying protocols provide integrity and
   confidentiality protection.

   This document describes a general purpose authentication method for
   the SSH authentication protocol.  This method is suitable for
   interactive authentication methods which do not need any special
   software support on the client side.  Instead all authentication data
   should be entered via the keyboard.  The major goal of this method is
   to allow the SSH client to have little or no knowledge of the
   specifics of the underlying authentication mechanism(s) used by the
   SSH server.  This will allow the server to arbitrarily select or
   change the underlying authentication mechanism(s) without having to
   update client code.

   The name for this authentication method is "keyboard-interactive".

   This document should be read only after reading the SSH architecture
   document [SSH-ARCH] and the SSH authentication document
   [SSH-USERAUTH].  This document freely uses terminology and notation
   from both documents without reference or further explanation.

   This document also describes some of the client interaction with the
   user in obtaining the authentication information.  While this is
   somewhat out of the scope of a protocol specification, it is
   described here anyway since some aspects of the protocol are
   specifically designed based on user interface issues, and omitting
   this information may lead to incompatible or awkward implementations.

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
   document are to be interpreted as described in [RFC-2119].

2. Rationale

   Currently defined authentication methods for SSH are tightly coupled
   with the underlying authentication mechanism.  This makes it
   difficult to add new mechanisms for authentication as all clients
   must be updated to support the new mechanism.  With the generic
   method defined here, clients will not require code changes to support
   new authentication mechanisms, and if a separate authentication layer
   is used, such as [PAM], then the server may not need any code changes
   either.




F. Cusack, M. Forssen   Expires November 1, 2003                [Page 2]

Internet Draft   SSH Generic Interactive Authentication      May 1, 2003


   This presents a significant advantage to other methods, such as the
   "password" method (defined in [SSH-USERAUTH]), as new (presumably
   stronger) methods may be added "at will" and system security can be
   transparently enhanced.

   Challenge-response and One Time Password mechanisms are also easily
   supported with this authentication method.

   This authentication method is however limited to authentication
   mechanisms which do not require any special code, such as hardware
   drivers or password mangling, on the client.

3. Protocol Exchanges

   The client initiates the authentication with a
   SSH_MSG_USERAUTH_REQUEST message.  The server then requests
   authentication information from the client with a
   SSH_MSG_USERAUTH_INFO_REQUEST message.  The client obtains the
   information from the user and then responds with a
   SSM_MSG_USERAUTH_INFO_RESPONSE message.  The server MUST NOT send
   another SSH_MSG_USERAUTH_INFO_REQUEST before it has received the
   answer from the client.

3.1 Initial Exchange

   The authentication starts with the client sending the following
   packet:

      byte      SSH_MSG_USERAUTH_REQUEST
      string    user name (ISO-10646 UTF-8, as defined in [RFC-2279])
      string    service name (US-ASCII)
      string    "keyboard-interactive" (US-ASCII)
      string    language tag (as defined in [RFC-3066])
      string    submethods (ISO-10646 UTF-8)

   The language tag is deprecated and SHOULD be the empty string.  It
   may be removed in a future revision of this specification.  The
   server SHOULD instead select the language used based on the tags
   communicated during key exchange [SSH-TRANS].

   If the language tag is not the empty string, the server SHOULD use
   the specified language for any messages sent to the client as part of
   this protocol.  The language tag SHOULD NOT be used for language
   selection for messages outside of this protocol.  The language to be
   used if the server does not support the requested language is
   implementation-dependent.

   The submethods field is included so the user can give a hint of which



F. Cusack, M. Forssen   Expires November 1, 2003                [Page 3]

Internet Draft   SSH Generic Interactive Authentication      May 1, 2003


   actual methods he wants to use.  It is a a comma-separated list of
   authentication submethods (software or hardware) which the user
   prefers.  If the client has knowledge of the submethods preferred by
   the user, presumably through a configuration setting, it MAY use the
   submethods field to pass this information to the server.  Otherwise
   it MUST send the empty string.

   The actual names of the submethods is something which the user and
   the server needs to agree upon.

   Server interpretation of the submethods field is implementation-
   dependent.

   One possible implementation strategy of the submethods field on the
   server is that, unless the user may use multiple different
   submethods, the server ignores this field.  If the user may
   authenticate using one of several different submethods the server
   should treat the submethods field as a hint on which submethod the
   user wants to use this time.

   Note that when this message is sent to the server, the client has not
   yet prompted the user for a password, and so that information is NOT
   included with this initial message (unlike the "password" method).

   The server MUST reply with either a SSH_MSG_USERAUTH_SUCCESS,
   SSH_MSG_USERAUTH_FAILURE, or SSH_MSG_USERAUTH_INFO_REQUEST message.

   The server SHOULD NOT reply with the SSH_MSG_USERAUTH_FAILURE message
   if the failure is based on the user name or service name; instead it
   SHOULD send SSH_MSG_USERAUTH_INFO_REQUEST message(s) which look just
   like the one(s) which would have been sent in cases where
   authentication should proceed, and then send the failure message
   (after a suitable delay, as described below).  The goal is to make it
   impossible to find valid usernames by just comparing the results when
   authenticating as different users.

3.2 Information Requests

   Requests are generated from the server using the
   SSH_MSG_USERAUTH_INFO_REQUEST message.

   The server may send as many requests as are necessary to authenticate
   the client; the client MUST be prepared to handle multiple exchanges.
   However the server MUST NOT ever have more than one
   SSH_MSG_USERAUTH_INFO_REQUEST message outstanding. That is, it may
   not send another request before the client has answered.





F. Cusack, M. Forssen   Expires November 1, 2003                [Page 4]

Internet Draft   SSH Generic Interactive Authentication      May 1, 2003


   The SSH_MSG_USERAUTH_INFO_REQUEST message is defined as follows:

      byte      SSH_MSG_USERAUTH_INFO_REQUEST
      string    name (ISO-10646 UTF-8)
      string    instruction (ISO-10646 UTF-8)
      string    language tag (as defined in [RFC-3066])
      int       num-prompts
      string    prompt[1] (ISO-10646 UTF-8)
      boolean   echo[1]
      ...
      string    prompt[num-prompts] (ISO-10646 UTF-8)
      boolean   echo[num-prompts]

   The server SHOULD take into consideration that some clients may not
   be able to properly display a long name or prompt field (see next
   section), and limit the lengths of those fields if possible.  For
   example, instead of an instruction field of "Enter Password" and a
   prompt field of "Password for user23@host.domain: ", a better choice
   might be an instruction field of
   "Password authentication for user23@host.domain" and a prompt field
   of "Password: ".  It is expected that this authentication method
   would typically be backended by [PAM] and so such choices would not
   be possible.

   The name and instruction fields MAY be empty strings, the client MUST
   be prepared to handle this correctly.  The prompt field(s) MUST NOT
   be empty strings.

   The language tag SHOULD describe the language used in the textual
   fields.  If the server does not know the language used, or if
   multiple languages are used, the language tag MUST be the empty
   string.

   The num-prompts field may be `0', in which case there will be no
   prompt/echo fields in the message, but the client SHOULD still
   display the name and instruction fields (as described below).

3.3 User Interface

   Upon receiving a request message, the client SHOULD prompt the user
   as follows:

   A command line interface (CLI) client SHOULD print the name and
   instruction (if non-empty), adding newlines.  Then for each prompt in
   turn, the client SHOULD display the prompt and read the user input.

   A graphical user interface (GUI) client has many choices on how to
   prompt the user.  One possibility is to use the name field (possibly



F. Cusack, M. Forssen   Expires November 1, 2003                [Page 5]

Internet Draft   SSH Generic Interactive Authentication      May 1, 2003


   prefixed with the application's name) as the title of a dialog window
   in which the prompt(s) are presented.  In that dialog window, the
   instruction field would be a text message, and the prompts would be
   labels for text entry fields.  All fields SHOULD be presented to the
   user, for example an implementation SHOULD NOT discard the name field
   because its windows lack titles; it SHOULD instead find another way
   to display this information.  If prompts are presented in a dialog
   window, then the client SHOULD NOT present each prompt in a separate
   window.

   All clients MUST properly handle an instruction field with embedded
   newlines.  They SHOULD also be able to display at least 30 characters
   for the name and prompts.  If the server presents names or prompts
   longer than 30 characters, the client MAY truncate these fields to
   the length it can display.  If the client does truncate any fields,
   there MUST be an obvious indication that such truncation has occured.
   The instruction field SHOULD NOT be truncated.

   Clients SHOULD use control character filtering as discussed in
   [SSH-ARCH] to avoid attacks by including terminal control characters
   in the fields to be displayed.

   For each prompt, the corresponding echo field indicates whether or
   not the user input should be echoed as characters are typed.  Clients
   SHOULD correctly echo/mask user input for each prompt independently
   of other prompts in the request message.  If a client does not honor
   the echo field for whatever reason, then the client MUST err on the
   side of masking input.  A GUI client might like to have a checkbox
   toggling echo/mask.  Clients SHOULD NOT add any additional characters
   to the prompt such as ": " (colon-space); the server is responsible
   for supplying all text to be displayed to the user.  Clients MUST
   also accept empty responses from the user and pass them on as empty
   strings.

3.4 Information Responses

   After obtaining the requested information from the user, the client
   MUST respond with a SSH_MSG_USERAUTH_INFO_RESPONSE message.

   The format of the SSH_MSG_USERAUTH_INFO_RESPONSE message is as
   follows:

      byte      SSH_MSG_USERAUTH_INFO_RESPONSE
      int       num-responses
      string    response[1] (ISO-10646 UTF-8)
      ...
      string    response[num-responses] (ISO-10646 UTF-8)




F. Cusack, M. Forssen   Expires November 1, 2003                [Page 6]

Internet Draft   SSH Generic Interactive Authentication      May 1, 2003


   Note that the responses are encoded in ISO-10646 UTF-8.  It is up to
   the server how it interprets the responses and validates them.
   However, if the client reads the responses in some other encoding
   (e.g., ISO 8859-1), it MUST convert the responses to ISO-10646 UTF-8
   before transmitting.

   If the num-responses field does not match the num-prompts field in
   the request message, the server MUST send a failure message.

   In the case that the server sends a `0' num-prompts field in the
   request message, the client MUST send a response message with a `0'
   num-responses field.

   The responses MUST be ordered as the prompts were ordered.  That is,
   response[n] MUST be the answer to prompt[n].

   After receiving the response, the server MUST send either a
   SSH_MSG_USERAUTH_SUCCESS, SSH_MSG_USERAUTH_FAILURE, or another
   SSH_MSG_USERAUTH_INFO_REQUEST message.

   If the server fails to authenticate the user (through the underlying
   authentication mechanism(s)), it SHOULD NOT send another request
   message(s) in an attempt to obtain new authentication data, instead
   it SHOULD send a failure message.  The only time the server should
   send multiple request messages is if additional authentication data
   is needed (i.e., because there are multiple underlying authentication
   mechanisms that must be used to authenticate the user).

   If the server intends to respond with a failure message, it MAY delay
   for an implementation-dependent time before sending to the client.
   It is suspected that implementations are likely to make the time
   delay a configurable, a suggested default is 2 seconds.

4. Authentication Examples

   Here are two example exchanges between a client and server.  The
   first is an example of challenge/response with a handheld token.
   This is an authentication that is not otherwise possible with other
   authentication methods.

      C:   byte      SSH_MSG_USERAUTH_REQUEST
      C:   string    "user23"
      C:   string    "ssh-userauth"
      C:   string    "keyboard-interactive"
      C:   string    ""
      C:   string    ""





F. Cusack, M. Forssen   Expires November 1, 2003                [Page 7]

Internet Draft   SSH Generic Interactive Authentication      May 1, 2003


      S:   byte      SSH_MSG_USERAUTH_INFO_REQUEST
      S:   string    "CRYPTOCard Authentication"
      S:   string    "The challenge is '14315716'"
      S:   string    "en-US"
      S:   int       1
      S:   string    "Response: "
      S:   boolean   TRUE

      [Client prompts user for password]

      C:   byte      SSH_MSG_USERAUTH_INFO_RESPONSE
      C:   int       1
      C:   string    "6d757575"

      S:   byte      SSH_MSG_USERAUTH_SUCCESS

   The second example is of a standard password authentication, in
   this case the user's password is expired.

      C:   byte      SSH_MSG_USERAUTH_REQUEST
      C:   string    "user23"
      C:   string    "ssh-userauth"
      C:   string    "keyboard-interactive"
      C:   string    "en-US"
      C:   string    ""

      S:   byte      SSH_MSG_USERAUTH_INFO_REQUEST
      S:   string    "Password Authentication"
      S:   string    ""
      S:   string    "en-US"
      S:   int       1
      S:   string    "Password: "
      S:   boolean   FALSE

      [Client prompts user for password]

      C:   byte      SSH_MSG_USERAUTH_INFO_RESPONSE
      C:   int       1
      C:   string    "password"












F. Cusack, M. Forssen   Expires November 1, 2003                [Page 8]

Internet Draft   SSH Generic Interactive Authentication      May 1, 2003


      S:   byte      SSH_MSG_USERAUTH_INFO_REQUEST
      S:   string    "Password Expired"
      S:   string    "Your password has expired."
      S:   string    "en-US"
      S:   int       2
      S:   string    "Enter new password: "
      S:   boolean   FALSE
      S:   string    "Enter it again: "
      S:   boolean   FALSE

      [Client prompts user for new password]

      C:   byte      SSH_MSG_USERAUTH_INFO_RESPONSE
      C:   int       2
      C:   string    "newpass"
      C:   string    "newpass"

      S:   byte      SSH_MSG_USERAUTH_INFO_REQUEST
      S:   string    "Password changed"
      S:   string    "Password successfully changed for user23."
      S:   string    "en-US"
      S:   int       0

      [Client displays message to user]

      C:   byte      SSH_MSG_USERAUTH_INFO_RESPONSE
      C:   int       0

      S:   byte      SSH_MSG_USERAUTH_SUCCESS

5. IANA Considerations

   The userauth type "keyboard-interactive" is used for this
   authentication method.

   The following method-specific constants are used with this
   authentication method:

   SSH_MSG_USERAUTH_INFO_REQUEST           60
   SSH_MSG_USERAUTH_INFO_RESPONSE          61

6. Security Considerations

   The authentication protocol, and this authentication method, depends
   on the security of the underlying SSH transport layer.  Without the
   confidentiality provided therein, any authentication data passed with
   this method is subject to interception.




F. Cusack, M. Forssen   Expires November 1, 2003                [Page 9]

Internet Draft   SSH Generic Interactive Authentication      May 1, 2003


   The number of client-server exchanges required to complete an
   authentication using this method may be variable.  It is possible
   that an observer may gain valuable information simply by counting
   that number.  For example, an observer may guess that a user's
   password has expired, and with further observation may be able to
   determine the frequency of a site's password expiration policy.

7. References

7.1 Normative References


   [RFC-2119]      Bradner, S., "Key words for use in RFCs to Indicate
                   Requirement Level", BCP 14, RFC 2119, March 1997.


   [RFC-2279]      Yergeau, F., "UTF-8, a transformation format of
                   Unicode and ISO 10646", RFC 2279, October 1996.


   [RFC-3066]      Alvestrand, H., "Tags for the Identification of
                   Languages", BCP 47, RFC 3066, January 2001.


   [SSH-ARCH]      Ylonen, T., Kivinen, T, Saarinen, M., Rinne, T., and
                   Lehtinen, S., "SSH Protocol Architecture", work in
                   progress, draft-ietf-secsh-architecture-13.txt,
                   September, 2002.


   [SSH-CONNECT]   Ylonen, T., Kivinen, T, Saarinen, M., Rinne, T., and
                   Lehtinen, S., "SSH Connection Protocol", work in
                   progress, draft-ietf-secsh-connect-16.txt, September,
                   2002.


   [SSH-TRANS]     Ylonen, T., Kivinen, T, Saarinen, M., Rinne, T., and
                   Lehtinen, S., "SSH Transport Layer Protocol", work in
                   progress, draft-ietf-secsh-transport-15.txt,
                   September, 2002.


   [SSH-USERAUTH]  Ylonen, T., Kivinen, T, Saarinen, M., Rinne, T., and
                   Lehtinen, S., "SSH Authentication Protocol", work in
                   progress, draft-ietf-secsh-userauth-16.txt,
                   September, 2002.





F. Cusack, M. Forssen   Expires November 1, 2003               [Page 10]

Internet Draft   SSH Generic Interactive Authentication      May 1, 2003


7.2 Informative References


   [PAM]           Samar, V., Schemers, R., "Unified Login With
                   Pluggable Authentication Modules (PAM)", OSF RFC
                   86.0, October 1995

8. Author's Addresses

   Frank Cusack
   Google, Inc.
   2400 Bayshore Parkway
   Mountain View, CA 94043
   Email: frank@google.com

   Martin Forssen
   Appgate AB
   Stora Badhusgatan 18-20
   SE-411 21 Gothenburg
   SWEDEN
   Email: maf@appgate.com






























F. Cusack, M. Forssen   Expires November 1, 2003               [Page 11]