draft-ietf-secsh-userauth-20.txt   draft-ietf-secsh-userauth-21.txt 
Network Working Group T. Ylonen Network Working Group T. Ylonen
Internet-Draft SSH Communications Security Corp Internet-Draft SSH Communications Security Corp
Expires: November 23, 2004 C. Lonvick, Ed. Expires: December 1, 2004 C. Lonvick, Ed.
Cisco Systems, Inc Cisco Systems, Inc
May 25, 2004 June 2, 2004
SSH Authentication Protocol SSH Authentication Protocol
draft-ietf-secsh-userauth-20.txt draft-ietf-secsh-userauth-21.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 other groups may also distribute working documents as
Internet-Drafts. Internet-Drafts.
skipping to change at page 1, line 33 skipping to change at page 1, line 33
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in 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 November 23, 2004. This Internet-Draft will expire on December 1, 2004.
Copyright Notice Copyright Notice
Copyright (C) The Internet Society (2004). All Rights Reserved. Copyright (C) The Internet Society (2004). 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 SSH services over an insecure network. This document describes the SSH
authentication protocol framework and public key, password, and authentication protocol framework and public key, password, and
skipping to change at page 2, line 14 skipping to change at page 2, line 14
Table of Contents Table of Contents
1. Contributors . . . . . . . . . . . . . . . . . . . . . . . . . 3 1. Contributors . . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
3. Conventions Used in This Document . . . . . . . . . . . . . . 3 3. Conventions Used in This Document . . . . . . . . . . . . . . 3
3.1 The Authentication Protocol Framework . . . . . . . . . . 4 3.1 The Authentication Protocol Framework . . . . . . . . . . 4
3.1.1 Authentication Requests . . . . . . . . . . . . . . . 4 3.1.1 Authentication Requests . . . . . . . . . . . . . . . 4
3.1.2 Responses to Authentication Requests . . . . . . . . . 5 3.1.2 Responses to Authentication Requests . . . . . . . . . 5
3.1.3 The "none" Authentication Request . . . . . . . . . . 6 3.1.3 The "none" Authentication Request . . . . . . . . . . 6
3.1.4 Completion of User Authentication . . . . . . . . . . 7 3.1.4 Completion of User Authentication . . . . . . . . . . 6
3.1.5 Banner Message . . . . . . . . . . . . . . . . . . . . 7 3.1.5 Banner Message . . . . . . . . . . . . . . . . . . . . 7
3.2 Authentication Protocol Message Numbers . . . . . . . . . 7 3.2 Authentication Protocol Message Numbers . . . . . . . . . 7
3.3 Public Key Authentication Method: publickey . . . . . . . 8 3.3 Public Key Authentication Method: publickey . . . . . . . 8
3.4 Password Authentication Method: password . . . . . . . . . 10 3.4 Password Authentication Method: password . . . . . . . . . 10
3.5 Host-Based Authentication: hostbased . . . . . . . . . . . 11 3.5 Host-Based Authentication: hostbased . . . . . . . . . . . 11
4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12
5. Security Considerations . . . . . . . . . . . . . . . . . . . 13 5. Security Considerations . . . . . . . . . . . . . . . . . . . 13
6. References . . . . . . . . . . . . . . . . . . . . . . . . . . 13 6. References . . . . . . . . . . . . . . . . . . . . . . . . . . 13
6.1 Normative . . . . . . . . . . . . . . . . . . . . . . . . . 13 6.1 Normative . . . . . . . . . . . . . . . . . . . . . . . . . 13
6.2 Informative . . . . . . . . . . . . . . . . . . . . . . . . 14 6.2 Informative . . . . . . . . . . . . . . . . . . . . . . . . 13
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . 14 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . 14
Intellectual Property and Copyright Statements . . . . . . . . 15 Intellectual Property and Copyright Statements . . . . . . . . 15
1. Contributors 1. Contributors
The major original contributors of this document were: Tatu Ylonen, The major original contributors of this document were: Tatu Ylonen,
Tero Kivinen, Timo J. Rinne, Sami Lehtinen (all of SSH Tero Kivinen, Timo J. Rinne, Sami Lehtinen (all of SSH
Communications Security Corp), and Markku-Juhani O. Saarinen Communications Security Corp), and Markku-Juhani O. Saarinen
(University of Jyvaskyla). Darren Moffit was the original editor of (University of Jyvaskyla). Darren Moffit was the original editor of
this document and also made very substantial contributions. this document and also made very substantial contributions.
skipping to change at page 4, line 39 skipping to change at page 4, line 39
the implementation SHOULD limit the number of failed authentication the implementation SHOULD limit the number of failed authentication
attempts a client may perform in a single session (the RECOMMENDED attempts a client may perform in a single session (the RECOMMENDED
limit is 20 attempts). If the threshold is exceeded, the server limit is 20 attempts). If the threshold is exceeded, the server
SHOULD disconnect. SHOULD disconnect.
3.1.1 Authentication Requests 3.1.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 on Only the first few fields are defined; the remaining fields depend 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 string user name in ISO-10646 UTF-8 encoding [RFC2279]
[RFC2279] string service name in US-ASCII
) string method name in US-ASCII
string service name (in 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 some authentication states if they change. If it is unable to flush some
authentication state, it MUST disconnect if the user or service name authentication state, it MUST disconnect if the user or service name
changes. changes.
The service name specifies the service to start after authentication. The service name specifies the service to start after authentication.
skipping to change at page 6, line 36 skipping to change at page 6, line 33
request will result in further exchange of messages. No request will result in further exchange of messages. No
SSH_MSG_USERAUTH_FAILURE message will be sent for the aborted method. SSH_MSG_USERAUTH_FAILURE message will be sent for the aborted method.
SSH_MSG_USERAUTH_SUCCESS MUST be sent only once. When SSH_MSG_USERAUTH_SUCCESS MUST be sent only once. When
SSH_MSG_USERAUTH_SUCCESS has been sent, any further authentication SSH_MSG_USERAUTH_SUCCESS has been sent, any further authentication
requests received after that SHOULD be silently ignored. requests received after that SHOULD be silently ignored.
Any non-authentication messages sent by the client after the request Any non-authentication messages sent by the client after the request
that resulted in SSH_MSG_USERAUTH_SUCCESS being sent MUST be passed 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 to the service being run on top of this protocol. Such messages can
be identified by their message numbers (see Section Message Numbers be identified by their message numbers (see Section 3.2).
(Section 3.2)).
3.1.3 The "none" Authentication Request 3.1.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 MUST If no authentication at all is needed for the user, the server MUST
return SSH_MSG_USERAUTH_SUCCESS. Otherwise, the server MUST return return SSH_MSG_USERAUTH_SUCCESS. Otherwise, the server MUST 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.
skipping to change at page 7, line 26 skipping to change at page 7, line 20
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 `/etc/issue', UNIX machines, for example, normally display text from `/etc/issue',
or use "tcp wrappers" or similar software to display a banner before or use "tcp wrappers" or similar software to display a banner before
issuing a login prompt. issuing a login prompt.
The SSH server may send a SSH_MSG_USERAUTH_BANNER message at any time The SSH server may send a SSH_MSG_USERAUTH_BANNER message at any time
before authentication is successful. This message contains text to before authentication is successful. This message contains text to
be displayed to the client user before authentication is attempted. be displayed to the client user before authentication is 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 in ISO-10646 UTF-8 encoding
string language tag (as defined in string language tag as defined in [RFC3066]
[RFC3066]
)
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 separate attempt, and since some client software will need to open a separate
window for this warning, the client software may allow the user to window for this warning, the client software may allow the user to
explicitly disable the display of banners from the server. The explicitly disable the display of banners from 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
skipping to change at page 8, line 4 skipping to change at page 7, line 44
3.2 Authentication Protocol Message Numbers 3.2 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 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 running Message numbers of 80 and higher are reserved for protocols running
after this authentication protocol, so receiving one of them before after this authentication protocol, so receiving one of them before
authentication is complete is an error, to which the server MUST authentication is complete is an error, to which the server MUST
respond by disconnecting (preferably with a proper disconnect message respond by disconnecting, preferably with a proper 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
skipping to change at page 10, line 25 skipping to change at page 10, line 16
Password authentication uses the following packets. Note that a Password authentication uses the following packets. Note that a
server MAY request the user to change the password. All server MAY request the user to change the password. All
implementations SHOULD 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 in ISO-10646 UTF-8 encoding
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 in the password database. However, if the client reads the password in
some other encoding (e.g., ISO 8859-1 (ISO Latin1)), it MUST convert some other encoding (e.g., ISO 8859-1 - ISO Latin1), it MUST convert
the password to ISO-10646 UTF-8 before transmitting, and the server the password to ISO-10646 UTF-8 before transmitting, and the server
MUST convert the password to the encoding used on that system for MUST convert the password to the encoding used on that 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. Both packet, the entire packet is encrypted by the transport layer. 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
skipping to change at page 10, line 48 skipping to change at page 10, line 39
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, if the password has expired the server SHOULD failure. However, if the password has expired the server SHOULD
indicate this by responding with SSH_MSG_USERAUTH_PASSWD_CHANGEREQ. indicate this by responding with SSH_MSG_USERAUTH_PASSWD_CHANGEREQ.
In any case the server MUST NOT allow an expired password to be used In any case the server MUST NOT allow an expired password to be used
for authentication. for authentication.
byte SSH_MSG_USERAUTH_PASSWD_CHANGEREQ byte SSH_MSG_USERAUTH_PASSWD_CHANGEREQ
string prompt (ISO-10646 UTF-8) string prompt in ISO-10646 UTF-8 encoding
string language tag (as defined in string language tag as defined in [RFC3066]
[RFC3066]
)
In this case, the client MAY continue with a different authentication In this case, the client MAY continue with a different authentication
method, or request a new password from the user and retry password method, or request a new password from the user and retry password
authentication using the following message. The client MAY also send authentication using the following message. The client MAY also send
this message instead of the normal password authentication request this message instead of the normal password authentication request
without the server asking for it. 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 in ISO-10646 UTF-8 encoding
string plaintext new password (ISO-10646 UTF-8) string plaintext new password in ISO-10646 UTF-8 encoding
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
skipping to change at page 12, line 27 skipping to change at page 12, line 13
authorization (but no further authentication) is performed based on authorization (but no further authentication) is performed based on
the user names on the server and the client, and the client host the user names on the server and the client, 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 expressed as the FQDN in US-ASCII
string user name on the client host (ISO-10646 UTF-8) string user name on the client host in ISO-10646 UTF-8 encoding
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 host
key" are defined in the transport layer specification. The "public key" are defined in the transport layer specification. The "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 following Signature is a signature with the private host key of the 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 expressed as the FQDN in US-ASCII
string user name on the client host(ISO-10646 UTF-8) string user name on the client host in ISO-10646 UTF-8 encoding
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 is 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 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 appropriate value by the given host key. The server MAY ignore the
client user name, if it wants to authenticate only the client host. client user name, if it wants to authenticate only the 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.
4. IANA Considerations 4. IANA Considerations
This document is part of a set, the IANA considerations for the SSH This document is part of a set. The IANA considerations for the SSH
protocol as defined in [SSH-ARCH], [SSH-TRANS], [SSH-CONNECT], and protocol as defined in [SSH-ARCH], [SSH-TRANS], [SSH-CONNECT], and
this document, are detailed in [SSH-NUMBERS]. this document, are detailed in [SSH-NUMBERS].
5. Security Considerations 5. 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 machine, layer protocol, which has already authenticated the server machine,
established an encrypted communications channel, and computed a established an encrypted communications channel, and computed a
unique session identifier for this session. The transport layer unique session identifier for this session. The transport layer
provides forward secrecy for password authentication and other provides forward secrecy for password authentication and other
methods that rely on secret data. methods that rely on secret data.
Full security considerations for this protocol are provided in Full security considerations for this protocol are provided in
Section 8 of [SSH-ARCH] [SSH-ARCH].
6. References 6. References
6.1 Normative 6.1 Normative
[SSH-ARCH] [SSH-ARCH]
Ylonen, T. and C. Lonvick, "SSH Protocol Architecture", Ylonen, T. and C. Lonvick, "SSH Protocol Architecture",
I-D draft-ietf-architecture-17.txt, May 2004. I-D draft-ietf-architecture-16.txt, May 2004.
[SSH-CONNECT] [SSH-CONNECT]
Ylonen, T. and C. Lonvick, "SSH Connection Protocol", I-D Ylonen, T. and C. Lonvick, "SSH Connection Protocol", I-D
draft-ietf-connect-20.txt, May 2004. draft-ietf-connect-19.txt, May 2004.
[SSH-TRANS] [SSH-TRANS]
Ylonen, T. and C. Lonvick, "SSH Transport Layer Protocol", Ylonen, T. and C. Lonvick, "SSH Transport Layer Protocol",
I-D draft-ietf-transport-19.txt, May 2004. I-D draft-ietf-transport-18.txt, May 2004.
[SSH-NUMBERS] [SSH-NUMBERS]
Ylonen, T. and C. Lonvick, "SSH Protocol Assigned Ylonen, T. and C. Lonvick, "SSH Protocol Assigned
Numbers", I-D draft-ietf-assignednumbers-07.txt, May 2004. Numbers", I-D draft-ietf-assignednumbers-06.txt, May 2004.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997. Requirement Levels", BCP 14, RFC 2119, March 1997.
6.2 Informative 6.2 Informative
[RFC2279] Yergeau, F., "UTF-8, a transformation format of ISO [RFC2279] Yergeau, F., "UTF-8, a transformation format of ISO
10646", RFC 2279, January 1998. 10646", RFC 2279, January 1998.
[RFC3066] Alvestrand, H., "Tags for the Identification of [RFC3066] Alvestrand, H., "Tags for the Identification of
 End of changes. 

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