idnits 2.17.1 draft-ssh-ext-auth-info-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 111 has weird spacing: '... string ext...' == Line 112 has weird spacing: '... string ext...' == Line 124 has weird spacing: '... string nam...' == Line 146 has weird spacing: '... string aut...' == Line 147 has weird spacing: '... string mes...' == (1 more instance...) -- The document date (March 18, 2018) is 2230 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) No issues found here. Summary: 0 errors (**), 0 flaws (~~), 7 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Internet-Draft D. Bider 3 Intended status: Standards Track Bitvise Limited 4 Expires: September 18, 2018 March 18, 2018 6 Extended authentication information in Secure Shell (SSH) 7 draft-ssh-ext-auth-info-01.txt 9 Abstract 11 This memo defines a way for SSH server applications to send additional 12 information to clients as part of authentication failure. A mechanism 13 to relay such information can reduce the need for end user support in 14 situations where a client would successfully authenticate, but cannot 15 log in for a policy reason, such as password age or public key size. 17 Status 19 This Internet-Draft is submitted in full conformance with the 20 provisions of BCP 78 and BCP 79. 22 Internet-Drafts are working documents of the Internet Engineering Task 23 Force (IETF), its areas, and its working groups. Note that other 24 groups may also distribute working documents as Internet-Drafts. 26 Internet-Drafts are draft documents valid for a maximum of six months 27 and may be updated, replaced, or obsoleted by other documents at any 28 time. It is inappropriate to use Internet-Drafts as reference material 29 or to cite them other than as "work in progress." 31 The list of current Internet-Drafts can be accessed at 32 http://www.ietf.org/1id-abstracts.html 34 The list of Internet-Draft Shadow Directories can be accessed at 35 http://www.ietf.org/shadow.html 37 Copyright 39 Copyright (c) 2018 IETF Trust and the persons identified as the 40 document authors. All rights reserved. 42 This document is subject to BCP 78 and the IETF Trust's Legal 43 Provisions Relating to IETF Documents 44 (http://trustee.ietf.org/license-info) in effect on the date of 45 publication of this document. Please review these documents 46 carefully, as they describe your rights and restrictions with respect 47 to this document. Code Components extracted from this document must 48 include Simplified BSD License text as described in Section 4.e of 49 the Trust Legal Provisions and are provided without warranty as 50 described in the Simplified BSD License. 52 1. Overview and Rationale 54 Secure Shell (SSH) is a common protocol for secure communication on 55 the Internet. In [RFC4252], SSH defines a standard failure message, 56 SSH_MSG_USERAUTH_FAILURE, for use with "password", "publickey", and 57 other authentication methods. 59 The SSH_MSG_USERAUTH_FAILURE message was designed under the assumption 60 that the server never needs to inform the client about exact reasons 61 behind an authentication failure. In practice, there are situations 62 where revealing such information is beneficial, and is not a risk. In 63 these situations, not revealing the cause of failure deprives client 64 software and end users of information needed to appropriately respond. 66 This memo describes a mechanism which leverages [SSH-EXT-INFO] for 67 client software to signal that it is willing to receive extra 68 information as part of the SSH_MSG_USERAUTH_FAILURE message. A format 69 for the additional information is described, as well as definitions 70 for a number of common status codes. 72 1.1. Requirements Terminology 74 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 75 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 76 document are to be interpreted as described in [RFC2119]. 78 2. Indicating Support 80 Extended information cannot be sent to clients that do not indicate 81 support: widely used clients disconnect on unexpected data. Therefore, 82 SSH clients and servers that support this extension SHALL implement 83 [SSH-EXT-INFO]. When sending SSH_MSG_EXT_INFO to a server that signals 84 support for that message, a client MAY include this extension: 86 string extension-name = "ext-auth-info" 87 string extension-value = (empty) 89 The client MUST send an empty extension value. A server that does not 90 expect an extension value MUST ignore it, regardless of the value. 91 Future specifications MAY define new meanings for this value. 93 3. Extended Format of SSH_MSG_USERAUTH_FAILURE 95 When sending SSH_MSG_USERAUTH_FAILURE to a client that signals support 96 for this mechanism as per Section 2, the server MAY send the message 97 in original format, as specified in [RFC4252]: 99 byte SSH_MSG_USERAUTH_FAILURE 100 name-list authentications that can continue 101 boolean partial success 103 If the server decides additional information is safe to send, the 104 server MAY extend the format of SSH_MSG_USERAUTH_FAILURE as follows: 106 byte SSH_MSG_USERAUTH_FAILURE 107 name-list authentications that can continue 108 boolean partial success 109 uint32 N = number of ext-auth-info pairs 110 the following two fields repeated N times: 111 string ext-auth-info pair name 112 string ext-auth-info pair value (binary) 114 An ext-auth-info pair name follows the format of an algorithm or 115 method name as specified in [RFC4251], Section 6. 117 The remainder of this section describes initially defined 118 ext-auth-info pairs. 120 3.1. "keyboard-interactive" Submethods 122 The name and value for this ext-auth-info pair are encoded as follows: 124 string name = "kbdi-submethods" 125 name-list value = available submethods for "keyboard-interactive" 127 Note that a name-list is a special case of a string. The value of this 128 ext-auth-info pair is therefore a name-list, not a string containing 129 an encoded name-list. 131 A server MAY send this ext-auth-info pair regardless of whether the 132 authentication method "keyboard-interactive" is included in the field 133 "authentications that can continue" in SSH_MSG_USERAUTH_FAILURE. 135 A client MAY use information in this ext-auth-info pair to indicate a 136 submethod preference during "keyboard-interactive" authentication, or 137 to make a choice between "keyboard-interactive" and other available 138 authentication methods. 140 3.2. Authentication Status 142 The name and value for this ext-auth-info pair are encoded as follows: 144 string name = "auth-status" 145 string value = binary encoding of the following 3 or more fields: 146 string authentication status name 147 string message (in UTF-8 encoding without BOM) 148 string language tag (as per [RFC5646]) 149 151 If the server sends this ext-auth-info pair, it MUST send all three 152 fields that are part of value (and perhaps optional status-specific 153 data). It is not permissible to send e.g. only the authentication 154 status name, but no message or language tag. 156 After the language tag, clients MUST tolerate optional data. If a 157 client does not understand the optional data, it MUST ignore it. 159 An authentication status name follows the format of an algorithm or 160 method name as specified in [RFC4251], Section 6. 162 3.2.1. Authentication Status Names 164 The following authentication status names are defined: 166 "internal-error" 167 MAY be sent in response to any authentication request. The request 168 could not be processed due to an internal server error. It is 169 appropriate to contact the server administrator. 171 "transient-conflict" 172 MAY be sent in response to any authentication request. The request 173 could not be processed due to a transient server-side conflict. The 174 issue may be resolved if the request is tried again, or the 175 connection is re-attempted. 177 "account-disabled" 178 MAY be sent in response to any authentication request. Credentials 179 were valid, but the account is disabled. 181 "account-restriction" 182 MAY be sent in response to any authentication request. Credentials 183 were valid, but the account is restricted in a non-absolute manner 184 (e.g. logon hours) that prevents login. 186 "pk-size-restriction" 187 MAY be sent in response to public key authentication. The public key 188 sent by the client is known to the server, but does not meet the 189 server's key size criteria. 191 "pk-alg-restriction" 192 MAY be sent in response to public key authentication. The public key 193 sent by the client is known to the server, but the key or signature 194 uses an algorithm not supported or accepted by the server. 196 "password-expired" 197 MAY be sent in response to password authentication. The password 198 was correct, but is expired and must change, AND cannot be changed 199 in the current session. If the password can be changed, the server 200 SHOULD instead send SSH_MSG_USERAUTH_PASSWORD_CHANGEREQ. 202 "password-must-change" 203 MAY be sent in response to password authentication. The password 204 was correct, is not expired, but must change, AND cannot be changed 205 in the current session. If the password can be changed, the server 206 SHOULD instead send SSH_MSG_USERAUTH_PASSWORD_CHANGEREQ. 208 "password-cannot-change" 209 MAY be sent in response to a password change request. Password 210 change cannot be performed regardless of the new password requested. 212 "gss-no-mechanism" 213 MAY be sent in response to a GSSAPI authentication request that 214 enumerates no supported mechanisms. 216 "gss-identity" 217 MAY be sent in response to a GSSAPI authentication request when 218 the server cannot verify that the GSSAPI identity is the same as 219 that named in the SSH authentication request. 221 3.2.2. Authentication conditions WITHOUT status names 223 Authentication status names are intentionally NOT defined for the 224 following conditions: 226 - Password change request: Password ill-formed 227 - Password change request: Password does not meet policy requirements 229 In these cases, the server SHOULD instead send (potentially another) 230 SSH_MSG_USERAUTH_PASSWORD_CHANGEREQ with an appropriate message. 232 4. IANA Considerations 234 4.1. Additions to existing tables 236 IANA is requested to insert the following entries into the table 237 Extension Names (added in [SSH-EXT-INFO]) under Secure Shell (SSH) 238 Protocol Parameters [RFC4250]: 240 Extension Name Reference Note 241 ext-auth-info [this document] Section 2 243 4.2. New table: Extended Authentication Information Pair Names 245 Under Secure Shell (SSH) Protocol Parameters, IANA is requested to 246 create a new table, Extended Authentication Information Pair Names, 247 with initial content: 249 Pair Name Reference Note 250 kbdi-submethods [this document] Section 3.1 251 auth-status [this document] Section 3.2 253 4.3. New table: Authentication Status Names 255 Under Secure Shell (SSH) Protocol Parameters, IANA is requested to 256 create a new table, Authentication Status Names, with initial content: 258 Extension Name Reference Note 259 internal-error [this document] Section 3.2.1 260 transient-error [this document] Section 3.2.1 261 account-disabled [this document] Section 3.2.1 262 account-restriction [this document] Section 3.2.1 263 pk-size-restriction [this document] Section 3.2.1 264 pk-alg-restriction [this document] Section 3.2.1 265 password-expired [this document] Section 3.2.1 266 password-must-change [this document] Section 3.2.1 267 password-cannot-change [this document] Section 3.2.1 268 gss-no-mechanism [this document] Section 3.2.1 269 gss-identity [this document] Section 3.2.1 271 5. Security Considerations 273 Servers MUST NOT send extended authentication information if this 274 would reveal sensitive information to an untrusted client. 276 For example, the status "account-disabled" is meant to be sent to a 277 user who would successfully authenticate, and the only reason they 278 cannot log in is because their account is disabled. Extended 279 information with this status SHOULD NOT be sent to a user who is 280 trying to log into a disabled account with an incorrect password. 282 6. References 284 6.1. Normative References 286 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 287 Requirement Levels", BCP 14, RFC 2119, March 1997. 289 [RFC4251] Ylonen, T. and Lonvick, C., Ed., "The Secure Shell (SSH) 290 Protocol Architecture", RFC 4251, January 2006. 292 [RFC4252] Ylonen, T. and Lonvick, C., Ed., "The Secure Shell (SSH) 293 Authentication Protocol", RFC 4252, January 2006. 295 [RFC5646] Phillips, A., Ed. and Davis, M., Ed., "Tags for 296 Identifying Languages", RFC 5646, September 2009. 298 [SSH-EXT-INFO] 299 Bider, D., "Extension Negotiation in Secure Shell (SSH)", 300 draft-ietf-curdle-ssh-ext-info-15.txt, September 2017, 301 . 304 6.2. Informative References 306 [RFC4250] Lehtinen, S. and Lonvick, C., Ed., "The Secure Shell (SSH) 307 Protocol Assigned Numbers", RFC 4250, January 2006. 309 Author's Address 311 Denis Bider 312 Bitvise Limited 313 4105 Lombardy Ct 314 Colleyville, TX 76034 315 United States of America 317 Phone: +1 817 313 8515 318 EMail: ietf-ssh3@denisbider.com 319 URI: https://www.bitvise.com/