idnits 2.17.1 draft-ietf-secsh-userauth-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Cannot find the required boilerplate sections (Copyright, IPR, etc.) in this document. Expected boilerplate is as follows today (2024-03-29) according to https://trustee.ietf.org/license-info : IETF Trust Legal Provisions of 28-dec-2009, Section 6.a: This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 2: Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 3: This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. 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. ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. ** The document seems to lack a 1id_guidelines paragraph about 6 months document validity -- however, there's a paragraph with a matching beginning. Boilerplate error? ** The document seems to lack a 1id_guidelines paragraph about the list of current Internet-Drafts. ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. == 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 an Authors' Addresses Section. Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 118 has weird spacing: '... string use...' == Line 119 has weird spacing: '... string ser...' == Line 120 has weird spacing: '... string met...' == Line 164 has weird spacing: '... string aut...' == Line 203 has weird spacing: '... string use...' == (35 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 (March 22, 1997) is 9869 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) No issues found here. Summary: 9 errors (**), 0 flaws (~~), 7 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 Network Working Group Tatu Ylonen 2 INTERNET-DRAFT SSH Communications Security 3 draft-ietf-secsh-userauth-00.txt March 22, 1997 4 Expires: September 1, 1997 6 SSH Authentication Protocol 8 Status of This memo 10 This document is an Internet-Draft. Internet-Drafts are working 11 documents of the Internet Engineering Task Force (IETF), its areas, 12 and its working groups. Note that other groups may also distribute 13 working documents as Internet-Drafts. 15 Internet-Drafts are draft documents valid for a maximum of six 16 months and may be updated, replaced, or obsoleted by other documents 17 at any time. It is inappropriate to use Internet-Drafts as reference 18 material or to cite them other than as ``work in progress.'' 20 To learn the current status of any Internet-Draft, please check 21 the ``1id-abstracts.txt'' listing contained in the Internet-Drafts 22 Shadow Directories on ftp.is.co.za (Africa), nic.nordu.net (Europe), 23 munnari.oz.au (Pacific Rim), ds.internic.net (US East Coast), 24 or ftp.isi.edu (US West Coast). 26 Abstract 28 This documents describes the SSH authentication protocol. It is used to 29 prove that the client is authorized access the requested service with 30 the supplied user name. This authorization can be demonstrated through 31 possession of a password, through possession of a key, by authenticating 32 the client host and user, by some other method, or a combination of 33 these. 35 Table of Contents 37 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . 2 38 2. User Authentication . . . . . . . . . . . . . . . . . . . . . . 2 39 2.1. Authentication Requests . . . . . . . . . . . . . . . . . . 3 40 2.2. Responses to Authentication Requests . . . . . . . . . . . . 4 41 2.3. No Authentication . . . . . . . . . . . . . . . . . . . . . 4 42 2.4. Password-Style Authentications . . . . . . . . . . . . . . . 5 43 2.4.1. Password Authentication . . . . . . . . . . . . . . . . 5 44 2.4.2. SecurID Authentication . . . . . . . . . . . . . . . . . 5 45 2.5. One-Time Passwords and Similar Methods . . . . . . . . . . . 5 46 2.5.1. S/KEY . . . . . . . . . . . . . . . . . . . . . . . . . 6 47 2.5.2. NRL OPIE . . . . . . . . . . . . . . . . . . . . . . . . 6 48 2.6. Other Authentication Methods . . . . . . . . . . . . . . . . 6 49 2.6.1. Public Key Authentication . . . . . . . . . . . . . . . 6 50 2.6.2. Host-Based Authentication . . . . . . . . . . . . . . . 7 51 2.6.3. Kerberos Authentication . . . . . . . . . . . . . . . . 8 52 3. When Authentication Is Complete . . . . . . . . . . . . . . . . 9 53 4. Banner Message . . . . . . . . . . . . . . . . . . . . . . . . . 9 54 5. Message Numbers . . . . . . . . . . . . . . . . . . . . . . . . 10 55 6. Address of Author . . . . . . . . . . . . . . . . . . . . . . . 10 57 1. Introduction 59 This protocol is designed to run over the SSH transport layer protocol 60 using the same packet-based protocol as the transport layer. The 61 service name is "ssh-userauth". 63 Authentication works by the client first declaring the service name and 64 the user name to be used to access the service. The server then 65 responds with the set of authentication methods that are acceptable; the 66 client then sends an authentication request, and this dialog continues 67 until access has been granted or denied. 69 When this protocol starts, it receives the session identifier from the 70 transport layer protocol. The session identifier uniquely identifies 71 this session and is suitable for signing to prove ownership of a private 72 key. 74 2. User Authentication 76 Authentication is mostly client-driven. The client sends an 77 authentication request, and the server responds with success or failure. 78 With a failure response the server informs the client which methods may 79 be used to continue the dialog, thus guiding the client through a 80 potentially complex sequence of authentications. 82 Authentication methods are identified by names (strings). Some methods 83 are defined in the protocol; additional methods may be defined using the 84 syntax "name@domainname" as the method name (for example, 85 "footoken@footoken.com"). This ensures that private extensions can be 86 implemented without breaking compatibility and without requiring a 87 central registry of method names. Method names are case-sensitive. 88 Names must consist of non-control characters. Commas are not allowed in 89 names; at signs can only be used for the purpose described above. 91 The following methods are predefined: 93 none Checks if no authentication ok 94 password Knowledge of password 95 securid SecurID authentication 96 skey S/KEY one-time passwords 97 opie NRL OPIE one-time passwords 98 publickeytest Tests whether a key is acceptable 99 publickey Possession of private key 100 hostbased Identity of client host and user 101 kerberos4 Kerberos v4 authentication 102 kerberos5 Kerberos v5 authentication 103 kerberos-afs AFS Kerberos authentication 105 The server should have a timeout for authentication, and disconnect if 106 the authentication has not been accepted within the timeout period. The 107 recommended timeout period is 10 minutes. Additionally, the 108 implementation may want to limit the number of authentication attempts a 109 client may perform (the recommended limit is 20 attempts). 111 2.1. Authentication Requests 113 All authentication requests use the same generic message format. Only 114 the first few fields are defined; the remaining fields depend on the 115 authentication method. 117 vlint32 SSH_MSG_USERAUTH_REQUEST 118 string user 119 string service 120 string method name 121 rest of the packet is method-specific 123 The user name and service are repeated in every new authentication 124 attempt, and may change. The server implementation must carefully check 125 them in every message, and must flush any accumulated authentication 126 state if they change. 128 If the requested service is not available, the server may disconnect 129 immediately or any time later. 131 If the requested user does not exist, the server is allowed to 132 disconnect, or may send a bogus list of acceptable authentications but 133 never accept any. This makes it possible for the server to avoid 134 disclosing information about which accounts exist. 136 There are several authentication methods that basically work by the 137 client sending some kind of identifying string (or other data) to the 138 server, and the server directly responding with success or failure. 140 Examples of this style of authentication are "password" and "securid" 141 methods. Other such methods may be defined later. 143 Another common form is one where the server sends a prompt (a 144 challenge), and the client is supposed to respond appropriately based on 145 the challenge. Most one-time password methods use this form; examples 146 include "skey" and "opie". 148 While there is usually little point in clients sending requests that the 149 server does not list as acceptable, sending such requests is not an 150 error, and the server should simply reject requests that it does not 151 recognize. 153 An authentication request may result in a further exchange of messages. 154 All such messages depend on the authentication method used, and the 155 client may at any time continue with a new SSH_MSG_USERAUTH_REQUEST 156 message, in which case the server must abandon the previous 157 authentication attempt and continue with the new one. 159 2.2. Responses to Authentication Requests 161 If the server rejects the authentication request, it responds with 163 vlint32 SSH_MSG_USERAUTH_FAILURE 164 string authentications_that_can_continue 166 authentications_that_can_continue is a comma-separated list of 167 authentication method names that may productively continue the 168 authentication dialog. Methods that require interaction with the user 169 should not be listed unless they can actually be used to authenticate 170 this user. Note that successful response to one method in the list may 171 not be enough to be accepted; the server is allowed to require multiple 172 authentications. The server should not list authentications that it has 173 already accepted. 175 When the server accepts authentication, it responds with 177 vlint32 SSH_MSG_USERAUTH_SUCCESS 179 The client may send several authentication requests without waiting for 180 responses from previous requests. The server will acknowledge any 181 failed requests with a SSH_SMSG_AUTH_FAILURE message. However, 182 SSH_SMSG_AUTH_SUCCESS is sent only once, and any further authentication 183 requests received after that are silently ignored. 185 Once SSH_MSG_USERAUTH_SUCCESS has been sent, any non-authentication 186 messages sent by the client will be passed to the service being run 187 above this authentication protocol. 188 2.3. No Authentication 190 A client may request the list of real authentication methods that may 191 continue by using the "none" authentication method. This is actually an 192 authentication request: if no authentication at all is needed for the 193 user, this returns SSH_MSG_USERAUTH_SUCCESS. Otherwise, this returns 194 failure and with it the list of authentication methods that can 195 continue. 197 2.4. Password-Style Authentications 199 All password-style authentication methods use a single message of the 200 following format. The server responds with success or failure. 202 vlint32 SSH_MSG_USERAUTH_REQUEST 203 string user 204 string service 205 string method name 206 string authenticating string 208 2.4.1. Password Authentication 210 This is conventional password authentication. The method name is 211 "password"; the authenticating string is the plaintext password. Note 212 that the password is sent as plaintext in the packet, but the entire 213 packet (including the password) is encrypted by the transport layer. It 214 is not possible for the client to hash the password, because it cannot 215 know how the server stores the password. 217 2.4.2. SecurID Authentication 219 SecurID is a timing-based hardware token authenticator. The user enters 220 a code displayed on the token as authentication. The entered token is 221 passed in the following message. 223 The method name for SecurID authentication is "securid"; the 224 authenticating string is the code displayed on the hardware token. 226 2.5. One-Time Passwords and Similar Methods 228 All one-time password authentication methods use the following message 229 exchange: 231 vlint32 SSH_MSG_USERAUTH_REQUEST 232 string user 233 string service 234 string method name 236 The server responds with either SSH_MSG_USERAUTH_FAILURE or 238 vlint32 SSH_MSG_USERAUTH_OTP_PROMPT 239 string prompt 241 The client then responds with either a new authentication request or 243 vlint32 SSH_MSG_USERAUTH_OTP_RESPONSE 244 string response 246 The server responds to this message with either success or failure. 248 2.5.1. S/KEY 250 S/KEY is an early one-time password mechanism. The method name is 251 "skey". 253 2.5.2. NRL OPIE 255 NRL OPIE is another one-time password mechanism. The method name for it 256 is "opie". 258 2.6. Other Authentication Methods 260 2.6.1. Public Key Authentication 262 The possession of a private key can serve as authentication. This 263 method works by sending a signature created by the private key. 265 Private keys are often stored encrypted at the client host, and the user 266 must supply a passphrase before the signature can be generated. To 267 avoid needing to supply passphrases when it is not necessary, the client 268 can optionally query whether a particular key is acceptable as 269 authentication. This done with the following message. The key may 270 include certificates. 272 vlint32 SSH_MSG_USERAUTH_REQUEST 273 string user 274 string service 275 string "publickeytest" 276 string public key algorithm name 277 string public key to be used for authentication 279 Public key algorithms are defined in the transport layer specification. 280 The key may include certificates. 282 The server will respond to this message with either 283 SSH_MSG_USERAUTH_FAILURE or with 285 vlint32 SSH_MSG_USERAUTH_PK_OK 287 However, no response is sent after a successful authentication. 289 To do actual authentication, the client should then send a signature 290 generated by the public key. It is permissible to send the signature 291 directly without first querying whether the key is acceptable. 293 vlint32 SSH_MSG_USERAUTH_REQUEST 294 string user 295 string service 296 string "publickey" 297 string public key algorithm name 298 string public key to be used for authentication 299 string signature 301 The public key may contain certificates. 303 Signature is a signature by the corresponding private key of the HASH 304 of the concatenation of the following, in this order: 306 o the session identifier (which binds the signature to the server host 307 key and the particular key exchange), 309 o length of the user name as a 32-bit integer, msb first, 311 o user name (without length or null characters), 313 o length of the service name as a 32-bit integer, msb first, 315 o service name (without length or null characters), 317 o length of the public key algorithm name as a 32-bit integer, msb 318 first, 320 o public key algorithm name (without length or null characters), 322 o length of the public key from the message as a 32-bit integer, msb 323 first, and 325 o the public key from the message (without length or null characters). 327 When the server receives this message, it checks whether the supplied 328 key is acceptable for authentication, and if so, checks whether the 329 signature is correct. 331 If both checks succeed, authentication may be granted (the server may 332 also require further authentication with other methods, without letting 333 the client know at this point that authentication has partially 334 succeeded). 336 2.6.2. Host-Based Authentication 338 Some sites wish to allow authentication based on the host where the user 339 is coming from and the user name on the remote host. While this form of 340 authentication is not suitable for high-security sites, it can be very 341 convenient in many environments. The client requests this form of 342 authentication by sending the following message. 344 vlint32 SSH_MSG_USERAUTH_REQUEST 345 string user 346 string service 347 string "hostbased" 348 string public key algorithm for host key 349 string public host key for client host 350 string client host name 351 string client user name 352 string signature 354 The public key may contain certificates. Public key algorithm names are 355 defined in the transport layer protocol specification. 357 Signature is a signature by the host key of HASH of the concatenation of 358 the following, in this order: 360 o the session identifier (which binds the signature to the server host 361 key and the particular key exchange), 363 o length of the user name as a 32-bit integer, msb first, 365 o user name (without length or null characters), 367 o length of the service name as a 32-bit integer, msb first, 369 o service name (without length or null characters), 371 o length of the public host key algorithm name as a 32-bit integer, msb 372 first, 374 o public host key algorithm name (without length or null characters), 376 o length of the public host key from the message as a 32-bit integer, 377 msb first, 379 o the public host key from the message (without length or null 380 characters), 382 o length of the client host name as a 32-bit integer, msb first, 384 o client host name (without length or null characters), 386 o length of the client user name as a 32-bit integer, msb first, and 388 o client user name (without length or null characters). 390 Authentication is accepted if the server can verify that the host key 391 actually belongs to the client host, the given user on that host is 392 allowed to log in, and the signature is a valid signature on the 393 appropriate value by the given host key. (The server is also allowed to 394 ignore the client user name, if it only wants to authenticate the client 395 host.) 397 It is recommended that whenever possible, the server performs additional 398 checks to verify that the network address obtained from the (untrusted) 399 network matches the given client host name. This makes exploiting 400 compromised host keys more difficult. Note that this may require 401 special handling for connections coming through a firewall. 403 2.6.3. Kerberos Authentication 404 There are several ways to authenticate the user using Kerberos (OSF DCE 405 and AFS are also incarnations of Kerberos). Different versions of 406 Kerberos (v4, v5, DCE, and AFS) have different capabilities. Separate 407 messages have been defined for each of these. In each case, the server 408 should respond with success or failure. 410 vlint32 SSH_MSG_USERAUTH_REQUEST 411 string user 412 string service 413 string "kerberos4" 414 string kerberos v4 credentials 416 vlint32 SSH_MSG_USERAUTH_REQUEST 417 string user 418 string service 419 string "kerberos5" 420 string kerberos v5 credentials 421 string kerberos v5 ticket granting ticket (may be empty) 423 vlint32 SSH_MSG_USERAUTH_REQUEST 424 string user 425 string service 426 string "kerberos-afs" 427 string AFS token 429 The Kerberos authentication requests should be sent before other 430 authentication requests. The other authentication methods may need to 431 access files from the user's home directory, which may not be accessible 432 until e.g. the AFS token has been passed. Note that even if these 433 requests fail, they may have side effects, such as making the home 434 directory accessible. 436 3. When Authentication Is Complete 438 Authentication is complete when the server has responded with 439 SSH_MSG_USERAUTH_SUCCESS. Any SSH_MSG_USERAUTH_REQUEST messages 440 received after sending this message will be silently ignored. 442 When sending SSH_MSG_USERAUTH_SUCCESS, the server also starts whatever 443 application was requested as the service. Any non-authentication 444 messages received will be passed to the requested service. 446 4. Banner Message 448 The server may send a SSH_MSG_USERAUTH_BANNER message at any time. This 449 message contains a message to be displayed to the client user before 450 attempting authentication. On most Unix machines, this message is read 451 from /etc/issue. In some jurisdictions, sending a warning message 452 before authentication may be relevant to getting legal protection. The 453 message may contain newlines. 455 vlint32 SSH_MSG_USERAUTH_BANNER 456 string message 458 The client should normally display the message on screen if convenient. 459 However, it may be sent on every login, and opening a separate window 460 for it would probably be too annoying. The client is thus free to 461 ignore it, but displaying it should be possible at least if explicitly 462 requested. 464 5. Message Numbers 466 All message numbers used by this authencation protocol are in the range 467 30..39, which is part of the range reserved for protocols running on top 468 of the SSH transport layer protocol. Message numbers above and 469 including 40 are reserved for protocols running on top of this level. 470 Receiving them before authentication is complete is an error, and the 471 server must disconnect in this case. After successful authentication, 472 these messages are passed to the higher-level service. 474 The server should ignore any method-specific messages received while 475 expecting an authentication request. These might sometimes result if 476 the client sends an authentication request that the server does not 477 understand. 479 #define SSH_MSG_USERAUTH_BANNER 31 480 #define SSH_MSG_USERAUTH_FAILURE 32 481 #define SSH_MSG_USERAUTH_SUCCESS 33 482 #define SSH_MSG_USERAUTH_REQUEST 34 484 /* Messages 35-39 are reserved for method-specific messages. 485 Different authentication methods may reuse the same message 486 numbers. */ 487 /* Key-based */ 488 #define SSH_MSG_USERAUTH_PK_OK 35 489 /* One-time passwords */ 490 #define SSH_MSG_USERAUTH_OTP_PROMPT 35 491 #define SSH_MSG_USERAUTH_OTP_RESPONSE 36 493 6. Address of Author 495 Tatu Ylonen 496 SSH Communications Security Ltd. 497 Tekniikantie 12 498 FIN-02150 ESPOO 499 Finland 501 E-mail: ylo@ssh.fi