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

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