draft-ietf-secsh-userauth-10.txt   draft-ietf-secsh-userauth-11.txt 
Network Working Group T. Ylonen Network Working Group T. Ylonen
INTERNET-DRAFT T. Kivinen Internet-Draft T. Kivinen
draft-ietf-secsh-userauth-10.txt M. Saarinen Expires: January 18, 2002 SSH Communications Security Corp
Expires: 2 September, 2001 T. Rinne M. Saarinen
University of Jyvaskyla
T. Rinne
S. Lehtinen S. Lehtinen
SSH Communications Security SSH Communications Security Corp
2 March, 2001 July 20, 2001
Secure Shell Authentication Protocol SSH Authentication Protocol
draft-ietf-secsh-userauth-11.txt
Status of This Memo Status of this Memo
This document is an Internet-Draft and is in full conformance This document is an Internet-Draft and is in full conformance with
with all provisions of Section 10 of RFC2026. all provisions of Section 10 of RFC2026.
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that Task Force (IETF), its areas, and its working groups. Note that
other groups may also distribute working documents as other groups may also distribute working documents as Internet-
Internet-Drafts. Drafts.
Internet-Drafts are draft documents valid for a maximum of six Internet-Drafts are draft documents valid for a maximum of six
months and may be updated, replaced, or obsoleted by other months and may be updated, replaced, or obsoleted by other
documents at any time. It is inappropriate to use Internet- documents at any time. It is inappropriate to use Internet-Drafts
Drafts as reference material or to cite them other than as as reference material or to cite them other than as "work in
"work in progress." progress."
The list of current Internet-Drafts can be accessed at The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt http://www.ietf.org/ietf/1id-abstracts.txt.
The list of Internet-Draft Shadow Directories can be accessed at The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html. http://www.ietf.org/shadow.html.
This Internet-Draft will expire on January 18, 2002.
Copyright Notice
Copyright (C) The Internet Society (2001). All Rights Reserved.
Abstract Abstract
The Secure Shell Remote Login Protocol is a protocol for secure remote SSH is a protocol for secure remote login and other secure network
login and other secure network services over an insecure network. This services over an insecure network. This document describes the
document describes the Secure Shell authentication protocol framework SSH authentication protocol framework and public key, password,
and public key, password, and host-based client authentication methods. and host-based client authentication methods. Additional
Additional authentication methods are described in separate documents. authentication methods are described in separate documents. The
The Secure Shell Authentication Protocol runs on top of the Secure Shell SSH authentication protocol runs on top of the SSH transport layer
Transport Layer Protocol and provides a single authenticated tunnel for protocol and provides a single authenticated tunnel for the SSH
the Secure Shell Connection Protocol. connection protocol.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . 2 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
2. The Authentication Protocol Framework . . . . . . . . . . . . . 2 2. The Authentication Protocol Framework . . . . . . . . . . . . 3
2.1. Authentication Requests . . . . . . . . . . . . . . . . . . 3 2.1 Authentication Requests . . . . . . . . . . . . . . . . . . . 4
2.2. Responses to Authentication Requests . . . . . . . . . . . . 4 2.2 Responses to Authentication Requests . . . . . . . . . . . . . 5
2.3. The "none" Authentication Request . . . . . . . . . . . . . 4 2.3 The "none" Authentication Request . . . . . . . . . . . . . . 6
2.4. Completion of User Authentication . . . . . . . . . . . . . 5 2.4 Completion of User Authentication . . . . . . . . . . . . . . 6
2.5. Banner Message . . . . . . . . . . . . . . . . . . . . . . . 5 2.5 Banner Message . . . . . . . . . . . . . . . . . . . . . . . . 6
3. Authentication Protocol Message Numbers . . . . . . . . . . . . 5 3. Authentication Protocol Message Numbers . . . . . . . . . . . 7
4. Public Key Authentication Method: publickey . . . . . . . . . . 6 4. Public Key Authentication Method: publickey . . . . . . . . . 7
5. Password Authentication Method: password . . . . . . . . . . . . 7 5. Password Authentication Method: password . . . . . . . . . . . 9
6. Host-Based Authentication: hostbased . . . . . . . . . . . . . . 9 6. Host-Based Authentication: hostbased . . . . . . . . . . . . . 11
7. Security Considerations . . . . . . . . . . . . . . . . . . . . 10 7. Security Considerations . . . . . . . . . . . . . . . . . . . 12
8. Trademark Issues . . . . . . . . . . . . . . . . . . . . . . . . 10 8. Trademark Issues . . . . . . . . . . . . . . . . . . . . . . . 12
9. References . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 9. Additional Information . . . . . . . . . . . . . . . . . . . . 13
10. Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . 11 References . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . 13
Full Copyright Statement . . . . . . . . . . . . . . . . . . . 15
1. Introduction 1. Introduction
The Secure Shell Authentication Protocol is a general-purpose user The SSH authentication protocol is a general-purpose user
authentication protocol. It is intended to be run over the Secure Shell authentication protocol. It is intended to be run over the SSH
Transport Layer Protocol [SECSH-TRANS]. This protocol assumes that the transport layer protocol [SSH-TRANS]. This protocol assumes that
underlying protocols provide integrity and confidentiality protection. the underlying protocols provide integrity and confidentiality
protection.
This document should be read only after reading the Secure Shell Remote This document should be read only after reading the SSH
Login Protocol Architecture document [SECSH-ARCH]. This document freely architecture document [SSH-ARCH]. This document freely uses
uses terminology and notation from the architecture document without terminology and notation from the architecture document without
reference or further explanation. reference or further explanation.
The service name for this protocol is "ssh-userauth". The service name for this protocol is "ssh-userauth".
When this protocol starts, it receives the session identifier from the When this protocol starts, it receives the session identifier from
lower-level protocol (this is the exchange hash H from the first key the lower-level protocol (this is the exchange hash H from the
exchange). The session identifier uniquely identifies this session and first key exchange). The session identifier uniquely identifies
is suitable for signing in order to prove ownership of a private key. this session and is suitable for signing in order to prove
This protocol also needs to know whether the lower-level protocol ownership of a private key. This protocol also needs to know
provides confidentiality protection. whether the lower-level protocol provides confidentiality
protection.
2. The Authentication Protocol Framework 2. The Authentication Protocol Framework
The server drives the authentication by telling the client which The server drives the authentication by telling the client which
authentication methods can be used to continue the exchange at any given authentication methods can be used to continue the exchange at any
time. The client has the freedom to try the methods listed by the server given time. The client has the freedom to try the methods listed
in any order. This gives the server complete control over the by the server in any order. This gives the server complete
authentication process if desired, but also gives enough flexibility for control over the authentication process if desired, but also gives
the client to use the methods it supports or that are most convenient enough flexibility for the client to use the methods it supports
for the user, when multiple methods are offered by the server. or that are most convenient for the user, when multiple methods
are offered by the server.
Authentication methods are identified by their name, as defined in Authentication methods are identified by their name, as defined in
[SECSH-ARCH]. The "none" method is reserved, and MUST NOT be listed as [SSH-ARCH]. The "none" method is reserved, and MUST NOT be listed
as supported. However, it MAY be sent by the client. The server
supported. However, it MAY be sent by the client. The server MUST MUST always reject this request, unless the client is to be
always reject this request, unless the client is to be allowed in allowed in without any authentication, in which case the server
without any authentication, in which case the server MUST accept this MUST accept this request. The main purpose of sending this
request. The main purpose of sending this request is to get the list of request is to get the list of supported methods from the server.
supported methods from the server.
The server SHOULD have a timeout for authentication, and disconnect if The server SHOULD have a timeout for authentication, and
the authentication has not been accepted within the timeout period. The disconnect if the authentication has not been accepted within the
RECOMMENDED timeout period is 10 minutes. Additionally, the timeout period. The RECOMMENDED timeout period is 10 minutes.
implementation SHOULD limit the number of failed authentication attempts Additionally, the implementation SHOULD limit the number of failed
a client may perform in a single session (the RECOMMENDED limit is 20 authentication attempts a client may perform in a single session
attempts). If the threshold is exceeded, the server SHOULD disconnect. (the RECOMMENDED limit is 20 attempts). If the threshold is
exceeded, the server SHOULD disconnect.
2.1. Authentication Requests 2.1 Authentication Requests
All authentication requests MUST use the following message format. Only All authentication requests MUST use the following message format.
the first few fields are defined; the remaining fields depend on the Only the first few fields are defined; the remaining fields depend
authentication method. on the authentication method.
byte SSH_MSG_USERAUTH_REQUEST byte SSH_MSG_USERAUTH_REQUEST
string user name (in ISO-10646 UTF-8 encoding [RFC-2279]) string user name (in ISO-10646 UTF-8 encoding [RFC2279])
string service name (in US-ASCII) string service name (in US-ASCII)
string method name (US-ASCII) string method name (US-ASCII)
The rest of the packet is method-specific. The rest of the packet is method-specific.
The user name and service are repeated in every new authentication The user name and service are repeated in every new authentication
attempt, and MAY change. The server implementation MUST carefully check attempt, and MAY change. The server implementation MUST carefully
them in every message, and MUST flush any accumulated authentication check them in every message, and MUST flush any accumulated
states if they change. If it is unable to flush some authentication authentication states if they change. If it is unable to flush
state, it MUST disconnect if the user or service name changes. some authentication state, it MUST disconnect if the user or
service name changes.
The service name specifies the service to start after authentication.
There may be several different authenticated services provided. If the
requested service is not available, the server MAY disconnect
immediately or at any later time. Sending a proper disconnect message
is RECOMMENDED. In any case, if the service does not exist,
authentication MUST NOT be accepted.
If the requested user does not exist, the server MAY disconnect, or MAY The service name specifies the service to start after
send a bogus list of acceptable authentication methods, but never accept authentication. There may be several different authenticated
any. This makes it possible for the server to avoid disclosing services provided. If the requested service is not available, the
information on which accounts exist. In any case, if the user does not server MAY disconnect immediately or at any later time. Sending a
exist, the authentication request MUST NOT be accepted. proper disconnect message is RECOMMENDED. In any case, if the
service does not exist, authentication MUST NOT be accepted.
While there is usually little point for clients to send requests that If the requested user does not exist, the server MAY disconnect,
the server does not list as acceptable, sending such requests is not an or MAY send a bogus list of acceptable authentication methods, but
error, and the server SHOULD simply reject requests that it does not never accept any. This makes it possible for the server to avoid
recognize. disclosing information on which accounts exist. In any case, if
the user does not exist, the authentication request MUST NOT be
accepted.
An authentication request MAY result in a further exchange of messages. While there is usually little point for clients to send requests
All such messages depend on the authentication method used, and the that the server does not list as acceptable, sending such requests
client MAY at any time continue with a new SSH_MSG_USERAUTH_REQUEST is not an error, and the server SHOULD simply reject requests that
message, in which case the server MUST abandon the previous it does not recognize.
authentication attempt and continue with the new one. An authentication request MAY result in a further exchange of
messages. All such messages depend on the authentication method
used, and the client MAY at any time continue with a new
SSH_MSG_USERAUTH_REQUEST message, in which case the server MUST
abandon the previous authentication attempt and continue with the
new one.
2.2. Responses to Authentication Requests 2.2 Responses to Authentication Requests
If the server rejects the authentication request, it MUST respond with If the server rejects the authentication request, it MUST respond
the following: with the following:
byte SSH_MSG_USERAUTH_FAILURE byte SSH_MSG_USERAUTH_FAILURE
string authentications that can continue string authentications that can continue
boolean partial success boolean partial success
"Authentications that can continue" is a comma-separated list of "Authentications that can continue" is a comma-separated list of
authentication method names that may productively continue the authentication method names that may productively continue the
authentication dialog. authentication dialog.
It is RECOMMENDED that servers only include those methods in the list It is RECOMMENDED that servers only include those methods in the
that are actually useful. However, it is not illegal to include methods list that are actually useful. However, it is not illegal to
that cannot be used to authenticate the user. include methods that cannot be used to authenticate the user.
Already successfully completed authentications SHOULD NOT be included in Already successfully completed authentications SHOULD NOT be
the list, unless they really should be performed again for some reason. included in the list, unless they really should be performed again
for some reason.
"Partial success" MUST be TRUE if the authentication request to which "Partial success" MUST be TRUE if the authentication request to
this is a response was successful. It MUST be FALSE if the request was which this is a response was successful. It MUST be FALSE if the
not successfully processed. request was not successfully processed.
When the server accepts authentication, it MUST respond with the When the server accepts authentication, it MUST respond with the
following: following:
byte SSH_MSG_USERAUTH_SUCCESS byte SSH_MSG_USERAUTH_SUCCESS
Note that this is not sent after each step in a multi-method Note that this is not sent after each step in a multi-method
authentication sequence, but only when the authentication is complete. authentication sequence, but only when the authentication is
complete.
The client MAY send several authentication requests without waiting for
responses from previous requests. The server MUST acknowledge any
failed requests with a SSH_MSG_USERAUTH_FAILURE message. However,
SSH_MSG_USERAUTH_SUCCESS MUST be sent only once, and once
SSH_MSG_USERAUTH_SUCCESS has been sent, any further authentication
requests received after that SHOULD be silently ignored.
Any non-authentication messages sent by the client after the request The client MAY send several authentication requests without
that resulted in SSH_MSG_USERAUTH_SUCCESS being sent MUST be passed to waiting for responses from previous requests. The server MUST
the service being run on top of this protocol. Such messages can be acknowledge any failed requests with a SSH_MSG_USERAUTH_FAILURE
identified by their message numbers (see Section ``Message Numbers''). message. However, SSH_MSG_USERAUTH_SUCCESS MUST be sent only
once, and once SSH_MSG_USERAUTH_SUCCESS has been sent, any further
authentication requests received after that SHOULD be silently
ignored.
2.3. The "none" Authentication Request Any non-authentication messages sent by the client after the
request that resulted in SSH_MSG_USERAUTH_SUCCESS being sent MUST
be passed to the service being run on top of this protocol. Such
messages can be identified by their message numbers (see Section
Message Numbers (Section 3)).
A client may request a list of authentication methods that may continue 2.3 The "none" Authentication Request
by using the "none" authentication method.
If no authentication at all is needed for the user, the server MUST A client may request a list of authentication methods that may
return SSH_MSG_USERAUTH_SUCCESS. Otherwise, the server MUST return continue by using the "none" authentication method.
SSH_MSG_USERAUTH_FAILURE and MAY return with it a list of authentication If no authentication at all is needed for the user, the server
methods that can continue. MUST return SSH_MSG_USERAUTH_SUCCESS. Otherwise, the server MUST
return SSH_MSG_USERAUTH_FAILURE and MAY return with it a list of
authentication methods that can continue.
This method MUST NOT be listed as supported by the server. This method MUST NOT be listed as supported by the server.
2.4. Completion of User Authentication 2.4 Completion of User Authentication
Authentication is complete when the server has responded with Authentication is complete when the server has responded with
SSH_MSG_USERAUTH_SUCCESS; all authentication related messages received SSH_MSG_USERAUTH_SUCCESS; all authentication related messages
after sending this message SHOULD be silently ignored. received after sending this message SHOULD be silently ignored.
After sending SSH_MSG_USERAUTH_SUCCESS, the server starts the requested After sending SSH_MSG_USERAUTH_SUCCESS, the server starts the
service. requested service.
2.5. Banner Message 2.5 Banner Message
In some jurisdictions, sending a warning message before authentication In some jurisdictions, sending a warning message before
may be relevant for getting legal protection. Many UNIX machines, for authentication may be relevant for getting legal protection. Many
example, normally display text from `/etc/issue', or use "tcp wrappers" UNIX machines, for example, normally display text from
or similar software to display a banner before issuing a login prompt. `/etc/issue', or use "tcp wrappers" or similar software to display
a banner before issuing a login prompt.
The server may send a SSH_MSG_USERAUTH_BANNER message at any time before The SSH server may send a SSH_MSG_USERAUTH_BANNER message at any
authentication is successful. This message contains text to be time before authentication is successful. This message contains
displayed to the client user before authentication is attempted. The text to be displayed to the client user before authentication is
format is as follows: attempted. The format is as follows:
byte SSH_MSG_USERAUTH_BANNER byte SSH_MSG_USERAUTH_BANNER
string message (ISO-10646 UTF-8) string message (ISO-10646 UTF-8)
string language tag (as defined in [RFC-1766]) string language tag (as defined in [RFC1766])
The client SHOULD by default display the message on the screen. The client SHOULD by default display the message on the screen.
However, since the message is likely to be sent for every login attempt, However, since the message is likely to be sent for every login
and since some client software will need to open a separate window for attempt, and since some client software will need to open a
this warning, the client software may allow the user to explicitly separate window for this warning, the client software may allow
disable the display of banners from the server. The message may consist the user to explicitly disable the display of banners from the
of multiple lines. server. The message may consist of multiple lines.
If the message string is displayed, control character filtering If the message string is displayed, control character filtering
discussed in [SECSH-ARCH] SHOULD be used to avoid attacks by sending discussed in [SSH-ARCH] SHOULD be used to avoid attacks by sending
terminal control characters. terminal control characters.
3. Authentication Protocol Message Numbers 3. Authentication Protocol Message Numbers
All message numbers used by this authentication protocol are in the All message numbers used by this authentication protocol are in
range from 50 to 79, which is part of the range reserved for protocols the range from 50 to 79, which is part of the range reserved for
running on top of the Secure Shell Transport Layer Protocol. protocols running on top of the SSH transport layer protocol.
Message numbers of 80 and higher are reserved for protocols running Message numbers of 80 and higher are reserved for protocols
after this authentication protocol, so receiving one of them before running after this authentication protocol, so receiving one of
authentication is complete is an error, to which the server MUST respond them before authentication is complete is an error, to which the
by disconnecting (preferably with a proper disconnect message sent first server MUST respond by disconnecting (preferably with a proper
to ease troubleshooting). disconnect message sent first to ease troubleshooting).
After successful authentication, such messages are passed to the higher- After successful authentication, such messages are passed to the
level service. higher-level service.
These are the general authentication message codes: These are the general authentication message codes:
#define SSH_MSG_USERAUTH_REQUEST 50 #define SSH_MSG_USERAUTH_REQUEST 50
#define SSH_MSG_USERAUTH_FAILURE 51 #define SSH_MSG_USERAUTH_FAILURE 51
#define SSH_MSG_USERAUTH_SUCCESS 52 #define SSH_MSG_USERAUTH_SUCCESS 52
#define SSH_MSG_USERAUTH_BANNER 53 #define SSH_MSG_USERAUTH_BANNER 53
In addition to the above, there is a range of message numbers (60..79) In addition to the above, there is a range of message numbers
reserved for method-specific messages. These messages are only sent by (60..79) reserved for method-specific messages. These messages
the server (client sends only SSH_MSG_USERAUTH_REQUEST messages). are only sent by the server (client sends only
Different authentication methods reuse the same message numbers. SSH_MSG_USERAUTH_REQUEST messages). Different authentication
methods reuse the same message numbers.
4. Public Key Authentication Method: publickey 4. Public Key Authentication Method: publickey
The only REQUIRED authentication method is public key authentication. The only REQUIRED authentication method is public key
All implementations MUST support this method; however, not all users authentication. All implementations MUST support this method;
need to have public keys, and most local policies are not likely to however, not all users need to have public keys, and most local
require public key authentication for all users in the near future. policies are not likely to require public key authentication for
all users in the near future.
With this method, the possession of a private key serves as With this method, the possession of a private key serves as
authentication. This method works by sending a signature created with a authentication. This method works by sending a signature created
private key of the user. The server MUST check that the key is a valid with a private key of the user. The server MUST check that the
authenticator for the user, and MUST check that the signature is valid. key is a valid authenticator for the user, and MUST check that the
If both hold, the authentication request MUST be accepted; otherwise it signature is valid. If both hold, the authentication request MUST
MUST be rejected. (Note that the server MAY require additional be accepted; otherwise it MUST be rejected. (Note that the server
authentications after successful authentication.) MAY require additional authentications after successful
Private keys are often stored in an encrypted form at the client host, authentication.)
and the user must supply a passphrase before the signature can be
generated. Even if they are not, the signing operation involves some Private keys are often stored in an encrypted form at the client
expensive computation. To avoid unnecessary processing and user host, and the user must supply a passphrase before the signature
interaction, the following message is provided for querying whether can be generated. Even if they are not, the signing operation
authentication using the key would be acceptable. involves some expensive computation. To avoid unnecessary
processing and user interaction, the following message is provided
for querying whether authentication using the key would be
acceptable.
byte SSH_MSG_USERAUTH_REQUEST byte SSH_MSG_USERAUTH_REQUEST
string user name string user name
string service string service
string "publickey" string "publickey"
boolean FALSE boolean FALSE
string public key algorithm name string public key algorithm name
string public key blob string public key blob
Public key algorithms are defined in the transport layer specification Public key algorithms are defined in the transport layer
[SECSH-TRANS]. The public key blob may contain certificates. specification [SSH-TRANS]. The public key blob may contain
certificates.
Any public key algorithm may be offered for use in authentication. In Any public key algorithm may be offered for use in authentication.
particular, the list is not constrained by what was negotiated during In particular, the list is not constrained by what was negotiated
key exchange. If the server does not support some algorithm, it MUST during key exchange. If the server does not support some
simply reject the request. algorithm, it MUST simply reject the request.
The server MUST respond to this message with either The server MUST respond to this message with either
SSH_MSG_USERAUTH_FAILURE or with the following: SSH_MSG_USERAUTH_FAILURE or with the following:
byte SSH_MSG_USERAUTH_PK_OK byte SSH_MSG_USERAUTH_PK_OK
string public key algorithm name from the request string public key algorithm name from the request
string public key blob from the request string public key blob from the request
To perform actual authentication, the client MAY then send a signature To perform actual authentication, the client MAY then send a
generated using the private key. The client MAY send the signature signature generated using the private key. The client MAY send
directly without first verifying whether the key is acceptable. The the signature directly without first verifying whether the key is
signature is sent using the following packet: acceptable. The signature is sent using the following packet:
byte SSH_MSG_USERAUTH_REQUEST byte SSH_MSG_USERAUTH_REQUEST
string user name string user name
string service string service
string "publickey" string "publickey"
boolean TRUE boolean TRUE
string public key algorithm name string public key algorithm name
string public key to be used for authentication string public key to be used for authentication
string signature string signature
skipping to change at page 7, line 38 skipping to change at page 9, line 12
string session identifier string session identifier
byte SSH_MSG_USERAUTH_REQUEST byte SSH_MSG_USERAUTH_REQUEST
string user name string user name
string service string service
string "publickey" string "publickey"
boolean TRUE boolean TRUE
string public key algorithm name string public key algorithm name
string public key to be used for authentication string public key to be used for authentication
When the server receives this message, it MUST check whether the When the server receives this message, it MUST check whether the
supplied key is acceptable for authentication, and if so, it MUST check supplied key is acceptable for authentication, and if so, it MUST
whether the signature is correct. check whether the signature is correct.
If both checks succeed, this method is successful. Note that the server If both checks succeed, this method is successful. Note that the
may require additional authentications. The server MUST respond with server may require additional authentications. The server MUST
SSH_MSG_USERAUTH_SUCCESS (if no more authentications are needed), or respond with SSH_MSG_USERAUTH_SUCCESS (if no more authentications
SSH_MSG_USERAUTH_FAILURE (if the request failed, or more authentications are needed), or SSH_MSG_USERAUTH_FAILURE (if the request failed,
are needed). or more authentications are needed).
The following method-specific message numbers are used by the publickey The following method-specific message numbers are used by the
authentication method. publickey authentication method.
/* Key-based */ /* Key-based */
#define SSH_MSG_USERAUTH_PK_OK 60 #define SSH_MSG_USERAUTH_PK_OK 60
5. Password Authentication Method: password 5. Password Authentication Method: password
Password authentication uses the following packets. Note that a server Password authentication uses the following packets. Note that a
MAY request the user to change the password. All implementations SHOULD server MAY request the user to change the password. All
support password authentication. implementations SHOULD support password authentication.
byte SSH_MSG_USERAUTH_REQUEST byte SSH_MSG_USERAUTH_REQUEST
string user name string user name
string service string service
string "password" string "password"
boolean FALSE boolean FALSE
string plaintext password (ISO-10646 UTF-8) string plaintext password (ISO-10646 UTF-8)
Note that the password is encoded in ISO-10646 UTF-8. It is up to the Note that the password is encoded in ISO-10646 UTF-8. It is up to
server how it interprets the password and validates it against the the server how it interprets the password and validates it against
password database. However, if the client reads the password in some the password database. However, if the client reads the password
other encoding (e.g., ISO 8859-1 (ISO Latin1)), it MUST convert the in some other encoding (e.g., ISO 8859-1 (ISO Latin1)), it MUST
password to ISO-10646 UTF-8 before transmitting, and the server MUST convert the password to ISO-10646 UTF-8 before transmitting, and
convert the password to the encoding used on that system for passwords. the server MUST convert the password to the encoding used on that
system for passwords.
Note that even though the cleartext password is transmitted in the Note that even though the cleartext password is transmitted in the
packet, the entire packet is encrypted by the transport layer. Both the packet, the entire packet is encrypted by the transport layer.
server and the client should check whether the underlying transport Both the server and the client should check whether the underlying
layer provides confidentiality (i.e., if encryption is being used). If transport layer provides confidentiality (i.e., if encryption is
no confidentiality is provided (none cipher), password authentication being used). If no confidentiality is provided (none cipher),
SHOULD be disabled. If there is no confidentiality or no MAC, password password authentication SHOULD be disabled. If there is no
change SHOULD be disabled. confidentiality or no MAC, password change SHOULD be disabled.
Normally, the server responds to this message with success or failure. Normally, the server responds to this message with success or
However, the server MAY also respond with failure. However, the server MAY also respond with
SSH_MSG_USERAUTH_PASSWD_CHANGEREQ. SSH_MSG_USERAUTH_PASSWD_CHANGEREQ.
byte SSH_MSG_USERAUTH_PASSWD_CHANGEREQ byte SSH_MSG_USERAUTH_PASSWD_CHANGEREQ
string prompt (ISO-10646 UTF-8) string prompt (ISO-10646 UTF-8)
string language tag (as defined in [RFC-1766]) string language tag (as defined in [RFC1766])
In this case, the software client SHOULD request a new password from the In this case, the software client SHOULD request a new password
user, and send a new request using the following message. The client from the user, and send a new request using the following message.
may also send this message instead of the normal password authentication The client may also send this message instead of the normal
request without the server asking for it. password authentication request without the server asking for it.
byte SSH_MSG_USERAUTH_REQUEST byte SSH_MSG_USERAUTH_REQUEST
string user name string user name
string service string service
string "password" string "password"
boolean TRUE boolean TRUE
string plaintext old password (ISO-10646 UTF-8) string plaintext old password (ISO-10646 UTF-8)
string plaintext new password (ISO-10646 UTF-8) string plaintext new password (ISO-10646 UTF-8)
The server must reply to request message with SSH_MSG_USERAUTH_SUCCESS, The server must reply to request message with
SSH_MSG_USERAUTH_FAILURE, or another SSH_MSG_USERAUTH_PASSWD_CHANGEREQ. SSH_MSG_USERAUTH_SUCCESS, SSH_MSG_USERAUTH_FAILURE, or another
The meaning of these is as follows: SSH_MSG_USERAUTH_PASSWD_CHANGEREQ. The meaning of these is as
follows:
SSH_MSG_USERAUTH_SUCCESS SSH_MSG_USERAUTH_SUCCESS The password has been changed, and
The password has been changed, and authentication has been authentication has been successfully completed.
successfully completed. SSH_MSG_USERAUTH_FAILURE with partial success The password has
been changed, but more authentications are needed.
SSH_MSG_USERAUTH_FAILURE with partial success SSH_MSG_USERAUTH_FAILURE without partial success The password
The password has been changed, but more authentications are has not been changed. Either password changing was not
needed. supported, or the old password was bad. Note that if the
server has already sent SSH_MSG_USERAUTH_PASSWD_CHANGEREQ, we
SSH_MSG_USERAUTH_FAILURE without partial success know that it supports changing the password.
The password has not been changed. Either password changing was SSH_MSG_USERAUTH_CHANGEREQ The password was not changed because
not supported, or the old password was bad. Note that if the the new password was not acceptable (e.g. too easy to guess).
server has already sent SSH_MSG_USERAUTH_PASSWD_CHANGEREQ, we know
that it supports changing the password.
SSH_MSG_USERAUTH_CHANGEREQ
The password was not changed because the new password was not
acceptable (e.g. too easy to guess).
The following method-specific message numbers are used by the password The following method-specific message numbers are used by the
authentication method. password authentication method.
#define SSH_MSG_USERAUTH_PASSWD_CHANGEREQ 60 #define SSH_MSG_USERAUTH_PASSWD_CHANGEREQ 60
6. Host-Based Authentication: hostbased 6. Host-Based Authentication: hostbased
Some sites wish to allow authentication based on the host where the user Some sites wish to allow authentication based on the host where
is coming from, and the user name on the remote host. While this form the user is coming from, and the user name on the remote host.
of authentication is not suitable for high-security sites, it can be While this form of authentication is not suitable for high-
very convenient in many environments. This form of authentication is security sites, it can be very convenient in many environments.
OPTIONAL. When used, special care SHOULD be taken to prevent a regular This form of authentication is OPTIONAL. When used, special care
user from obtaining the private host key. SHOULD be taken to prevent a regular user from obtaining the
private host key.
The client requests this form of authentication by sending the following The client requests this form of authentication by sending the
message. It is similar to the UNIX "rhosts" and "hosts.equiv" styles of following message. It is similar to the UNIX "rhosts" and
authentication, except that the identity of the client host is checked "hosts.equiv" styles of authentication, except that the identity
more rigorously. of the client host is checked more rigorously.
This method works by having the client send a signature created with the This method works by having the client send a signature created
private key of the client host, which the server checks with that host's with the private key of the client host, which the server checks
public key. Once the client host's identity is established, with that host's public key. Once the client host's identity is
authorization (but no further authentication) is performed based on the established, authorization (but no further authentication) is
user names on the server and the client, and the client host name. performed based on the user names on the server and the client,
and the client host name.
byte SSH_MSG_USERAUTH_REQUEST byte SSH_MSG_USERAUTH_REQUEST
string user name string user name
string service string service
string "hostbased" string "hostbased"
string public key algorithm for host key string public key algorithm for host key
string public host key and certificates for client host string public host key and certificates for client host
string client host name (FQDN; US-ASCII) string client host name (FQDN; US-ASCII)
string client user name on the remote host (ISO-10646 UTF-8) string client user name on the remote host (ISO-10646 UTF-8)
string signature string signature
Public key algorithm names for use in "public key algorithm for host Public key algorithm names for use in "public key algorithm for
key" are defined in the transport layer specification. The "public host host key" are defined in the transport layer specification. The
key for client host" may include certificates. "public host key for client host" may include certificates.
Signature is a signature with the private host key of the following Signature is a signature with the private host key of the
data, in this order: following data, in this order:
string session identifier string session identifier
byte SSH_MSG_USERAUTH_REQUEST byte SSH_MSG_USERAUTH_REQUEST
string user name string user name
string service string service
string "hostbased" string "hostbased"
string public key algorithm for host key string public key algorithm for host key
string public host key and certificates for client host string public host key and certificates for client host
string client host name (FQDN; US-ASCII) string client host name (FQDN; US-ASCII)
string client user name on the remote host (ISO-10646 UTF-8) string client user name on the remote host (ISO-10646 UTF-8)
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 is a valid signature
on the appropriate value by the given host key. The server MAY
ignore the client user name, if it wants to authenticate only the
client host.
The server MUST verify that the host key actually belongs to the client It is RECOMMENDED that whenever possible, the server perform
host named in the message, that the given user on that host is allowed additional checks to verify that the network address obtained from
to log in, and that the signature is a valid signature on the the (untrusted) network matches the given client host name. This
appropriate value by the given host key. The server MAY ignore the makes exploiting compromised host keys more difficult. Note that
client user name, if it wants to authenticate only the client host. this may require special handling for connections coming through a
firewall.
It is RECOMMENDED that whenever possible, the server perform additional
checks to verify that the network address obtained from the (untrusted)
network matches the given client host name. This makes exploiting
compromised host keys more difficult. Note that this may require
special handling for connections coming through a firewall.
7. Security Considerations 7. Security Considerations
The purpose of this protocol is to perform client user authentication. The purpose of this protocol is to perform client user
It assumed that this runs over a secure transport layer protocol, which authentication. It assumed that this runs over a secure transport
has already authenticated the server machine, established an encrypted layer protocol, which has already authenticated the server
communications channel, and computed a unique session identifier for machine, established an encrypted communications channel, and
this session. The transport layer provides forward secrecy for password 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. authentication and other methods that rely on secret data.
The server may go into a "sleep" period after repeated unsuccessful The server may go into a "sleep" period after repeated
authentications to make key search harder. unsuccessful authentications to make key search harder.
If the transport layer does not provide encryption, authentication If the transport layer does not provide encryption, authentication
methods that rely on secret data SHOULD be disabled. If it does not methods that rely on secret data SHOULD be disabled. If it does
provide MAC protection, requests to change authentication data (e.g. not provide MAC protection, requests to change authentication data
password change) SHOULD be disabled to avoid an attacker from modifying (e.g. password change) SHOULD be disabled to avoid an attacker
the ciphertext without being noticed, rendering the new authentication from modifying the ciphertext without being noticed, rendering the
data unusable (denial of service). new authentication data unusable (denial of service).
Several authentication methods with different security characteristics Several authentication methods with different security
are allowed. It is up to the server's local policy to decide which characteristics are allowed. It is up to the server's local
methods (or combinations of methods) it is willing to accept for each policy to decide which methods (or combinations of methods) it is
user. Authentication is no stronger than the weakest combination willing to accept for each user. Authentication is no stronger
allowed. than the weakest combination allowed.
Special care should be taken when designing debug messages. These Special care should be taken when designing debug messages. These
messages may reveal surprising amounts of information about the host if messages may reveal surprising amounts of information about the
not properly designed. Debug messages can be disabled (during user host if not properly designed. Debug messages can be disabled
authentication phase) if high security is required. (during user authentication phase) if high security is required.
8. Trademark Issues 8. Trademark Issues
"ssh" is a registered trademark of SSH Communications Security Corp in As of this writing, SSH Communications Security Oy claims ssh as
the United States and/or other countries. its trademark. As with all IPR claims the IETF takes no position
regarding the validity or scope of this trademark claim.
9. References 9. Additional Information
[RFC-1766] Alvestrand, H: "Tags for the Identification of Languages", The current document editor is: Darren.Moffat@Sun.COM. Comments
March 1995. on this internet draft should be sent to the IETF SECSH working
group, details at: http://ietf.org/html.charters/secsh-
charter.html
[RFC-2279] Yergeau, F: "UTF-8, a transformation format of ISO 10646", References
January 1998.
[SECSH-ARCH] Ylonen, T., et al: "Secure Shell Remote Login Protocol [RFC1766] Alvestrand, H., "Tags for the Identification of
Architecture", Internet-Draft, draft-secsh-architecture-08.txt Languages", RFC 1766, March 1995.
[SECSH-TRANS] Ylonen, T., et al: "Secure Shell Transport Layer [RFC2279] Yergeau, F., "UTF-8, a transformation format of
Protocol", Internet-Draft, draft-secsh-transport-10.txt ISO 10646", RFC 2279, January 1998.
[SECSH-CONNECT] Ylonen, T., et al: "Secure Shell Connection Protocol", [SSH-ARCH] Ylonen, T., "SSH Protocol Architecture", I-D
Internet-Draft, draft-secsh-connect-10.txt draft-ietf-architecture-09.txt, July 2001.
10. Authors' Addresses [SSH-TRANS] Ylonen, T., "SSH Transport Layer Protocol", I-D
draft-ietf-transport-11.txt, July 2001.
[SSH-USERAUTH] Ylonen, T., "SSH Authentication Protocol", I-D
draft-ietf-userauth-11.txt, July 2001.
[SSH-CONNECT] Ylonen, T., "SSH Connection Protocol", I-D draft-
ietf-connect-11.txt, July 2001.
Authors' Addresses
Tatu Ylonen Tatu Ylonen
SSH Communications Security Corp SSH Communications Security Corp
Fredrikinkatu 42 Fredrikinkatu 42
FIN-00100 HELSINKI HELSINKI FIN-00100
Finland Finland
E-mail: ylo@ssh.com
EMail: ylo@ssh.com
Tero Kivinen Tero Kivinen
SSH Communications Security Corp SSH Communications Security Corp
Fredrikinkatu 42 Fredrikinkatu 42
FIN-00100 HELSINKI HELSINKI FIN-00100
Finland Finland
E-mail: kivinen@ssh.com
EMail: kivinen@ssh.com
Markku-Juhani O. Saarinen Markku-Juhani O. Saarinen
University of Jyvaskyla University of Jyvaskyla
Timo J. Rinne Timo J. Rinne
SSH Communications Security Corp SSH Communications Security Corp
Fredrikinkatu 42 Fredrikinkatu 42
FIN-00100 HELSINKI HELSINKI FIN-00100
Finland Finland
E-mail: tri@ssh.com
EMail: tri@ssh.com
Sami Lehtinen Sami Lehtinen
SSH Communications Security Corp SSH Communications Security Corp
Fredrikinkatu 42 Fredrikinkatu 42
FIN-00100 HELSINKI HELSINKI FIN-00100
Finland Finland
E-mail: sjl@ssh.com
EMail: sjl@ssh.com
Full Copyright Statement
Copyright (C) The Internet Society (2001). All Rights Reserved.
This document and translations of it may be copied and furnished
to others, and derivative works that comment on or otherwise
explain it or assist in its implementation may be prepared,
copied, published and distributed, in whole or in part, without
restriction of any kind, provided that the above copyright notice
and this paragraph are included on all such copies and derivative
works. However, this document itself may not be modified in any
way, such as by removing the copyright notice or references to the
Internet Society or other Internet organizations, except as needed
for the purpose of developing Internet standards in which case the
procedures for copyrights defined in the Internet Standards
process must be followed, or as required to translate it into
languages other than English.
The limited permissions granted above are perpetual and will not
be revoked by the Internet Society or its successors or assigns.
This document and the information contained herein is provided on
an "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET
ENGINEERING TASK FORCE DISCLAIMS 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.
Acknowledgement
Funding for the RFC Editor function is currently provided by the
Internet Society.
 End of changes. 

This html diff was produced by rfcdiff 1.23, available from http://www.levkowetz.com/ietf/tools/rfcdiff/