RFC 4252
The Secure Shell (SSH) Authentication Protocol
RFC 4252: The Secure Shell (SSH) Authentication Protocol πβ¨
okay bestie, let's get into RFC 4252 π It's by T. Ylonen (SSH Communications Security Corp) and C. Lonvick, Ed. (Cisco Systems, Inc.). It's a Standards Track doc from January 2006. The title block doesn't list anything it obsoletes or updates, so it's giving fresh start πΈ
Status of This Memo
this doc specifies an Internet standards track protocol for the Internet community, and it's asking for discussion and suggestions π¬ If you want the standardization state and status of this protocol, check the current edition of "Internet Official Protocol Standards" (STD 1). Distribution of this memo is unlimited π¦
Copyright Notice
Copyright (C) The Internet Society (2006).
Abstract
the Secure Shell Protocol (SSH) is a protocol for secure remote login and other secure network services over an insecure network π This document covers the SSH authentication protocol framework plus public key, password, and host-based client authentication methods. Additional authentication methods live in separate documents. The SSH authentication protocol runs on top of the SSH transport layer protocol and gives the SSH connection protocol a single authenticated tunnel. main character energy π
Table of Contents
1. Introduction ....................................................2
2. Contributors ....................................................3
3. Conventions Used in This Document ...............................3
4. The Authentication Protocol Framework ...........................4
5. Authentication Requests .........................................4
5.1. Responses to Authentication Requests .......................5
5.2. The "none" Authentication Request ..........................7
5.3. Completion of User Authentication ..........................7
5.4. Banner Message .............................................7
6. Authentication Protocol Message Numbers .........................8
7. Public Key Authentication Method: "publickey" ...................8
8. Password Authentication Method: "password" .....................10
9. Host-Based Authentication: "hostbased" .........................12
10. IANA Considerations ...........................................14
11. Security Considerations .......................................14
12. References ....................................................15
12.1. Normative References .....................................15
12.2. Informative References ...................................15
Authors' Addresses ................................................16
Trademark Notice ..................................................16
1. Introduction β¨
the SSH authentication protocol is a general-purpose user authentication protocol π§ It's meant to run over the SSH transport layer protocol [SSH-TRANS]. This protocol assumes the underlying protocols already provide integrity and confidentiality protection, so it's not doing that part itself π
read the SSH architecture document [SSH-ARCH] before this one. This doc uses terminology and notation from the architecture doc without explaining it again, so you'll want to already be up to speed π
the 'service name' for this protocol is ssh-userauth. π
when this protocol starts, it gets the session identifier from the lower-level protocol. That's the exchange hash H from the first key exchange. The session identifier uniquely identifies this session and is suitable for signing to prove ownership of a private key π This protocol also needs to know whether the lower-level protocol provides confidentiality protection.
2. Contributors π«Ά
the major original contributors to this set of documents were Tatu Ylonen, Tero Kivinen, Timo J. Rinne, and Sami Lehtinen (all of SSH Communications Security Corp), plus Markku-Juhani O. Saarinen (University of Jyvaskyla). Darren Moffat was the original editor and also made very substantial contributions π
so many people helped shape this document over the years π The people who should be acknowledged include Mats Andersson, Ben Harris, Bill Sommerfeld, Brent McClure, Niels Moller, Damien Miller, Derek Fawcus, Frank Cusack, Heikki Nousiainen, Jakob Schlyter, Jeff Van Dyke, Jeffrey Altman, Jeffrey Hutzelman, Jon Bright, Joseph Galbraith, Ken Hornstein, Markus Friedl, Martin Forssen, Nicolas Williams, Niels Provos, Perry Metzger, Peter Gutmann, Simon Josefsson, Simon Tatham, Wei Dai, Denis Bider, der Mouse, and Tadayoshi Kohno. Being listed doesn't mean they endorse this document. It just means they contributed to it π
3. Conventions Used in This Document π
all documents related to the SSH protocols shall use the keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" to describe requirements. Those keywords get interpreted the way [RFC2119] describes β¨
the keywords "PRIVATE USE", "HIERARCHICAL ALLOCATION", "FIRST COME FIRST SERVED", "EXPERT REVIEW", "SPECIFICATION REQUIRED", "IESG APPROVAL", "IETF CONSENSUS", and "STANDARDS ACTION" show up when they're describing namespace allocation. They get interpreted the way [RFC2434] says ποΈ
protocol fields and their possible values are defined in this set of documents. The fields get defined in the message definitions. For example, SSH_MSG_CHANNEL_DATA is defined like this:
byte SSH_MSG_CHANNEL_DATA
uint32 recipient channel
string data
when the docs reference fields, they're in single quotes. When they reference values that fill those fields, they're in double quotes. Using the example above, possible values for 'data' are "foo" and "bar" π
4. The Authentication Protocol Framework π
the server runs the authentication by telling the client which methods can be used to keep the exchange going at any given time π The client gets to try the listed methods in whatever order it wants. The server has complete control over the process if it wants that, but when several methods are offered, the client still gets enough flexibility to use the ones it supports or the ones that are most convenient for the user π¦
authentication methods get identified by their name, as defined in [SSH-ARCH]. The "none" method is reserved, so it MUST NOT be listed as supported. However, the client MAY still send it. The server MUST always reject this request, unless the client is supposed to get access with no authentication at all. In that case, the server MUST accept this request. The whole point of sending it is to get the list of supported methods back from the server π§
the server SHOULD have a timeout for authentication and disconnect if the authentication hasn't been accepted in time. The RECOMMENDED timeout period is 10 minutes β° The implementation SHOULD also limit how many failed authentication attempts a client can make in one session. The RECOMMENDED limit is 20 attempts. If that threshold gets exceeded, the server SHOULD disconnect.
more thoughts about authentication timeouts and retries are in [ssh-1.2.30] π
5. Authentication Requests π₯
every authentication request MUST use the following message format. Only the first few fields are defined. The remaining fields depend on the authentication method π
byte SSH_MSG_USERAUTH_REQUEST
string user name in ISO-10646 UTF-8 encoding [RFC3629]
string service name in US-ASCII
string method name in US-ASCII
.... method specific fields
the 'user name' and 'service name' get repeated in every new authentication attempt, and they MAY change π The server implementation MUST carefully check them in every message, and MUST flush any accumulated authentication states if they change. If it can't flush an authentication state, it MUST disconnect if the 'user name' or 'service name' changes. no cap, this part is serious π¨
the 'service name' says which service starts after authentication. There may be several different authenticated services. If the requested service isn't available, the server MAY disconnect right away or at any later time. Sending a proper disconnect message is RECOMMENDED πΈ Either way, if the service doesn't exist, authentication MUST NOT be accepted.
if the requested 'user name' doesn't exist, the server MAY disconnect. It MAY also send a bogus list of acceptable authentication 'method name' values, but it should never accept any of them π This keeps the server from leaking info about which accounts exist. Either way, if the 'user name' doesn't exist, the authentication request MUST NOT be accepted.
clients usually have little reason to send requests the server doesn't list as acceptable. Sending one isn't an error though, and the server SHOULD simply reject requests it doesn't recognize.
an authentication request MAY lead to a further exchange of messages. All of those messages depend on the authentication 'method name' being used. The client MAY at any time continue with a new SSH_MSG_USERAUTH_REQUEST message. In that case, the server MUST abandon the previous authentication attempt and continue with the new one π¦
the following 'method name' values are defined:
"publickey" REQUIRED
"password" OPTIONAL
"hostbased" OPTIONAL
"none" NOT RECOMMENDED
additional 'method name' values may be defined as specified in [SSH-ARCH] and [SSH-NUMBERS] π§ββοΈ
5.1. Responses to Authentication Requests β¨
okay so if the server says no to an auth request, it MUST reply with this π
byte SSH_MSG_USERAUTH_FAILURE
name-list authentications that can continue
boolean partial success
The authentications that can continue field is a comma-separated name-list of method name values that could still keep the auth conversation going π¦
Servers are RECOMMENDED to only list the method name values that are actually useful π«Ά Listing one that can't authenticate the user isn't illegal, but it's not the move either π
Already successfully completed authentications SHOULD NOT be included in the name-list, unless they should be performed again for some reason π
The partial success value MUST be TRUE if the authentication request it's replying to was successful. It MUST be FALSE if the request was not successfully processed. very clear, very iconic β¨
When the server accepts authentication, it MUST respond with this:
byte SSH_MSG_USERAUTH_SUCCESS
Note that this is not sent after each step in a multi-method authentication sequence. It only shows up once the whole thing is complete π
The client MAY send several authentication requests without waiting for responses to the previous ones πΈ The server MUST process each request completely and acknowledge any failed request with a SSH_MSG_USERAUTH_FAILURE message before it moves on to the next request. no skipping ahead, bestie π
A request that needs more messages exchanged will be aborted by a subsequent request. A client MUST NOT send a subsequent request if it hasn't received a response from the server for a previous request. A SSH_MSG_USERAUTH_FAILURE message MUST NOT be sent for an aborted method π
SSH_MSG_USERAUTH_SUCCESS MUST be sent only once. After it has been sent, any further authentication requests that come in SHOULD be silently ignored π₯
Any non-authentication messages the client sends after the request that resulted in SSH_MSG_USERAUTH_SUCCESS being sent MUST be passed to the service running on top of this protocol. You can tell these messages apart by their message numbers (see Section 6) π§
5.2. The "none" Authentication Request π
A client can ask for a list of method name values that may continue by using the "none" method name π
If no authentication is needed for the user, the server MUST return SSH_MSG_USERAUTH_SUCCESS. Otherwise, the server MUST return SSH_MSG_USERAUTH_FAILURE and MAY include a list of methods that may continue in its authentications that can continue value π
This method name MUST NOT be listed as supported by the server π
5.3. Completion of User Authentication π¦
Authentication is complete once the server has responded with SSH_MSG_USERAUTH_SUCCESS. All authentication-related messages received after that SHOULD be silently ignored β¨
After sending SSH_MSG_USERAUTH_SUCCESS, the server starts the requested service π
5.4. Banner Message π
In some jurisdictions, sending a warning message before authentication may be relevant for getting legal protection. Lots of UNIX machines, for example, normally show text from /etc/issue, use TCP wrappers, or similar software to display a banner before the login prompt π
The SSH server may send an SSH_MSG_USERAUTH_BANNER message at any time after this authentication protocol starts and before authentication is successful. This message has text to show the client user before authentication is attempted. It's laid out like this:
byte SSH_MSG_USERAUTH_BANNER
string message in ISO-10646 UTF-8 encoding [RFC3629]
string language tag [RFC3066]
By default, the client SHOULD display the message on the screen π But since the message is probably going to be sent for every login attempt, and some client software needs a separate window for this warning, the client software may let the user explicitly turn off banner display π The message may have multiple lines, with line breaks marked by CRLF pairs.
If the message string is displayed, control character filtering, discussed in [SSH-ARCH], SHOULD be used to avoid attacks that send terminal control characters π this part is serious, no cap
6. Authentication Protocol Message Numbers π§
All message numbers used by this authentication protocol are in the range from 50 to 79. That range is part of the space reserved for protocols that run on top of the SSH transport layer protocol π
Message numbers 80 and higher are reserved for protocols that run after this authentication protocol. So if you get one of them before authentication is complete, that's an error, and the server MUST respond by disconnecting, ideally with a proper disconnect message so it's easier to troubleshoot π«Ά
After successful authentication, those messages get passed up to the higher-level service β¨
These are the general authentication message codes:
SSH_MSG_USERAUTH_REQUEST 50
SSH_MSG_USERAUTH_FAILURE 51
SSH_MSG_USERAUTH_SUCCESS 52
SSH_MSG_USERAUTH_BANNER 53
On top of those, the range 60 to 79 is reserved for method-specific messages. These are only sent by the server, since the client only sends SSH_MSG_USERAUTH_REQUEST messages. Different authentication methods reuse the same message numbers πΈ
7. Public Key Authentication Method: "publickey" π
The only REQUIRED authentication method name is "publickey" authentication. All implementations MUST support this method π
Not every user needs to have public keys, though, and most local policies probably won't require public key authentication for all users anytime soon π¦
With this method, owning a private key counts as authentication. It works by sending a signature created with the user's private key. The server MUST check that the key is a valid authenticator for the user, and MUST check that the signature is valid. If both hold, the authentication request MUST be accepted. Otherwise, it MUST be rejected. Note that the server MAY require additional authentications after a successful one π
Private keys are often stored encrypted at the client host, so the user has to supply a passphrase before the signature can be generated. Even when they aren't encrypted, the signing operation involves some expensive computation. To avoid unnecessary processing and user interaction, this message exists for checking whether "publickey" authentication would be acceptable π
byte SSH_MSG_USERAUTH_REQUEST
string user name in ISO-10646 UTF-8 encoding [RFC3629]
string service name in US-ASCII
string "publickey"
boolean FALSE
string public key algorithm name
string public key blob
Public key algorithms are defined in the transport layer specification [SSH-TRANS]. The public key blob may contain certificates π
Any public key algorithm may be offered for use in authentication. In particular, the list isn't limited to what was negotiated during key exchange. If the server doesn't support some algorithm, it MUST simply reject the request π
The server MUST respond to this message with either SSH_MSG_USERAUTH_FAILURE or the following:
byte SSH_MSG_USERAUTH_PK_OK
string public key algorithm name from the request
string public key blob from the request
To actually authenticate, the client MAY then send a signature generated with the private key. The client MAY also send the signature directly without first checking whether the key is acceptable π«Ά The signature goes out in this packet:
byte SSH_MSG_USERAUTH_REQUEST
string user name
string service name
string "publickey"
boolean TRUE
string public key algorithm name
string public key to be used for authentication
string signature
The signature value is a signature, made with the corresponding private key, over the following data, in this order:
string session identifier
byte SSH_MSG_USERAUTH_REQUEST
string user name
string service name
string "publickey"
boolean TRUE
string public key algorithm name
string public key to be used for authentication
When the server gets this message, it MUST check whether the supplied key is acceptable for authentication. If it is, the server MUST check whether the signature is correct π₯
If both checks succeed, this method is successful. Note that the server may require additional authentications. The server MUST respond with SSH_MSG_USERAUTH_SUCCESS (if no more authentications are needed) or SSH_MSG_USERAUTH_FAILURE (if the request failed or more authentications are needed) β¨
The following method-specific message numbers are used by the "publickey" authentication method π
SSH_MSG_USERAUTH_PK_OK 60
8. Password Authentication Method: "password" π
Okay bestie, password auth is up next π It uses these packets, and heads up: a server MAY ask a user to change their password π Also, all implementations SHOULD support password authentication β¨
byte SSH_MSG_USERAUTH_REQUEST
string user name
string service name
string "password"
boolean FALSE
string plaintext password in ISO-10646 UTF-8 encoding [RFC3629]
The plaintext password is encoded in ISO-10646 UTF-8. How the server reads it and checks it against the password database is up to the server π«Ά BUT if the client types the password in some other encoding (like ISO 8859-1, aka ISO Latin1), it MUST convert it to ISO-10646 UTF-8 before sending it, and the server MUST convert it to whatever encoding that system uses for passwords. Main character energy, zero drama π
From an internationalization standpoint, the goal is that a user's password works no matter what OS or client software they're using π Getting there takes normalization. Systems that support non-ASCII passwords SHOULD always normalize passwords and user names whenever they're added to the database, or compared (with or without hashing) to existing entries in the database. SSH implementations that both store and compare passwords SHOULD use [RFC4013] for normalization. Very organized, very iconic π
Here's a plot twist π even though the cleartext password is sent in the packet, the entire packet is encrypted by the transport layer π Both the server and the client should check whether the transport layer actually provides confidentiality (aka whether encryption is being used). If there's no confidentiality ("none" cipher), password authentication SHOULD be disabled. If there's no confidentiality or no MAC, password change SHOULD be disabled. No encryption, no passwords, periodt π«
Normally the server answers this message with success or failure. However, if the password has expired, the server SHOULD tell the client by responding with SSH_MSG_USERAUTH_PASSWD_CHANGEREQ. Either way, the server MUST NOT allow an expired password to be used for authentication. Expired is expired, no exceptions π
byte SSH_MSG_USERAUTH_PASSWD_CHANGEREQ
string prompt in ISO-10646 UTF-8 encoding [RFC3629]
string language tag [RFC3066]
In this case, the client MAY continue with a different authentication method, or ask the user for a new password and retry password authentication using the following message. The client MAY also send this message instead of the normal password authentication request, even if the server didn't ask for it π¦
byte SSH_MSG_USERAUTH_REQUEST
string user name
string service name
string "password"
boolean TRUE
string plaintext old password in ISO-10646 UTF-8 encoding
[RFC3629]
string plaintext new password in ISO-10646 UTF-8 encoding
[RFC3629]
The server must reply to each request message with SSH_MSG_USERAUTH_SUCCESS, SSH_MSG_USERAUTH_FAILURE, or another SSH_MSG_USERAUTH_PASSWD_CHANGEREQ. Here's what each one means π
SSH_MSG_USERAUTH_SUCCESS- The password has been changed, and authentication has been successfully completed. πSSH_MSG_USERAUTH_FAILUREwith partial success - The password has been changed, but more authentications are needed.SSH_MSG_USERAUTH_FAILUREwithout partial success - The password has not been changed. Either password changing wasn't supported, or the old password was bad. Also, if the server has already sentSSH_MSG_USERAUTH_PASSWD_CHANGEREQ, we know it supports changing the password.SSH_MSG_USERAUTH_CHANGEREQ- The password wasn't changed because the new password wasn't acceptable (e.g., too easy to guess) π ββοΈ
The following method-specific message numbers are used by the password authentication method. Numbers, babe π’
SSH_MSG_USERAUTH_PASSWD_CHANGEREQ 60
9. Host-Based Authentication: "hostbased" π₯οΈ
Some sites want to allow authentication based on the host the user is coming from, plus the user name on that remote host. This form of authentication is not suitable for high-security sites, lowkey, but it can be super convenient in lots of environments β¨ This form of authentication is OPTIONAL. When it's used, special care SHOULD be taken to prevent a regular user from getting their hands on the private host key π
The client requests this form of authentication by sending the following message. It's giving UNIX "rhosts" and "hosts.equiv" vibes, except the identity of the client host gets checked way more rigorously π§
This method works by having the client send a signature created with the private key of the client host, and the server checks it with that host's public key. Once the client host's identity is established, authorization (but no further authentication) is performed based on the user names on the server and the client, and the client host name π«Ά
byte SSH_MSG_USERAUTH_REQUEST
string user name
string service name
string "hostbased"
string public key algorithm for host key
string public host key and certificates for client host
string client host name expressed as the FQDN in US-ASCII
string user name on the client host in ISO-10646 UTF-8 encoding
[RFC3629]
string signature
Public key algorithm names for use in 'public key algorithm for host key' are defined in the transport layer specification [SSH-TRANS]. The 'public host key and certificates for client host' may include certificates π
The value of 'signature' is a signature, made with the private host key, of the following data, in this order:
string session identifier
byte SSH_MSG_USERAUTH_REQUEST
string user name
string service name
string "hostbased"
string public key algorithm for host key
string public host key and certificates for client host
string client host name expressed as the FQDN in US-ASCII
string user name on the client host in ISO-10646 UTF-8 encoding
[RFC3629]
The server MUST verify that the host key actually belongs to the client host named in the message, that the given user on that host is allowed to log in, and that the 'signature' value is a valid signature on the appropriate value by the given host key. The server MAY ignore the client 'user name' if it only wants to authenticate the client host π€·ββοΈ
Whenever possible, it is RECOMMENDED that the server also check that the network address it got from the (untrusted) network matches the given client host name π΅οΈββοΈ This makes exploiting compromised host keys way harder. Heads up, this might need special handling for connections coming through a firewall π§±
10. IANA Considerations π
This document is part of a set. The IANA considerations for the SSH protocol, as defined in [SSH-ARCH], [SSH-TRANS], [SSH-CONNECT], and this document, are detailed in [SSH-NUMBERS] ποΈ
11. Security Considerations π‘οΈ
The purpose of this protocol is to perform client user authentication, and it is assumed that this runs over a secure transport layer protocol. That transport has already authenticated the server machine, established an encrypted communications channel, and computed a unique session identifier for this session. The transport layer provides forward secrecy for password authentication and other methods that rely on secret data. Honestly, the security foundation here is iconic π
Full security considerations for this protocol are provided in [SSH-ARCH] π
12. References π
12.1. Normative References
- [SSH-ARCH] Ylonen, T. and C. Lonvick, Ed., "The Secure Shell (SSH) Protocol Architecture", RFC 4251, January 2006.
- [SSH-CONNECT] Ylonen, T. and C. Lonvick, Ed., "The Secure Shell (SSH) Connection Protocol", RFC 4254, January 2006.
- [SSH-TRANS] Ylonen, T. and C. Lonvick, Ed., "The Secure Shell (SSH) Transport Layer Protocol", RFC 4253, January 2006.
- [SSH-NUMBERS] Lehtinen, S. and C. Lonvick, Ed., "The Secure Shell (SSH) Protocol Assigned Numbers", RFC 4250, January 2006.
- [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997.
- [RFC2434] Narten, T. and H. Alvestrand, "Guidelines for Writing an IANA Considerations Section in RFCs", BCP 26, RFC 2434, October 1998.
- [RFC3066] Alvestrand, H., "Tags for the Identification of Languages", BCP 47, RFC 3066, January 2001.
- [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 10646", STD 63, RFC 3629, November 2003.
- [RFC4013] Zeilenga, K., "SASLprep: Stringprep Profile for User Names and Passwords", RFC 4013, February 2005.
12.2. Informative References
- [ssh-1.2.30] Ylonen, T., "ssh-1.2.30/RFC", File within compressed tarball ftp://ftp.funet.fi/pub/unix/security/login/ssh/ssh-1.2.30.tar.gz, November 1995.
Authors' Addresses ποΈ
Tatu Ylonen
SSH Communications Security Corp
Valimotie 17
00380 Helsinki
Finland
EMail: ylo@ssh.com
Chris Lonvick (editor)
Cisco Systems, Inc.
12515 Research Blvd.
Austin 78759
USA
EMail: clonvick@cisco.com
Trademark Notice β’οΈ
"ssh" is a registered trademark in the United States and/or other countries.
Full Copyright Statement Β©οΈ
Copyright (C) The Internet Society (2006).
This document is subject to the rights, licenses and restrictions contained in BCP 78, and except as set forth therein, the authors retain all their rights.
This document and the information contained herein are provided on an "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Intellectual Property πΌ
The IETF takes no position regarding the validity or scope of any Intellectual Property Rights or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; nor does it represent that it has made any independent effort to identify any such rights. Information on the procedures with respect to rights in RFC documents can be found in BCP 78 and BCP 79.
Copies of IPR disclosures made to the IETF Secretariat and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this specification can be obtained from the IETF on-line IPR repository at http://www.ietf.org/ipr.
The IETF invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights that may cover technology that may be required to implement this standard. Please address the information to the IETF at ietf-ipr@ietf.org.
Acknowledgement π«Ά
Funding for the RFC Editor function is provided by the IETF Administrative Support Activity (IASA).
π¦ where this page comes from
- ietf: rfc4252 2006-01
- π girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms