draft-ietf-secsh-userauth-25.txt   draft-ietf-secsh-userauth-26.txt 
Network Working Group C. Lonvick, Ed. Network Working Group C. Lonvick, Ed.
Internet-Draft Cisco Systems, Inc. Internet-Draft Cisco Systems, Inc.
Expires: June 9, 2005 December 9, 2004 Expires: August 21, 2005 February 17, 2005
SSH Authentication Protocol SSH Authentication Protocol
draft-ietf-secsh-userauth-25.txt draft-ietf-secsh-userauth-26.txt
Status of this Memo Status of this Memo
This document is an Internet-Draft and is subject to all provisions This document is an Internet-Draft and is subject to all provisions
of section 3 of RFC 3667. By submitting this Internet-Draft, each of Section 3 of RFC 3667. By submitting this Internet-Draft, each
author represents that any applicable patent or other IPR claims of author represents that any applicable patent or other IPR claims of
which he or she is aware have been or will be disclosed, and any of which he or she is aware have been or will be disclosed, and any of
which he or she become aware will be disclosed, in accordance with which he or she become aware will be disclosed, in accordance with
RFC 3668. RFC 3668.
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 35 skipping to change at page 1, line 35
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 June 9, 2005. This Internet-Draft will expire on August 21, 2005.
Copyright Notice Copyright Notice
Copyright (C) The Internet Society (2004). Copyright (C) The Internet Society (2005).
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
host-based client authentication methods. Additional authentication host-based client authentication methods. Additional authentication
methods are described in separate documents. The SSH authentication methods are described in separate documents. The SSH authentication
protocol runs on top of the SSH transport layer protocol and provides protocol runs on top of the SSH transport layer protocol and provides
a single authenticated tunnel for the SSH connection protocol. a single authenticated tunnel for the SSH connection protocol.
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
4. The Authentication Protocol Framework . . . . . . . . . . . . 4 4. The Authentication Protocol Framework . . . . . . . . . . . 4
5. Authentication Requests . . . . . . . . . . . . . . . . . . . 4 5. Authentication Requests . . . . . . . . . . . . . . . . . . 5
5.1 Responses to Authentication Requests . . . . . . . . . . . 5 5.1 Responses to Authentication Requests . . . . . . . . . . . 6
5.2 The "none" Authentication Request . . . . . . . . . . . . 7 5.2 The "none" Authentication Request . . . . . . . . . . . . 7
5.3 Completion of User Authentication . . . . . . . . . . . . 7 5.3 Completion of User Authentication . . . . . . . . . . . . 7
5.4 Banner Message . . . . . . . . . . . . . . . . . . . . . . 7 5.4 Banner Message . . . . . . . . . . . . . . . . . . . . . . 7
6. Authentication Protocol Message Numbers . . . . . . . . . . . 8 6. Authentication Protocol Message Numbers . . . . . . . . . . 8
7. Public Key Authentication Method: publickey . . . . . . . . . 8 7. Public Key Authentication Method: publickey . . . . . . . . 8
8. Password Authentication Method: password . . . . . . . . . . . 10 8. Password Authentication Method: password . . . . . . . . . . 10
9. Host-Based Authentication: hostbased . . . . . . . . . . . . . 12 9. Host-Based Authentication: hostbased . . . . . . . . . . . . 12
10. IANA Considerations . . . . . . . . . . . . . . . . . . . . 13 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . 13
11. Security Considerations . . . . . . . . . . . . . . . . . . 13 11. Security Considerations . . . . . . . . . . . . . . . . . . 14
12. References . . . . . . . . . . . . . . . . . . . . . . . . . 14 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 14
12.1 Normative . . . . . . . . . . . . . . . . . . . . . . . . . 14 12.1 Normative . . . . . . . . . . . . . . . . . . . . . . . 14
12.2 Informative . . . . . . . . . . . . . . . . . . . . . . . . 14 12.2 Informative . . . . . . . . . . . . . . . . . . . . . . 15
Author's Address . . . . . . . . . . . . . . . . . . . . . . . 15 Author's Address . . . . . . . . . . . . . . . . . . . . . . 15
Intellectual Property and Copyright Statements . . . . . . . . 16 Intellectual Property and Copyright Statements . . . . . . . 16
1. Contributors 1. Contributors
The major original contributors of this set of documents have been: The major original contributors of this set of documents have been:
Tatu Ylonen, Tero Kivinen, Timo J. Rinne, Sami Lehtinen (all of SSH Tatu Ylonen, 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 set of documents and also made very substantial contributions. this set of documents and also made very substantial contributions.
Additional contributors to this document include [need list]. Additional contributors to this document include [need list].
skipping to change at page 4, line 9 skipping to change at page 4, line 9
"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" to describe "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" to describe
requirements. These keywords are to be interpreted as described in requirements. These keywords are to be interpreted as described in
[RFC2119]. [RFC2119].
The keywords "PRIVATE USE", "HIERARCHICAL ALLOCATION", "FIRST COME The keywords "PRIVATE USE", "HIERARCHICAL ALLOCATION", "FIRST COME
FIRST SERVED", "EXPERT REVIEW", "SPECIFICATION REQUIRED", "IESG FIRST SERVED", "EXPERT REVIEW", "SPECIFICATION REQUIRED", "IESG
APPROVAL", "IETF CONSENSUS", and "STANDARDS ACTION" that appear in APPROVAL", "IETF CONSENSUS", and "STANDARDS ACTION" that appear in
this document when used to describe namespace allocation are to be this document when used to describe namespace allocation are to be
interpreted as described in [RFC2434]. interpreted as described in [RFC2434].
Protocol fields and possible values to fill them are defined in this
set of documents. Protocol fields will be defined in the message
definitions. As an example, SSH_MSG_CHANNEL_DATA is defined as
follows.
byte SSH_MSG_CHANNEL_DATA
uint32 recipient channel
string data
Throughout these documents, when the fields are referenced, they will
appear within single quotes. When values to fill those fields are
referenced, they will appear within double quotes. Using the above
example, possible values for 'data' are "foo" and "bar".
4. The Authentication Protocol Framework 4. 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 by given time. The client has the freedom to try the methods listed by
the server in any order. This gives the server complete control over the server in any order. This gives the server complete control over
the authentication process if desired, but also gives enough the authentication process if desired, but also gives enough
flexibility for the client to use the methods it supports or that are flexibility for the client to use the methods it supports or that are
most convenient for the user, when multiple methods are offered by most convenient for the user, when multiple methods are offered by
the server. the server.
skipping to change at page 5, line 16 skipping to change at page 5, line 30
flush some authentication state, it MUST disconnect if the 'user flush some authentication state, it MUST disconnect if the 'user
name' or 'service name' changes. name' or 'service name' changes.
The 'service name' specifies the service to start after The 'service name' specifies the service to start after
authentication. There may be several different authenticated authentication. There may be several different authenticated
services provided. If the requested service is not available, the services provided. If the requested service is not available, the
server MAY disconnect immediately or at any later time. Sending a server MAY disconnect immediately or at any later time. Sending a
proper disconnect message is RECOMMENDED. In any case, if the proper disconnect message is RECOMMENDED. In any case, if the
service does not exist, authentication MUST NOT be accepted. service does not exist, authentication MUST NOT be accepted.
If the requested user does not exist, the server MAY disconnect, or If the requested 'user name' does not exist, the server MAY
MAY send a bogus list of acceptable authentication 'method name' disconnect, or MAY send a bogus list of acceptable authentication
values, but never accept any. This makes it possible for the server 'method name' values, but never accept any. This makes it possible
to avoid disclosing information on which accounts exist. In any for the server to avoid disclosing information on which accounts
case, if the user does not exist, the authentication request MUST NOT exist. In any case, if the 'user name' does not exist, the
be accepted. authentication request MUST NOT be accepted.
While there is usually little point for clients to send requests that While there is usually little point for clients to send requests that
the server does not list as acceptable, sending such requests is not the server does not list as acceptable, sending such requests is not
an error, and the server SHOULD simply reject requests that it does an error, and the server SHOULD simply reject requests that 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
name' used, and the client MAY at any time continue with a new name' 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
skipping to change at page 7, line 35 skipping to change at page 7, line 47
5.4 Banner Message 5.4 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 '/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 after this authentication protocol starts and before authentication
be displayed to the client user before authentication is attempted. is successful. This message contains text to be displayed to the
The format is as follows: client user before authentication is attempted. The format is as
follows:
byte SSH_MSG_USERAUTH_BANNER byte SSH_MSG_USERAUTH_BANNER
string message in ISO-10646 UTF-8 encoding string message in ISO-10646 UTF-8 encoding
string language tag as defined in [RFC3066] string language tag as defined in [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
terminal control characters. terminal control characters.
6. Authentication Protocol Message Numbers 6. 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.
skipping to change at page 11, line 38 skipping to change at page 12, line 4
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 in ISO-10646 UTF-8 encoding string plaintext old password in ISO-10646 UTF-8 encoding
string plaintext new password in ISO-10646 UTF-8 encoding string plaintext new password in ISO-10646 UTF-8 encoding
The server must reply to each 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 has SSH_MSG_USERAUTH_FAILURE without partial success - The password
not been changed. Either password changing was not supported, or has not been changed. Either password changing was not supported,
the old password was bad. Note that if the server has already or the old password was bad. Note that if the server has already
sent SSH_MSG_USERAUTH_PASSWD_CHANGEREQ, we know that it supports sent SSH_MSG_USERAUTH_PASSWD_CHANGEREQ, we 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.
SSH_MSG_USERAUTH_PASSWD_CHANGEREQ 60 SSH_MSG_USERAUTH_PASSWD_CHANGEREQ 60
9. Host-Based Authentication: hostbased 9. Host-Based Authentication: hostbased
Some sites wish to allow authentication based on the host where the Some sites wish to allow authentication based on the host where the
skipping to change at page 13, line 22 skipping to change at page 13, line 34
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 expressed as the FQDN in US-ASCII string client host name expressed as the FQDN in US-ASCII
string user name on the client host in ISO-10646 UTF-8 encoding 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' value is a valid allowed to log in, and that the 'signature' value is a valid
signature on the appropriate value by the given host key. The server 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 MAY ignore the client 'user name', if it wants to authenticate only
client host. 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.
10. IANA Considerations 10. IANA Considerations
skipping to change at page 14, line 10 skipping to change at page 14, line 23
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
[SSH-ARCH]. [SSH-ARCH].
12. References 12. References
12.1 Normative 12.1 Normative
[SSH-ARCH] [SSH-ARCH]
Lonvick, C., "SSH Protocol Architecture", I-D Lonvick, C., "SSH Protocol Architecture",
draft-ietf-secsh-architecture-20.txt, December 2004. I-D draft-ietf-secsh-architecture-21.txt, February 2005.
[SSH-CONNECT] [SSH-CONNECT]
Lonvick, C., "SSH Connection Protocol", I-D Lonvick, C., "SSH Connection Protocol",
draft-ietf-secsh-connect-23.txt, December 2004. I-D draft-ietf-secsh-connect-24.txt, February 2005.
[SSH-TRANS] [SSH-TRANS]
Lonvick, C., "SSH Transport Layer Protocol", I-D Lonvick, C., "SSH Transport Layer Protocol",
draft-ietf-secsh-transport-22.txt, December 2004. I-D draft-ietf-secsh-transport-23.txt, February 2005.
[SSH-NUMBERS] [SSH-NUMBERS]
Lonvick, C., "SSH Protocol Assigned Numbers", I-D Lonvick, C., "SSH Protocol Assigned Numbers",
draft-ietf-secsh-assignednumbers-10.txt, December 2004. I-D draft-ietf-secsh-assignednumbers-11.txt, February
2005.
[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.
[RFC2434] Narten, T. and H. Alvestrand, "Guidelines for Writing an [RFC2434] Narten, T. and H. Alvestrand, "Guidelines for Writing an
IANA Considerations Section in RFCs", BCP 26, RFC 2434, IANA Considerations Section in RFCs", BCP 26, RFC 2434,
October 1998. October 1998.
[RFC3066] Alvestrand, H., "Tags for the Identification of [RFC3066] Alvestrand, H., "Tags for the Identification of
Languages", BCP 47, RFC 3066, January 2001. Languages", BCP 47, RFC 3066, January 2001.
[RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO
10646", STD 63, RFC 3629, November 2003. 10646", STD 63, RFC 3629, November 2003.
[I-D.ietf-sasl-saslprep] [I-D.ietf-sasl-saslprep]
Zeilenga, K., "SASLprep: Stringprep profile for user names Zeilenga, K., "SASLprep: Stringprep profile for user names
and passwords", draft-ietf-sasl-saslprep-10 (work in and passwords",
progress), July 2004. Internet-Draft draft-ietf-sasl-saslprep-10, July 2004.
12.2 Informative 12.2 Informative
[ssh-1.2.30] [ssh-1.2.30]
Ylonen, T., "ssh-1.2.30/RFC", File within compressed Ylonen, T., "ssh-1.2.30/RFC", File within compressed
tarball ftp://ftp.funet.fi/pub/unix/security/login/ssh/ tarball ftp://ftp.funet.fi/pub/unix/security/login/ssh/
ssh-1.2.30.tar.gz, November 1995. ssh-1.2.30.tar.gz, November 1995.
Author's Address Author's Address
Chris Lonvick (editor) Chris Lonvick (editor)
Cisco Systems, Inc. Cisco Systems, Inc.
12515 Research Blvd. 12515 Research Blvd.
Austin 78759 Austin 78759
USA USA
EMail: clonvick@cisco.com Email: clonvick@cisco.com
Intellectual Property Statement Intellectual Property Statement
The IETF takes no position regarding the validity or scope of any The IETF takes no position regarding the validity or scope of any
Intellectual Property Rights or other rights that might be claimed to Intellectual Property Rights or other rights that might be claimed to
pertain to the implementation or use of the technology described in pertain to the implementation or use of the technology described in
this document or the extent to which any license under such rights this document or the extent to which any license under such rights
might or might not be available; nor does it represent that it has might or might not be available; nor does it represent that it has
made any independent effort to identify any such rights. Information made any independent effort to identify any such rights. Information
on the procedures with respect to rights in RFC documents can be on the procedures with respect to rights in RFC documents can be
skipping to change at page 16, line 46 skipping to change at page 16, line 46
This document and the information contained herein are provided on an This document and the information contained herein are provided on an
"AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Copyright Statement Copyright Statement
Copyright (C) The Internet Society (2004). This document is subject Copyright (C) The Internet Society (2005). This document is subject
to the rights, licenses and restrictions contained in BCP 78, and to the rights, licenses and restrictions contained in BCP 78, and
except as set forth therein, the authors retain all their rights. except as set forth therein, the authors retain all their rights.
Acknowledgment Acknowledgment
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/