You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@mina.apache.org by gn...@apache.org on 2013/07/26 15:30:50 UTC
[1/9] Remove third party documents from scm
Updated Branches:
refs/heads/master 5bd7629ef -> 46ea09302
http://git-wip-us.apache.org/repos/asf/mina-sshd/blob/46ea0930/sshd-core/src/docs/rfc4256.txt
----------------------------------------------------------------------
diff --git a/sshd-core/src/docs/rfc4256.txt b/sshd-core/src/docs/rfc4256.txt
deleted file mode 100644
index 44f1758..0000000
--- a/sshd-core/src/docs/rfc4256.txt
+++ /dev/null
@@ -1,675 +0,0 @@
-
-
-
-
-
-
-Network Working Group F. Cusack
-Request for Comments: 4256 savecore.net
-Category: Standards Track M. Forssen
- AppGate Network Security AB
- January 2006
-
-
- Generic Message Exchange Authentication for
- the Secure Shell Protocol (SSH)
-
-Status of This Memo
-
- This document specifies an Internet standards track protocol for the
- Internet community, and requests discussion and suggestions for
- improvements. Please refer to the current edition of the "Internet
- Official Protocol Standards" (STD 1) for the standardization state
- and status of this protocol. Distribution of this memo is unlimited.
-
-Copyright Notice
-
- Copyright (C) The Internet Society (2006).
-
-Abstract
-
- The Secure Shell Protocol (SSH) is a protocol for secure remote login
- and other secure network services over an insecure network. This
- document describes a general purpose authentication method for the
- SSH protocol, suitable for interactive authentications where the
- authentication data should be entered via a keyboard (or equivalent
- alphanumeric input device). The major goal of this method is to
- allow the SSH client to support a whole class of authentication
- mechanism(s) without knowing the specifics of the actual
- authentication mechanism(s).
-
-1. Introduction
-
- The SSH authentication protocol [SSH-USERAUTH] is a general-purpose
- user authentication protocol. It is intended to be run over the SSH
- transport layer protocol [SSH-TRANS]. The authentication protocol
- assumes that the underlying protocols provide integrity and
- confidentiality protection.
-
- This document describes a general purpose authentication method for
- the SSH authentication protocol. This method is suitable for
- interactive authentication methods that do not need any special
- software support on the client side. Instead, all authentication
- data should be entered via the keyboard. The major goal of this
- method is to allow the SSH client to have little or no knowledge of
-
-
-
-Cusack & Forssen Standards Track [Page 1]
-
-RFC 4256 SSH Generic Interactive Authentication January 2006
-
-
- the specifics of the underlying authentication mechanism(s) used by
- the SSH server. This will allow the server to arbitrarily select or
- change the underlying authentication mechanism(s) without having to
- update client code.
-
- The name for this authentication method is "keyboard-interactive".
-
- This document should be read only after reading the SSH architecture
- document [SSH-ARCH] and the SSH authentication document
- [SSH-USERAUTH]. This document freely uses terminology and notation
- from both documents without reference or further explanation.
-
- This document also describes some of the client interaction with the
- user in obtaining the authentication information. While this is
- somewhat out of the scope of a protocol specification, it is
- described here anyway because some aspects of the protocol are
- specifically designed based on user interface issues, and omitting
- this information may lead to incompatible or awkward implementations.
-
- The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
- "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
- document are to be interpreted as described in [RFC-2119].
-
-2. Rationale
-
- Currently defined authentication methods for SSH are tightly coupled
- with the underlying authentication mechanism. This makes it
- difficult to add new mechanisms for authentication as all clients
- must be updated to support the new mechanism. With the generic
- method defined here, clients will not require code changes to support
- new authentication mechanisms, and if a separate authentication layer
- is used, such as [PAM], then the server may not need any code changes
- either.
-
- This presents a significant advantage to other methods, such as the
- "password" method (defined in [SSH-USERAUTH]), as new (presumably
- stronger) methods may be added "at will" and system security can be
- transparently enhanced.
-
- Challenge-response and One Time Password mechanisms are also easily
- supported with this authentication method.
-
- However, this authentication method is limited to authentication
- mechanisms that do not require any special code, such as hardware
- drivers or password mangling, on the client.
-
-
-
-
-
-
-Cusack & Forssen Standards Track [Page 2]
-
-RFC 4256 SSH Generic Interactive Authentication January 2006
-
-
-3. Protocol Exchanges
-
- The client initiates the authentication with an
- SSH_MSG_USERAUTH_REQUEST message. The server then requests
- authentication information from the client with an
- SSH_MSG_USERAUTH_INFO_REQUEST message. The client obtains the
- information from the user and then responds with an
- SSM_MSG_USERAUTH_INFO_RESPONSE message. The server MUST NOT send
- another SSH_MSG_USERAUTH_INFO_REQUEST before it has received the
- answer from the client.
-
-3.1. Initial Exchange
-
- The authentication starts with the client sending the following
- packet:
-
- byte SSH_MSG_USERAUTH_REQUEST
- string user name (ISO-10646 UTF-8, as defined in [RFC-3629])
- string service name (US-ASCII)
- string "keyboard-interactive" (US-ASCII)
- string language tag (as defined in [RFC-3066])
- string submethods (ISO-10646 UTF-8)
-
- The language tag is deprecated and SHOULD be the empty string. It
- may be removed in a future revision of this specification. Instead,
- the server SHOULD select the language to be used based on the tags
- communicated during key exchange [SSH-TRANS].
-
- If the language tag is not the empty string, the server SHOULD use
- the specified language for any messages sent to the client as part of
- this protocol. The language tag SHOULD NOT be used for language
- selection for messages outside of this protocol. If the server does
- not support the requested language, the language to be used is
- implementation-dependent.
-
- The submethods field is included so the user can give a hint of which
- actual methods he wants to use. It is a comma-separated list of
- authentication submethods (software or hardware) that the user
- prefers. If the client has knowledge of the submethods preferred by
- the user, presumably through a configuration setting, it MAY use the
- submethods field to pass this information to the server. Otherwise,
- it MUST send the empty string.
-
- The actual names of the submethods is something the user and the
- server need to agree upon.
-
- Server interpretation of the submethods field is implementation-
- dependent.
-
-
-
-Cusack & Forssen Standards Track [Page 3]
-
-RFC 4256 SSH Generic Interactive Authentication January 2006
-
-
- One possible implementation strategy of the submethods field on the
- server is that, unless the user may use multiple different
- submethods, the server ignores this field. If the user may
- authenticate using one of several different submethods, the server
- should treat the submethods field as a hint on which submethod the
- user wants to use this time.
-
- Note that when this message is sent to the server, the client has not
- yet prompted the user for a password, and so that information is NOT
- included with this initial message (unlike the "password" method).
-
- The server MUST reply with an SSH_MSG_USERAUTH_SUCCESS,
- SSH_MSG_USERAUTH_FAILURE, or SSH_MSG_USERAUTH_INFO_REQUEST message.
-
- The server SHOULD NOT reply with the SSH_MSG_USERAUTH_FAILURE message
- if the failure is based on the user name or service name; instead, it
- SHOULD send SSH_MSG_USERAUTH_INFO_REQUEST message(s), which look just
- like the one(s) that would have been sent in cases where
- authentication should proceed, and then send the failure message
- (after a suitable delay, as described below). The goal is to make it
- impossible to find valid usernames by comparing the results when
- authenticating as different users.
-
- The server MAY reply with an SSH_MSG_USERAUTH_SUCCESS message if no
- authentication is required for the user in question. However, a
- better approach, for reasons discussed above, might be to reply with
- an SSH_MSG_USERAUTH_INFO_REQUEST message and ignore (don't validate)
- the response.
-
-3.2. Information Requests
-
- Requests are generated from the server using the
- SSH_MSG_USERAUTH_INFO_REQUEST message.
-
- The server may send as many requests as are necessary to authenticate
- the client; the client MUST be prepared to handle multiple exchanges.
- However, the server MUST NOT ever have more than one
- SSH_MSG_USERAUTH_INFO_REQUEST message outstanding. That is, it may
- not send another request before the client has answered.
-
-
-
-
-
-
-
-
-
-
-
-
-Cusack & Forssen Standards Track [Page 4]
-
-RFC 4256 SSH Generic Interactive Authentication January 2006
-
-
- The SSH_MSG_USERAUTH_INFO_REQUEST message is defined as follows:
-
- byte SSH_MSG_USERAUTH_INFO_REQUEST
- string name (ISO-10646 UTF-8)
- string instruction (ISO-10646 UTF-8)
- string language tag (as defined in [RFC-3066])
- int num-prompts
- string prompt[1] (ISO-10646 UTF-8)
- boolean echo[1]
- ...
- string prompt[num-prompts] (ISO-10646 UTF-8)
- boolean echo[num-prompts]
-
- The language tag is deprecated and SHOULD be the empty string. It
- may be removed in a future revision of this specification. Instead,
- the server SHOULD select the language used based on the tags
- communicated during key exchange [SSH-TRANS].
-
- If the language tag is not the empty string, the server SHOULD use
- the specified language for any messages sent to the client as part of
- this protocol. The language tag SHOULD NOT be used for language
- selection for messages outside of this protocol. If the server does
- not support the requested language, the language to be used is
- implementation-dependent.
-
- The server SHOULD take into consideration that some clients may not
- be able to properly display a long name or prompt field (see next
- section), and limit the lengths of those fields if possible. For
- example, instead of an instruction field of "Enter Password" and a
- prompt field of "Password for user23@host.domain: ", a better choice
- might be an instruction field of "Password authentication for
- user23@host.domain" and a prompt field of "Password: ". It is
- expected that this authentication method would typically be backended
- by [PAM] and so such choices would not be possible.
-
- The name and instruction fields MAY be empty strings; the client MUST
- be prepared to handle this correctly. The prompt field(s) MUST NOT
- be empty strings.
-
- The num-prompts field may be `0', in which case there will be no
- prompt/echo fields in the message, but the client SHOULD still
- display the name and instruction fields (as described below).
-
-
-
-
-
-
-
-
-
-Cusack & Forssen Standards Track [Page 5]
-
-RFC 4256 SSH Generic Interactive Authentication January 2006
-
-
-3.3. User Interface
-
- Upon receiving a request message, the client SHOULD prompt the user
- as follows:
-
- A command line interface (CLI) client SHOULD print the name and
- instruction (if non-empty), adding newlines. Then, for each prompt
- in turn, the client SHOULD display the prompt and read the user
- input.
-
- A graphical user interface (GUI) client has many choices on how to
- prompt the user. One possibility is to use the name field (possibly
- prefixed with the application's name) as the title of a dialog window
- in which the prompt(s) are presented. In that dialog window, the
- instruction field would be a text message, and the prompts would be
- labels for text entry fields. All fields SHOULD be presented to the
- user. For example, an implementation SHOULD NOT discard the name
- field because its windows lack titles; instead, it SHOULD find
- another way to display this information. If prompts are presented in
- a dialog window, then the client SHOULD NOT present each prompt in a
- separate window.
-
- All clients MUST properly handle an instruction field with embedded
- newlines. They SHOULD also be able to display at least 30 characters
- for the name and prompts. If the server presents names or prompts
- longer than 30 characters, the client MAY truncate these fields to
- the length it can display. If the client does truncate any fields,
- there MUST be an obvious indication that such truncation has
- occurred. The instruction field SHOULD NOT be truncated.
-
- Clients SHOULD use control character filtering, as discussed in
- [SSH-ARCH], to avoid attacks by including terminal control characters
- in the fields to be displayed.
-
- For each prompt, the corresponding echo field indicates whether the
- user input should be echoed as characters are typed. Clients SHOULD
- correctly echo/mask user input for each prompt independently of other
- prompts in the request message. If a client does not honor the echo
- field for whatever reason, then the client MUST err on the side of
- masking input. A GUI client might like to have a checkbox toggling
- echo/mask. Clients SHOULD NOT add any additional characters to the
- prompt, such as ": " (colon-space); the server is responsible for
- supplying all text to be displayed to the user. Clients MUST also
- accept empty responses from the user and pass them on as empty
- strings.
-
-
-
-
-
-
-Cusack & Forssen Standards Track [Page 6]
-
-RFC 4256 SSH Generic Interactive Authentication January 2006
-
-
-3.4. Information Responses
-
- After obtaining the requested information from the user, the client
- MUST respond with an SSH_MSG_USERAUTH_INFO_RESPONSE message.
-
- The format of the SSH_MSG_USERAUTH_INFO_RESPONSE message is as
- follows:
-
- byte SSH_MSG_USERAUTH_INFO_RESPONSE
- int num-responses
- string response[1] (ISO-10646 UTF-8)
- ...
- string response[num-responses] (ISO-10646 UTF-8)
-
- Note that the responses are encoded in ISO-10646 UTF-8. It is up to
- the server how it interprets the responses and validates them.
- However, if the client reads the responses in some other encoding
- (e.g., ISO 8859-1), it MUST convert the responses to ISO-10646 UTF-8
- before transmitting.
-
- From an internationalization standpoint, it is desired that if a user
- enters responses, the authentication process will work regardless of
- what OS and client software they are using. Doing so requires
- normalization. Systems supporting non-ASCII passwords SHOULD always
- normalize passwords and usernames whenever they are added to the
- database, or compare them (with or without hashing) to existing
- entries in the database. SSH implementations that both store the
- passwords and compare them SHOULD use [SASLPREP] for normalization.
-
- If the num-responses field does not match the num-prompts field in
- the request message, the server MUST send a failure message.
-
- In the case that the server sends a `0' num-prompts field in the
- request message, the client MUST send a response message with a `0'
- num-responses field to complete the exchange.
-
- The responses MUST be ordered as the prompts were ordered. That is,
- response[n] MUST be the answer to prompt[n].
-
- After receiving the response, the server MUST send either an
- SSH_MSG_USERAUTH_SUCCESS, SSH_MSG_USERAUTH_FAILURE, or another
- SSH_MSG_USERAUTH_INFO_REQUEST message.
-
- If the server fails to authenticate the user (through the underlying
- authentication mechanism(s)), it SHOULD NOT send another request
- message(s) in an attempt to obtain new authentication data; instead,
- it SHOULD send a failure message. The only time the server should
- send multiple request messages is if additional authentication data
-
-
-
-Cusack & Forssen Standards Track [Page 7]
-
-RFC 4256 SSH Generic Interactive Authentication January 2006
-
-
- is needed (i.e., because there are multiple underlying authentication
- mechanisms that must be used to authenticate the user).
-
- If the server intends to respond with a failure message, it MAY delay
- for an implementation-dependent time before sending it to the client.
- It is suspected that implementations are likely to make the time
- delay configurable; a suggested default is 2 seconds.
-
-4. Authentication Examples
-
- Here are two example exchanges between a client and server. The
- first is an example of challenge/response with a handheld token.
- This is an authentication that is not otherwise possible with other
- authentication methods.
-
- C: byte SSH_MSG_USERAUTH_REQUEST
- C: string "user23"
- C: string "ssh-userauth"
- C: string "keyboard-interactive"
- C: string ""
- C: string ""
-
- S: byte SSH_MSG_USERAUTH_INFO_REQUEST
- S: string "CRYPTOCard Authentication"
- S: string "The challenge is '14315716'"
- S: string "en-US"
- S: int 1
- S: string "Response: "
- S: boolean TRUE
-
- [Client prompts user for password]
-
- C: byte SSH_MSG_USERAUTH_INFO_RESPONSE
- C: int 1
- C: string "6d757575"
-
- S: byte SSH_MSG_USERAUTH_SUCCESS
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Cusack & Forssen Standards Track [Page 8]
-
-RFC 4256 SSH Generic Interactive Authentication January 2006
-
-
- The second example is a standard password authentication; in this
- case, the user's password is expired.
-
- C: byte SSH_MSG_USERAUTH_REQUEST
- C: string "user23"
- C: string "ssh-userauth"
- C: string "keyboard-interactive"
- C: string "en-US"
- C: string ""
-
- S: byte SSH_MSG_USERAUTH_INFO_REQUEST
- S: string "Password Authentication"
- S: string ""
- S: string "en-US"
- S: int 1
- S: string "Password: "
- S: boolean FALSE
-
- [Client prompts user for password]
-
- C: byte SSH_MSG_USERAUTH_INFO_RESPONSE
- C: int 1
- C: string "password"
-
- S: byte SSH_MSG_USERAUTH_INFO_REQUEST
- S: string "Password Expired"
- S: string "Your password has expired."
- S: string "en-US"
- S: int 2
- S: string "Enter new password: "
- S: boolean FALSE
- S: string "Enter it again: "
- S: boolean FALSE
-
- [Client prompts user for new password]
-
- C: byte SSH_MSG_USERAUTH_INFO_RESPONSE
- C: int 2
- C: string "newpass"
- C: string "newpass"
-
- S: byte SSH_MSG_USERAUTH_INFO_REQUEST
- S: string "Password changed"
- S: string "Password successfully changed for user23."
- S: string "en-US"
- S: int 0
-
-
-
-
-
-Cusack & Forssen Standards Track [Page 9]
-
-RFC 4256 SSH Generic Interactive Authentication January 2006
-
-
- [Client displays message to user]
-
- C: byte SSH_MSG_USERAUTH_INFO_RESPONSE
- C: int 0
-
- S: byte SSH_MSG_USERAUTH_SUCCESS
-
-5. IANA Considerations
-
- The userauth type "keyboard-interactive" is used for this
- authentication method.
-
- The following method-specific constants are used with this
- authentication method:
-
- SSH_MSG_USERAUTH_INFO_REQUEST 60
- SSH_MSG_USERAUTH_INFO_RESPONSE 61
-
-6. Security Considerations
-
- The authentication protocol and this authentication method depend on
- the security of the underlying SSH transport layer. Without the
- confidentiality provided therein, any authentication data passed with
- this method is subject to interception.
-
- The number of client-server exchanges required to complete an
- authentication using this method may be variable. It is possible
- that an observer may gain valuable information simply by counting
- that number. For example, an observer may guess that a user's
- password has expired, and with further observation may be able to
- determine the password lifetime imposed by a site's password
- expiration policy.
-
-7. References
-
-7.1. Normative References
-
- [RFC-2119] Bradner, S., "Key words for use in RFCs to Indicate
- Requirement Levels", BCP 14, RFC 2119, March 1997.
-
- [RFC-3629] Yergeau, F., "UTF-8, a transformation format of ISO
- 10646", STD 63, RFC 3629, November 2003.
-
- [RFC-3066] Alvestrand, H., "Tags for the Identification of
- Languages", BCP 47, RFC 3066, January 2001.
-
-
-
-
-
-
-Cusack & Forssen Standards Track [Page 10]
-
-RFC 4256 SSH Generic Interactive Authentication January 2006
-
-
- [SSH-ARCH] Ylonen, T. and C. Lonvick, Ed., "The Secure Shell
- (SSH) Protocol Architecture", RFC 4251, January 2006.
-
- [SSH-USERAUTH] Ylonen, T. and C. Lonvick, Ed., "The Secure Shell
- (SSH) Authentication Protocol", RFC 4252, January
- 2006.
-
- [SSH-TRANS] Ylonen, T. and C. Lonvick, Ed., "The Secure Shell
- (SSH) Transport Layer Protocol", RFC 4253, January
- 2006.
-
- [SASLPREP] Zeilenga, K., "SASLprep: Stringprep Profile for User
- Names and Passwords", RFC 4013, February 2005.
-
-7.2. Informative References
-
- [PAM] Samar, V., Schemers, R., "Unified Login With
- Pluggable Authentication Modules (PAM)", OSF RFC
- 86.0, October 1995.
-
-Authors' Addresses
-
- Frank Cusack
- savecore.net
-
- EMail: frank@savecore.net
-
-
- Martin Forssen
- AppGate Network Security AB
- Otterhallegatan 2
- SE-411 18 Gothenburg
- SWEDEN
-
- EMail: maf@appgate.com
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Cusack & Forssen Standards Track [Page 11]
-
-RFC 4256 SSH Generic Interactive Authentication January 2006
-
-
-Full Copyright Statement
-
- Copyright (C) The Internet Society (2006).
-
- This document is subject to the rights, licenses and restrictions
- contained in BCP 78, and except as set forth therein, the authors
- retain all their rights.
-
- This document and the information contained herein are provided on an
- "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
- OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
- ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
- INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
- INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
- WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
-
-Intellectual Property
-
- The IETF takes no position regarding the validity or scope of any
- Intellectual Property Rights or other rights that might be claimed to
- pertain to the implementation or use of the technology described in
- this document or the extent to which any license under such rights
- might or might not be available; nor does it represent that it has
- made any independent effort to identify any such rights. Information
- on the procedures with respect to rights in RFC documents can be
- found in BCP 78 and BCP 79.
-
- Copies of IPR disclosures made to the IETF Secretariat and any
- assurances of licenses to be made available, or the result of an
- attempt made to obtain a general license or permission for the use of
- such proprietary rights by implementers or users of this
- specification can be obtained from the IETF on-line IPR repository at
- http://www.ietf.org/ipr.
-
- The IETF invites any interested party to bring to its attention any
- copyrights, patents or patent applications, or other proprietary
- rights that may cover technology that may be required to implement
- this standard. Please address the information to the IETF at
- ietf-ipr@ietf.org.
-
-Acknowledgement
-
- Funding for the RFC Editor function is provided by the IETF
- Administrative Support Activity (IASA).
-
-
-
-
-
-
-
-Cusack & Forssen Standards Track [Page 12]
-
http://git-wip-us.apache.org/repos/asf/mina-sshd/blob/46ea0930/sshd-core/src/docs/rfc4345.txt
----------------------------------------------------------------------
diff --git a/sshd-core/src/docs/rfc4345.txt b/sshd-core/src/docs/rfc4345.txt
deleted file mode 100644
index 6b764a1..0000000
--- a/sshd-core/src/docs/rfc4345.txt
+++ /dev/null
@@ -1,283 +0,0 @@
-
-
-
-
-
-
-Network Working Group B. Harris
-Request for Comments: 4345 January 2006
-Category: Standards Track
-
-
- Improved Arcfour Modes for
- the Secure Shell (SSH) Transport Layer Protocol
-
-Status of This Memo
-
- This document specifies an Internet standards track protocol for the
- Internet community, and requests discussion and suggestions for
- improvements. Please refer to the current edition of the "Internet
- Official Protocol Standards" (STD 1) for the standardization state
- and status of this protocol. Distribution of this memo is unlimited.
-
-Copyright Notice
-
- Copyright (C) The Internet Society (2006).
-
-Abstract
-
- This document specifies methods of using the Arcfour cipher in the
- Secure Shell (SSH) protocol that mitigate the weakness of the
- cipher's key-scheduling algorithm.
-
-1. Introduction
-
- Secure Shell (SSH) [RFC4251] is a secure remote-login protocol. It
- allows for the use of an extensible variety of symmetric cipher
- algorithms to provide confidentiality for data in transit. One of
- the algorithms specified in the base protocol is "arcfour", which
- specifies the use of Arcfour (also known as RC4), a fast stream
- cipher. As [RFC4253] says, though, "Arcfour (and RC4) has problems
- with weak keys, and should be used with caution." These problems are
- described in more detail in [MANTIN01], along with a recommendation
- to discard the first 1536 bytes of keystream so as to ensure that the
- cipher's internal state is thoroughly mixed. This document specifies
- new cipher algorithms for SSH that follow this recommendation.
-
-2. Conventions Used in this Document
-
- The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
- "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
- document are to be interpreted as described in [RFC2119].
-
-
-
-
-
-
-Harris Standards Track [Page 1]
-
-RFC 4345 Improved Arcfour Modes for SSH January 2006
-
-
-3. Applicability Statement
-
- Implementations of Arcfour are typically slightly faster and much
- smaller than those of any other encryption algorithm currently
- defined for SSH. This must be balanced, though, against the known
- security problems with Arcfour described in Section 5. In most
- cases, where speed and code size are not critical issues, the
- algorithms specified by [RFC4344] should be used instead.
-
-4. Algorithm Definitions
-
- The "arcfour128" algorithm is the RC4 cipher, as described in
- [SCHNEIER], using a 128-bit key. The first 1536 bytes of keystream
- generated by the cipher MUST be discarded, and the first byte of the
- first encrypted packet MUST be encrypted using the 1537th byte of
- keystream.
-
- The "arcfour256" algorithm is the same, but uses a 256-bit key.
-
-5. Security Considerations
-
- The security considerations in [RFC4251] apply.
-
- The discarded bytes of keystream MUST be kept secret and MUST NOT be
- transmitted over the network. The contents of these bytes could
- reveal information about the key.
-
- There are two classes of attack on Arcfour described in [MIRONOV].
- Strong distinguishers distinguish an Arcfour keystream from
- randomness at the start of the stream and are defended against by the
- algorithm defined in this document. Weak distinguishers can operate
- on any part of the keystream, and the best ones, described in [FMcG]
- and [MANTIN05], can use data from multiple, different keystreams. A
- consequence of this is that encrypting the same data (for instance, a
- password) sufficiently many times in separate Arcfour keystreams can
- be sufficient to leak information about it to an adversary. It is
- thus RECOMMENDED that Arcfour (either in the form described here or
- that described in [RFC4251]) not be used for high-volume password-
- authenticated connections.
-
-6. IANA Considerations
-
- The IANA has assigned the Encryption Algorithm Names "arcfour128" and
- "arcfour256" in accordance with [RFC4250].
-
-
-
-
-
-
-
-Harris Standards Track [Page 2]
-
-RFC 4345 Improved Arcfour Modes for SSH January 2006
-
-
-7. References
-
-7.1. Normative References
-
- [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
- Requirement Levels", BCP 14, RFC 2119, March 1997.
-
- [RFC4250] Lehtinen, S. and C. Lonvick, Ed., "The Secure Shell (SSH)
- Protocol Assigned Numbers", RFC 4250, January 2006.
-
- [RFC4251] Ylonen, T. and C. Lonvick, Ed., "The Secure Shell (SSH)
- Protocol Architecture", RFC 4251, January 2006.
-
- [RFC4253] Ylonen, T. and C. Lonvick, Ed., "The Secure Shell (SSH)
- Transport Layer Protocol", RFC 4253, January 2006
-
- [RFC4344] Bellare, M., Kohno, T., and C. Namprempre, "The Secure
- Shell (SSH) Transport Layer Encryption Modes", RFC 4344,
- January 2006.
-
- [SCHNEIER] Schneier, B., "Applied Cryptography Second Edition:
- protocols algorithms and source in code in C", John Wiley
- and Sons, New York, NY, 1996.
-
-7.2. Informative References
-
- [FMcG] Fluhrer, S. and D. McGrew, "Statistical Analysis of the
- Alleged RC4 Keystream Generator", Fast Software
- Encryption: 7th International Workshop, FSE 2000, April
- 2000, <http://www.mindspring.com/~dmcgrew/rc4-03.pdf>.
-
- [MANTIN01] Mantin, I., "Analysis of the Stream Cipher RC4", M.Sc.
- Thesis, Weizmann Institute of Science, 2001, <http://
- www.wisdom.weizmann.ac.il/~itsik/RC4/Papers/Mantin1.zip>.
-
- [MIRONOV] Mironov, I., "(Not So) Random Shuffles of RC4", Advances
- in Cryptology -- CRYPTO 2002: 22nd Annual International
- Cryptology Conference, August 2002,
- <http://eprint.iacr.org/2002/067.pdf>.
-
- [MANTIN05] Mantin, I., "Predicting and Distinguishing Attacks on RC4
- Keystream Generator", Advances in Cryptology -- EUROCRYPT
- 2005: 24th Annual International Conference on the Theory
- and Applications of Cryptographic Techniques, May 2005.
-
-
-
-
-
-
-
-Harris Standards Track [Page 3]
-
-RFC 4345 Improved Arcfour Modes for SSH January 2006
-
-
-Author's Address
-
- Ben Harris
- 2a Eachard Road
- CAMBRIDGE
- CB3 0HY
- UNITED KINGDOM
-
- EMail: bjh21@bjh21.me.uk
-
-Trademark Notice
-
- "RC4" and "SSH" are registered trademarks in the United States.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Harris Standards Track [Page 4]
-
-RFC 4345 Improved Arcfour Modes for SSH January 2006
-
-
-Full Copyright Statement
-
- Copyright (C) The Internet Society (2006).
-
- This document is subject to the rights, licenses and restrictions
- contained in BCP 78, and except as set forth therein, the authors
- retain all their rights.
-
- This document and the information contained herein are provided on an
- "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
- OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
- ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
- INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
- INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
- WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
-
-Intellectual Property
-
- The IETF takes no position regarding the validity or scope of any
- Intellectual Property Rights or other rights that might be claimed to
- pertain to the implementation or use of the technology described in
- this document or the extent to which any license under such rights
- might or might not be available; nor does it represent that it has
- made any independent effort to identify any such rights. Information
- on the procedures with respect to rights in RFC documents can be
- found in BCP 78 and BCP 79.
-
- Copies of IPR disclosures made to the IETF Secretariat and any
- assurances of licenses to be made available, or the result of an
- attempt made to obtain a general license or permission for the use of
- such proprietary rights by implementers or users of this
- specification can be obtained from the IETF on-line IPR repository at
- http://www.ietf.org/ipr.
-
- The IETF invites any interested party to bring to its attention any
- copyrights, patents or patent applications, or other proprietary
- rights that may cover technology that may be required to implement
- this standard. Please address the information to the IETF at
- ietf-ipr@ietf.org.
-
-Acknowledgement
-
- Funding for the RFC Editor function is provided by the IETF
- Administrative Support Activity (IASA).
-
-
-
-
-
-
-
-Harris Standards Track [Page 5]
-
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/mina-sshd/blob/46ea0930/sshd-core/src/docs/rfc4419.txt
----------------------------------------------------------------------
diff --git a/sshd-core/src/docs/rfc4419.txt b/sshd-core/src/docs/rfc4419.txt
deleted file mode 100644
index 87f9af7..0000000
--- a/sshd-core/src/docs/rfc4419.txt
+++ /dev/null
@@ -1,563 +0,0 @@
-
-
-
-
-
-
-Network Working Group M. Friedl
-Request for Comments: 4419 N. Provos
-Category: Standards Track W. Simpson
- March 2006
-
-
- Diffie-Hellman Group Exchange for
- the Secure Shell (SSH) Transport Layer Protocol
-
-Status of This Memo
-
- This document specifies an Internet standards track protocol for the
- Internet community, and requests discussion and suggestions for
- improvements. Please refer to the current edition of the "Internet
- Official Protocol Standards" (STD 1) for the standardization state
- and status of this protocol. Distribution of this memo is unlimited.
-
-Copyright Notice
-
- Copyright (C) The Internet Society (2006).
-
-Abstract
-
- This memo describes a new key exchange method for the Secure Shell
- (SSH) protocol. It allows the SSH server to propose new groups on
- which to perform the Diffie-Hellman key exchange to the client. The
- proposed groups need not be fixed and can change with time.
-
-1. Overview and Rationale
-
- SSH [RFC4251] is a very common protocol for secure remote login on
- the Internet. Currently, SSH performs the initial key exchange using
- the "diffie-hellman-group1-sha1" method [RFC4253]. This method
- prescribes a fixed group on which all operations are performed.
-
- The Diffie-Hellman key exchange provides a shared secret that cannot
- be determined by either party alone. Furthermore, the shared secret
- is known only to the participant parties. In SSH, the key exchange
- is signed with the host key to provide host authentication.
-
- The security of the Diffie-Hellman key exchange is based on the
- difficulty of solving the Discrete Logarithm Problem (DLP). Since we
- expect that the SSH protocol will be in use for many years in the
- future, we fear that extensive precomputation and more efficient
- algorithms to compute the discrete logarithm over a fixed group might
- pose a security threat to the SSH protocol.
-
-
-
-
-
-Friedl, et al. Standards Track [Page 1]
-
-RFC 4419 SSH DH Group Exchange March 2006
-
-
- The ability to propose new groups will reduce the incentive to use
- precomputation for more efficient calculation of the discrete
- logarithm. The server can constantly compute new groups in the
- background.
-
-2. Requirements Notation
-
- The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
- "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
- document are to be interpreted as described in [RFC2119].
-
-3. Diffie-Hellman Group and Key Exchange
-
- The server keeps a list of safe primes and corresponding generators
- that it can select from. A prime p is safe if p = 2q + 1 and q is
- prime. New primes can be generated in the background.
-
- The generator g should be chosen such that the order of the generated
- subgroup does not factor into small primes; that is, with p = 2q + 1,
- the order has to be either q or p - 1. If the order is p - 1, then
- the exponents generate all possible public values, evenly distributed
- throughout the range of the modulus p, without cycling through a
- smaller subset. Such a generator is called a "primitive root" (which
- is trivial to find when p is "safe").
-
- The client requests a modulus from the server indicating the
- preferred size. In the following description (C is the client, S is
- the server, the modulus p is a large safe prime, and g is a generator
- for a subgroup of GF(p), min is the minimal size of p in bits that is
- acceptable to the client, n is the size of the modulus p in bits that
- the client would like to receive from the server, max is the maximal
- size of p in bits that the client can accept, V_S is S's version
- string, V_C is C's version string, K_S is S's public host key, I_C is
- C's KEXINIT message, and I_S is S's KEXINIT message that has been
- exchanged before this part begins):
-
- 1. C sends "min || n || max" to S, indicating the minimal acceptable
- group size, the preferred size of the group, and the maximal
- group size in bits the client will accept.
-
- 2. S finds a group that best matches the client's request, and sends
- "p || g" to C.
-
- 3. C generates a random number x, where 1 < x < (p-1)/2. It
- computes e = g^x mod p, and sends "e" to S.
-
-
-
-
-
-
-Friedl, et al. Standards Track [Page 2]
-
-RFC 4419 SSH DH Group Exchange March 2006
-
-
- 4. S generates a random number y, where 0 < y < (p-1)/2, and
- computes f = g^y mod p. S receives "e". It computes K = e^y mod
- p, H = hash(V_C || V_S || I_C || I_S || K_S || min || n || max ||
- p || g || e || f || K) (these elements are encoded according to
- their types; see below), and signature s on H with its private
- host key. S sends "K_S || f || s" to C. The signing operation
- may involve a second hashing operation.
-
- 5. C verifies that K_S really is the host key for S (e.g., using
- certificates or a local database to obtain the public key). C is
- also allowed to accept the key without verification; however,
- doing so will render the protocol insecure against active attacks
- (but may be desirable for practical reasons in the short term in
- many environments). C then computes K = f^x mod p, H = hash(V_C
- || V_S || I_C || I_S || K_S || min || n || max || p || g || e ||
- f || K), and verifies the signature s on H.
-
- Servers and clients SHOULD support groups with a modulus length of k
- bits, where 1024 <= k <= 8192. The recommended values for min and
- max are 1024 and 8192, respectively.
-
- Either side MUST NOT send or accept e or f values that are not in the
- range [1, p-1]. If this condition is violated, the key exchange
- fails. To prevent confinement attacks, they MUST accept the shared
- secret K only if 1 < K < p - 1.
-
- The server should return the smallest group it knows that is larger
- than the size the client requested. If the server does not know a
- group that is larger than the client request, then it SHOULD return
- the largest group it knows. In all cases, the size of the returned
- group SHOULD be at least 1024 bits.
-
- This is implemented with the following messages. The hash algorithm
- for computing the exchange hash is defined by the method name, and is
- called HASH. The public key algorithm for signing is negotiated with
- the KEXINIT messages.
-
- First, the client sends:
-
- byte SSH_MSG_KEY_DH_GEX_REQUEST
- uint32 min, minimal size in bits of an acceptable group
- uint32 n, preferred size in bits of the group the server will send
- uint32 max, maximal size in bits of an acceptable group
-
-
-
-
-
-
-
-
-Friedl, et al. Standards Track [Page 3]
-
-RFC 4419 SSH DH Group Exchange March 2006
-
-
- The server responds with
-
- byte SSH_MSG_KEX_DH_GEX_GROUP
- mpint p, safe prime
- mpint g, generator for subgroup in GF(p)
-
- The client responds with:
-
- byte SSH_MSG_KEX_DH_GEX_INIT
- mpint e
-
- The server responds with:
-
- byte SSH_MSG_KEX_DH_GEX_REPLY
- string server public host key and certificates (K_S)
- mpint f
- string signature of H
-
- The hash H is computed as the HASH hash of the concatenation of the
- following:
-
- string V_C, the client's version string (CR and NL excluded)
- string V_S, the server's version string (CR and NL excluded)
- string I_C, the payload of the client's SSH_MSG_KEXINIT
- string I_S, the payload of the server's SSH_MSG_KEXINIT
- string K_S, the host key
- uint32 min, minimal size in bits of an acceptable group
- uint32 n, preferred size in bits of the group the server will send
- uint32 max, maximal size in bits of an acceptable group
- mpint p, safe prime
- mpint g, generator for subgroup
- mpint e, exchange value sent by the client
- mpint f, exchange value sent by the server
- mpint K, the shared secret
-
- This value is called the exchange hash, and it is used to
- authenticate the key exchange as per [RFC4253].
-
-4. Key Exchange Methods
-
- This document defines two new key exchange methods:
- "diffie-hellman-group-exchange-sha1" and
- "diffie-hellman-group-exchange-sha256".
-
-
-
-
-
-
-
-
-Friedl, et al. Standards Track [Page 4]
-
-RFC 4419 SSH DH Group Exchange March 2006
-
-
-4.1. diffie-hellman-group-exchange-sha1
-
- The "diffie-hellman-group-exchange-sha1" method specifies
- Diffie-Hellman Group and Key Exchange with SHA-1 [FIPS-180-2] as
- HASH.
-
-4.2. diffie-hellman-group-exchange-sha256
-
- The "diffie-hellman-group-exchange-sha256" method specifies
- Diffie-Hellman Group and Key Exchange with SHA-256 [FIPS-180-2] as
- HASH.
-
- Note that the hash used in key exchange (in this case, SHA-256) must
- also be used in the key derivation pseudo-random function (PRF), as
- per the requirement in the "Output from Key Exchange" section in
- [RFC4253].
-
-5. Summary of Message Numbers
-
- The following message numbers have been defined in this document.
- They are in a name space private to this document and not assigned by
- IANA.
-
- #define SSH_MSG_KEX_DH_GEX_REQUEST_OLD 30
- #define SSH_MSG_KEX_DH_GEX_REQUEST 34
- #define SSH_MSG_KEX_DH_GEX_GROUP 31
- #define SSH_MSG_KEX_DH_GEX_INIT 32
- #define SSH_MSG_KEX_DH_GEX_REPLY 33
-
- SSH_MSG_KEX_DH_GEX_REQUEST_OLD is used for backward compatibility.
- Instead of sending "min || n || max", the client only sends "n". In
- addition, the hash is calculated using only "n" instead of "min || n
- || max".
-
- The numbers 30-49 are key exchange specific and may be redefined by
- other kex methods.
-
-6. Implementation Notes
-
-6.1. Choice of Generator
-
- One useful technique is to select the generator, and then limit the
- modulus selection sieve to primes with that generator:
-
- 2 when p (mod 24) = 11.
- 5 when p (mod 10) = 3 or 7.
-
-
-
-
-
-Friedl, et al. Standards Track [Page 5]
-
-RFC 4419 SSH DH Group Exchange March 2006
-
-
- It is recommended to use 2 as generator, because it improves
- efficiency in multiplication performance. It is usable even when it
- is not a primitive root, as it still covers half of the space of
- possible residues.
-
-6.2. Private Exponents
-
- To increase the speed of the key exchange, both client and server may
- reduce the size of their private exponents. It should be at least
- twice as long as the key material that is generated from the shared
- secret. For more details, see the paper by van Oorschot and Wiener
- [VAN-OORSCHOT].
-
-7. Security Considerations
-
- This protocol aims to be simple and uses only well-understood
- primitives. This encourages acceptance by the community and allows
- for ease of implementation, which hopefully leads to a more secure
- system.
-
- The use of multiple moduli inhibits a determined attacker from
- precalculating moduli exchange values, and discourages dedication of
- resources for analysis of any particular modulus.
-
- It is important to employ only safe primes as moduli, as they allow
- us to find a generator g so that the order of the generated subgroup
- does not factor into small primes, that is, with p = 2q + 1, the
- order has to be either q or p - 1. If the order is p - 1, then the
- exponents generate all possible public values, evenly distributed
- throughout the range of the modulus p, without cycling through a
- smaller subset. Van Oorshot and Wiener note that using short private
- exponents with a random prime modulus p makes the computation of the
- discrete logarithm easy [VAN-OORSCHOT]. However, they also state
- that this problem does not apply to safe primes.
-
- The least significant bit of the private exponent can be recovered
- when the modulus is a safe prime [MENEZES]. However, this is not a
- problem if the size of the private exponent is big enough. Related
- to this, Waldvogel and Massey note: When private exponents are chosen
- independently and uniformly at random from {0,...,p-2}, the key
- entropy is less than 2 bits away from the maximum, lg(p-1)
- [WALDVOGEL].
-
- The security considerations in [RFC4251] also apply to this key
- exchange method.
-
-
-
-
-
-
-Friedl, et al. Standards Track [Page 6]
-
-RFC 4419 SSH DH Group Exchange March 2006
-
-
-8. Acknowledgements
-
- The document is derived in part from "SSH Transport Layer Protocol"
- [RFC4253] by T. Ylonen, T. Kivinen, M. Saarinen, T. Rinne, and S.
- Lehtinen.
-
- Markku-Juhani Saarinen pointed out that the least significant bit of
- the private exponent can be recovered efficiently when using safe
- primes and a subgroup with an order divisible by two.
-
- Bodo Moeller suggested that the server send only one group, reducing
- the complexity of the implementation and the amount of data that
- needs to be exchanged between client and server.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Friedl, et al. Standards Track [Page 7]
-
-RFC 4419 SSH DH Group Exchange March 2006
-
-
-Appendix A: Generation of Safe Primes
-
- The "Handbook of Applied Cryptography" [MENEZES] lists the following
- algorithm to generate a k-bit safe prime p. It has been modified so
- that 2 is a generator for the multiplicative group mod p.
-
- 1. Do the following:
-
- 1. Select a random (k-1)-bit prime q, so that q mod 12 = 5.
-
- 2. Compute p := 2q + 1, and test whether p is prime (using,
- e.g., trial division and the Rabin-Miller test).
-
- 2. Repeat until p is prime.
-
- If an implementation uses the OpenSSL libraries, a group consisting
- of a 1024-bit safe prime and 2 as generator can be created as
- follows:
-
- DH *d = NULL;
- d = DH_generate_parameters(1024, DH_GENERATOR_2, NULL, NULL);
- BN_print_fp(stdout, d->p);
-
- The order of the subgroup generated by 2 is q = p - 1.
-
-References
-
-Normative References
-
- [FIPS-180-2] National Institute of Standards and Technology (NIST),
- "Secure Hash Standard (SHS)", FIPS PUB 180-2,
- August 2002.
-
- [RFC4251] Ylonen, T. and C. Lonvick, "The Secure Shell (SSH)
- Protocol Architecture", RFC 4251, January 2006.
-
- [RFC4253] Lonvick, C., "The Secure Shell (SSH) Transport Layer
- Protocol", RFC 4253, January 2006.
-
- [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
- Requirement Levels", BCP 14, RFC 2119, March 1997.
-
-Informative References
-
- [MENEZES] Menezes, A., van Oorschot, P., and S. Vanstone,
- "Handbook of Applied Cryptography", CRC Press, p. 537,
- 1996.
-
-
-
-
-Friedl, et al. Standards Track [Page 8]
-
-RFC 4419 SSH DH Group Exchange March 2006
-
-
- [VAN-OORSCHOT] van Oorschot, P. and M. Wiener, "On Diffie-Hellman key
- agreement with short exponents", Advances in
- Cryptology -EUROCRYPT'96, LNCS 1070,
- Springer-Verlag, pp. 332-343, 1996.
-
- [WALDVOGEL] Waldvogel, C. and J. Massey, "The probability
- distribution of the Diffie-Hellman key", Proceedings
- of AUSCRYPT 92, LNCS 718, Springer-Verlag, pp.
- 492-504, 1993.
-
-Authors' Addresses
-
- Markus Friedl
- EMail: markus@openbsd.org
-
-
- Niels Provos
- EMail: provos@citi.umich.edu
-
-
- William A. Simpson
- EMail: wsimpson@greendragon.com
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Friedl, et al. Standards Track [Page 9]
-
-RFC 4419 SSH DH Group Exchange March 2006
-
-
-Full Copyright Statement
-
- Copyright (C) The Internet Society (2006).
-
- This document is subject to the rights, licenses and restrictions
- contained in BCP 78, and except as set forth therein, the authors
- retain all their rights.
-
- This document and the information contained herein are provided on an
- "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
- OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
- ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
- INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
- INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
- WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
-
-Intellectual Property
-
- The IETF takes no position regarding the validity or scope of any
- Intellectual Property Rights or other rights that might be claimed to
- pertain to the implementation or use of the technology described in
- this document or the extent to which any license under such rights
- might or might not be available; nor does it represent that it has
- made any independent effort to identify any such rights. Information
- on the procedures with respect to rights in RFC documents can be
- found in BCP 78 and BCP 79.
-
- Copies of IPR disclosures made to the IETF Secretariat and any
- assurances of licenses to be made available, or the result of an
- attempt made to obtain a general license or permission for the use of
- such proprietary rights by implementers or users of this
- specification can be obtained from the IETF on-line IPR repository at
- http://www.ietf.org/ipr.
-
- The IETF invites any interested party to bring to its attention any
- copyrights, patents or patent applications, or other proprietary
- rights that may cover technology that may be required to implement
- this standard. Please address the information to the IETF at
- ietf-ipr@ietf.org.
-
-Acknowledgement
-
- Funding for the RFC Editor function is provided by the IETF
- Administrative Support Activity (IASA).
-
-
-
-
-
-
-
-Friedl, et al. Standards Track [Page 10]
-
[4/9] Remove third party documents from scm
Posted by gn...@apache.org.
http://git-wip-us.apache.org/repos/asf/mina-sshd/blob/46ea0930/sshd-core/src/docs/rfc4252.txt
----------------------------------------------------------------------
diff --git a/sshd-core/src/docs/rfc4252.txt b/sshd-core/src/docs/rfc4252.txt
deleted file mode 100644
index ddb6146..0000000
--- a/sshd-core/src/docs/rfc4252.txt
+++ /dev/null
@@ -1,955 +0,0 @@
-
-
-
-
-
-
-Network Working Group T. Ylonen
-Request for Comments: 4252 SSH Communications Security Corp
-Category: Standards Track C. Lonvick, Ed.
- Cisco Systems, Inc.
- January 2006
-
-
- The Secure Shell (SSH) Authentication Protocol
-
-Status of This Memo
-
- This document specifies an Internet standards track protocol for the
- Internet community, and requests discussion and suggestions for
- improvements. Please refer to the current edition of the "Internet
- Official Protocol Standards" (STD 1) for the standardization state
- and status of this protocol. Distribution of this memo is unlimited.
-
-Copyright Notice
-
- Copyright (C) The Internet Society (2006).
-
-Abstract
-
- The Secure Shell Protocol (SSH) is a protocol for secure remote login
- and other secure network services over an insecure network. This
- document describes the SSH authentication protocol framework and
- public key, password, and host-based client authentication methods.
- Additional authentication methods are described in separate
- documents. The SSH authentication protocol runs on top of the SSH
- transport layer protocol and provides a single authenticated tunnel
- for the SSH connection protocol.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Ylonen & Lonvick Standards Track [Page 1]
-
-RFC 4252 SSH Authentication Protocol January 2006
-
-
-Table of Contents
-
- 1. Introduction ....................................................2
- 2. Contributors ....................................................3
- 3. Conventions Used in This Document ...............................3
- 4. The Authentication Protocol Framework ...........................4
- 5. Authentication Requests .........................................4
- 5.1. Responses to Authentication Requests .......................5
- 5.2. The "none" Authentication Request ..........................7
- 5.3. Completion of User Authentication ..........................7
- 5.4. Banner Message .............................................7
- 6. Authentication Protocol Message Numbers .........................8
- 7. Public Key Authentication Method: "publickey" ...................8
- 8. Password Authentication Method: "password" .....................10
- 9. Host-Based Authentication: "hostbased" .........................12
- 10. IANA Considerations ...........................................14
- 11. Security Considerations .......................................14
- 12. References ....................................................15
- 12.1. Normative References .....................................15
- 12.2. Informative References ...................................15
- Authors' Addresses ................................................16
- Trademark Notice ..................................................16
-
-1. Introduction
-
- The SSH authentication protocol is a general-purpose user
- authentication protocol. It is intended to be run over the SSH
- transport layer protocol [SSH-TRANS]. This protocol assumes that the
- underlying protocols provide integrity and confidentiality
- protection.
-
- This document should be read only after reading the SSH architecture
- document [SSH-ARCH]. This document freely uses terminology and
- notation from the architecture document without reference or further
- explanation.
-
- The 'service name' for this protocol is "ssh-userauth".
-
- When this protocol starts, it receives the session identifier from
- the lower-level protocol (this is the exchange hash H from the first
- key exchange). The session identifier uniquely identifies this
- session and is suitable for signing in order to prove ownership of a
- private key. This protocol also needs to know whether the lower-
- level protocol provides confidentiality protection.
-
-
-
-
-
-
-
-Ylonen & Lonvick Standards Track [Page 2]
-
-RFC 4252 SSH Authentication Protocol January 2006
-
-
-2. Contributors
-
- The major original contributors of this set of documents have been:
- Tatu Ylonen, Tero Kivinen, Timo J. Rinne, Sami Lehtinen (all of SSH
- Communications Security Corp), and Markku-Juhani O. Saarinen
- (University of Jyvaskyla). Darren Moffat was the original editor of
- this set of documents and also made very substantial contributions.
-
- Many people contributed to the development of this document over the
- years. People who should be acknowledged include Mats Andersson, Ben
- Harris, Bill Sommerfeld, Brent McClure, Niels Moller, Damien Miller,
- Derek Fawcus, Frank Cusack, Heikki Nousiainen, Jakob Schlyter, Jeff
- Van Dyke, Jeffrey Altman, Jeffrey Hutzelman, Jon Bright, Joseph
- Galbraith, Ken Hornstein, Markus Friedl, Martin Forssen, Nicolas
- Williams, Niels Provos, Perry Metzger, Peter Gutmann, Simon
- Josefsson, Simon Tatham, Wei Dai, Denis Bider, der Mouse, and
- Tadayoshi Kohno. Listing their names here does not mean that they
- endorse this document, but that they have contributed to it.
-
-3. Conventions Used in This Document
-
- All documents related to the SSH protocols shall use the keywords
- "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
- "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" to describe
- requirements. These keywords are to be interpreted as described in
- [RFC2119].
-
- The keywords "PRIVATE USE", "HIERARCHICAL ALLOCATION", "FIRST COME
- FIRST SERVED", "EXPERT REVIEW", "SPECIFICATION REQUIRED", "IESG
- APPROVAL", "IETF CONSENSUS", and "STANDARDS ACTION" that appear in
- this document when used to describe namespace allocation are to be
- 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".
-
-
-
-
-
-Ylonen & Lonvick Standards Track [Page 3]
-
-RFC 4252 SSH Authentication Protocol January 2006
-
-
-4. The Authentication Protocol Framework
-
- The server drives the authentication by telling the client which
- authentication methods can be used to continue the exchange at any
- 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 authentication process if desired, but also gives enough
- flexibility for the client to use the methods it supports or that are
- most convenient for the user, when multiple methods are offered by
- the server.
-
- Authentication methods are identified by their name, as defined in
- [SSH-ARCH]. The "none" method is reserved, and MUST NOT be listed as
- supported. However, it MAY be sent by the client. The server MUST
- always reject this request, unless the client is to be granted access
- without any authentication, in which case, the server MUST accept
- this request. The main purpose of sending this request is to get the
- list of supported methods from the server.
-
- The server SHOULD have a timeout for authentication and disconnect if
- the authentication has not been accepted within the timeout period.
- The RECOMMENDED timeout period is 10 minutes. Additionally, the
- implementation SHOULD limit the number of failed authentication
- attempts a client may perform in a single session (the RECOMMENDED
- limit is 20 attempts). If the threshold is exceeded, the server
- SHOULD disconnect.
-
- Additional thoughts about authentication timeouts and retries may be
- found in [ssh-1.2.30].
-
-5. Authentication Requests
-
- All authentication requests MUST use the following message format.
- Only the first few fields are defined; the remaining fields depend on
- the authentication method.
-
- byte SSH_MSG_USERAUTH_REQUEST
- string user name in ISO-10646 UTF-8 encoding [RFC3629]
- string service name in US-ASCII
- string method name in US-ASCII
- .... method specific fields
-
- The 'user name' and 'service name' are repeated in every new
- authentication attempt, and MAY change. The server implementation
- MUST carefully check them in every message, and MUST flush any
- accumulated authentication states if they change. If it is unable to
-
-
-
-
-
-Ylonen & Lonvick Standards Track [Page 4]
-
-RFC 4252 SSH Authentication Protocol January 2006
-
-
- flush an authentication state, it MUST disconnect if the 'user name'
- or 'service name' changes.
-
- The 'service name' specifies the service to start after
- authentication. There may be several different authenticated
- services provided. If the requested service is not available, the
- server MAY disconnect immediately or at any later time. Sending a
- proper disconnect message is RECOMMENDED. In any case, if the
- service does not exist, authentication MUST NOT be accepted.
-
- If the requested 'user name' does not exist, the server MAY
- disconnect, or MAY send a bogus list of acceptable authentication
- 'method name' values, but never accept any. This makes it possible
- for the server to avoid disclosing information on which accounts
- exist. In any case, if the 'user name' does not exist, the
- authentication request MUST NOT be accepted.
-
- While there is usually little point for clients to send requests that
- the server does not list as acceptable, sending such requests is not
- an error, and the server SHOULD simply reject requests that it does
- not recognize.
-
- An authentication request MAY result in a further exchange of
- messages. All such messages depend on the authentication 'method
- name' used, and the client MAY at any time continue with a new
- SSH_MSG_USERAUTH_REQUEST message, in which case the server MUST
- abandon the previous authentication attempt and continue with the new
- one.
-
- The following 'method name' values are defined.
-
- "publickey" REQUIRED
- "password" OPTIONAL
- "hostbased" OPTIONAL
- "none" NOT RECOMMENDED
-
- Additional 'method name' values may be defined as specified in
- [SSH-ARCH] and [SSH-NUMBERS].
-
-5.1. Responses to Authentication Requests
-
- If the server rejects the authentication request, it MUST respond
- with the following:
-
- byte SSH_MSG_USERAUTH_FAILURE
- name-list authentications that can continue
- boolean partial success
-
-
-
-
-Ylonen & Lonvick Standards Track [Page 5]
-
-RFC 4252 SSH Authentication Protocol January 2006
-
-
- The 'authentications that can continue' is a comma-separated name-
- list of authentication 'method name' values that may productively
- continue the authentication dialog.
-
- It is RECOMMENDED that servers only include those 'method name'
- values in the name-list that are actually useful. However, it is not
- illegal to include 'method name' values that cannot be used to
- authenticate the user.
-
- Already successfully completed authentications SHOULD NOT be included
- in the name-list, unless they should be performed again for some
- reason.
-
- The value of 'partial success' MUST be TRUE if the authentication
- request to which this is a response was successful. It MUST be FALSE
- if the request was not successfully processed.
-
- When the server accepts authentication, it MUST respond with the
- following:
-
- byte SSH_MSG_USERAUTH_SUCCESS
-
- Note that this is not sent after each step in a multi-method
- authentication sequence, but only when the authentication is
- complete.
-
- The client MAY send several authentication requests without waiting
- for responses from previous requests. The server MUST process each
- request completely and acknowledge any failed requests with a
- SSH_MSG_USERAUTH_FAILURE message before processing the next request.
-
- A request that requires further messages to be exchanged will be
- aborted by a subsequent request. A client MUST NOT send a subsequent
- request if it has not received a response from the server for a
- previous request. A SSH_MSG_USERAUTH_FAILURE message MUST NOT be
- sent for an aborted method.
-
- SSH_MSG_USERAUTH_SUCCESS MUST be sent only once. When
- SSH_MSG_USERAUTH_SUCCESS has been sent, any further authentication
- requests received after that SHOULD be silently ignored.
-
- Any non-authentication messages sent by the client after the request
- that resulted in SSH_MSG_USERAUTH_SUCCESS being sent MUST be passed
- to the service being run on top of this protocol. Such messages can
- be identified by their message numbers (see Section 6).
-
-
-
-
-
-
-Ylonen & Lonvick Standards Track [Page 6]
-
-RFC 4252 SSH Authentication Protocol January 2006
-
-
-5.2. The "none" Authentication Request
-
- A client may request a list of authentication 'method name' values
- that may continue by using the "none" authentication 'method name'.
-
- If no authentication is needed for the user, the server MUST return
- SSH_MSG_USERAUTH_SUCCESS. Otherwise, the server MUST return
- SSH_MSG_USERAUTH_FAILURE and MAY return with it a list of methods
- that may continue in its 'authentications that can continue' value.
-
- This 'method name' MUST NOT be listed as supported by the server.
-
-5.3. Completion of User Authentication
-
- Authentication is complete when the server has responded with
- SSH_MSG_USERAUTH_SUCCESS. All authentication related messages
- received after sending this message SHOULD be silently ignored.
-
- After sending SSH_MSG_USERAUTH_SUCCESS, the server starts the
- requested service.
-
-5.4. Banner Message
-
- In some jurisdictions, sending a warning message before
- authentication may be relevant for getting legal protection. Many
- UNIX machines, for example, normally display text from /etc/issue,
- use TCP wrappers, or similar software to display a banner before
- issuing a login prompt.
-
- The SSH server may send an SSH_MSG_USERAUTH_BANNER message at any
- time after this authentication protocol starts and before
- authentication is successful. This message contains text to be
- displayed to the client user before authentication is attempted. The
- format is as follows:
-
- byte SSH_MSG_USERAUTH_BANNER
- string message in ISO-10646 UTF-8 encoding [RFC3629]
- string language tag [RFC3066]
-
- By default, the client SHOULD display the 'message' on the screen.
- However, since the 'message' is likely to be sent for every login
- attempt, and since some client software will need to open a separate
- window for this warning, the client software may allow the user to
- explicitly disable the display of banners from the server. The
- 'message' may consist of multiple lines, with line breaks indicated
- by CRLF pairs.
-
-
-
-
-
-Ylonen & Lonvick Standards Track [Page 7]
-
-RFC 4252 SSH Authentication Protocol January 2006
-
-
- If the 'message' string is displayed, control character filtering,
- discussed in [SSH-ARCH], SHOULD be used to avoid attacks by sending
- terminal control characters.
-
-6. Authentication Protocol Message Numbers
-
- All message numbers used by this authentication protocol are in the
- range from 50 to 79, which is part of the range reserved for
- protocols running on top of the SSH transport layer protocol.
-
- Message numbers of 80 and higher are reserved for protocols running
- after this authentication protocol, so receiving one of them before
- authentication is complete is an error, to which the server MUST
- respond by disconnecting, preferably with a proper disconnect message
- sent to ease troubleshooting.
-
- After successful authentication, such messages are passed to the
- higher-level service.
-
- These are the general authentication message codes:
-
- SSH_MSG_USERAUTH_REQUEST 50
- SSH_MSG_USERAUTH_FAILURE 51
- SSH_MSG_USERAUTH_SUCCESS 52
- SSH_MSG_USERAUTH_BANNER 53
-
- In addition to the above, there is a range of message numbers (60 to
- 79) reserved for method-specific messages. These messages are only
- sent by the server (client sends only SSH_MSG_USERAUTH_REQUEST
- messages). Different authentication methods reuse the same message
- numbers.
-
-7. Public Key Authentication Method: "publickey"
-
- The only REQUIRED authentication 'method name' is "publickey"
- authentication. All implementations MUST support this method;
- however, not all users need to have public keys, and most local
- policies are not likely to require public key authentication for all
- users in the near future.
-
- With this method, the possession of a private key serves as
- authentication. This method works by sending a signature created
- with a private key of the user. The server MUST check that the key
- is a valid authenticator for the user, and MUST check that the
- signature is valid. If both hold, the authentication request MUST be
- accepted; otherwise, it MUST be rejected. Note that the server MAY
- require additional authentications after successful authentication.
-
-
-
-
-Ylonen & Lonvick Standards Track [Page 8]
-
-RFC 4252 SSH Authentication Protocol January 2006
-
-
- Private keys are often stored in an encrypted form at the client
- host, and the user must supply a passphrase before the signature can
- be generated. Even if they are not, the signing operation involves
- some expensive computation. To avoid unnecessary processing and user
- interaction, the following message is provided for querying whether
- authentication using the "publickey" method would be acceptable.
-
- byte SSH_MSG_USERAUTH_REQUEST
- string user name in ISO-10646 UTF-8 encoding [RFC3629]
- string service name in US-ASCII
- string "publickey"
- boolean FALSE
- string public key algorithm name
- string public key blob
-
- Public key algorithms are defined in the transport layer
- specification [SSH-TRANS]. The 'public key blob' may contain
- certificates.
-
- Any public key algorithm may be offered for use in authentication.
- In particular, the list is not constrained by what was negotiated
- during key exchange. If the server does not support some algorithm,
- it MUST simply reject the request.
-
- The server MUST respond to this message with either
- SSH_MSG_USERAUTH_FAILURE or with the following:
-
- byte SSH_MSG_USERAUTH_PK_OK
- string public key algorithm name from the request
- string public key blob from the request
-
- To perform actual authentication, the client MAY then send a
- signature generated using the private key. The client MAY send the
- signature directly without first verifying whether the key is
- acceptable. The signature is sent using the following packet:
-
- byte SSH_MSG_USERAUTH_REQUEST
- string user name
- string service name
- string "publickey"
- boolean TRUE
- string public key algorithm name
- string public key to be used for authentication
- string signature
-
-
-
-
-
-
-
-Ylonen & Lonvick Standards Track [Page 9]
-
-RFC 4252 SSH Authentication Protocol January 2006
-
-
- The value of 'signature' is a signature by the corresponding private
- key over the following data, in the following order:
-
- string session identifier
- byte SSH_MSG_USERAUTH_REQUEST
- string user name
- string service name
- string "publickey"
- boolean TRUE
- string public key algorithm name
- string public key to be used for authentication
-
- When the server receives this message, it MUST check whether the
- supplied key is acceptable for authentication, and if so, it MUST
- check whether the signature is correct.
-
- If both checks succeed, this method is successful. Note that the
- server may require additional authentications. The server MUST
- respond with SSH_MSG_USERAUTH_SUCCESS (if no more authentications are
- needed), or SSH_MSG_USERAUTH_FAILURE (if the request failed, or more
- authentications are needed).
-
- The following method-specific message numbers are used by the
- "publickey" authentication method.
-
- SSH_MSG_USERAUTH_PK_OK 60
-
-8. Password Authentication Method: "password"
-
- Password authentication uses the following packets. Note that a
- server MAY request that a user change the password. All
- implementations SHOULD support password authentication.
-
- byte SSH_MSG_USERAUTH_REQUEST
- string user name
- string service name
- string "password"
- boolean FALSE
- string plaintext password in ISO-10646 UTF-8 encoding [RFC3629]
-
- Note that the 'plaintext password' value is encoded in ISO-10646
- UTF-8. It is up to the server how to interpret the password and
- validate it against the password database. However, if the client
- reads the password in 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 MUST convert the password to the
- encoding used on that system for passwords.
-
-
-
-
-Ylonen & Lonvick Standards Track [Page 10]
-
-RFC 4252 SSH Authentication Protocol January 2006
-
-
- From an internationalization standpoint, it is desired that if a user
- enters their password, the authentication process will work
- regardless of what OS and client software the user is using. Doing
- so requires normalization. Systems supporting non-ASCII passwords
- SHOULD always normalize passwords and user names whenever they are
- added to the database, or compared (with or without hashing) to
- existing entries in the database. SSH implementations that both
- store the passwords and compare them SHOULD use [RFC4013] for
- normalization.
-
- Note that even though the cleartext password is transmitted in the
- packet, the entire packet is encrypted by the transport layer. Both
- the server and the client should check whether the underlying
- transport layer provides confidentiality (i.e., if encryption is
- being used). If no confidentiality is provided ("none" cipher),
- password authentication SHOULD be disabled. If there is no
- confidentiality or no MAC, password change SHOULD be disabled.
-
- Normally, the server responds to this message with success or
- failure. However, if the password has expired, the server SHOULD
- indicate this by responding with SSH_MSG_USERAUTH_PASSWD_CHANGEREQ.
- In any case, the server MUST NOT allow an expired password to be used
- for authentication.
-
- byte SSH_MSG_USERAUTH_PASSWD_CHANGEREQ
- string prompt in ISO-10646 UTF-8 encoding [RFC3629]
- string language tag [RFC3066]
-
- In this case, the client MAY continue with a different authentication
- method, or request a new password from the user and retry password
- authentication using the following message. The client MAY also send
- this message instead of the normal password authentication request
- without the server asking for it.
-
- byte SSH_MSG_USERAUTH_REQUEST
- string user name
- string service name
- string "password"
- boolean TRUE
- string plaintext old password in ISO-10646 UTF-8 encoding
- [RFC3629]
- string plaintext new password in ISO-10646 UTF-8 encoding
- [RFC3629]
-
-
-
-
-
-
-
-
-Ylonen & Lonvick Standards Track [Page 11]
-
-RFC 4252 SSH Authentication Protocol January 2006
-
-
- The server must reply to each request message with
- SSH_MSG_USERAUTH_SUCCESS, SSH_MSG_USERAUTH_FAILURE, or another
- SSH_MSG_USERAUTH_PASSWD_CHANGEREQ. The meaning of these is as
- follows:
-
- SSH_MSG_USERAUTH_SUCCESS - The password has been changed, and
- authentication has been successfully completed.
-
- SSH_MSG_USERAUTH_FAILURE with partial success - The password has
- been changed, but more authentications are needed.
-
- SSH_MSG_USERAUTH_FAILURE without partial success - The password
- has not been changed. Either password changing was not supported,
- or the old password was bad. Note that if the server has already
- sent SSH_MSG_USERAUTH_PASSWD_CHANGEREQ, we know that it supports
- changing the password.
-
- SSH_MSG_USERAUTH_CHANGEREQ - The password was not changed because
- the new password was not acceptable (e.g., too easy to guess).
-
- The following method-specific message numbers are used by the
- password authentication method.
-
- SSH_MSG_USERAUTH_PASSWD_CHANGEREQ 60
-
-9. Host-Based Authentication: "hostbased"
-
- Some sites wish to allow authentication based on the host that the
- user is coming from and the user name on the remote host. While this
- form of authentication is not suitable for high-security sites, it
- can be very convenient in many environments. This form of
- authentication is OPTIONAL. When used, special care SHOULD be taken
- to prevent a regular user from obtaining the private host key.
-
- The client requests this form of authentication by sending the
- following message. It is similar to the UNIX "rhosts" and
- "hosts.equiv" styles of authentication, except that the identity of
- the client host is checked more rigorously.
-
- This method works by having the client send a signature created with
- the private key of the client host, which the server checks with that
- host's public key. Once the client host's identity is established,
- authorization (but no further authentication) is performed based on
- the user names on the server and the client, and the client host
- name.
-
-
-
-
-
-
-Ylonen & Lonvick Standards Track [Page 12]
-
-RFC 4252 SSH Authentication Protocol January 2006
-
-
- byte SSH_MSG_USERAUTH_REQUEST
- string user name
- string service name
- string "hostbased"
- string public key algorithm for host key
- string public host key and certificates for client host
- string client host name expressed as the FQDN in US-ASCII
- string user name on the client host in ISO-10646 UTF-8 encoding
- [RFC3629]
- string signature
-
- Public key algorithm names for use in 'public key algorithm for host
- key' are defined in the transport layer specification [SSH-TRANS].
- The 'public host key and certificates for client host' may include
- certificates.
-
- The value of 'signature' is a signature with the private host key of
- the following data, in this order:
-
- string session identifier
- byte SSH_MSG_USERAUTH_REQUEST
- string user name
- string service name
- string "hostbased"
- string public key algorithm for host key
- string public host key and certificates for client host
- string client host name expressed as the FQDN in US-ASCII
- string user name on the client host in ISO-10646 UTF-8 encoding
- [RFC3629]
-
- The server MUST verify that the host key actually belongs to the
- client host named in the message, that the given user on that host is
- allowed to log in, and that the 'signature' value is a valid
- signature on the appropriate value by the given host key. The server
- MAY ignore the client 'user name', if it wants to authenticate only
- the client host.
-
- Whenever possible, it is RECOMMENDED that the server perform
- additional checks to verify that the network address obtained from
- the (untrusted) network matches the given client host name. This
- makes exploiting compromised host keys more difficult. Note that
- this may require special handling for connections coming through a
- firewall.
-
-
-
-
-
-
-
-
-Ylonen & Lonvick Standards Track [Page 13]
-
-RFC 4252 SSH Authentication Protocol January 2006
-
-
-10. IANA Considerations
-
- This document is part of a set. The IANA considerations for the SSH
- protocol, as defined in [SSH-ARCH], [SSH-TRANS], [SSH-CONNECT], and
- this document, are detailed in [SSH-NUMBERS].
-
-11. Security Considerations
-
- The purpose of this protocol is to perform client user
- authentication. It assumed that this runs over a secure transport
- layer protocol, which has already authenticated the server machine,
- established an encrypted communications channel, and computed a
- unique session identifier for this session. The transport layer
- provides forward secrecy for password authentication and other
- methods that rely on secret data.
-
- Full security considerations for this protocol are provided in
- [SSH-ARCH].
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Ylonen & Lonvick Standards Track [Page 14]
-
-RFC 4252 SSH Authentication Protocol January 2006
-
-
-12. References
-
-12.1. Normative References
-
- [SSH-ARCH] Ylonen, T. and C. Lonvick, Ed., "The Secure Shell (SSH)
- Protocol Architecture", RFC 4251, January 2006.
-
- [SSH-CONNECT] Ylonen, T. and C. Lonvick, Ed., "The Secure Shell (SSH)
- Connection Protocol", RFC 4254, January 2006.
-
- [SSH-TRANS] Ylonen, T. and C. Lonvick, Ed., "The Secure Shell (SSH)
- Transport Layer Protocol", RFC 4253, January 2006.
-
- [SSH-NUMBERS] Lehtinen, S. and C. Lonvick, Ed., "The Secure Shell
- (SSH) Protocol Assigned Numbers", RFC 4250, January
- 2006.
-
- [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
- Requirement Levels", BCP 14, RFC 2119, March 1997.
-
- [RFC2434] Narten, T. and H. Alvestrand, "Guidelines for Writing
- an IANA Considerations Section in RFCs", BCP 26, RFC
- 2434, October 1998.
-
- [RFC3066] Alvestrand, H., "Tags for the Identification of
- Languages", BCP 47, RFC 3066, January 2001.
-
- [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO
- 10646", STD 63, RFC 3629, November 2003.
-
- [RFC4013] Zeilenga, K., "SASLprep: Stringprep Profile for User
- Names and Passwords", RFC 4013, February 2005.
-
-12.2. Informative References
-
- [ssh-1.2.30] Ylonen, T., "ssh-1.2.30/RFC", File within compressed
- tarball ftp://ftp.funet.fi/pub/unix/security/login/
- ssh/ssh-1.2.30.tar.gz, November 1995.
-
-
-
-
-
-
-
-
-
-
-
-
-
-Ylonen & Lonvick Standards Track [Page 15]
-
-RFC 4252 SSH Authentication Protocol January 2006
-
-
-Authors' Addresses
-
- Tatu Ylonen
- SSH Communications Security Corp
- Valimotie 17
- 00380 Helsinki
- Finland
-
- EMail: ylo@ssh.com
-
-
- Chris Lonvick (editor)
- Cisco Systems, Inc.
- 12515 Research Blvd.
- Austin 78759
- USA
-
- EMail: clonvick@cisco.com
-
-Trademark Notice
-
- "ssh" is a registered trademark in the United States and/or other
- countries.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Ylonen & Lonvick Standards Track [Page 16]
-
-RFC 4252 SSH Authentication Protocol January 2006
-
-
-Full Copyright Statement
-
- Copyright (C) The Internet Society (2006).
-
- This document is subject to the rights, licenses and restrictions
- contained in BCP 78, and except as set forth therein, the authors
- retain all their rights.
-
- This document and the information contained herein are provided on an
- "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
- OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
- ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
- INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
- INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
- WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
-
-Intellectual Property
-
- The IETF takes no position regarding the validity or scope of any
- Intellectual Property Rights or other rights that might be claimed to
- pertain to the implementation or use of the technology described in
- this document or the extent to which any license under such rights
- might or might not be available; nor does it represent that it has
- made any independent effort to identify any such rights. Information
- on the procedures with respect to rights in RFC documents can be
- found in BCP 78 and BCP 79.
-
- Copies of IPR disclosures made to the IETF Secretariat and any
- assurances of licenses to be made available, or the result of an
- attempt made to obtain a general license or permission for the use of
- such proprietary rights by implementers or users of this
- specification can be obtained from the IETF on-line IPR repository at
- http://www.ietf.org/ipr.
-
- The IETF invites any interested party to bring to its attention any
- copyrights, patents or patent applications, or other proprietary
- rights that may cover technology that may be required to implement
- this standard. Please address the information to the IETF at
- ietf-ipr@ietf.org.
-
-Acknowledgement
-
- Funding for the RFC Editor function is provided by the IETF
- Administrative Support Activity (IASA).
-
-
-
-
-
-
-
-Ylonen & Lonvick Standards Track [Page 17]
-
[3/9] Remove third party documents from scm
Posted by gn...@apache.org.
http://git-wip-us.apache.org/repos/asf/mina-sshd/blob/46ea0930/sshd-core/src/docs/rfc4253.txt
----------------------------------------------------------------------
diff --git a/sshd-core/src/docs/rfc4253.txt b/sshd-core/src/docs/rfc4253.txt
deleted file mode 100644
index 20e296e..0000000
--- a/sshd-core/src/docs/rfc4253.txt
+++ /dev/null
@@ -1,1795 +0,0 @@
-
-
-
-
-
-
-Network Working Group T. Ylonen
-Request for Comments: 4253 SSH Communications Security Corp
-Category: Standards Track C. Lonvick, Ed.
- Cisco Systems, Inc.
- January 2006
-
-
- The Secure Shell (SSH) Transport Layer Protocol
-
-Status of This Memo
-
- This document specifies an Internet standards track protocol for the
- Internet community, and requests discussion and suggestions for
- improvements. Please refer to the current edition of the "Internet
- Official Protocol Standards" (STD 1) for the standardization state
- and status of this protocol. Distribution of this memo is unlimited.
-
-Copyright Notice
-
- Copyright (C) The Internet Society (2006).
-
-Abstract
-
- The Secure Shell (SSH) is a protocol for secure remote login and
- other secure network services over an insecure network.
-
- This document describes the SSH transport layer protocol, which
- typically runs on top of TCP/IP. The protocol can be used as a basis
- for a number of secure network services. It provides strong
- encryption, server authentication, and integrity protection. It may
- also provide compression.
-
- Key exchange method, public key algorithm, symmetric encryption
- algorithm, message authentication algorithm, and hash algorithm are
- all negotiated.
-
- This document also describes the Diffie-Hellman key exchange method
- and the minimal set of algorithms that are needed to implement the
- SSH transport layer protocol.
-
-
-
-
-
-
-
-
-
-
-
-
-Ylonen & Lonvick Standards Track [Page 1]
-
-RFC 4253 SSH Transport Layer Protocol January 2006
-
-
-Table of Contents
-
- 1. Introduction ....................................................3
- 2. Contributors ....................................................3
- 3. Conventions Used in This Document ...............................3
- 4. Connection Setup ................................................4
- 4.1. Use over TCP/IP ............................................4
- 4.2. Protocol Version Exchange ..................................4
- 5. Compatibility With Old SSH Versions .............................5
- 5.1. Old Client, New Server .....................................6
- 5.2. New Client, Old Server .....................................6
- 5.3. Packet Size and Overhead ...................................6
- 6. Binary Packet Protocol ..........................................7
- 6.1. Maximum Packet Length ......................................8
- 6.2. Compression ................................................8
- 6.3. Encryption .................................................9
- 6.4. Data Integrity ............................................12
- 6.5. Key Exchange Methods ......................................13
- 6.6. Public Key Algorithms .....................................13
- 7. Key Exchange ...................................................15
- 7.1. Algorithm Negotiation .....................................17
- 7.2. Output from Key Exchange ..................................20
- 7.3. Taking Keys Into Use ......................................21
- 8. Diffie-Hellman Key Exchange ....................................21
- 8.1. diffie-hellman-group1-sha1 ................................23
- 8.2. diffie-hellman-group14-sha1 ...............................23
- 9. Key Re-Exchange ................................................23
- 10. Service Request ...............................................24
- 11. Additional Messages ...........................................25
- 11.1. Disconnection Message ....................................25
- 11.2. Ignored Data Message .....................................26
- 11.3. Debug Message ............................................26
- 11.4. Reserved Messages ........................................27
- 12. Summary of Message Numbers ....................................27
- 13. IANA Considerations ...........................................27
- 14. Security Considerations .......................................28
- 15. References ....................................................29
- 15.1. Normative References .....................................29
- 15.2. Informative References ...................................30
- Authors' Addresses ................................................31
- Trademark Notice ..................................................31
-
-
-
-
-
-
-
-
-
-
-Ylonen & Lonvick Standards Track [Page 2]
-
-RFC 4253 SSH Transport Layer Protocol January 2006
-
-
-1. Introduction
-
- The SSH transport layer is a secure, low level transport protocol.
- It provides strong encryption, cryptographic host authentication, and
- integrity protection.
-
- Authentication in this protocol level is host-based; this protocol
- does not perform user authentication. A higher level protocol for
- user authentication can be designed on top of this protocol.
-
- The protocol has been designed to be simple and flexible to allow
- parameter negotiation, and to minimize the number of round-trips.
- The key exchange method, public key algorithm, symmetric encryption
- algorithm, message authentication algorithm, and hash algorithm are
- all negotiated. It is expected that in most environments, only 2
- round-trips will be needed for full key exchange, server
- authentication, service request, and acceptance notification of
- service request. The worst case is 3 round-trips.
-
-2. Contributors
-
- The major original contributors of this set of documents have been:
- Tatu Ylonen, Tero Kivinen, Timo J. Rinne, Sami Lehtinen (all of SSH
- Communications Security Corp), and Markku-Juhani O. Saarinen
- (University of Jyvaskyla). Darren Moffat was the original editor of
- this set of documents and also made very substantial contributions.
-
- Many people contributed to the development of this document over the
- years. People who should be acknowledged include Mats Andersson, Ben
- Harris, Bill Sommerfeld, Brent McClure, Niels Moller, Damien Miller,
- Derek Fawcus, Frank Cusack, Heikki Nousiainen, Jakob Schlyter, Jeff
- Van Dyke, Jeffrey Altman, Jeffrey Hutzelman, Jon Bright, Joseph
- Galbraith, Ken Hornstein, Markus Friedl, Martin Forssen, Nicolas
- Williams, Niels Provos, Perry Metzger, Peter Gutmann, Simon
- Josefsson, Simon Tatham, Wei Dai, Denis Bider, der Mouse, and
- Tadayoshi Kohno. Listing their names here does not mean that they
- endorse this document, but that they have contributed to it.
-
-3. Conventions Used in This Document
-
- All documents related to the SSH protocols shall use the keywords
- "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
- "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" to describe
- requirements. These keywords are to be interpreted as described in
- [RFC2119].
-
-
-
-
-
-
-Ylonen & Lonvick Standards Track [Page 3]
-
-RFC 4253 SSH Transport Layer Protocol January 2006
-
-
- The keywords "PRIVATE USE", "HIERARCHICAL ALLOCATION", "FIRST COME
- FIRST SERVED", "EXPERT REVIEW", "SPECIFICATION REQUIRED", "IESG
- APPROVAL", "IETF CONSENSUS", and "STANDARDS ACTION" that appear in
- this document when used to describe namespace allocation are to be
- 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. Connection Setup
-
- SSH works over any 8-bit clean, binary-transparent transport. The
- underlying transport SHOULD protect against transmission errors, as
- such errors cause the SSH connection to terminate.
-
- The client initiates the connection.
-
-4.1. Use over TCP/IP
-
- When used over TCP/IP, the server normally listens for connections on
- port 22. This port number has been registered with the IANA, and has
- been officially assigned for SSH.
-
-4.2. Protocol Version Exchange
-
- When the connection has been established, both sides MUST send an
- identification string. This identification string MUST be
-
- SSH-protoversion-softwareversion SP comments CR LF
-
- Since the protocol being defined in this set of documents is version
- 2.0, the 'protoversion' MUST be "2.0". The 'comments' string is
- OPTIONAL. If the 'comments' string is included, a 'space' character
- (denoted above as SP, ASCII 32) MUST separate the 'softwareversion'
- and 'comments' strings. The identification MUST be terminated by a
- single Carriage Return (CR) and a single Line Feed (LF) character
- (ASCII 13 and 10, respectively). Implementers who wish to maintain
-
-
-
-Ylonen & Lonvick Standards Track [Page 4]
-
-RFC 4253 SSH Transport Layer Protocol January 2006
-
-
- compatibility with older, undocumented versions of this protocol may
- want to process the identification string without expecting the
- presence of the carriage return character for reasons described in
- Section 5 of this document. The null character MUST NOT be sent.
- The maximum length of the string is 255 characters, including the
- Carriage Return and Line Feed.
-
- The part of the identification string preceding the Carriage Return
- and Line Feed is used in the Diffie-Hellman key exchange (see Section
- 8).
-
- The server MAY send other lines of data before sending the version
- string. Each line SHOULD be terminated by a Carriage Return and Line
- Feed. Such lines MUST NOT begin with "SSH-", and SHOULD be encoded
- in ISO-10646 UTF-8 [RFC3629] (language is not specified). Clients
- MUST be able to process such lines. Such lines MAY be silently
- ignored, or MAY be displayed to the client user. If they are
- displayed, control character filtering, as discussed in [SSH-ARCH],
- SHOULD be used. The primary use of this feature is to allow TCP-
- wrappers to display an error message before disconnecting.
-
- Both the 'protoversion' and 'softwareversion' strings MUST consist of
- printable US-ASCII characters, with the exception of whitespace
- characters and the minus sign (-). The 'softwareversion' string is
- primarily used to trigger compatibility extensions and to indicate
- the capabilities of an implementation. The 'comments' string SHOULD
- contain additional information that might be useful in solving user
- problems. As such, an example of a valid identification string is
-
- SSH-2.0-billsSSH_3.6.3q3<CR><LF>
-
- This identification string does not contain the optional 'comments'
- string and is thus terminated by a CR and LF immediately after the
- 'softwareversion' string.
-
- Key exchange will begin immediately after sending this identifier.
- All packets following the identification string SHALL use the binary
- packet protocol, which is described in Section 6.
-
-5. Compatibility With Old SSH Versions
-
- As stated earlier, the 'protoversion' specified for this protocol is
- "2.0". Earlier versions of this protocol have not been formally
- documented, but it is widely known that they use 'protoversion' of
- "1.x" (e.g., "1.5" or "1.3"). At the time of this writing, many
- implementations of SSH are utilizing protocol version 2.0, but it is
- known that there are still devices using the previous versions.
- During the transition period, it is important to be able to work in a
-
-
-
-Ylonen & Lonvick Standards Track [Page 5]
-
-RFC 4253 SSH Transport Layer Protocol January 2006
-
-
- way that is compatible with the installed SSH clients and servers
- that use the older version of the protocol. Information in this
- section is only relevant for implementations supporting compatibility
- with SSH versions 1.x. For those interested, the only known
- documentation of the 1.x protocol is contained in README files that
- are shipped along with the source code [ssh-1.2.30].
-
-5.1. Old Client, New Server
-
- Server implementations MAY support a configurable compatibility flag
- that enables compatibility with old versions. When this flag is on,
- the server SHOULD identify its 'protoversion' as "1.99". Clients
- using protocol 2.0 MUST be able to identify this as identical to
- "2.0". In this mode, the server SHOULD NOT send the Carriage Return
- character (ASCII 13) after the identification string.
-
- In the compatibility mode, the server SHOULD NOT send any further
- data after sending its identification string until it has received an
- identification string from the client. The server can then determine
- whether the client is using an old protocol, and can revert to the
- old protocol if required. In the compatibility mode, the server MUST
- NOT send additional data before the identification string.
-
- When compatibility with old clients is not needed, the server MAY
- send its initial key exchange data immediately after the
- identification string.
-
-5.2. New Client, Old Server
-
- Since the new client MAY immediately send additional data after its
- identification string (before receiving the server's identification
- string), the old protocol may already be corrupt when the client
- learns that the server is old. When this happens, the client SHOULD
- close the connection to the server, and reconnect using the old
- protocol.
-
-5.3. Packet Size and Overhead
-
- Some readers will worry about the increase in packet size due to new
- headers, padding, and the Message Authentication Code (MAC). The
- minimum packet size is in the order of 28 bytes (depending on
- negotiated algorithms). The increase is negligible for large
- packets, but very significant for one-byte packets (telnet-type
- sessions). There are, however, several factors that make this a
- non-issue in almost all cases:
-
- o The minimum size of a TCP/IP header is 32 bytes. Thus, the
- increase is actually from 33 to 51 bytes (roughly).
-
-
-
-Ylonen & Lonvick Standards Track [Page 6]
-
-RFC 4253 SSH Transport Layer Protocol January 2006
-
-
- o The minimum size of the data field of an Ethernet packet is 46
- bytes [RFC0894]. Thus, the increase is no more than 5 bytes.
- When Ethernet headers are considered, the increase is less than 10
- percent.
-
- o The total fraction of telnet-type data in the Internet is
- negligible, even with increased packet sizes.
-
- The only environment where the packet size increase is likely to have
- a significant effect is PPP [RFC1661] over slow modem lines (PPP
- compresses the TCP/IP headers, emphasizing the increase in packet
- size). However, with modern modems, the time needed to transfer is
- in the order of 2 milliseconds, which is a lot faster than people can
- type.
-
- There are also issues related to the maximum packet size. To
- minimize delays in screen updates, one does not want excessively
- large packets for interactive sessions. The maximum packet size is
- negotiated separately for each channel.
-
-6. Binary Packet Protocol
-
- Each packet is in the following format:
-
- uint32 packet_length
- byte padding_length
- byte[n1] payload; n1 = packet_length - padding_length - 1
- byte[n2] random padding; n2 = padding_length
- byte[m] mac (Message Authentication Code - MAC); m = mac_length
-
- packet_length
- The length of the packet in bytes, not including 'mac' or the
- 'packet_length' field itself.
-
- padding_length
- Length of 'random padding' (bytes).
-
- payload
- The useful contents of the packet. If compression has been
- negotiated, this field is compressed. Initially, compression
- MUST be "none".
-
- random padding
- Arbitrary-length padding, such that the total length of
- (packet_length || padding_length || payload || random padding)
- is a multiple of the cipher block size or 8, whichever is
-
-
-
-
-
-Ylonen & Lonvick Standards Track [Page 7]
-
-RFC 4253 SSH Transport Layer Protocol January 2006
-
-
- larger. There MUST be at least four bytes of padding. The
- padding SHOULD consist of random bytes. The maximum amount of
- padding is 255 bytes.
-
- mac
- Message Authentication Code. If message authentication has
- been negotiated, this field contains the MAC bytes. Initially,
- the MAC algorithm MUST be "none".
-
- Note that the length of the concatenation of 'packet_length',
- 'padding_length', 'payload', and 'random padding' MUST be a multiple
- of the cipher block size or 8, whichever is larger. This constraint
- MUST be enforced, even when using stream ciphers. Note that the
- 'packet_length' field is also encrypted, and processing it requires
- special care when sending or receiving packets. Also note that the
- insertion of variable amounts of 'random padding' may help thwart
- traffic analysis.
-
- The minimum size of a packet is 16 (or the cipher block size,
- whichever is larger) bytes (plus 'mac'). Implementations SHOULD
- decrypt the length after receiving the first 8 (or cipher block size,
- whichever is larger) bytes of a packet.
-
-6.1. Maximum Packet Length
-
- All implementations MUST be able to process packets with an
- uncompressed payload length of 32768 bytes or less and a total packet
- size of 35000 bytes or less (including 'packet_length',
- 'padding_length', 'payload', 'random padding', and 'mac'). The
- maximum of 35000 bytes is an arbitrarily chosen value that is larger
- than the uncompressed length noted above. Implementations SHOULD
- support longer packets, where they might be needed. For example, if
- an implementation wants to send a very large number of certificates,
- the larger packets MAY be sent if the identification string indicates
- that the other party is able to process them. However,
- implementations SHOULD check that the packet length is reasonable in
- order for the implementation to avoid denial of service and/or buffer
- overflow attacks.
-
-6.2. Compression
-
- If compression has been negotiated, the 'payload' field (and only it)
- will be compressed using the negotiated algorithm. The
- 'packet_length' field and 'mac' will be computed from the compressed
- payload. Encryption will be done after compression.
-
-
-
-
-
-
-Ylonen & Lonvick Standards Track [Page 8]
-
-RFC 4253 SSH Transport Layer Protocol January 2006
-
-
- Compression MAY be stateful, depending on the method. Compression
- MUST be independent for each direction, and implementations MUST
- allow independent choosing of the algorithm for each direction. In
- practice however, it is RECOMMENDED that the compression method be
- the same in both directions.
-
- The following compression methods are currently defined:
-
- none REQUIRED no compression
- zlib OPTIONAL ZLIB (LZ77) compression
-
- The "zlib" compression is described in [RFC1950] and in [RFC1951].
- The compression context is initialized after each key exchange, and
- is passed from one packet to the next, with only a partial flush
- being performed at the end of each packet. A partial flush means
- that the current compressed block is ended and all data will be
- output. If the current block is not a stored block, one or more
- empty blocks are added after the current block to ensure that there
- are at least 8 bits, counting from the start of the end-of-block code
- of the current block to the end of the packet payload.
-
- Additional methods may be defined as specified in [SSH-ARCH] and
- [SSH-NUMBERS].
-
-6.3. Encryption
-
- An encryption algorithm and a key will be negotiated during the key
- exchange. When encryption is in effect, the packet length, padding
- length, payload, and padding fields of each packet MUST be encrypted
- with the given algorithm.
-
- The encrypted data in all packets sent in one direction SHOULD be
- considered a single data stream. For example, initialization vectors
- SHOULD be passed from the end of one packet to the beginning of the
- next packet. All ciphers SHOULD use keys with an effective key
- length of 128 bits or more.
-
- The ciphers in each direction MUST run independently of each other.
- Implementations MUST allow the algorithm for each direction to be
- independently selected, if multiple algorithms are allowed by local
- policy. In practice however, it is RECOMMENDED that the same
- algorithm be used in both directions.
-
-
-
-
-
-
-
-
-
-Ylonen & Lonvick Standards Track [Page 9]
-
-RFC 4253 SSH Transport Layer Protocol January 2006
-
-
- The following ciphers are currently defined:
-
- 3des-cbc REQUIRED three-key 3DES in CBC mode
- blowfish-cbc OPTIONAL Blowfish in CBC mode
- twofish256-cbc OPTIONAL Twofish in CBC mode,
- with a 256-bit key
- twofish-cbc OPTIONAL alias for "twofish256-cbc"
- (this is being retained
- for historical reasons)
- twofish192-cbc OPTIONAL Twofish with a 192-bit key
- twofish128-cbc OPTIONAL Twofish with a 128-bit key
- aes256-cbc OPTIONAL AES in CBC mode,
- with a 256-bit key
- aes192-cbc OPTIONAL AES with a 192-bit key
- aes128-cbc RECOMMENDED AES with a 128-bit key
- serpent256-cbc OPTIONAL Serpent in CBC mode, with
- a 256-bit key
- serpent192-cbc OPTIONAL Serpent with a 192-bit key
- serpent128-cbc OPTIONAL Serpent with a 128-bit key
- arcfour OPTIONAL the ARCFOUR stream cipher
- with a 128-bit key
- idea-cbc OPTIONAL IDEA in CBC mode
- cast128-cbc OPTIONAL CAST-128 in CBC mode
- none OPTIONAL no encryption; NOT RECOMMENDED
-
- The "3des-cbc" cipher is three-key triple-DES (encrypt-decrypt-
- encrypt), where the first 8 bytes of the key are used for the first
- encryption, the next 8 bytes for the decryption, and the following 8
- bytes for the final encryption. This requires 24 bytes of key data
- (of which 168 bits are actually used). To implement CBC mode, outer
- chaining MUST be used (i.e., there is only one initialization
- vector). This is a block cipher with 8-byte blocks. This algorithm
- is defined in [FIPS-46-3]. Note that since this algorithm only has
- an effective key length of 112 bits ([SCHNEIER]), it does not meet
- the specifications that SSH encryption algorithms should use keys of
- 128 bits or more. However, this algorithm is still REQUIRED for
- historical reasons; essentially, all known implementations at the
- time of this writing support this algorithm, and it is commonly used
- because it is the fundamental interoperable algorithm. At some
- future time, it is expected that another algorithm, one with better
- strength, will become so prevalent and ubiquitous that the use of
- "3des-cbc" will be deprecated by another STANDARDS ACTION.
-
- The "blowfish-cbc" cipher is Blowfish in CBC mode, with 128-bit keys
- [SCHNEIER]. This is a block cipher with 8-byte blocks.
-
-
-
-
-
-
-Ylonen & Lonvick Standards Track [Page 10]
-
-RFC 4253 SSH Transport Layer Protocol January 2006
-
-
- The "twofish-cbc" or "twofish256-cbc" cipher is Twofish in CBC mode,
- with 256-bit keys as described [TWOFISH]. This is a block cipher
- with 16-byte blocks.
-
- The "twofish192-cbc" cipher is the same as above, but with a 192-bit
- key.
-
- The "twofish128-cbc" cipher is the same as above, but with a 128-bit
- key.
-
- The "aes256-cbc" cipher is AES (Advanced Encryption Standard)
- [FIPS-197], in CBC mode. This version uses a 256-bit key.
-
- The "aes192-cbc" cipher is the same as above, but with a 192-bit key.
-
- The "aes128-cbc" cipher is the same as above, but with a 128-bit key.
-
- The "serpent256-cbc" cipher in CBC mode, with a 256-bit key as
- described in the Serpent AES submission.
-
- The "serpent192-cbc" cipher is the same as above, but with a 192-bit
- key.
-
- The "serpent128-cbc" cipher is the same as above, but with a 128-bit
- key.
-
- The "arcfour" cipher is the Arcfour stream cipher with 128-bit keys.
- The Arcfour cipher is believed to be compatible with the RC4 cipher
- [SCHNEIER]. Arcfour (and RC4) has problems with weak keys, and
- should be used with caution.
-
- The "idea-cbc" cipher is the IDEA cipher in CBC mode [SCHNEIER].
-
- The "cast128-cbc" cipher is the CAST-128 cipher in CBC mode with a
- 128-bit key [RFC2144].
-
- The "none" algorithm specifies that no encryption is to be done.
- Note that this method provides no confidentiality protection, and it
- is NOT RECOMMENDED. Some functionality (e.g., password
- authentication) may be disabled for security reasons if this cipher
- is chosen.
-
- Additional methods may be defined as specified in [SSH-ARCH] and in
- [SSH-NUMBERS].
-
-
-
-
-
-
-
-Ylonen & Lonvick Standards Track [Page 11]
-
-RFC 4253 SSH Transport Layer Protocol January 2006
-
-
-6.4. Data Integrity
-
- Data integrity is protected by including with each packet a MAC that
- is computed from a shared secret, packet sequence number, and the
- contents of the packet.
-
- The message authentication algorithm and key are negotiated during
- key exchange. Initially, no MAC will be in effect, and its length
- MUST be zero. After key exchange, the 'mac' for the selected MAC
- algorithm will be computed before encryption from the concatenation
- of packet data:
-
- mac = MAC(key, sequence_number || unencrypted_packet)
-
- where unencrypted_packet is the entire packet without 'mac' (the
- length fields, 'payload' and 'random padding'), and sequence_number
- is an implicit packet sequence number represented as uint32. The
- sequence_number is initialized to zero for the first packet, and is
- incremented after every packet (regardless of whether encryption or
- MAC is in use). It is never reset, even if keys/algorithms are
- renegotiated later. It wraps around to zero after every 2^32
- packets. The packet sequence_number itself is not included in the
- packet sent over the wire.
-
- The MAC algorithms for each direction MUST run independently, and
- implementations MUST allow choosing the algorithm independently for
- both directions. In practice however, it is RECOMMENDED that the
- same algorithm be used in both directions.
-
- The value of 'mac' resulting from the MAC algorithm MUST be
- transmitted without encryption as the last part of the packet. The
- number of 'mac' bytes depends on the algorithm chosen.
-
- The following MAC algorithms are currently defined:
-
- hmac-sha1 REQUIRED HMAC-SHA1 (digest length = key
- length = 20)
- hmac-sha1-96 RECOMMENDED first 96 bits of HMAC-SHA1 (digest
- length = 12, key length = 20)
- hmac-md5 OPTIONAL HMAC-MD5 (digest length = key
- length = 16)
- hmac-md5-96 OPTIONAL first 96 bits of HMAC-MD5 (digest
- length = 12, key length = 16)
- none OPTIONAL no MAC; NOT RECOMMENDED
-
- The "hmac-*" algorithms are described in [RFC2104]. The "*-n" MACs
- use only the first n bits of the resulting value.
-
-
-
-
-Ylonen & Lonvick Standards Track [Page 12]
-
-RFC 4253 SSH Transport Layer Protocol January 2006
-
-
- SHA-1 is described in [FIPS-180-2] and MD5 is described in [RFC1321].
-
- Additional methods may be defined, as specified in [SSH-ARCH] and in
- [SSH-NUMBERS].
-
-6.5. Key Exchange Methods
-
- The key exchange method specifies how one-time session keys are
- generated for encryption and for authentication, and how the server
- authentication is done.
-
- Two REQUIRED key exchange methods have been defined:
-
- diffie-hellman-group1-sha1 REQUIRED
- diffie-hellman-group14-sha1 REQUIRED
-
- These methods are described in Section 8.
-
- Additional methods may be defined as specified in [SSH-NUMBERS]. The
- name "diffie-hellman-group1-sha1" is used for a key exchange method
- using an Oakley group, as defined in [RFC2409]. SSH maintains its
- own group identifier space that is logically distinct from Oakley
- [RFC2412] and IKE; however, for one additional group, the Working
- Group adopted the number assigned by [RFC3526], using diffie-
- hellman-group14-sha1 for the name of the second defined group.
- Implementations should treat these names as opaque identifiers and
- should not assume any relationship between the groups used by SSH and
- the groups defined for IKE.
-
-6.6. Public Key Algorithms
-
- This protocol has been designed to operate with almost any public key
- format, encoding, and algorithm (signature and/or encryption).
-
- There are several aspects that define a public key type:
-
- o Key format: how is the key encoded and how are certificates
- represented. The key blobs in this protocol MAY contain
- certificates in addition to keys.
-
- o Signature and/or encryption algorithms. Some key types may not
- support both signing and encryption. Key usage may also be
- restricted by policy statements (e.g., in certificates). In this
- case, different key types SHOULD be defined for the different
- policy alternatives.
-
- o Encoding of signatures and/or encrypted data. This includes but
- is not limited to padding, byte order, and data formats.
-
-
-
-Ylonen & Lonvick Standards Track [Page 13]
-
-RFC 4253 SSH Transport Layer Protocol January 2006
-
-
- The following public key and/or certificate formats are currently
- defined:
-
- ssh-dss REQUIRED sign Raw DSS Key
- ssh-rsa RECOMMENDED sign Raw RSA Key
- pgp-sign-rsa OPTIONAL sign OpenPGP certificates (RSA key)
- pgp-sign-dss OPTIONAL sign OpenPGP certificates (DSS key)
-
- Additional key types may be defined, as specified in [SSH-ARCH] and
- in [SSH-NUMBERS].
-
- The key type MUST always be explicitly known (from algorithm
- negotiation or some other source). It is not normally included in
- the key blob.
-
- Certificates and public keys are encoded as follows:
-
- string certificate or public key format identifier
- byte[n] key/certificate data
-
- The certificate part may be a zero length string, but a public key is
- required. This is the public key that will be used for
- authentication. The certificate sequence contained in the
- certificate blob can be used to provide authorization.
-
- Public key/certificate formats that do not explicitly specify a
- signature format identifier MUST use the public key/certificate
- format identifier as the signature identifier.
-
- Signatures are encoded as follows:
-
- string signature format identifier (as specified by the
- public key/certificate format)
- byte[n] signature blob in format specific encoding.
-
- The "ssh-dss" key format has the following specific encoding:
-
- string "ssh-dss"
- mpint p
- mpint q
- mpint g
- mpint y
-
- Here, the 'p', 'q', 'g', and 'y' parameters form the signature key
- blob.
-
-
-
-
-
-
-Ylonen & Lonvick Standards Track [Page 14]
-
-RFC 4253 SSH Transport Layer Protocol January 2006
-
-
- Signing and verifying using this key format is done according to the
- Digital Signature Standard [FIPS-186-2] using the SHA-1 hash
- [FIPS-180-2].
-
- The resulting signature is encoded as follows:
-
- string "ssh-dss"
- string dss_signature_blob
-
- The value for 'dss_signature_blob' is encoded as a string containing
- r, followed by s (which are 160-bit integers, without lengths or
- padding, unsigned, and in network byte order).
-
- The "ssh-rsa" key format has the following specific encoding:
-
- string "ssh-rsa"
- mpint e
- mpint n
-
- Here the 'e' and 'n' parameters form the signature key blob.
-
- Signing and verifying using this key format is performed according to
- the RSASSA-PKCS1-v1_5 scheme in [RFC3447] using the SHA-1 hash.
-
- The resulting signature is encoded as follows:
-
- string "ssh-rsa"
- string rsa_signature_blob
-
- The value for 'rsa_signature_blob' is encoded as a string containing
- s (which is an integer, without lengths or padding, unsigned, and in
- network byte order).
-
- The "pgp-sign-rsa" method indicates the certificates, the public key,
- and the signature are in OpenPGP compatible binary format
- ([RFC2440]). This method indicates that the key is an RSA-key.
-
- The "pgp-sign-dss" is as above, but indicates that the key is a
- DSS-key.
-
-7. Key Exchange
-
- Key exchange (kex) begins by each side sending name-lists of
- supported algorithms. Each side has a preferred algorithm in each
- category, and it is assumed that most implementations, at any given
- time, will use the same preferred algorithm. Each side MAY guess
-
-
-
-
-
-Ylonen & Lonvick Standards Track [Page 15]
-
-RFC 4253 SSH Transport Layer Protocol January 2006
-
-
- which algorithm the other side is using, and MAY send an initial key
- exchange packet according to the algorithm, if appropriate for the
- preferred method.
-
- The guess is considered wrong if:
-
- o the kex algorithm and/or the host key algorithm is guessed wrong
- (server and client have different preferred algorithm), or
-
- o if any of the other algorithms cannot be agreed upon (the
- procedure is defined below in Section 7.1).
-
- Otherwise, the guess is considered to be right, and the
- optimistically sent packet MUST be handled as the first key exchange
- packet.
-
- However, if the guess was wrong, and a packet was optimistically sent
- by one or both parties, such packets MUST be ignored (even if the
- error in the guess would not affect the contents of the initial
- packet(s)), and the appropriate side MUST send the correct initial
- packet.
-
- A key exchange method uses explicit server authentication if the key
- exchange messages include a signature or other proof of the server's
- authenticity. A key exchange method uses implicit server
- authentication if, in order to prove its authenticity, the server
- also has to prove that it knows the shared secret, K, by sending a
- message and a corresponding MAC that the client can verify.
-
- The key exchange method defined by this document uses explicit server
- authentication. However, key exchange methods with implicit server
- authentication MAY be used with this protocol. After a key exchange
- with implicit server authentication, the client MUST wait for a
- response to its service request message before sending any further
- data.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Ylonen & Lonvick Standards Track [Page 16]
-
-RFC 4253 SSH Transport Layer Protocol January 2006
-
-
-7.1. Algorithm Negotiation
-
- Key exchange begins by each side sending the following packet:
-
- byte SSH_MSG_KEXINIT
- byte[16] cookie (random bytes)
- name-list kex_algorithms
- name-list server_host_key_algorithms
- name-list encryption_algorithms_client_to_server
- name-list encryption_algorithms_server_to_client
- name-list mac_algorithms_client_to_server
- name-list mac_algorithms_server_to_client
- name-list compression_algorithms_client_to_server
- name-list compression_algorithms_server_to_client
- name-list languages_client_to_server
- name-list languages_server_to_client
- boolean first_kex_packet_follows
- uint32 0 (reserved for future extension)
-
- Each of the algorithm name-lists MUST be a comma-separated list of
- algorithm names (see Algorithm Naming in [SSH-ARCH] and additional
- information in [SSH-NUMBERS]). Each supported (allowed) algorithm
- MUST be listed in order of preference, from most to least.
-
- The first algorithm in each name-list MUST be the preferred (guessed)
- algorithm. Each name-list MUST contain at least one algorithm name.
-
- cookie
- The 'cookie' MUST be a random value generated by the sender.
- Its purpose is to make it impossible for either side to fully
- determine the keys and the session identifier.
-
- kex_algorithms
- Key exchange algorithms were defined above. The first
- algorithm MUST be the preferred (and guessed) algorithm. If
- both sides make the same guess, that algorithm MUST be used.
- Otherwise, the following algorithm MUST be used to choose a key
- exchange method: Iterate over client's kex algorithms, one at a
- time. Choose the first algorithm that satisfies the following
- conditions:
-
- + the server also supports the algorithm,
-
- + if the algorithm requires an encryption-capable host key,
- there is an encryption-capable algorithm on the server's
- server_host_key_algorithms that is also supported by the
- client, and
-
-
-
-
-Ylonen & Lonvick Standards Track [Page 17]
-
-RFC 4253 SSH Transport Layer Protocol January 2006
-
-
- + if the algorithm requires a signature-capable host key,
- there is a signature-capable algorithm on the server's
- server_host_key_algorithms that is also supported by the
- client.
-
- If no algorithm satisfying all these conditions can be found, the
- connection fails, and both sides MUST disconnect.
-
- server_host_key_algorithms
- A name-list of the algorithms supported for the server host
- key. The server lists the algorithms for which it has host
- keys; the client lists the algorithms that it is willing to
- accept. There MAY be multiple host keys for a host, possibly
- with different algorithms.
-
- Some host keys may not support both signatures and encryption
- (this can be determined from the algorithm), and thus not all
- host keys are valid for all key exchange methods.
-
- Algorithm selection depends on whether the chosen key exchange
- algorithm requires a signature or an encryption-capable host
- key. It MUST be possible to determine this from the public key
- algorithm name. The first algorithm on the client's name-list
- that satisfies the requirements and is also supported by the
- server MUST be chosen. If there is no such algorithm, both
- sides MUST disconnect.
-
- encryption_algorithms
- A name-list of acceptable symmetric encryption algorithms (also
- known as ciphers) in order of preference. The chosen
- encryption algorithm to each direction MUST be the first
- algorithm on the client's name-list that is also on the
- server's name-list. If there is no such algorithm, both sides
- MUST disconnect.
-
- Note that "none" must be explicitly listed if it is to be
- acceptable. The defined algorithm names are listed in Section
- 6.3.
-
- mac_algorithms
- A name-list of acceptable MAC algorithms in order of
- preference. The chosen MAC algorithm MUST be the first
- algorithm on the client's name-list that is also on the
- server's name-list. If there is no such algorithm, both sides
- MUST disconnect.
-
- Note that "none" must be explicitly listed if it is to be
- acceptable. The MAC algorithm names are listed in Section 6.4.
-
-
-
-Ylonen & Lonvick Standards Track [Page 18]
-
-RFC 4253 SSH Transport Layer Protocol January 2006
-
-
- compression_algorithms
- A name-list of acceptable compression algorithms in order of
- preference. The chosen compression algorithm MUST be the first
- algorithm on the client's name-list that is also on the
- server's name-list. If there is no such algorithm, both sides
- MUST disconnect.
-
- Note that "none" must be explicitly listed if it is to be
- acceptable. The compression algorithm names are listed in
- Section 6.2.
-
- languages
- This is a name-list of language tags in order of preference
- [RFC3066]. Both parties MAY ignore this name-list. If there
- are no language preferences, this name-list SHOULD be empty as
- defined in Section 5 of [SSH-ARCH]. Language tags SHOULD NOT
- be present unless they are known to be needed by the sending
- party.
-
- first_kex_packet_follows
- Indicates whether a guessed key exchange packet follows. If a
- guessed packet will be sent, this MUST be TRUE. If no guessed
- packet will be sent, this MUST be FALSE.
-
- After receiving the SSH_MSG_KEXINIT packet from the other side,
- each party will know whether their guess was right. If the
- other party's guess was wrong, and this field was TRUE, the
- next packet MUST be silently ignored, and both sides MUST then
- act as determined by the negotiated key exchange method. If
- the guess was right, key exchange MUST continue using the
- guessed packet.
-
- After the SSH_MSG_KEXINIT message exchange, the key exchange
- algorithm is run. It may involve several packet exchanges, as
- specified by the key exchange method.
-
- Once a party has sent a SSH_MSG_KEXINIT message for key exchange or
- re-exchange, until it has sent a SSH_MSG_NEWKEYS message (Section
- 7.3), it MUST NOT send any messages other than:
-
- o Transport layer generic messages (1 to 19) (but
- SSH_MSG_SERVICE_REQUEST and SSH_MSG_SERVICE_ACCEPT MUST NOT be
- sent);
-
- o Algorithm negotiation messages (20 to 29) (but further
- SSH_MSG_KEXINIT messages MUST NOT be sent);
-
- o Specific key exchange method messages (30 to 49).
-
-
-
-Ylonen & Lonvick Standards Track [Page 19]
-
-RFC 4253 SSH Transport Layer Protocol January 2006
-
-
- The provisions of Section 11 apply to unrecognized messages.
-
- Note, however, that during a key re-exchange, after sending a
- SSH_MSG_KEXINIT message, each party MUST be prepared to process an
- arbitrary number of messages that may be in-flight before receiving a
- SSH_MSG_KEXINIT message from the other party.
-
-7.2. Output from Key Exchange
-
- The key exchange produces two values: a shared secret K, and an
- exchange hash H. Encryption and authentication keys are derived from
- these. The exchange hash H from the first key exchange is
- additionally used as the session identifier, which is a unique
- identifier for this connection. It is used by authentication methods
- as a part of the data that is signed as a proof of possession of a
- private key. Once computed, the session identifier is not changed,
- even if keys are later re-exchanged.
-
- Each key exchange method specifies a hash function that is used in
- the key exchange. The same hash algorithm MUST be used in key
- derivation. Here, we'll call it HASH.
-
- Encryption keys MUST be computed as HASH, of a known value and K, as
- follows:
-
- o Initial IV client to server: HASH(K || H || "A" || session_id)
- (Here K is encoded as mpint and "A" as byte and session_id as raw
- data. "A" means the single character A, ASCII 65).
-
- o Initial IV server to client: HASH(K || H || "B" || session_id)
-
- o Encryption key client to server: HASH(K || H || "C" || session_id)
-
- o Encryption key server to client: HASH(K || H || "D" || session_id)
-
- o Integrity key client to server: HASH(K || H || "E" || session_id)
-
- o Integrity key server to client: HASH(K || H || "F" || session_id)
-
- Key data MUST be taken from the beginning of the hash output. As
- many bytes as needed are taken from the beginning of the hash value.
- If the key length needed is longer than the output of the HASH, the
- key is extended by computing HASH of the concatenation of K and H and
- the entire key so far, and appending the resulting bytes (as many as
- HASH generates) to the key. This process is repeated until enough
- key material is available; the key is taken from the beginning of
- this value. In other words:
-
-
-
-
-Ylonen & Lonvick Standards Track [Page 20]
-
-RFC 4253 SSH Transport Layer Protocol January 2006
-
-
- K1 = HASH(K || H || X || session_id) (X is e.g., "A")
- K2 = HASH(K || H || K1)
- K3 = HASH(K || H || K1 || K2)
- ...
- key = K1 || K2 || K3 || ...
-
- This process will lose entropy if the amount of entropy in K is
- larger than the internal state size of HASH.
-
-7.3. Taking Keys Into Use
-
- Key exchange ends by each side sending an SSH_MSG_NEWKEYS message.
- This message is sent with the old keys and algorithms. All messages
- sent after this message MUST use the new keys and algorithms.
-
- When this message is received, the new keys and algorithms MUST be
- used for receiving.
-
- The purpose of this message is to ensure that a party is able to
- respond with an SSH_MSG_DISCONNECT message that the other party can
- understand if something goes wrong with the key exchange.
-
- byte SSH_MSG_NEWKEYS
-
-8. Diffie-Hellman Key Exchange
-
- The Diffie-Hellman (DH) key exchange provides a shared secret that
- cannot be determined by either party alone. The key exchange is
- combined with a signature with the host key to provide host
- authentication. This key exchange method provides explicit server
- authentication as defined in Section 7.
-
- The following steps are used to exchange a key. In this, C is the
- client; S is the server; p is a large safe prime; g is a generator
- for a subgroup of GF(p); q is the order of the subgroup; V_S is S's
- identification string; V_C is C's identification string; K_S is S's
- public host key; I_C is C's SSH_MSG_KEXINIT message and I_S is S's
- SSH_MSG_KEXINIT message that have been exchanged before this part
- begins.
-
- 1. C generates a random number x (1 < x < q) and computes
- e = g^x mod p. C sends e to S.
-
-
-
-
-
-
-
-
-
-Ylonen & Lonvick Standards Track [Page 21]
-
-RFC 4253 SSH Transport Layer Protocol January 2006
-
-
- 2. S generates a random number y (0 < y < q) and computes
- f = g^y mod p. S receives e. It computes K = e^y mod p,
- H = hash(V_C || V_S || I_C || I_S || K_S || e || f || K)
- (these elements are encoded according to their types; see below),
- and signature s on H with its private host key. S sends
- (K_S || f || s) to C. The signing operation may involve a
- second hashing operation.
-
- 3. C verifies that K_S really is the host key for S (e.g., using
- certificates or a local database). C is also allowed to accept
- the key without verification; however, doing so will render the
- protocol insecure against active attacks (but may be desirable for
- practical reasons in the short term in many environments). C then
- computes K = f^x mod p, H = hash(V_C || V_S || I_C || I_S || K_S
- || e || f || K), and verifies the signature s on H.
-
- Values of 'e' or 'f' that are not in the range [1, p-1] MUST NOT be
- sent or accepted by either side. If this condition is violated, the
- key exchange fails.
-
- This is implemented with the following messages. The hash algorithm
- for computing the exchange hash is defined by the method name, and is
- called HASH. The public key algorithm for signing is negotiated with
- the SSH_MSG_KEXINIT messages.
-
- First, the client sends the following:
-
- byte SSH_MSG_KEXDH_INIT
- mpint e
-
- The server then responds with the following:
-
- byte SSH_MSG_KEXDH_REPLY
- string server public host key and certificates (K_S)
- mpint f
- string signature of H
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Ylonen & Lonvick Standards Track [Page 22]
-
-RFC 4253 SSH Transport Layer Protocol January 2006
-
-
- The hash H is computed as the HASH hash of the concatenation of the
- following:
-
- string V_C, the client's identification string (CR and LF
- excluded)
- string V_S, the server's identification string (CR and LF
- excluded)
- string I_C, the payload of the client's SSH_MSG_KEXINIT
- string I_S, the payload of the server's SSH_MSG_KEXINIT
- string K_S, the host key
- mpint e, exchange value sent by the client
- mpint f, exchange value sent by the server
- mpint K, the shared secret
-
- This value is called the exchange hash, and it is used to
- authenticate the key exchange. The exchange hash SHOULD be kept
- secret.
-
- The signature algorithm MUST be applied over H, not the original
- data. Most signature algorithms include hashing and additional
- padding (e.g., "ssh-dss" specifies SHA-1 hashing). In that case, the
- data is first hashed with HASH to compute H, and H is then hashed
- with SHA-1 as part of the signing operation.
-
-8.1. diffie-hellman-group1-sha1
-
- The "diffie-hellman-group1-sha1" method specifies the Diffie-Hellman
- key exchange with SHA-1 as HASH, and Oakley Group 2 [RFC2409] (1024-
- bit MODP Group). This method MUST be supported for interoperability
- as all of the known implementations currently support it. Note that
- this method is named using the phrase "group1", even though it
- specifies the use of Oakley Group 2.
-
-8.2. diffie-hellman-group14-sha1
-
- The "diffie-hellman-group14-sha1" method specifies a Diffie-Hellman
- key exchange with SHA-1 as HASH and Oakley Group 14 [RFC3526] (2048-
- bit MODP Group), and it MUST also be supported.
-
-9. Key Re-Exchange
-
- Key re-exchange is started by sending an SSH_MSG_KEXINIT packet when
- not already doing a key exchange (as described in Section 7.1). When
- this message is received, a party MUST respond with its own
- SSH_MSG_KEXINIT message, except when the received SSH_MSG_KEXINIT
- already was a reply. Either party MAY initiate the re-exchange, but
- roles MUST NOT be changed (i.e., the server remains the server, and
- the client remains the client).
-
-
-
-Ylonen & Lonvick Standards Track [Page 23]
-
-RFC 4253 SSH Transport Layer Protocol January 2006
-
-
- Key re-exchange is performed using whatever encryption was in effect
- when the exchange was started. Encryption, compression, and MAC
- methods are not changed before a new SSH_MSG_NEWKEYS is sent after
- the key exchange (as in the initial key exchange). Re-exchange is
- processed identically to the initial key exchange, except for the
- session identifier that will remain unchanged. It is permissible to
- change some or all of the algorithms during the re-exchange. Host
- keys can also change. All keys and initialization vectors are
- recomputed after the exchange. Compression and encryption contexts
- are reset.
-
- It is RECOMMENDED that the keys be changed after each gigabyte of
- transmitted data or after each hour of connection time, whichever
- comes sooner. However, since the re-exchange is a public key
- operation, it requires a fair amount of processing power and should
- not be performed too often.
-
- More application data may be sent after the SSH_MSG_NEWKEYS packet
- has been sent; key exchange does not affect the protocols that lie
- above the SSH transport layer.
-
-10. Service Request
-
- After the key exchange, the client requests a service. The service
- is identified by a name. The format of names and procedures for
- defining new names are defined in [SSH-ARCH] and [SSH-NUMBERS].
-
- Currently, the following names have been reserved:
-
- ssh-userauth
- ssh-connection
-
- Similar local naming policy is applied to the service names, as is
- applied to the algorithm names. A local service should use the
- PRIVATE USE syntax of "servicename@domain".
-
- byte SSH_MSG_SERVICE_REQUEST
- string service name
-
- If the server rejects the service request, it SHOULD send an
- appropriate SSH_MSG_DISCONNECT message and MUST disconnect.
-
- When the service starts, it may have access to the session identifier
- generated during the key exchange.
-
-
-
-
-
-
-
-Ylonen & Lonvick Standards Track [Page 24]
-
-RFC 4253 SSH Transport Layer Protocol January 2006
-
-
- If the server supports the service (and permits the client to use
- it), it MUST respond with the following:
-
- byte SSH_MSG_SERVICE_ACCEPT
- string service name
-
- Message numbers used by services should be in the area reserved for
- them (see [SSH-ARCH] and [SSH-NUMBERS]). The transport level will
- continue to process its own messages.
-
- Note that after a key exchange with implicit server authentication,
- the client MUST wait for a response to its service request message
- before sending any further data.
-
-11. Additional Messages
-
- Either party may send any of the following messages at any time.
-
-11.1. Disconnection Message
-
- byte SSH_MSG_DISCONNECT
- uint32 reason code
- string description in ISO-10646 UTF-8 encoding [RFC3629]
- string language tag [RFC3066]
-
- This message causes immediate termination of the connection. All
- implementations MUST be able to process this message; they SHOULD be
- able to send this message.
-
- The sender MUST NOT send or receive any data after this message, and
- the recipient MUST NOT accept any data after receiving this message.
- The Disconnection Message 'description' string gives a more specific
- explanation in a human-readable form. The Disconnection Message
- 'reason code' gives the reason in a more machine-readable format
- (suitable for localization), and can have the values as displayed in
- the table below. Note that the decimal representation is displayed
- in this table for readability, but the values are actually uint32
- values.
-
-
-
-
-
-
-
-
-
-
-
-
-
-Ylonen & Lonvick Standards Track [Page 25]
-
-RFC 4253 SSH Transport Layer Protocol January 2006
-
-
- Symbolic name reason code
- ------------- -----------
- SSH_DISCONNECT_HOST_NOT_ALLOWED_TO_CONNECT 1
- SSH_DISCONNECT_PROTOCOL_ERROR 2
- SSH_DISCONNECT_KEY_EXCHANGE_FAILED 3
- SSH_DISCONNECT_RESERVED 4
- SSH_DISCONNECT_MAC_ERROR 5
- SSH_DISCONNECT_COMPRESSION_ERROR 6
- SSH_DISCONNECT_SERVICE_NOT_AVAILABLE 7
- SSH_DISCONNECT_PROTOCOL_VERSION_NOT_SUPPORTED 8
- SSH_DISCONNECT_HOST_KEY_NOT_VERIFIABLE 9
- SSH_DISCONNECT_CONNECTION_LOST 10
- SSH_DISCONNECT_BY_APPLICATION 11
- SSH_DISCONNECT_TOO_MANY_CONNECTIONS 12
- SSH_DISCONNECT_AUTH_CANCELLED_BY_USER 13
- SSH_DISCONNECT_NO_MORE_AUTH_METHODS_AVAILABLE 14
- SSH_DISCONNECT_ILLEGAL_USER_NAME 15
-
- If the 'description' string is displayed, the control character
- filtering discussed in [SSH-ARCH] should be used to avoid attacks by
- sending terminal control characters.
-
- Requests for assignments of new Disconnection Message 'reason code'
- values (and associated 'description' text) in the range of 0x00000010
- to 0xFDFFFFFF MUST be done through the IETF CONSENSUS method, as
- described in [RFC2434]. The Disconnection Message 'reason code'
- values in the range of 0xFE000000 through 0xFFFFFFFF are reserved for
- PRIVATE USE. As noted, the actual instructions to the IANA are in
- [SSH-NUMBERS].
-
-11.2. Ignored Data Message
-
- byte SSH_MSG_IGNORE
- string data
-
- All implementations MUST understand (and ignore) this message at any
- time (after receiving the identification string). No implementation
- is required to send them. This message can be used as an additional
- protection measure against advanced traffic analysis techniques.
-
-11.3. Debug Message
-
- byte SSH_MSG_DEBUG
- boolean always_display
- string message in ISO-10646 UTF-8 encoding [RFC3629]
- string language tag [RFC3066]
-
-
-
-
-
-Ylonen & Lonvick Standards Track [Page 26]
-
-RFC 4253 SSH Transport Layer Protocol January 2006
-
-
- All implementations MUST understand this message, but they are
- allowed to ignore it. This message is used to transmit information
- that may help debugging. If 'always_display' is TRUE, the message
- SHOULD be displayed. Otherwise, it SHOULD NOT be displayed unless
- debugging information has been explicitly requested by the user.
-
- The 'message' doesn't need to contain a newline. It is, however,
- allowed to consist of multiple lines separated by CRLF (Carriage
- Return - Line Feed) pairs.
-
- If the 'message' string is displayed, the terminal control character
- filtering discussed in [SSH-ARCH] should be used to avoid attacks by
- sending terminal control characters.
-
-11.4. Reserved Messages
-
- An implementation MUST respond to all unrecognized messages with an
- SSH_MSG_UNIMPLEMENTED message in the order in which the messages were
- received. Such messages MUST be otherwise ignored. Later protocol
- versions may define other meanings for these message types.
-
- byte SSH_MSG_UNIMPLEMENTED
- uint32 packet sequence number of rejected message
-
-12. Summary of Message Numbers
-
- The following is a summary of messages and their associated message
- number.
-
- SSH_MSG_DISCONNECT 1
- SSH_MSG_IGNORE 2
- SSH_MSG_UNIMPLEMENTED 3
- SSH_MSG_DEBUG 4
- SSH_MSG_SERVICE_REQUEST 5
- SSH_MSG_SERVICE_ACCEPT 6
- SSH_MSG_KEXINIT 20
- SSH_MSG_NEWKEYS 21
-
- Note that numbers 30-49 are used for kex packets. Different kex
- methods may reuse message numbers in this range.
-
-13. IANA Considerations
-
- This document is part of a set. The IANA considerations for the SSH
- protocol as defined in [SSH-ARCH], [SSH-USERAUTH], [SSH-CONNECT], and
- this document, are detailed in [SSH-NUMBERS].
-
-
-
-
-
-Ylonen & Lonvick Standards Track [Page 27]
-
-RFC 4253 SSH Transport Layer Protocol January 2006
-
-
-14. Security Considerations
-
- This protocol provides a secure encrypted channel over an insecure
- network. It performs server host authentication, key exchange,
- encryption, and integrity protection. It also derives a unique
- session ID that may be used by higher-level protocols.
-
- Full security considerations for this protocol are provided in
- [SSH-ARCH].
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Ylonen & Lonvick Standards Track [Page 28]
-
-RFC 4253 SSH Transport Layer Protocol January 2006
-
-
-15. References
-
-15.1. Normative References
-
- [SSH-ARCH] Ylonen, T. and C. Lonvick, Ed., "The Secure Shell
- (SSH) Protocol Architecture", RFC 4251, January 2006.
-
- [SSH-USERAUTH] Ylonen, T. and C. Lonvick, Ed., "The Secure Shell
- (SSH) Authentication Protocol", RFC 4252, January
- 2006.
-
- [SSH-CONNECT] Ylonen, T. and C. Lonvick, Ed., "The Secure Shell
- (SSH) Connection Protocol", RFC 4254, January 2006.
-
- [SSH-NUMBERS] Lehtinen, S. and C. Lonvick, Ed., "The Secure Shell
- (SSH) Protocol Assigned Numbers", RFC 4250, January
- 2006.
-
- [RFC1321] Rivest, R., "The MD5 Message-Digest Algorithm ", RFC
- 1321, April 1992.
-
- [RFC1950] Deutsch, P. and J-L. Gailly, "ZLIB Compressed Data
- Format Specification version 3.3", RFC 1950, May 1996.
-
- [RFC1951] Deutsch, P., "DEFLATE Compressed Data Format
- Specification version 1.3", RFC 1951, May 1996.
-
- [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC:
- Keyed-Hashing for Message Authentication", RFC 2104,
- February 1997.
-
- [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
- Requirement Levels", BCP 14, RFC 2119, March 1997.
-
- [RFC2144] Adams, C., "The CAST-128 Encryption Algorithm", RFC
- 2144, May 1997.
-
- [RFC2409] Harkins, D. and D. Carrel, "The Internet Key Exchange
- (IKE)", RFC 2409, November 1998.
-
- [RFC2434] Narten, T. and H. Alvestrand, "Guidelines for Writing
- an IANA Considerations Section in RFCs", BCP 26, RFC
- 2434, October 1998.
-
- [RFC2440] Callas, J., Donnerhacke, L., Finney, H., and R.
- Thayer, "OpenPGP Message Format", RFC 2440, November
- 1998.
-
-
-
-
-Ylonen & Lonvick Standards Track [Page 29]
-
-RFC 4253 SSH Transport Layer Protocol January 2006
-
-
- [RFC3066] Alvestrand, H., "Tags for the Identification of
- Languages", BCP 47, RFC 3066, January 2001.
-
- [RFC3447] Jonsson, J. and B. Kaliski, "Public-Key Cryptography
- Standards (PKCS) #1: RSA Cryptography Specifications
- Version 2.1", RFC 3447, February 2003.
-
- [RFC3526] Kivinen, T. and M. Kojo, "More Modular Exponential
- (MODP) Diffie-Hellman groups for Internet Key Exchange
- (IKE)", RFC 3526, May 2003.
-
- [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO
- 10646", STD 63, RFC 3629, November 2003.
-
- [FIPS-180-2] US National Institute of Standards and Technology,
- "Secure Hash Standard (SHS)", Federal Information
- Processing Standards Publication 180-2, August 2002.
-
- [FIPS-186-2] US National Institute of Standards and Technology,
- "Digital Signature Standard (DSS)", Federal
- Information Processing Standards Publication 186-2,
- January 2000.
-
- [FIPS-197] US National Institute of Standards and Technology,
- "Advanced Encryption Standard (AES)", Federal
- Information Processing Standards Publication 197,
- November 2001.
-
- [FIPS-46-3] US National Institute of Standards and Technology,
- "Data Encryption Standard (DES)", Federal Information
- Processing Standards Publication 46-3, October 1999.
-
- [SCHNEIER] Schneier, B., "Applied Cryptography Second Edition:
- protocols algorithms and source in code in C", John
- Wiley and Sons, New York, NY, 1996.
-
- [TWOFISH] Schneier, B., "The Twofish Encryptions Algorithm: A
- 128-Bit Block Cipher, 1st Edition", March 1999.
-
-15.2. Informative References
-
- [RFC0894] Hornig, C., "Standard for the transmission of IP
- datagrams over Ethernet networks", STD 41, RFC 894,
- April 1984.
-
- [RFC1661] Simpson, W., "The Point-to-Point Protocol (PPP)", STD
- 51, RFC 1661, July 1994.
-
-
-
-
-Ylonen & Lonvick Standards Track [Page 30]
-
-RFC 4253 SSH Transport Layer Protocol January 2006
-
-
- [RFC2412] Orman, H., "The OAKLEY Key Determination Protocol",
- RFC 2412, November 1998.
-
- [ssh-1.2.30] Ylonen, T., "ssh-1.2.30/RFC", File within compressed
- tarball ftp://ftp.funet.fi/pub/unix/security/
- login/ssh/ssh-1.2.30.tar.gz, November 1995.
-
-Authors' Addresses
-
- Tatu Ylonen
- SSH Communications Security Corp
- Valimotie 17
- 00380 Helsinki
- Finland
-
- EMail: ylo@ssh.com
-
-
- Chris Lonvick (editor)
- Cisco Systems, Inc.
- 12515 Research Blvd.
- Austin 78759
- USA
-
- EMail: clonvick@cisco.com
-
-Trademark Notice
-
- "ssh" is a registered trademark in the United States and/or other
- countries.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Ylonen & Lonvick Standards Track [Page 31]
-
-RFC 4253 SSH Transport Layer Protocol January 2006
-
-
-Full Copyright Statement
-
- Copyright (C) The Internet Society (2006).
-
- This document is subject to the rights, licenses and restrictions
- contained in BCP 78, and except as set forth therein, the authors
- retain all their rights.
-
- This document and the information contained herein are provided on an
- "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
- OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
- ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
- INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
- INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
- WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
-
-Intellectual Property
-
- The IETF takes no position regarding the validity or scope of any
- Intellectual Property Rights or other rights that might be claimed to
- pertain to the implementation or use of the technology described in
- this document or the extent to which any license under such rights
- might or might not be available; nor does it represent that it has
- made any independent effort to identify any such rights. Information
- on the procedures with respect to rights in RFC documents can be
- found in BCP 78 and BCP 79.
-
- Copies of IPR disclosures made to the IETF Secretariat and any
- assurances of licenses to be made available, or the result of an
- attempt made to obtain a general license or permission for the use of
- such proprietary rights by implementers or users of this
- specification can be obtained from the IETF on-line IPR repository at
- http://www.ietf.org/ipr.
-
- The IETF invites any interested party to bring to its attention any
- copyrights, patents or patent applications, or other proprietary
- rights that may cover technology that may be required to implement
- this standard. Please address the information to the IETF at
- ietf-ipr@ietf.org.
-
-Acknowledgement
-
- Funding for the RFC Editor function is provided by the IETF
- Administrative Support Activity (IASA).
-
-
-
-
-
-
-
-Ylonen & Lonvick Standards Track [Page 32]
-
[2/9] Remove third party documents from scm
Posted by gn...@apache.org.
http://git-wip-us.apache.org/repos/asf/mina-sshd/blob/46ea0930/sshd-core/src/docs/rfc4254.txt
----------------------------------------------------------------------
diff --git a/sshd-core/src/docs/rfc4254.txt b/sshd-core/src/docs/rfc4254.txt
deleted file mode 100644
index ebbf4e6..0000000
--- a/sshd-core/src/docs/rfc4254.txt
+++ /dev/null
@@ -1,1347 +0,0 @@
-
-
-
-
-
-
-Network Working Group T. Ylonen
-Request for Comments: 4254 SSH Communications Security Corp
-Category: Standards Track C. Lonvick, Ed.
- Cisco Systems, Inc.
- January 2006
-
-
- The Secure Shell (SSH) Connection Protocol
-
-Status of This Memo
-
- This document specifies an Internet standards track protocol for the
- Internet community, and requests discussion and suggestions for
- improvements. Please refer to the current edition of the "Internet
- Official Protocol Standards" (STD 1) for the standardization state
- and status of this protocol. Distribution of this memo is unlimited.
-
-Copyright Notice
-
- Copyright (C) The Internet Society (2006).
-
-Abstract
-
- Secure Shell (SSH) is a protocol for secure remote login and other
- secure network services over an insecure network.
-
- This document describes the SSH Connection Protocol. It provides
- interactive login sessions, remote execution of commands, forwarded
- TCP/IP connections, and forwarded X11 connections. All of these
- channels are multiplexed into a single encrypted tunnel.
-
- The SSH Connection Protocol has been designed to run on top of the
- SSH transport layer and user authentication protocols.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Ylonen & Lonvick Standards Track [Page 1]
-
-RFC 4254 SSH Connection Protocol January 2006
-
-
-Table of Contents
-
- 1. Introduction ....................................................2
- 2. Contributors ....................................................3
- 3. Conventions Used in This Document ...............................3
- 4. Global Requests .................................................4
- 5. Channel Mechanism ...............................................5
- 5.1. Opening a Channel ..........................................5
- 5.2. Data Transfer ..............................................7
- 5.3. Closing a Channel ..........................................9
- 5.4. Channel-Specific Requests ..................................9
- 6. Interactive Sessions ...........................................10
- 6.1. Opening a Session .........................................10
- 6.2. Requesting a Pseudo-Terminal ..............................11
- 6.3. X11 Forwarding ............................................11
- 6.3.1. Requesting X11 Forwarding ..........................11
- 6.3.2. X11 Channels .......................................12
- 6.4. Environment Variable Passing ..............................12
- 6.5. Starting a Shell or a Command .............................13
- 6.6. Session Data Transfer .....................................14
- 6.7. Window Dimension Change Message ...........................14
- 6.8. Local Flow Control ........................................14
- 6.9. Signals ...................................................15
- 6.10. Returning Exit Status ....................................15
- 7. TCP/IP Port Forwarding .........................................16
- 7.1. Requesting Port Forwarding ................................16
- 7.2. TCP/IP Forwarding Channels ................................18
- 8. Encoding of Terminal Modes .....................................19
- 9. Summary of Message Numbers .....................................21
- 10. IANA Considerations ...........................................21
- 11. Security Considerations .......................................21
- 12. References ....................................................22
- 12.1. Normative References .....................................22
- 12.2. Informative References ...................................22
- Authors' Addresses ................................................23
- Trademark Notice ..................................................23
-
-1. Introduction
-
- The SSH Connection Protocol has been designed to run on top of the
- SSH transport layer and user authentication protocols ([SSH-TRANS]
- and [SSH-USERAUTH]). It provides interactive login sessions, remote
- execution of commands, forwarded TCP/IP connections, and forwarded
- X11 connections.
-
- The 'service name' for this protocol is "ssh-connection".
-
-
-
-
-
-Ylonen & Lonvick Standards Track [Page 2]
-
-RFC 4254 SSH Connection Protocol January 2006
-
-
- This document should be read only after reading the SSH architecture
- document [SSH-ARCH]. This document freely uses terminology and
- notation from the architecture document without reference or further
- explanation.
-
-2. Contributors
-
- The major original contributors of this set of documents have been:
- Tatu Ylonen, Tero Kivinen, Timo J. Rinne, Sami Lehtinen (all of SSH
- Communications Security Corp), and Markku-Juhani O. Saarinen
- (University of Jyvaskyla). Darren Moffat was the original editor of
- this set of documents and also made very substantial contributions.
-
- Many people contributed to the development of this document over the
- years. People who should be acknowledged include Mats Andersson, Ben
- Harris, Bill Sommerfeld, Brent McClure, Niels Moller, Damien Miller,
- Derek Fawcus, Frank Cusack, Heikki Nousiainen, Jakob Schlyter, Jeff
- Van Dyke, Jeffrey Altman, Jeffrey Hutzelman, Jon Bright, Joseph
- Galbraith, Ken Hornstein, Markus Friedl, Martin Forssen, Nicolas
- Williams, Niels Provos, Perry Metzger, Peter Gutmann, Simon
- Josefsson, Simon Tatham, Wei Dai, Denis Bider, der Mouse, and
- Tadayoshi Kohno. Listing their names here does not mean that they
- endorse this document, but that they have contributed to it.
-
-3. Conventions Used in This Document
-
- All documents related to the SSH protocols shall use the keywords
- "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
- "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" to describe
- requirements. These keywords are to be interpreted as described in
- [RFC2119].
-
- The keywords "PRIVATE USE", "HIERARCHICAL ALLOCATION", "FIRST COME
- FIRST SERVED", "EXPERT REVIEW", "SPECIFICATION REQUIRED", "IESG
- APPROVAL", "IETF CONSENSUS", and "STANDARDS ACTION" that appear in
- this document when used to describe namespace allocation are to be
- 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
-
-
-
-
-
-Ylonen & Lonvick Standards Track [Page 3]
-
-RFC 4254 SSH Connection Protocol January 2006
-
-
- 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. Global Requests
-
- There are several kinds of requests that affect the state of the
- remote end globally, independent of any channels. An example is a
- request to start TCP/IP forwarding for a specific port. Note that
- both the client and server MAY send global requests at any time, and
- the receiver MUST respond appropriately. All such requests use the
- following format.
-
- byte SSH_MSG_GLOBAL_REQUEST
- string request name in US-ASCII only
- boolean want reply
- .... request-specific data follows
-
- The value of 'request name' follows the DNS extensibility naming
- convention outlined in [SSH-ARCH].
-
- The recipient will respond to this message with
- SSH_MSG_REQUEST_SUCCESS or SSH_MSG_REQUEST_FAILURE if 'want reply' is
- TRUE.
-
- byte SSH_MSG_REQUEST_SUCCESS
- .... response specific data
-
- Usually, the 'response specific data' is non-existent.
-
- If the recipient does not recognize or support the request, it simply
- responds with SSH_MSG_REQUEST_FAILURE.
-
- byte SSH_MSG_REQUEST_FAILURE
-
- In general, the reply messages do not include request type
- identifiers. To make it possible for the originator of a request to
- identify to which request each reply refers, it is REQUIRED that
- replies to SSH_MSG_GLOBAL_REQUESTS MUST be sent in the same order as
- the corresponding request messages. For channel requests, replies
- that relate to the same channel MUST also be replied to in the right
- order. However, channel requests for distinct channels MAY be
- replied to out-of-order.
-
-
-
-
-
-
-
-Ylonen & Lonvick Standards Track [Page 4]
-
-RFC 4254 SSH Connection Protocol January 2006
-
-
-5. Channel Mechanism
-
- All terminal sessions, forwarded connections, etc., are channels.
- Either side may open a channel. Multiple channels are multiplexed
- into a single connection.
-
- Channels are identified by numbers at each end. The number referring
- to a channel may be different on each side. Requests to open a
- channel contain the sender's channel number. Any other channel-
- related messages contain the recipient's channel number for the
- channel.
-
- Channels are flow-controlled. No data may be sent to a channel until
- a message is received to indicate that window space is available.
-
-5.1. Opening a Channel
-
- When either side wishes to open a new channel, it allocates a local
- number for the channel. It then sends the following message to the
- other side, and includes the local channel number and initial window
- size in the message.
-
- byte SSH_MSG_CHANNEL_OPEN
- string channel type in US-ASCII only
- uint32 sender channel
- uint32 initial window size
- uint32 maximum packet size
- .... channel type specific data follows
-
- The 'channel type' is a name, as described in [SSH-ARCH] and
- [SSH-NUMBERS], with similar extension mechanisms. The 'sender
- channel' is a local identifier for the channel used by the sender of
- this message. The 'initial window size' specifies how many bytes of
- channel data can be sent to the sender of this message without
- adjusting the window. The 'maximum packet size' specifies the
- maximum size of an individual data packet that can be sent to the
- sender. For example, one might want to use smaller packets for
- interactive connections to get better interactive response on slow
- links.
-
- The remote side then decides whether it can open the channel, and
- responds with either SSH_MSG_CHANNEL_OPEN_CONFIRMATION or
- SSH_MSG_CHANNEL_OPEN_FAILURE.
-
-
-
-
-
-
-
-
-Ylonen & Lonvick Standards Track [Page 5]
-
-RFC 4254 SSH Connection Protocol January 2006
-
-
- byte SSH_MSG_CHANNEL_OPEN_CONFIRMATION
- uint32 recipient channel
- uint32 sender channel
- uint32 initial window size
- uint32 maximum packet size
- .... channel type specific data follows
-
- The 'recipient channel' is the channel number given in the original
- open request, and 'sender channel' is the channel number allocated by
- the other side.
-
- byte SSH_MSG_CHANNEL_OPEN_FAILURE
- uint32 recipient channel
- uint32 reason code
- string description in ISO-10646 UTF-8 encoding [RFC3629]
- string language tag [RFC3066]
-
- If the recipient of the SSH_MSG_CHANNEL_OPEN message does not support
- the specified 'channel type', it simply responds with
- SSH_MSG_CHANNEL_OPEN_FAILURE. The client MAY show the 'description'
- string to the user. If this is done, the client software should take
- the precautions discussed in [SSH-ARCH].
-
- The SSH_MSG_CHANNEL_OPEN_FAILURE 'reason code' values are defined in
- the following table. Note that the values for the 'reason code' are
- given in decimal format for readability, but they are actually uint32
- values.
-
- Symbolic name reason code
- ------------- -----------
- SSH_OPEN_ADMINISTRATIVELY_PROHIBITED 1
- SSH_OPEN_CONNECT_FAILED 2
- SSH_OPEN_UNKNOWN_CHANNEL_TYPE 3
- SSH_OPEN_RESOURCE_SHORTAGE 4
-
- Requests for assignments of new SSH_MSG_CHANNEL_OPEN 'reason code'
- values (and associated 'description' text) in the range of 0x00000005
- to 0xFDFFFFFF MUST be done through the IETF CONSENSUS method, as
- described in [RFC2434]. The IANA will not assign Channel Connection
- Failure 'reason code' values in the range of 0xFE000000 to
- 0xFFFFFFFF. Channel Connection Failure 'reason code' values in that
- range are left for PRIVATE USE, as described in [RFC2434].
-
- While it is understood that the IANA will have no control over the
- range of 0xFE000000 to 0xFFFFFFFF, this range will be split in two
- parts and administered by the following conventions.
-
-
-
-
-
-Ylonen & Lonvick Standards Track [Page 6]
-
-RFC 4254 SSH Connection Protocol January 2006
-
-
- o The range of 0xFE000000 to 0xFEFFFFFF is to be used in conjunction
- with locally assigned channels. For example, if a channel is
- proposed with a 'channel type' of "example_session@example.com",
- but fails, then the response will contain either a 'reason code'
- assigned by the IANA (as listed above and in the range of
- 0x00000001 to 0xFDFFFFFF) or a locally assigned value in the range
- of 0xFE000000 to 0xFEFFFFFF. Naturally, if the server does not
- understand the proposed 'channel type', even if it is a locally
- defined 'channel type', then the 'reason code' MUST be 0x00000003,
- as described above, if the 'reason code' is sent. If the server
- does understand the 'channel type', but the channel still fails to
- open, then the server SHOULD respond with a locally assigned
- 'reason code' value consistent with the proposed, local 'channel
- type'. It is assumed that practitioners will first attempt to use
- the IANA assigned 'reason code' values and then document their
- locally assigned 'reason code' values.
-
- o There are no restrictions or suggestions for the range starting
- with 0xFF. No interoperability is expected for anything used in
- this range. Essentially, it is for experimentation.
-
-5.2. Data Transfer
-
- The window size specifies how many bytes the other party can send
- before it must wait for the window to be adjusted. Both parties use
- the following message to adjust the window.
-
- byte SSH_MSG_CHANNEL_WINDOW_ADJUST
- uint32 recipient channel
- uint32 bytes to add
-
- After receiving this message, the recipient MAY send the given number
- of bytes more than it was previously allowed to send; the window size
- is incremented. Implementations MUST correctly handle window sizes
- of up to 2^32 - 1 bytes. The window MUST NOT be increased above
- 2^32 - 1 bytes.
-
- Data transfer is done with messages of the following type.
-
- byte SSH_MSG_CHANNEL_DATA
- uint32 recipient channel
- string data
-
- The maximum amount of data allowed is determined by the maximum
- packet size for the channel, and the current window size, whichever
- is smaller. The window size is decremented by the amount of data
- sent. Both parties MAY ignore all extra data sent after the allowed
- window is empty.
-
-
-
-Ylonen & Lonvick Standards Track [Page 7]
-
-RFC 4254 SSH Connection Protocol January 2006
-
-
- Implementations are expected to have some limit on the SSH transport
- layer packet size (any limit for received packets MUST be 32768 bytes
- or larger, as described in [SSH-TRANS]). The implementation of the
- SSH connection layer
-
- o MUST NOT advertise a maximum packet size that would result in
- transport packets larger than its transport layer is willing to
- receive.
-
- o MUST NOT generate data packets larger than its transport layer is
- willing to send, even if the remote end would be willing to accept
- very large packets.
-
- Additionally, some channels can transfer several types of data. An
- example of this is stderr data from interactive sessions. Such data
- can be passed with SSH_MSG_CHANNEL_EXTENDED_DATA messages, where a
- separate integer specifies the type of data. The available types and
- their interpretation depend on the type of channel.
-
- byte SSH_MSG_CHANNEL_EXTENDED_DATA
- uint32 recipient channel
- uint32 data_type_code
- string data
-
- Data sent with these messages consumes the same window as ordinary
- data.
-
- Currently, only the following type is defined. Note that the value
- for the 'data_type_code' is given in decimal format for readability,
- but the values are actually uint32 values.
-
- Symbolic name data_type_code
- ------------- --------------
- SSH_EXTENDED_DATA_STDERR 1
-
- Extended Channel Data Transfer 'data_type_code' values MUST be
- assigned sequentially. Requests for assignments of new Extended
- Channel Data Transfer 'data_type_code' values and their associated
- Extended Channel Data Transfer 'data' strings, in the range of
- 0x00000002 to 0xFDFFFFFF, MUST be done through the IETF CONSENSUS
- method as described in [RFC2434]. The IANA will not assign Extended
- Channel Data Transfer 'data_type_code' values in the range of
- 0xFE000000 to 0xFFFFFFFF. Extended Channel Data Transfer
- 'data_type_code' values in that range are left for PRIVATE USE, as
- described in [RFC2434]. As is noted, the actual instructions to the
- IANA are in [SSH-NUMBERS].
-
-
-
-
-
-Ylonen & Lonvick Standards Track [Page 8]
-
-RFC 4254 SSH Connection Protocol January 2006
-
-
-5.3. Closing a Channel
-
- When a party will no longer send more data to a channel, it SHOULD
- send SSH_MSG_CHANNEL_EOF.
-
- byte SSH_MSG_CHANNEL_EOF
- uint32 recipient channel
-
- No explicit response is sent to this message. However, the
- application may send EOF to whatever is at the other end of the
- channel. Note that the channel remains open after this message, and
- more data may still be sent in the other direction. This message
- does not consume window space and can be sent even if no window space
- is available.
-
- When either party wishes to terminate the channel, it sends
- SSH_MSG_CHANNEL_CLOSE. Upon receiving this message, a party MUST
- send back an SSH_MSG_CHANNEL_CLOSE unless it has already sent this
- message for the channel. The channel is considered closed for a
- party when it has both sent and received SSH_MSG_CHANNEL_CLOSE, and
- the party may then reuse the channel number. A party MAY send
- SSH_MSG_CHANNEL_CLOSE without having sent or received
- SSH_MSG_CHANNEL_EOF.
-
- byte SSH_MSG_CHANNEL_CLOSE
- uint32 recipient channel
-
- This message does not consume window space and can be sent even if no
- window space is available.
-
- It is RECOMMENDED that all data sent before this message be delivered
- to the actual destination, if possible.
-
-5.4. Channel-Specific Requests
-
- Many 'channel type' values have extensions that are specific to that
- particular 'channel type'. An example is requesting a pty (pseudo
- terminal) for an interactive session.
-
- All channel-specific requests use the following format.
-
- byte SSH_MSG_CHANNEL_REQUEST
- uint32 recipient channel
- string request type in US-ASCII characters only
- boolean want reply
- .... type-specific data follows
-
-
-
-
-
-Ylonen & Lonvick Standards Track [Page 9]
-
-RFC 4254 SSH Connection Protocol January 2006
-
-
- If 'want reply' is FALSE, no response will be sent to the request.
- Otherwise, the recipient responds with either
- SSH_MSG_CHANNEL_SUCCESS, SSH_MSG_CHANNEL_FAILURE, or request-specific
- continuation messages. If the request is not recognized or is not
- supported for the channel, SSH_MSG_CHANNEL_FAILURE is returned.
-
- This message does not consume window space and can be sent even if no
- window space is available. The values of 'request type' are local to
- each channel type.
-
- The client is allowed to send further messages without waiting for
- the response to the request.
-
- 'request type' names follow the DNS extensibility naming convention
- outlined in [SSH-ARCH] and [SSH-NUMBERS].
-
- byte SSH_MSG_CHANNEL_SUCCESS
- uint32 recipient channel
-
-
- byte SSH_MSG_CHANNEL_FAILURE
- uint32 recipient channel
-
- These messages do not consume window space and can be sent even if no
- window space is available.
-
-6. Interactive Sessions
-
- A session is a remote execution of a program. The program may be a
- shell, an application, a system command, or some built-in subsystem.
- It may or may not have a tty, and may or may not involve X11
- forwarding. Multiple sessions can be active simultaneously.
-
-6.1. Opening a Session
-
- A session is started by sending the following message.
-
- byte SSH_MSG_CHANNEL_OPEN
- string "session"
- uint32 sender channel
- uint32 initial window size
- uint32 maximum packet size
-
- Client implementations SHOULD reject any session channel open
- requests to make it more difficult for a corrupt server to attack the
- client.
-
-
-
-
-
-Ylonen & Lonvick Standards Track [Page 10]
-
-RFC 4254 SSH Connection Protocol January 2006
-
-
-6.2. Requesting a Pseudo-Terminal
-
- A pseudo-terminal can be allocated for the session by sending the
- following message.
-
- byte SSH_MSG_CHANNEL_REQUEST
- uint32 recipient channel
- string "pty-req"
- boolean want_reply
- string TERM environment variable value (e.g., vt100)
- uint32 terminal width, characters (e.g., 80)
- uint32 terminal height, rows (e.g., 24)
- uint32 terminal width, pixels (e.g., 640)
- uint32 terminal height, pixels (e.g., 480)
- string encoded terminal modes
-
- The 'encoded terminal modes' are described in Section 8. Zero
- dimension parameters MUST be ignored. The character/row dimensions
- override the pixel dimensions (when nonzero). Pixel dimensions refer
- to the drawable area of the window.
-
- The dimension parameters are only informational.
-
- The client SHOULD ignore pty requests.
-
-6.3. X11 Forwarding
-
-6.3.1. Requesting X11 Forwarding
-
- X11 forwarding may be requested for a session by sending a
- SSH_MSG_CHANNEL_REQUEST message.
-
- byte SSH_MSG_CHANNEL_REQUEST
- uint32 recipient channel
- string "x11-req"
- boolean want reply
- boolean single connection
- string x11 authentication protocol
- string x11 authentication cookie
- uint32 x11 screen number
-
- It is RECOMMENDED that the 'x11 authentication cookie' that is sent
- be a fake, random cookie, and that the cookie be checked and replaced
- by the real cookie when a connection request is received.
-
- X11 connection forwarding should stop when the session channel is
- closed. However, already opened forwardings should not be
- automatically closed when the session channel is closed.
-
-
-
-Ylonen & Lonvick Standards Track [Page 11]
-
-RFC 4254 SSH Connection Protocol January 2006
-
-
- If 'single connection' is TRUE, only a single connection should be
- forwarded. No more connections will be forwarded after the first, or
- after the session channel has been closed.
-
- The 'x11 authentication protocol' is the name of the X11
- authentication method used, e.g., "MIT-MAGIC-COOKIE-1".
-
- The 'x11 authentication cookie' MUST be hexadecimal encoded.
-
- The X Protocol is documented in [SCHEIFLER].
-
-6.3.2. X11 Channels
-
- X11 channels are opened with a channel open request. The resulting
- channels are independent of the session, and closing the session
- channel does not close the forwarded X11 channels.
-
- byte SSH_MSG_CHANNEL_OPEN
- string "x11"
- uint32 sender channel
- uint32 initial window size
- uint32 maximum packet size
- string originator address (e.g., "192.168.7.38")
- uint32 originator port
-
- The recipient should respond with SSH_MSG_CHANNEL_OPEN_CONFIRMATION
- or SSH_MSG_CHANNEL_OPEN_FAILURE.
-
- Implementations MUST reject any X11 channel open requests if they
- have not requested X11 forwarding.
-
-6.4. Environment Variable Passing
-
- Environment variables may be passed to the shell/command to be
- started later. Uncontrolled setting of environment variables in a
- privileged process can be a security hazard. It is recommended that
- implementations either maintain a list of allowable variable names or
- only set environment variables after the server process has dropped
- sufficient privileges.
-
- byte SSH_MSG_CHANNEL_REQUEST
- uint32 recipient channel
- string "env"
- boolean want reply
- string variable name
- string variable value
-
-
-
-
-
-Ylonen & Lonvick Standards Track [Page 12]
-
-RFC 4254 SSH Connection Protocol January 2006
-
-
-6.5. Starting a Shell or a Command
-
- Once the session has been set up, a program is started at the remote
- end. The program can be a shell, an application program, or a
- subsystem with a host-independent name. Only one of these requests
- can succeed per channel.
-
- byte SSH_MSG_CHANNEL_REQUEST
- uint32 recipient channel
- string "shell"
- boolean want reply
-
- This message will request that the user's default shell (typically
- defined in /etc/passwd in UNIX systems) be started at the other end.
-
- byte SSH_MSG_CHANNEL_REQUEST
- uint32 recipient channel
- string "exec"
- boolean want reply
- string command
-
- This message will request that the server start the execution of the
- given command. The 'command' string may contain a path. Normal
- precautions MUST be taken to prevent the execution of unauthorized
- commands.
-
- byte SSH_MSG_CHANNEL_REQUEST
- uint32 recipient channel
- string "subsystem"
- boolean want reply
- string subsystem name
-
- This last form executes a predefined subsystem. It is expected that
- these will include a general file transfer mechanism, and possibly
- other features. Implementations may also allow configuring more such
- mechanisms. As the user's shell is usually used to execute the
- subsystem, it is advisable for the subsystem protocol to have a
- "magic cookie" at the beginning of the protocol transaction to
- distinguish it from arbitrary output generated by shell
- initialization scripts, etc. This spurious output from the shell may
- be filtered out either at the server or at the client.
-
- The server SHOULD NOT halt the execution of the protocol stack when
- starting a shell or a program. All input and output from these
- SHOULD be redirected to the channel or to the encrypted tunnel.
-
- It is RECOMMENDED that the reply to these messages be requested and
- checked. The client SHOULD ignore these messages.
-
-
-
-Ylonen & Lonvick Standards Track [Page 13]
-
-RFC 4254 SSH Connection Protocol January 2006
-
-
- Subsystem names follow the DNS extensibility naming convention
- outlined in [SSH-NUMBERS].
-
-6.6. Session Data Transfer
-
- Data transfer for a session is done using SSH_MSG_CHANNEL_DATA and
- SSH_MSG_CHANNEL_EXTENDED_DATA packets and the window mechanism. The
- extended data type SSH_EXTENDED_DATA_STDERR has been defined for
- stderr data.
-
-6.7. Window Dimension Change Message
-
- When the window (terminal) size changes on the client side, it MAY
- send a message to the other side to inform it of the new dimensions.
-
- byte SSH_MSG_CHANNEL_REQUEST
- uint32 recipient channel
- string "window-change"
- boolean FALSE
- uint32 terminal width, columns
- uint32 terminal height, rows
- uint32 terminal width, pixels
- uint32 terminal height, pixels
-
- A response SHOULD NOT be sent to this message.
-
-6.8. Local Flow Control
-
- On many systems, it is possible to determine if a pseudo-terminal is
- using control-S/control-Q flow control. When flow control is
- allowed, it is often desirable to do the flow control at the client
- end to speed up responses to user requests. This is facilitated by
- the following notification. Initially, the server is responsible for
- flow control. (Here, again, client means the side originating the
- session, and server means the other side.)
-
- The message below is used by the server to inform the client when it
- can or cannot perform flow control (control-S/control-Q processing).
- If 'client can do' is TRUE, the client is allowed to do flow control
- using control-S and control-Q. The client MAY ignore this message.
-
- byte SSH_MSG_CHANNEL_REQUEST
- uint32 recipient channel
- string "xon-xoff"
- boolean FALSE
- boolean client can do
-
- No response is sent to this message.
-
-
-
-Ylonen & Lonvick Standards Track [Page 14]
-
-RFC 4254 SSH Connection Protocol January 2006
-
-
-6.9. Signals
-
- A signal can be delivered to the remote process/service using the
- following message. Some systems may not implement signals, in which
- case they SHOULD ignore this message.
-
- byte SSH_MSG_CHANNEL_REQUEST
- uint32 recipient channel
- string "signal"
- boolean FALSE
- string signal name (without the "SIG" prefix)
-
- 'signal name' values will be encoded as discussed in the passage
- describing SSH_MSG_CHANNEL_REQUEST messages using "exit-signal" in
- this section.
-
-6.10. Returning Exit Status
-
- When the command running at the other end terminates, the following
- message can be sent to return the exit status of the command.
- Returning the status is RECOMMENDED. No acknowledgement is sent for
- this message. The channel needs to be closed with
- SSH_MSG_CHANNEL_CLOSE after this message.
-
- The client MAY ignore these messages.
-
- byte SSH_MSG_CHANNEL_REQUEST
- uint32 recipient channel
- string "exit-status"
- boolean FALSE
- uint32 exit_status
-
- The remote command may also terminate violently due to a signal.
- Such a condition can be indicated by the following message. A zero
- 'exit_status' usually means that the command terminated successfully.
-
- byte SSH_MSG_CHANNEL_REQUEST
- uint32 recipient channel
- string "exit-signal"
- boolean FALSE
- string signal name (without the "SIG" prefix)
- boolean core dumped
- string error message in ISO-10646 UTF-8 encoding
- string language tag [RFC3066]
-
-
-
-
-
-
-
-Ylonen & Lonvick Standards Track [Page 15]
-
-RFC 4254 SSH Connection Protocol January 2006
-
-
- The 'signal name' is one of the following (these are from [POSIX]).
-
- ABRT
- ALRM
- FPE
- HUP
- ILL
- INT
- KILL
- PIPE
- QUIT
- SEGV
- TERM
- USR1
- USR2
-
- Additional 'signal name' values MAY be sent in the format
- "sig-name@xyz", where "sig-name" and "xyz" may be anything a
- particular implementer wants (except the "@" sign). However, it is
- suggested that if a 'configure' script is used, any non-standard
- 'signal name' values it finds be encoded as "SIG@xyz.config.guess",
- where "SIG" is the 'signal name' without the "SIG" prefix, and "xyz"
- is the host type, as determined by "config.guess".
-
- The 'error message' contains an additional textual explanation of the
- error message. The message may consist of multiple lines separated
- by CRLF (Carriage Return - Line Feed) pairs. The client software MAY
- display this message to the user. If this is done, the client
- software should take the precautions discussed in [SSH-ARCH].
-
-7. TCP/IP Port Forwarding
-
-7.1. Requesting Port Forwarding
-
- A party need not explicitly request forwardings from its own end to
- the other direction. However, if it wishes that connections to a
- port on the other side be forwarded to the local side, it must
- explicitly request this.
-
- byte SSH_MSG_GLOBAL_REQUEST
- string "tcpip-forward"
- boolean want reply
- string address to bind (e.g., "0.0.0.0")
- uint32 port number to bind
-
-
-
-
-
-
-
-Ylonen & Lonvick Standards Track [Page 16]
-
-RFC 4254 SSH Connection Protocol January 2006
-
-
- The 'address to bind' and 'port number to bind' specify the IP
- address (or domain name) and port on which connections for forwarding
- are to be accepted. Some strings used for 'address to bind' have
- special-case semantics.
-
- o "" means that connections are to be accepted on all protocol
- families supported by the SSH implementation.
-
- o "0.0.0.0" means to listen on all IPv4 addresses.
-
- o "::" means to listen on all IPv6 addresses.
-
- o "localhost" means to listen on all protocol families supported by
- the SSH implementation on loopback addresses only ([RFC3330] and
- [RFC3513]).
-
- o "127.0.0.1" and "::1" indicate listening on the loopback
- interfaces for IPv4 and IPv6, respectively.
-
- Note that the client can still filter connections based on
- information passed in the open request.
-
- Implementations should only allow forwarding privileged ports if the
- user has been authenticated as a privileged user.
-
- Client implementations SHOULD reject these messages; they are
- normally only sent by the client.
-
- If a client passes 0 as port number to bind and has 'want reply' as
- TRUE, then the server allocates the next available unprivileged port
- number and replies with the following message; otherwise, there is no
- response-specific data.
-
- byte SSH_MSG_REQUEST_SUCCESS
- uint32 port that was bound on the server
-
- A port forwarding can be canceled with the following message. Note
- that channel open requests may be received until a reply to this
- message is received.
-
- byte SSH_MSG_GLOBAL_REQUEST
- string "cancel-tcpip-forward"
- boolean want reply
- string address_to_bind (e.g., "127.0.0.1")
- uint32 port number to bind
-
- Client implementations SHOULD reject these messages; they are
- normally only sent by the client.
-
-
-
-Ylonen & Lonvick Standards Track [Page 17]
-
-RFC 4254 SSH Connection Protocol January 2006
-
-
-7.2. TCP/IP Forwarding Channels
-
- When a connection comes to a port for which remote forwarding has
- been requested, a channel is opened to forward the port to the other
- side.
-
- byte SSH_MSG_CHANNEL_OPEN
- string "forwarded-tcpip"
- uint32 sender channel
- uint32 initial window size
- uint32 maximum packet size
- string address that was connected
- uint32 port that was connected
- string originator IP address
- uint32 originator port
-
- Implementations MUST reject these messages unless they have
- previously requested a remote TCP/IP port forwarding with the given
- port number.
-
- When a connection comes to a locally forwarded TCP/IP port, the
- following packet is sent to the other side. Note that these messages
- MAY also be sent for ports for which no forwarding has been
- explicitly requested. The receiving side must decide whether to
- allow the forwarding.
-
- byte SSH_MSG_CHANNEL_OPEN
- string "direct-tcpip"
- uint32 sender channel
- uint32 initial window size
- uint32 maximum packet size
- string host to connect
- uint32 port to connect
- string originator IP address
- uint32 originator port
-
- The 'host to connect' and 'port to connect' specify the TCP/IP host
- and port where the recipient should connect the channel. The 'host
- to connect' may be either a domain name or a numeric IP address.
-
- The 'originator IP address' is the numeric IP address of the machine
- from where the connection request originates, and the 'originator
- port' is the port on the host from where the connection originated.
-
- Forwarded TCP/IP channels are independent of any sessions, and
- closing a session channel does not in any way imply that forwarded
- connections should be closed.
-
-
-
-
-Ylonen & Lonvick Standards Track [Page 18]
-
-RFC 4254 SSH Connection Protocol January 2006
-
-
- Client implementations SHOULD reject direct TCP/IP open requests for
- security reasons.
-
-8. Encoding of Terminal Modes
-
- All 'encoded terminal modes' (as passed in a pty request) are encoded
- into a byte stream. It is intended that the coding be portable
- across different environments. The stream consists of opcode-
- argument pairs wherein the opcode is a byte value. Opcodes 1 to 159
- have a single uint32 argument. Opcodes 160 to 255 are not yet
- defined, and cause parsing to stop (they should only be used after
- any other data). The stream is terminated by opcode TTY_OP_END
- (0x00).
-
- The client SHOULD put any modes it knows about in the stream, and the
- server MAY ignore any modes it does not know about. This allows some
- degree of machine-independence, at least between systems that use a
- POSIX-like tty interface. The protocol can support other systems as
- well, but the client may need to fill reasonable values for a number
- of parameters so the server pty gets set to a reasonable mode (the
- server leaves all unspecified mode bits in their default values, and
- only some combinations make sense).
-
- The naming of opcode values mostly follows the POSIX terminal mode
- flags. The following opcode values have been defined. Note that the
- values given below are in decimal format for readability, but they
- are actually byte values.
-
- opcode mnemonic description
- ------ -------- -----------
- 0 TTY_OP_END Indicates end of options.
- 1 VINTR Interrupt character; 255 if none. Similarly
- for the other characters. Not all of these
- characters are supported on all systems.
- 2 VQUIT The quit character (sends SIGQUIT signal on
- POSIX systems).
- 3 VERASE Erase the character to left of the cursor.
- 4 VKILL Kill the current input line.
- 5 VEOF End-of-file character (sends EOF from the
- terminal).
- 6 VEOL End-of-line character in addition to
- carriage return and/or linefeed.
- 7 VEOL2 Additional end-of-line character.
- 8 VSTART Continues paused output (normally
- control-Q).
- 9 VSTOP Pauses output (normally control-S).
- 10 VSUSP Suspends the current program.
- 11 VDSUSP Another suspend character.
-
-
-
-Ylonen & Lonvick Standards Track [Page 19]
-
-RFC 4254 SSH Connection Protocol January 2006
-
-
- 12 VREPRINT Reprints the current input line.
- 13 VWERASE Erases a word left of cursor.
- 14 VLNEXT Enter the next character typed literally,
- even if it is a special character
- 15 VFLUSH Character to flush output.
- 16 VSWTCH Switch to a different shell layer.
- 17 VSTATUS Prints system status line (load, command,
- pid, etc).
- 18 VDISCARD Toggles the flushing of terminal output.
- 30 IGNPAR The ignore parity flag. The parameter
- SHOULD be 0 if this flag is FALSE,
- and 1 if it is TRUE.
- 31 PARMRK Mark parity and framing errors.
- 32 INPCK Enable checking of parity errors.
- 33 ISTRIP Strip 8th bit off characters.
- 34 INLCR Map NL into CR on input.
- 35 IGNCR Ignore CR on input.
- 36 ICRNL Map CR to NL on input.
- 37 IUCLC Translate uppercase characters to
- lowercase.
- 38 IXON Enable output flow control.
- 39 IXANY Any char will restart after stop.
- 40 IXOFF Enable input flow control.
- 41 IMAXBEL Ring bell on input queue full.
- 50 ISIG Enable signals INTR, QUIT, [D]SUSP.
- 51 ICANON Canonicalize input lines.
- 52 XCASE Enable input and output of uppercase
- characters by preceding their lowercase
- equivalents with "\".
- 53 ECHO Enable echoing.
- 54 ECHOE Visually erase chars.
- 55 ECHOK Kill character discards current line.
- 56 ECHONL Echo NL even if ECHO is off.
- 57 NOFLSH Don't flush after interrupt.
- 58 TOSTOP Stop background jobs from output.
- 59 IEXTEN Enable extensions.
- 60 ECHOCTL Echo control characters as ^(Char).
- 61 ECHOKE Visual erase for line kill.
- 62 PENDIN Retype pending input.
- 70 OPOST Enable output processing.
- 71 OLCUC Convert lowercase to uppercase.
- 72 ONLCR Map NL to CR-NL.
- 73 OCRNL Translate carriage return to newline
- (output).
- 74 ONOCR Translate newline to carriage
- return-newline (output).
- 75 ONLRET Newline performs a carriage return
- (output).
-
-
-
-Ylonen & Lonvick Standards Track [Page 20]
-
-RFC 4254 SSH Connection Protocol January 2006
-
-
- 90 CS7 7 bit mode.
- 91 CS8 8 bit mode.
- 92 PARENB Parity enable.
- 93 PARODD Odd parity, else even.
-
- 128 TTY_OP_ISPEED Specifies the input baud rate in
- bits per second.
- 129 TTY_OP_OSPEED Specifies the output baud rate in
- bits per second.
-
-9. Summary of Message Numbers
-
- The following is a summary of messages and their associated message
- number.
-
- SSH_MSG_GLOBAL_REQUEST 80
- SSH_MSG_REQUEST_SUCCESS 81
- SSH_MSG_REQUEST_FAILURE 82
- SSH_MSG_CHANNEL_OPEN 90
- SSH_MSG_CHANNEL_OPEN_CONFIRMATION 91
- SSH_MSG_CHANNEL_OPEN_FAILURE 92
- SSH_MSG_CHANNEL_WINDOW_ADJUST 93
- SSH_MSG_CHANNEL_DATA 94
- SSH_MSG_CHANNEL_EXTENDED_DATA 95
- SSH_MSG_CHANNEL_EOF 96
- SSH_MSG_CHANNEL_CLOSE 97
- SSH_MSG_CHANNEL_REQUEST 98
- SSH_MSG_CHANNEL_SUCCESS 99
- SSH_MSG_CHANNEL_FAILURE 100
-
-10. IANA Considerations
-
- This document is part of a set. The IANA considerations for the SSH
- protocol as defined in [SSH-ARCH], [SSH-TRANS], [SSH-USERAUTH], and
- this document, are detailed in [SSH-NUMBERS].
-
-11. Security Considerations
-
- This protocol is assumed to run on top of a secure, authenticated
- transport. User authentication and protection against network-level
- attacks are assumed to be provided by the underlying protocols.
-
- Full security considerations for this protocol are provided in
- [SSH-ARCH]. Specific to this document, it is RECOMMENDED that
- implementations disable all the potentially dangerous features (e.g.,
- agent forwarding, X11 forwarding, and TCP/IP forwarding) if the host
- key has changed without notice or explanation.
-
-
-
-
-Ylonen & Lonvick Standards Track [Page 21]
-
-RFC 4254 SSH Connection Protocol January 2006
-
-
-12. References
-
-12.1. Normative References
-
- [SSH-ARCH] Ylonen, T. and C. Lonvick, Ed., "The Secure Shell
- (SSH) Protocol Architecture", RFC 4251, January 2006.
-
- [SSH-TRANS] Ylonen, T. and C. Lonvick, Ed., "The Secure Shell
- (SSH) Transport Layer Protocol", RFC 4253, January
- 2006.
-
- [SSH-USERAUTH] Ylonen, T. and C. Lonvick, Ed., "The Secure Shell
- (SSH) Authentication Protocol", RFC 4252, January
- 2006.
-
- [SSH-NUMBERS] Lehtinen, S. and C. Lonvick, Ed., "The Secure Shell
- (SSH) Protocol Assigned Numbers", RFC 4250, January
- 2006.
-
- [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
- Requirement Levels", BCP 14, RFC 2119, March 1997.
-
- [RFC2434] Narten, T. and H. Alvestrand, "Guidelines for Writing
- an IANA Considerations Section in RFCs", BCP 26, RFC
- 2434, October 1998.
-
- [RFC3066] Alvestrand, H., "Tags for the Identification of
- Languages", BCP 47, RFC 3066, January 2001.
-
- [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO
- 10646", STD 63, RFC 3629, November 2003.
-
-12.2. Informative References
-
- [RFC3330] IANA, "Special-Use IPv4 Addresses", RFC 3330,
- September 2002.
-
- [RFC3513] Hinden, R. and S. Deering, "Internet Protocol Version
- 6 (IPv6) Addressing Architecture", RFC 3513, April
- 2003.
-
- [SCHEIFLER] Scheifler, R., "X Window System : The Complete
- Reference to Xlib, X Protocol, Icccm, Xlfd, 3rd
- edition.", Digital Press ISBN 1555580882, February
- 1992.
-
-
-
-
-
-
-Ylonen & Lonvick Standards Track [Page 22]
-
-RFC 4254 SSH Connection Protocol January 2006
-
-
- [POSIX] ISO/IEC, 9945-1., "Information technology -- Portable
- Operating System Interface (POSIX)-Part 1: System
- Application Program Interface (API) C Language", ANSI/
- IEE Std 1003.1, July 1996.
-
-Authors' Addresses
-
- Tatu Ylonen
- SSH Communications Security Corp
- Valimotie 17
- 00380 Helsinki
- Finland
-
- EMail: ylo@ssh.com
-
-
- Chris Lonvick (editor)
- Cisco Systems, Inc.
- 12515 Research Blvd.
- Austin 78759
- USA
-
- EMail: clonvick@cisco.com
-
-Trademark Notice
-
- "ssh" is a registered trademark in the United States and/or other
- countries.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Ylonen & Lonvick Standards Track [Page 23]
-
-RFC 4254 SSH Connection Protocol January 2006
-
-
-Full Copyright Statement
-
- Copyright (C) The Internet Society (2006).
-
- This document is subject to the rights, licenses and restrictions
- contained in BCP 78, and except as set forth therein, the authors
- retain all their rights.
-
- This document and the information contained herein are provided on an
- "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
- OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
- ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
- INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
- INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
- WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
-
-Intellectual Property
-
- The IETF takes no position regarding the validity or scope of any
- Intellectual Property Rights or other rights that might be claimed to
- pertain to the implementation or use of the technology described in
- this document or the extent to which any license under such rights
- might or might not be available; nor does it represent that it has
- made any independent effort to identify any such rights. Information
- on the procedures with respect to rights in RFC documents can be
- found in BCP 78 and BCP 79.
-
- Copies of IPR disclosures made to the IETF Secretariat and any
- assurances of licenses to be made available, or the result of an
- attempt made to obtain a general license or permission for the use of
- such proprietary rights by implementers or users of this
- specification can be obtained from the IETF on-line IPR repository at
- http://www.ietf.org/ipr.
-
- The IETF invites any interested party to bring to its attention any
- copyrights, patents or patent applications, or other proprietary
- rights that may cover technology that may be required to implement
- this standard. Please address the information to the IETF at
- ietf-ipr@ietf.org.
-
-Acknowledgement
-
- Funding for the RFC Editor function is provided by the IETF
- Administrative Support Activity (IASA).
-
-
-
-
-
-
-
-Ylonen & Lonvick Standards Track [Page 24]
-
http://git-wip-us.apache.org/repos/asf/mina-sshd/blob/46ea0930/sshd-core/src/docs/rfc4255.txt
----------------------------------------------------------------------
diff --git a/sshd-core/src/docs/rfc4255.txt b/sshd-core/src/docs/rfc4255.txt
deleted file mode 100644
index f350b7a..0000000
--- a/sshd-core/src/docs/rfc4255.txt
+++ /dev/null
@@ -1,507 +0,0 @@
-
-
-
-
-
-
-Network Working Group J. Schlyter
-Request for Comments: 4255 OpenSSH
-Category: Standards Track W. Griffin
- SPARTA
- January 2006
-
-
- Using DNS to Securely Publish Secure Shell (SSH) Key Fingerprints
-
-Status of This Memo
-
- This document specifies an Internet standards track protocol for the
- Internet community, and requests discussion and suggestions for
- improvements. Please refer to the current edition of the "Internet
- Official Protocol Standards" (STD 1) for the standardization state
- and status of this protocol. Distribution of this memo is unlimited.
-
-Copyright Notice
-
- Copyright (C) The Internet Society (2006).
-
-Abstract
-
- This document describes a method of verifying Secure Shell (SSH) host
- keys using Domain Name System Security (DNSSEC). The document
- defines a new DNS resource record that contains a standard SSH key
- fingerprint.
-
-Table of Contents
-
- 1. Introduction ....................................................2
- 2. SSH Host Key Verification .......................................2
- 2.1. Method .....................................................2
- 2.2. Implementation Notes .......................................2
- 2.3. Fingerprint Matching .......................................3
- 2.4. Authentication .............................................3
- 3. The SSHFP Resource Record .......................................3
- 3.1. The SSHFP RDATA Format .....................................4
- 3.1.1. Algorithm Number Specification ......................4
- 3.1.2. Fingerprint Type Specification ......................4
- 3.1.3. Fingerprint .........................................5
- 3.2. Presentation Format of the SSHFP RR ........................5
- 4. Security Considerations .........................................5
- 5. IANA Considerations .............................................6
- 6. Normative References ............................................7
- 7. Informational References ........................................7
- 8. Acknowledgements ................................................8
-
-
-
-
-Schlyter & Griffin Standards Track [Page 1]
-
-RFC 4255 DNS and SSH Fingerprints January 2006
-
-
-1. Introduction
-
- The SSH [6] protocol provides secure remote login and other secure
- network services over an insecure network. The security of the
- connection relies on the server authenticating itself to the client
- as well as the user authenticating itself to the server.
-
- If a connection is established to a server whose public key is not
- already known to the client, a fingerprint of the key is presented to
- the user for verification. If the user decides that the fingerprint
- is correct and accepts the key, the key is saved locally and used for
- verification for all following connections. While some security-
- conscious users verify the fingerprint out-of-band before accepting
- the key, many users blindly accept the presented key.
-
- The method described here can provide out-of-band verification by
- looking up a fingerprint of the server public key in the DNS [1][2]
- and using DNSSEC [5] to verify the lookup.
-
- In order to distribute the fingerprint using DNS, this document
- defines a new DNS resource record, "SSHFP", to carry the fingerprint.
-
- Basic understanding of the DNS system [1][2] and the DNS security
- extensions [5] is assumed by this document.
-
- The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
- "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
- document are to be interpreted as described in RFC 2119 [3].
-
-2. SSH Host Key Verification
-
-2.1. Method
-
- Upon connection to an SSH server, the SSH client MAY look up the
- SSHFP resource record(s) for the host it is connecting to. If the
- algorithm and fingerprint of the key received from the SSH server
- match the algorithm and fingerprint of one of the SSHFP resource
- record(s) returned from DNS, the client MAY accept the identity of
- the server.
-
-2.2. Implementation Notes
-
- Client implementors SHOULD provide a configurable policy used to
- select the order of methods used to verify a host key. This document
- defines one method: Fingerprint storage in DNS. Another method
- defined in the SSH Architecture [6] uses local files to store keys
- for comparison. Other methods that could be defined in the future
- might include storing fingerprints in LDAP or other databases. A
-
-
-
-Schlyter & Griffin Standards Track [Page 2]
-
-RFC 4255 DNS and SSH Fingerprints January 2006
-
-
- configurable policy will allow administrators to determine which
- methods they want to use and in what order the methods should be
- prioritized. This will allow administrators to determine how much
- trust they want to place in the different methods.
-
- One specific scenario for having a configurable policy is where
- clients do not use fully qualified host names to connect to servers.
- In this scenario, the implementation SHOULD verify the host key
- against a local database before verifying the key via the fingerprint
- returned from DNS. This would help prevent an attacker from
- injecting a DNS search path into the local resolver and forcing the
- client to connect to a different host.
-
-2.3. Fingerprint Matching
-
- The public key and the SSHFP resource record are matched together by
- comparing algorithm number and fingerprint.
-
- The public key algorithm and the SSHFP algorithm number MUST
- match.
-
- A message digest of the public key, using the message digest
- algorithm specified in the SSHFP fingerprint type, MUST match the
- SSHFP fingerprint.
-
-2.4. Authentication
-
- A public key verified using this method MUST NOT be trusted if the
- SSHFP resource record (RR) used for verification was not
- authenticated by a trusted SIG RR.
-
- Clients that do validate the DNSSEC signatures themselves SHOULD use
- standard DNSSEC validation procedures.
-
- Clients that do not validate the DNSSEC signatures themselves MUST
- use a secure transport (e.g., TSIG [9], SIG(0) [10], or IPsec [8])
- between themselves and the entity performing the signature
- validation.
-
-3. The SSHFP Resource Record
-
- The SSHFP resource record (RR) is used to store a fingerprint of an
- SSH public host key that is associated with a Domain Name System
- (DNS) name.
-
- The RR type code for the SSHFP RR is 44.
-
-
-
-
-
-Schlyter & Griffin Standards Track [Page 3]
-
-RFC 4255 DNS and SSH Fingerprints January 2006
-
-
-3.1. The SSHFP RDATA Format
-
- The RDATA for a SSHFP RR consists of an algorithm number, fingerprint
- type and the fingerprint of the public host key.
-
- 1 1 1 1 1 1 1 1 1 1 2 2 2 2 2 2 2 2 2 2 3 3
- 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | algorithm | fp type | /
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ /
- / /
- / fingerprint /
- / /
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
-
-3.1.1. Algorithm Number Specification
-
- This algorithm number octet describes the algorithm of the public
- key. The following values are assigned:
-
- Value Algorithm name
- ----- --------------
- 0 reserved
- 1 RSA
- 2 DSS
-
- Reserving other types requires IETF consensus [4].
-
-3.1.2. Fingerprint Type Specification
-
- The fingerprint type octet describes the message-digest algorithm
- used to calculate the fingerprint of the public key. The following
- values are assigned:
-
- Value Fingerprint type
- ----- ----------------
- 0 reserved
- 1 SHA-1
-
- Reserving other types requires IETF consensus [4].
-
- For interoperability reasons, as few fingerprint types as possible
- should be reserved. The only reason to reserve additional types is
- to increase security.
-
-
-
-
-
-
-
-Schlyter & Griffin Standards Track [Page 4]
-
-RFC 4255 DNS and SSH Fingerprints January 2006
-
-
-3.1.3. Fingerprint
-
- The fingerprint is calculated over the public key blob as described
- in [7].
-
- The message-digest algorithm is presumed to produce an opaque octet
- string output, which is placed as-is in the RDATA fingerprint field.
-
-3.2. Presentation Format of the SSHFP RR
-
- The RDATA of the presentation format of the SSHFP resource record
- consists of two numbers (algorithm and fingerprint type) followed by
- the fingerprint itself, presented in hex, e.g.:
-
- host.example. SSHFP 2 1 123456789abcdef67890123456789abcdef67890
-
- The use of mnemonics instead of numbers is not allowed.
-
-4. Security Considerations
-
- Currently, the amount of trust a user can realistically place in a
- server key is proportional to the amount of attention paid to
- verifying that the public key presented actually corresponds to the
- private key of the server. If a user accepts a key without verifying
- the fingerprint with something learned through a secured channel, the
- connection is vulnerable to a man-in-the-middle attack.
-
- The overall security of using SSHFP for SSH host key verification is
- dependent on the security policies of the SSH host administrator and
- DNS zone administrator (in transferring the fingerprint), detailed
- aspects of how verification is done in the SSH implementation, and in
- the client's diligence in accessing the DNS in a secure manner.
-
- One such aspect is in which order fingerprints are looked up (e.g.,
- first checking local file and then SSHFP). We note that, in addition
- to protecting the first-time transfer of host keys, SSHFP can
- optionally be used for stronger host key protection.
-
- If SSHFP is checked first, new SSH host keys may be distributed by
- replacing the corresponding SSHFP in DNS.
-
- If SSH host key verification can be configured to require SSHFP,
- SSH host key revocation can be implemented by removing the
- corresponding SSHFP from DNS.
-
-
-
-
-
-
-
-Schlyter & Griffin Standards Track [Page 5]
-
-RFC 4255 DNS and SSH Fingerprints January 2006
-
-
- As stated in Section 2.2, we recommend that SSH implementors provide
- a policy mechanism to control the order of methods used for host key
- verification. One specific scenario for having a configurable policy
- is where clients use unqualified host names to connect to servers.
- In this case, we recommend that SSH implementations check the host
- key against a local database before verifying the key via the
- fingerprint returned from DNS. This would help prevent an attacker
- from injecting a DNS search path into the local resolver and forcing
- the client to connect to a different host.
-
- A different approach to solve the DNS search path issue would be for
- clients to use a trusted DNS search path, i.e., one not acquired
- through DHCP or other autoconfiguration mechanisms. Since there is
- no way with current DNS lookup APIs to tell whether a search path is
- from a trusted source, the entire client system would need to be
- configured with this trusted DNS search path.
-
- Another dependency is on the implementation of DNSSEC itself. As
- stated in Section 2.4, we mandate the use of secure methods for
- lookup and that SSHFP RRs are authenticated by trusted SIG RRs. This
- is especially important if SSHFP is to be used as a basis for host
- key rollover and/or revocation, as described above.
-
- Since DNSSEC only protects the integrity of the host key fingerprint
- after it is signed by the DNS zone administrator, the fingerprint
- must be transferred securely from the SSH host administrator to the
- DNS zone administrator. This could be done manually between the
- administrators or automatically using secure DNS dynamic update [11]
- between the SSH server and the nameserver. We note that this is no
- different from other key enrollment situations, e.g., a client
- sending a certificate request to a certificate authority for signing.
-
-5. IANA Considerations
-
- IANA has allocated the RR type code 44 for SSHFP from the standard RR
- type space.
-
- IANA has opened a new registry for the SSHFP RR type for public key
- algorithms. The defined types are:
-
- 0 is reserved
- 1 is RSA
- 2 is DSA
-
- Adding new reservations requires IETF consensus [4].
-
-
-
-
-
-
-Schlyter & Griffin Standards Track [Page 6]
-
-RFC 4255 DNS and SSH Fingerprints January 2006
-
-
- IANA has opened a new registry for the SSHFP RR type for fingerprint
- types. The defined types are:
-
- 0 is reserved
- 1 is SHA-1
-
- Adding new reservations requires IETF consensus [4].
-
-6. Normative References
-
- [1] Mockapetris, P., "Domain names - concepts and facilities", STD
- 13, RFC 1034, November 1987.
-
- [2] Mockapetris, P., "Domain names - implementation and
- specification", STD 13, RFC 1035, November 1987.
-
- [3] Bradner, S., "Key words for use in RFCs to Indicate Requirement
- Levels", BCP 14, RFC 2119, March 1997.
-
- [4] Narten, T. and H. Alvestrand, "Guidelines for Writing an IANA
- Considerations Section in RFCs", BCP 26, RFC 2434, October
- 1998.
-
- [5] Arends, R., Austein, R., Larson, M., Massey, D., and S. Rose,
- "DNS Security Introduction and Requirements", RFC 4033, March
- 2005.
-
- Arends, R., Austein, R., Larson, M., Massey, D., and S. Rose,
- "Resource Records for the DNS Security Extensions", RFC 4034,
- March 2005.
-
- Arends, R., Austein, R., Larson, M., Massey, D., and S. Rose,
- "Protocol Modifications for the DNS Security Extensions", RFC
- 4035, March 2005.
-
- [6] Ylonen, T. and C. Lonvick, Ed., "The Secure Shell (SSH)
- Protocol Architecture", RFC 4251, January 2006.
-
- [7] Ylonen, T. and C. Lonvick, Ed., "The Secure Shell (SSH)
- Transport Layer Protocol", RFC 4253, January 2006.
-
-7. Informational References
-
- [8] Thayer, R., Doraswamy, N., and R. Glenn, "IP Security Document
- Roadmap", RFC 2411, November 1998.
-
-
-
-
-
-
-Schlyter & Griffin Standards Track [Page 7]
-
-RFC 4255 DNS and SSH Fingerprints January 2006
-
-
- [9] Vixie, P., Gudmundsson, O., Eastlake 3rd, D., and B.
- Wellington, "Secret Key Transaction Authentication for DNS
- (TSIG)", RFC 2845, May 2000.
-
- [10] Eastlake 3rd, D., "DNS Request and Transaction Signatures
- ( SIG(0)s )", RFC 2931, September 2000.
-
- [11] Wellington, B., "Secure Domain Name System (DNS) Dynamic
- Update", RFC 3007, November 2000.
-
-8. Acknowledgements
-
- The authors gratefully acknowledge, in no particular order, the
- contributions of the following persons:
-
- Martin Fredriksson
-
- Olafur Gudmundsson
-
- Edward Lewis
-
- Bill Sommerfeld
-
-Authors' Addresses
-
- Jakob Schlyter
- OpenSSH
- 812 23rd Avenue SE
- Calgary, Alberta T2G 1N8
- Canada
-
- EMail: jakob@openssh.com
- URI: http://www.openssh.com/
-
-
- Wesley Griffin
- SPARTA
- 7075 Samuel Morse Drive
- Columbia, MD 21046
- USA
-
- EMail: wgriffin@sparta.com
- URI: http://www.sparta.com/
-
-
-
-
-
-
-
-
-Schlyter & Griffin Standards Track [Page 8]
-
-RFC 4255 DNS and SSH Fingerprints January 2006
-
-
-Full Copyright Statement
-
- Copyright (C) The Internet Society (2006).
-
- This document is subject to the rights, licenses and restrictions
- contained in BCP 78, and except as set forth therein, the authors
- retain all their rights.
-
- This document and the information contained herein are provided on an
- "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
- OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
- ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
- INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
- INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
- WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
-
-Intellectual Property
-
- The IETF takes no position regarding the validity or scope of any
- Intellectual Property Rights or other rights that might be claimed to
- pertain to the implementation or use of the technology described in
- this document or the extent to which any license under such rights
- might or might not be available; nor does it represent that it has
- made any independent effort to identify any such rights. Information
- on the procedures with respect to rights in RFC documents can be
- found in BCP 78 and BCP 79.
-
- Copies of IPR disclosures made to the IETF Secretariat and any
- assurances of licenses to be made available, or the result of an
- attempt made to obtain a general license or permission for the use of
- such proprietary rights by implementers or users of this
- specification can be obtained from the IETF on-line IPR repository at
- http://www.ietf.org/ipr.
-
- The IETF invites any interested party to bring to its attention any
- copyrights, patents or patent applications, or other proprietary
- rights that may cover technology that may be required to implement
- this standard. Please address the information to the IETF at
- ietf-ipr@ietf.org.
-
-Acknowledgement
-
- Funding for the RFC Editor function is provided by the IETF
- Administrative Support Activity (IASA).
-
-
-
-
-
-
-
-Schlyter & Griffin Standards Track [Page 9]
-
[6/9] Remove third party documents from scm
Posted by gn...@apache.org.
http://git-wip-us.apache.org/repos/asf/mina-sshd/blob/46ea0930/sshd-core/src/docs/draft-ietf-secsh-filexfer-13.txt
----------------------------------------------------------------------
diff --git a/sshd-core/src/docs/draft-ietf-secsh-filexfer-13.txt b/sshd-core/src/docs/draft-ietf-secsh-filexfer-13.txt
deleted file mode 100644
index 819d870..0000000
--- a/sshd-core/src/docs/draft-ietf-secsh-filexfer-13.txt
+++ /dev/null
@@ -1,3362 +0,0 @@
-
-
-
-
-Secure Shell Working Group J. Galbraith
-Internet-Draft VanDyke Software
-Expires: January 11, 2007 O. Saarenmaa
- F-Secure
- July 10, 2006
-
-
- SSH File Transfer Protocol
- draft-ietf-secsh-filexfer-13.txt
-
-Status of this Memo
-
- By submitting this Internet-Draft, each 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 becomes
- aware will be disclosed, in accordance with Section 6 of BCP 79.
-
- Internet-Drafts are working documents of the Internet Engineering
- Task Force (IETF), its areas, and its working groups. Note that
- other groups may also distribute working documents as Internet-
- Drafts.
-
- Internet-Drafts are draft documents valid for a maximum of six months
- and may be updated, replaced, or obsoleted by other documents at any
- time. It is inappropriate to use Internet-Drafts as reference
- material or to cite them other than as "work in progress."
-
- The list of current Internet-Drafts can be accessed at
- http://www.ietf.org/ietf/1id-abstracts.txt.
-
- The list of Internet-Draft Shadow Directories can be accessed at
- http://www.ietf.org/shadow.html.
-
- This Internet-Draft will expire on January 11, 2007.
-
-Copyright Notice
-
- Copyright (C) The Internet Society (2006).
-
-Abstract
-
- The SSH File Transfer Protocol provides secure file transfer
- functionality over any reliable, bidirectional octect stream. It is
- the standard file transfer protocol for use with the SSH2 protocol.
- This document describes the file transfer protocol and its interface
- to the SSH2 protocol suite.
-
-
-
-
-
-Galbraith & Saarenmaa Expires January 11, 2007 [Page 1]
-
-Internet-Draft SSH File Transfer Protocol July 2006
-
-
-Table of Contents
-
- 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4
- 2. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 4
- 3. Use with the SSH Connection Protocol . . . . . . . . . . . . . 4
- 3.1. The Use of 'stderr' in the server . . . . . . . . . . . . 5
- 4. General Packet Format . . . . . . . . . . . . . . . . . . . . 5
- 4.1. Request Synchronization and Reordering . . . . . . . . . . 6
- 4.2. New data types defined by this document . . . . . . . . . 7
- 4.3. Packet Types . . . . . . . . . . . . . . . . . . . . . . . 7
- 5. Protocol Initialization . . . . . . . . . . . . . . . . . . . 9
- 5.1. Client Initialization . . . . . . . . . . . . . . . . . . 9
- 5.2. Server Initialization . . . . . . . . . . . . . . . . . . 9
- 5.3. Determining Server Newline Convention . . . . . . . . . . 10
- 5.4. Supported Features . . . . . . . . . . . . . . . . . . . . 10
- 5.5. Version re-negotiation . . . . . . . . . . . . . . . . . . 14
- 6. File Names . . . . . . . . . . . . . . . . . . . . . . . . . . 15
- 7. File Attributes . . . . . . . . . . . . . . . . . . . . . . . 16
- 7.1. valid-attribute-flags . . . . . . . . . . . . . . . . . . 17
- 7.2. Type . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
- 7.3. Size . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
- 7.4. allocation-size . . . . . . . . . . . . . . . . . . . . . 19
- 7.5. Owner and Group . . . . . . . . . . . . . . . . . . . . . 19
- 7.6. Permissions . . . . . . . . . . . . . . . . . . . . . . . 20
- 7.7. Times . . . . . . . . . . . . . . . . . . . . . . . . . . 21
- 7.8. ACL . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
- 7.9. attrib-bits and attrib-bits-valid . . . . . . . . . . . . 24
- 7.10. text-hint . . . . . . . . . . . . . . . . . . . . . . . . 27
- 7.11. mime-type . . . . . . . . . . . . . . . . . . . . . . . . 27
- 7.12. link-count . . . . . . . . . . . . . . . . . . . . . . . . 27
- 7.13. untranslated-name . . . . . . . . . . . . . . . . . . . . 28
- 7.14. Extended Attributes . . . . . . . . . . . . . . . . . . . 28
- 8. Requests From the Client to the Server . . . . . . . . . . . . 28
- 8.1. Opening and Closing Files and Directories . . . . . . . . 28
- 8.1.1. Opening a File . . . . . . . . . . . . . . . . . . . . 29
- 8.1.2. Opening a Directory . . . . . . . . . . . . . . . . . 35
- 8.1.3. Closing Handles . . . . . . . . . . . . . . . . . . . 35
- 8.2. Reading and Writing . . . . . . . . . . . . . . . . . . . 36
- 8.2.1. Reading Files . . . . . . . . . . . . . . . . . . . . 36
- 8.2.2. Reading Directories . . . . . . . . . . . . . . . . . 37
- 8.2.3. Writing Files . . . . . . . . . . . . . . . . . . . . 37
- 8.3. Removing and Renaming Files . . . . . . . . . . . . . . . 38
- 8.4. Creating and Deleting Directories . . . . . . . . . . . . 39
- 8.5. Retrieving File Attributes . . . . . . . . . . . . . . . . 40
- 8.6. Setting File Attributes . . . . . . . . . . . . . . . . . 41
- 8.7. Dealing with Links . . . . . . . . . . . . . . . . . . . . 42
- 8.8. Byte-range locks . . . . . . . . . . . . . . . . . . . . . 43
- 8.8.1. Obtaining a byte range lock . . . . . . . . . . . . . 43
-
-
-
-Galbraith & Saarenmaa Expires January 11, 2007 [Page 2]
-
-Internet-Draft SSH File Transfer Protocol July 2006
-
-
- 8.8.2. Releasing a byte range lock . . . . . . . . . . . . . 44
- 8.9. Canonicalizing the Server-Side Path Name . . . . . . . . . 45
- 8.9.1. Best Practice for Dealing with Paths . . . . . . . . . 46
- 9. Responses from the Server to the Client . . . . . . . . . . . 47
- 9.1. Status Response . . . . . . . . . . . . . . . . . . . . . 48
- 9.2. Handle Response . . . . . . . . . . . . . . . . . . . . . 52
- 9.3. Data Response . . . . . . . . . . . . . . . . . . . . . . 52
- 9.4. Name Response . . . . . . . . . . . . . . . . . . . . . . 53
- 9.5. Attrs Response . . . . . . . . . . . . . . . . . . . . . . 53
- 10. Extensions . . . . . . . . . . . . . . . . . . . . . . . . . . 54
- 11. Implementation Considerations . . . . . . . . . . . . . . . . 55
- 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 55
- 13. Security Considerations . . . . . . . . . . . . . . . . . . . 55
- 14. Changes from Previous Protocol Versions . . . . . . . . . . . 57
- 15. References . . . . . . . . . . . . . . . . . . . . . . . . . . 57
- 15.1. Normative References . . . . . . . . . . . . . . . . . . . 57
- 15.2. Informative References . . . . . . . . . . . . . . . . . . 57
- Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 59
- Intellectual Property and Copyright Statements . . . . . . . . . . 60
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Galbraith & Saarenmaa Expires January 11, 2007 [Page 3]
-
-Internet-Draft SSH File Transfer Protocol July 2006
-
-
-1. Introduction
-
- This protocol provides secure file transfer (and more generally file
- system access). It is designed so that it could be used to implement
- a secure remote file system service as well as a secure file transfer
- service.
-
- This protocol assumes that it runs over a secure channel, such as a
- channel in [RFC4251], that the server has already authenticated the
- client, and that the identity of the client user is available to the
- protocol.
-
- In general, this protocol follows a simple request-response model.
- Each request and response contains a sequence number and multiple
- requests may be pending simultaneously. There are a relatively large
- number of different request messages, but a small number of possible
- response messages. Each request has one or more response messages
- that may be returned in result (e.g., a read either returns data or
- reports error status).
-
- The packet format descriptions in this specification follow the
- notation presented in [RFC4251].
-
- Even though this protocol is described in the context of the SSH2
- protocol, this protocol is general and independent of the rest of the
- SSH2 protocol suite. It could be used in a number of different
- applications, such as secure file transfer over TLS [RFC2246] and
- transfer of management information in VPN applications.
-
-
-2. Acknowledgements
-
- This document owes its initial creation and protocol design to Tatu
- Ylonen and Sami Lehtinen of SSH Communications Security Corp.
-
- We express our gratitude to them for their initial work on this
- protocol.
-
-
-3. Use with the SSH Connection Protocol
-
- When used with the SSH2 Protocol suite, this protocol is intended to
- be used as a subsystem as described in [RFC4254] in the section
- "Starting a Shell or a Command". The subsystem name used with this
- protocol is "sftp".
-
-
-
-
-
-
-Galbraith & Saarenmaa Expires January 11, 2007 [Page 4]
-
-Internet-Draft SSH File Transfer Protocol July 2006
-
-
-3.1. The Use of 'stderr' in the server
-
- This protocol uses stdout and stdin to transmit binary protocol data.
- The "session" channel ([RFC4254]), which is used by the subsystem,
- also supports the use of stderr.
-
- Data sent on stderr by the server SHOULD be considered free format
- debug or supplemental error information, and MAY be displayed to the
- user.
-
- For example, during initialization, there is no client request
- active, so errors or warning information cannot be sent to the client
- as part of the SFTP protocol at this early stage. However, the
- errors or warnings MAY be sent as stderr text.
-
-
-4. General Packet Format
-
- All packets transmitted over the secure connection are of the
- following format:
-
- uint32 length
- byte type
- uint32 request-id
- ... type specific fields ...
-
- 'length'
- The length of the entire packet, excluding the length field
- itself, such that, for example, for a packet type containing no
- type specific fields, the length field would be 5, and 9 bytes of
- data would be sent on the wire. (This is the packet format used
- in [RFC4253].)
-
- All packet descriptions in this document omit the length field for
- brevity; the length field MUST be included in any case.
-
- The maximum size of a packet is in practice determined by the
- client (the maximum size of read or write requests that it sends,
- plus a few bytes of packet overhead). All servers SHOULD support
- packets of at least 34000 bytes (where the packet size refers to
- the full length, including the header above). This should allow
- for reads and writes of at most 32768 bytes.
-
- 'type'
- The type code for the packet.
-
-
-
-
-
-
-Galbraith & Saarenmaa Expires January 11, 2007 [Page 5]
-
-Internet-Draft SSH File Transfer Protocol July 2006
-
-
- 'request-id'
- Each request from the client contains a 'request-id' field. Each
- response from the server includes that same 'request-id' from the
- request that the server is responding to. One possible
- implementation is for the client to us a monotonically increasing
- request sequence number (modulo 2^32). There is, however, no
- particular requirement the 'request-id' fields be unique.
-
- There are two packets, INIT and VERSION, which do not use the
- request-id.
-
- Packet descriptions in this document will contain the 'request-id'
- field, but will not redefine it.
-
-
- Implementations MUST ignore excess data at the end of an otherwise
- valid packet. Implementations MUST respond to unrecognized packet
- types with an SSH_FX_OP_UNSUPPORTED error. This will allow the
- protocol to be extended in a backwards compatible way as needed.
-
- Additionally, when a packet has two or more optional fields, and an
- implementation wishes to use the i-th optional field, all fields from
- 1 to i MUST be present. In other words, only fields after the last
- field the implementation wishes to send are actually optional.
-
- There is no limit on the number of outstanding (non-acknowledged)
- requests that the client may send to the server. In practice this is
- limited by the buffering available on the data stream and the queuing
- performed by the server. If the server's queues are full, it should
- not read any more data from the stream, and flow control will prevent
- the client from sending more requests. Note, however, that while
- there is no restriction on the protocol level, the client's API may
- provide a limit in order to prevent infinite queuing of outgoing
- requests at the client.
-
-4.1. Request Synchronization and Reordering
-
- The protocol and implementations MUST process requests relating to
- the same file in the order in which they are received. In other
- words, if an application submits multiple requests to the server, the
- results in the responses will be the same as if it had sent the
- requests one at a time and waited for the response in each case. For
- example, the server may process non-overlapping read/write requests
- to the same file in parallel, but overlapping reads and writes cannot
- be reordered or parallelized. However, there are no ordering
- restrictions on the server for processing requests from two different
- file transfer connections. The server may interleave and parallelize
- them at will.
-
-
-
-Galbraith & Saarenmaa Expires January 11, 2007 [Page 6]
-
-Internet-Draft SSH File Transfer Protocol July 2006
-
-
- There are no restrictions on the order in which responses to
- outstanding requests are delivered to the client, except that the
- server must ensure fairness in the sense that processing of no
- request will be indefinitely delayed even if the client is sending
- other requests so that there are multiple outstanding requests all
- the time.
-
- A client MUST be prepared to receive responses to multiple overlapped
- requests out of order.
-
-4.2. New data types defined by this document
-
- This document defines these data types in addition to those defined
- in [RFC4251].
-
- uint16
- Represents a 16-bit unsigned integer. Stored as 2 bytes in the
- order of decreasing significance (network byte order).
-
- int64
- Represents a 64-bit signed integer. Stored using two's
- complement, as eight bytes in the order of decreasing significance
- (network byte order).
-
- extension-pair
-
- string extension-name
- string extension-data
-
- 'extension-name' is the name of a protocol extension. Extensions
- not defined by IETF CONSENSUS MUST follow the the DNS
- extensibility naming convention outlined in [RFC4251].
-
- 'extension-data' is any data specific to the extension, and MAY be
- zero length if the extension has no data.
-
-
-4.3. Packet Types
-
- The following values are defined for packet types.
-
-
-
-
-
-
-
-
-
-
-
-Galbraith & Saarenmaa Expires January 11, 2007 [Page 7]
-
-Internet-Draft SSH File Transfer Protocol July 2006
-
-
- SSH_FXP_INIT 1
- SSH_FXP_VERSION 2
- SSH_FXP_OPEN 3
- SSH_FXP_CLOSE 4
- SSH_FXP_READ 5
- SSH_FXP_WRITE 6
- SSH_FXP_LSTAT 7
- SSH_FXP_FSTAT 8
- SSH_FXP_SETSTAT 9
- SSH_FXP_FSETSTAT 10
- SSH_FXP_OPENDIR 11
- SSH_FXP_READDIR 12
- SSH_FXP_REMOVE 13
- SSH_FXP_MKDIR 14
- SSH_FXP_RMDIR 15
- SSH_FXP_REALPATH 16
- SSH_FXP_STAT 17
- SSH_FXP_RENAME 18
- SSH_FXP_READLINK 19
- SSH_FXP_LINK 21
- SSH_FXP_BLOCK 22
- SSH_FXP_UNBLOCK 23
-
- SSH_FXP_STATUS 101
- SSH_FXP_HANDLE 102
- SSH_FXP_DATA 103
- SSH_FXP_NAME 104
- SSH_FXP_ATTRS 105
-
- SSH_FXP_EXTENDED 200
- SSH_FXP_EXTENDED_REPLY 201
-
- SSH_FXP_EXTENDED and SSH_FXP_EXTENDED_REPLY packets can be used to
- implement extensions, which can be vendor specific. See Section
- ''Extensions'' for more details.
-
- Values 210-255 are reserved for use in conjunction with these
- extensions. The SSH_FXP_EXTENDED packet can be used to negotiate the
- meaning of these reserved types. It is suggested that the actual
- value to be used also be negotiated, since this will prevent
- collision among multiple uncoordinated extensions.
-
- The server MUST respond with SSH_FXP_STATUS(SSH_FX_OP_UNSUPPORTED) if
- it receives a packet it does not recognize.
-
- The use of additional packet types in the non-extension range MUST be
- introduced through IETF consensus. New packet types to be sent from
- the client to the server MAY be introduced without changing the
-
-
-
-Galbraith & Saarenmaa Expires January 11, 2007 [Page 8]
-
-Internet-Draft SSH File Transfer Protocol July 2006
-
-
- protocol version (Section 5). Because the client has no way to
- respond to unrecognized packet types, new packet types to be sent
- from the server to the client the client MUST not used unless the
- protocol version is changed or the client has negotiated to received
- them. This negotiation MAY be explicit, through the use of
- extensions, or MAY be implicit, by the client itself using a packet
- type not defined above.
-
-
-5. Protocol Initialization
-
- When the file transfer protocol starts, the client first sends a
- SSH_FXP_INIT (including its version number) packet to the server.
- The server responds with a SSH_FXP_VERSION packet, supplying the
- lowest of its own and the client's version number. Both parties
- should from then on adhere to that particular version of the
- protocol.
-
- The version number of the protocol specified in this document is 6.
- The version number should be incremented for each incompatible
- revision of this protocol.
-
- Note that these two packets DO NOT contain a request id. These are
- the only such packets in the protocol.
-
-5.1. Client Initialization
-
- The SSH_FXP_INIT packet (from client to server) has the following
- data:
-
- uint32 version
-
- 'version' is the version number of the client. If the client wishes
- to interoperate with servers that support noncontiguous version
- numbers it SHOULD send '3', and then use the 'version-select'
- extension (see below.) Otherwise, this value is '6' for this version
- of the protocol.
-
-5.2. Server Initialization
-
- The SSH_FXP_VERSION packet (from server to client) has the following
- data:
-
- uint32 version
- extension-pair extensions[0..n]
-
- 'version' is the lower of the protocol version supported by the
- server and the version number received from the client.
-
-
-
-Galbraith & Saarenmaa Expires January 11, 2007 [Page 9]
-
-Internet-Draft SSH File Transfer Protocol July 2006
-
-
- 'extensions' is 0 or more extension-pairs (Section 4.2).
- Implementations MUST silently ignore any extensions whose names they
- do not recognize.
-
-5.3. Determining Server Newline Convention
-
- In order to correctly process text files in a cross platform
- compatible way, newline sequences must be converted between client
- and server conventions.
-
- The SSH_FXF_TEXT_MODE file open flag (Section 8.1.1) makes it
- possible to request that the server translate a file to a 'canonical'
- wire format. This format uses CRLF as the line separator.
-
- Servers for systems using other conventions MUST translate to and
- from the canonical form.
-
- However, to ease the burden of implementation on servers that use a
- single, simple, separator sequence the following extension allows the
- canonical format to be changed.
-
- string "newline"
- string new-canonical-separator (usually CR or LF or CRLF)
-
- All clients MUST support this extension.
-
- When processing text files, clients SHOULD NOT translate any
- character or sequence that is not an exact match of the server's
- newline separator.
-
- In particular, if the newline sequence being used is the canonical
- CRLF sequence, a lone CR or a lone LF SHOULD be written through
- without change.
-
-5.4. Supported Features
-
- The sftp protocol has grown to be very rich, and now supports a
- number of features that may not be available on all servers.
-
- When a server receives a request for a feature it cannot support, it
- MUST return a SSH_FX_OP_UNSUPPORTED status code, unless otherwise
- specified. The following extension facilitates clients being able to
- use the maximum available feature set, and yet not be overly burdened
- by dealing with SSH_FX_OP_UNSUPPORTED status codes. All servers MUST
- include it as part of their version packet.
-
-
-
-
-
-
-Galbraith & Saarenmaa Expires January 11, 2007 [Page 10]
-
-Internet-Draft SSH File Transfer Protocol July 2006
-
-
- string "supported2"
- string supported-structure
- uint32 supported-attribute-mask
- uint32 supported-attribute-bits
- uint32 supported-open-flags
- uint32 supported-access-mask
- uint32 max-read-size
- uint16 supported-open-block-vector
- uint16 supported-block-vector
- uint32 attrib-extension-count
- string attrib-extension-names[attrib_extension-count]
- uint32 extension-count
- string extension-names[extension-count]
-
- Note that the name "supported2" is used here to avoid conflict with
- the slightly different "supported" extension that was previously
- used.
- supported-attribute-mask
- This mask MAY be applied by the client to the 'File Attributes'
- valid-attribute-flags field (Section 7.1) in order to ensure that
- no unsupported attributes are present during a operation which
- writes attributes.
-
- supported-attribute-bits
- This mask MAY be applied by the client to the 'File Attributes'
- attrib-bits field (Section 7.9) in order to ensure that no
- unsupported attrib-bits are present during a operation which
- writes attribute bits.
-
- supported-open-flags
- The supported-open-flags mask MAY be applied by the client to the
- SSH_FXP_OPEN (Section 8.1.1) flags field.
-
- supported-access-mask
- This mask may be applied by the client to the ace-mask field of an
- ACL during a operation that writes the ACL.
-
- This mask SHOULD NOT be applied to the desired-access field of the
- SSH_FXP_OPEN (Section 8.1.1) request. Doing so will simply result
- in not requesting the access required by the client. In the case
- of open operations, the server is responsible for translating the
- client's requested access to a mode it supports that is sufficient
- to grant all access requested by the client.
-
-
-
-
-
-
-
-
-Galbraith & Saarenmaa Expires January 11, 2007 [Page 11]
-
-Internet-Draft SSH File Transfer Protocol July 2006
-
-
- max-read-size
- This is the maximum read size that the server guarantees to
- complete. For example, certain embedded server implementations
- complete only the first 4K of a read, even if there is additional
- data to be read from the file.
-
- If the server specifies a non-zero value for max-read-size, it
- MUST return the requested number of bytes for reads that are less
- than or equal to the value, unless it encounters EOF or an ERROR.
-
- The server MAY use this value to express that it is willing to
- handle very large read requests, in excess of the standard 34000
- bytes specified in Section 4.
-
- supported-open-block-vector
- supported-block-vector
- 16-bit masks specifying which combinations of blocking flags are
- supported. Each bit corresponds to one combination of the
- SSH_FXF_BLOCK_READ, SSH_FXF_BLOCK_WRITE, SSH_FXF_BLOCK_DELETE, and
- SSH_FXF_BLOCK_ADVISORY bits from Section 8.1.1.3, with a set bit
- corresponding to a supported combination and a clear bit an
- unsupported combination. The index of a bit, bit zero being the
- least significant bit, viewed as a four-bit number, corresponds to
- a combination of flag bits, shifted right so that BLOCK_READ is
- the least significant bit. The combination `no blocking flags'
- MUST be supported, so the low bit will always be set.
-
- For example, a server supporting only the classic advisory read
- (shared) and write (exclusive) locks would set the bits
- corresponding to READ+WRITE+ADVISORY, 0b1011, and WRITE+ADVISORY,
- 0b1010, plus the always-set bit 0b0000, giving a mask value of
- 0b0000110000000001, or 0x0c01; a server supporting no locking at
- all would set only bit zero, giving 0x0001.
-
- 'supported-open-block-masks' applies to the SSH_FXP_OPEN
- (Section 8.1.1) flags field. 'supported-block-masks' applies to
- the SSH_FXF_BLOCK request.
-
- attrib-extension-count
- Count of extension names in the attrib-extension-names array.
-
- attrib-extension-names
- Names of extensions that can be used in an ATTRS (Section 7.14)
- structure.
-
-
-
-
-
-
-
-Galbraith & Saarenmaa Expires January 11, 2007 [Page 12]
-
-Internet-Draft SSH File Transfer Protocol July 2006
-
-
- extension-count
- Count of extension names in the extension-names array.
-
- extension-names
- Names of extensions that can be used with the SSH_FXP_EXTEND
- (Section 10) packet.
-
-
- Naturally, if a given attribute field, attribute mask bit, open flag,
- or extension is required for correct operation, the client MUST
- either not mask the bit off, or MUST fail the operation gracefully
- without sending the request to the server.
-
- The client MAY send requests that are not supported by the server;
- however, it is not normally expected to be productive to do so. The
- client SHOULD apply the mask even to attrib structures received from
- the server. The server MAY include attributes or attrib-bits that
- are not included in the mask. Such attributes or attrib-bits are
- effectively read-only.
-
- The supported capabilities of the acl attribute are sent using the
- following extension.
-
- string "acl-supported"
- string supported-structure
- uint32 capabilities
-
- 'capabilities' is a combination of the following bits:
-
- SSH_ACL_CAP_ALLOW 0x00000001
- SSH_ACL_CAP_DENY 0x00000002
- SSH_ACL_CAP_AUDIT 0x00000004
- SSH_ACL_CAP_ALARM 0x00000008
- SSH_ACL_CAP_INHERIT_ACCESS 0x00000010
- SSH_ACL_CAP_INHERIT_AUDIT_ALARM 0x00000020
-
- SSH_ACL_CAP_ALLOW
- SSH_ACL_CAP_DENY
- SSH_ACL_CAP_AUDIT
- SSH_ACL_CAP_ALARM
- The server supports the associated ACL ACE type.
-
- SSH_ACL_CAP_INHERIT_ACCESS
- The server can control whether a ACL will inherit DENY and ALLOW
- ACEs that are marked inheritable from it's parent object.
-
-
-
-
-
-
-Galbraith & Saarenmaa Expires January 11, 2007 [Page 13]
-
-Internet-Draft SSH File Transfer Protocol July 2006
-
-
- SSH_ACL_CAP_INHERIT_AUDIT_ALARM
- The server can control whether a ACL will inherit AUDIT or ALARM
- ACEs that are marked inheritable from it's parent object.
-
-
-5.5. Version re-negotiation
-
- If the server supports other versions than what was negotiated, it
- may wish to send the 'versions' extension to inform the client of
- this fact. The client may then optionally choose to use one of the
- other versions supported.
-
- string "versions"
- string comma-separated-versions
-
- 'comma-separated-versions' is a string of comma separated version
- numbers. Defined versions are: "2", "3", "4", "5", "6". Any other
- version advertised by the server must follow the DNS extensibility
- naming convention outlined in [RFC4251].
-
- For example: "2,3,6,private@example.com".
-
- If the client and server have negotiated a a version greater than or
- equal to version '3' (the version at which SSH_FXP_EXTENDED was
- introduced) in the initial VERSION/INIT exchange, the client may
- select a new version to use from the list the server provided using
- the following SSH_FXP_EXTENDED request.
-
- string "version-select"
- string version-from-list
-
- If the 'version-from-list' is one of the versions on the servers
- list, the server MUST respond with SSH_FX_OK. If the server did not
- send the "versions" extension, or the version-from-list was not
- included, the server MAY send a status response describing the
- failure, but MUST then close the channel without processing any
- further requests.
-
- The 'version-select' MUST be the first request from the client to the
- server; if it is not, the server MUST fail the request and close the
- channel.
-
- Although this request does take a full round trip, no client need
- wait for the response before continuing, because any valid request
- MUST succeed, and any invalid request results in a channel close.
- Since the request is the first request, it is not possible for the
- server to have already sent responses conforming to the old version.
-
-
-
-
-Galbraith & Saarenmaa Expires January 11, 2007 [Page 14]
-
-Internet-Draft SSH File Transfer Protocol July 2006
-
-
- Typically, the client SHOULD NOT down-grade the protocol version
- using this extension; however, it is not forbidden to do so. One
- reason a client might do so is to work around a buggy implementation.
-
-
-6. File Names
-
- This protocol represents file names as strings. File names are
- assumed to use the slash ('/') character as a directory separator.
-
- File names starting with a slash are "absolute", and are relative to
- the root of the file system. Names starting with any other character
- are relative to the user's default directory (home directory). Note
- that identifying the user is assumed to take place outside of this
- protocol.
-
- Servers SHOULD interpret a path name component ".." (Section 13) as
- referring to the parent directory, and "." as referring to the
- current directory.
-
- An empty path name is valid, and it refers to the user's default
- directory (usually the user's home directory).
-
- Otherwise, no syntax is defined for file names by this specification.
- Clients should not make any other assumptions; however, they can
- splice path name components returned by SSH_FXP_READDIR together
- using a slash ('/') as the separator, and that will work as expected.
-
- It is understood that the lack of well-defined semantics for file
- names may cause interoperability problems between clients and servers
- using radically different operating systems. However, this approach
- is known to work acceptably with most systems, and alternative
- approaches that e.g. treat file names as sequences of structured
- components are quite complicated.
-
- The preferred encoding for filenames is UTF-8. This is consistent
- with IETF Policy on Character Sets and Languages [RFC2277] and it is
- further supposed that the server is more likely to support any local
- character set and be able to convert it to UTF-8.
-
- However, because the server does not always know the encoding of
- filenames, it is not always possible for the server to preform a
- valid translation to UTF-8. When an invalid translation to UTF-8 is
- preformed, it becomes impossible to manipulate the file, because the
- translation is not reversible. Therefore, the following extensions
- are provided in order to make it possible for the server to
- communicate it's abilities to the client, and to allow the client to
- control whether the server attempts the conversion.
-
-
-
-Galbraith & Saarenmaa Expires January 11, 2007 [Page 15]
-
-Internet-Draft SSH File Transfer Protocol July 2006
-
-
- A server MAY include the following extension with it's version
- packet.
-
- string "filename-charset"
- string charset-name
-
- A server that can always provide a valid UTF-8 translation for
- filenames SHOULD NOT send this extension. Otherwise, the server
- SHOULD send this extension and include the encoding most likely to be
- used for filenames. This value will most likely be derived from the
- LC_CTYPE on most unix-like systems.
-
- A server that does not send this extension MUST send all filenames
- encoded in UTF-8. All clients MUST support UTF-8 filenames.
-
- If the server included the 'filename-charset' extension with its
- VERSION packet, a client MAY send the following extension to turn off
- server translation to UTF-8.
-
- string "filename-translation-control"
- bool do-translate
-
- If the client does not send this extension, the server MUST continue
- to attempt translation to UTF-8. When a client sends this extension,
- the server MUST enable filename translation if 'do-translate' is
- true, or disable filename translation if it is false.
-
- The server MUST respond with a STATUS response; if the server sent a
- 'filename-charset' extension, the status MUST be SUCCESS. Otherwise,
- the status MUST be SSH_FX_OP_UNSUPPORTED.
-
- When UTF-8 is sent, the shortest valid UTF-8 encoding of the UNICODE
- data MUST be used. The server is responsible for converting the
- UNICODE data to whatever canonical form it requires. For example, if
- the server requires that precomposed characters always be used, the
- server MUST NOT assume the filename as sent by the client has this
- attribute, but must do this normalization itself.
-
-
-7. File Attributes
-
- A new compound data type, 'ATTRS', is defined for encoding file
- attributes. The same encoding is used both when returning file
- attributes from the server and when sending file attributes to the
- server.
-
-
-
-
-
-
-Galbraith & Saarenmaa Expires January 11, 2007 [Page 16]
-
-Internet-Draft SSH File Transfer Protocol July 2006
-
-
- uint32 valid-attribute-flags
- byte type always present
- uint64 size if flag SIZE
- uint64 allocation-size if flag ALLOCATION_SIZE
- string owner if flag OWNERGROUP
- string group if flag OWNERGROUP
- uint32 permissions if flag PERMISSIONS
- int64 atime if flag ACCESSTIME
- uint32 atime-nseconds if flag SUBSECOND_TIMES
- int64 createtime if flag CREATETIME
- uint32 createtime-nseconds if flag SUBSECOND_TIMES
- int64 mtime if flag MODIFYTIME
- uint32 mtime-nseconds if flag SUBSECOND_TIMES
- int64 ctime if flag CTIME
- uint32 ctime-nseconds if flag SUBSECOND_TIMES
- string acl if flag ACL
- uint32 attrib-bits if flag BITS
- uint32 attrib-bits-valid if flag BITS
- byte text-hint if flag TEXT_HINT
- string mime-type if flag MIME_TYPE
- uint32 link-count if flag LINK_COUNT
- string untranslated-name if flag UNTRANSLATED_NAME
- uint32 extended-count if flag EXTENDED
- extension-pair extensions
-
-7.1. valid-attribute-flags
-
- The 'valid-attribute-flags' specifies which of the fields are
- present. Those fields for which the corresponding flag is not set
- are not present (not included in the packet).
-
- The server generally includes all attributes it knows about; however,
- it may exclude attributes that are overly expensive to retrieve
- unless the client explicitly requests them.
-
- When writing attributes, the server SHOULD NOT modify attributes that
- are not present in the structure. However, if necessary, the server
- MAY use a default value for an absent attribute.
-
- In general, unless otherwise specified, if a server cannot support
- writing an attribute requested, it must fail the setstat operation.
- In this case, none of the attributes SHOULD be changed.
-
- New fields can be added only by incrementing the protocol version
- number (or by using the extension mechanism described below).
-
- The following values are defined:
-
-
-
-
-Galbraith & Saarenmaa Expires January 11, 2007 [Page 17]
-
-Internet-Draft SSH File Transfer Protocol July 2006
-
-
- SSH_FILEXFER_ATTR_SIZE 0x00000001
- SSH_FILEXFER_ATTR_PERMISSIONS 0x00000004
- SSH_FILEXFER_ATTR_ACCESSTIME 0x00000008
- SSH_FILEXFER_ATTR_CREATETIME 0x00000010
- SSH_FILEXFER_ATTR_MODIFYTIME 0x00000020
- SSH_FILEXFER_ATTR_ACL 0x00000040
- SSH_FILEXFER_ATTR_OWNERGROUP 0x00000080
- SSH_FILEXFER_ATTR_SUBSECOND_TIMES 0x00000100
- SSH_FILEXFER_ATTR_BITS 0x00000200
- SSH_FILEXFER_ATTR_ALLOCATION_SIZE 0x00000400
- SSH_FILEXFER_ATTR_TEXT_HINT 0x00000800
- SSH_FILEXFER_ATTR_MIME_TYPE 0x00001000
- SSH_FILEXFER_ATTR_LINK_COUNT 0x00002000
- SSH_FILEXFER_ATTR_UNTRANSLATED_NAME 0x00004000
- SSH_FILEXFER_ATTR_CTIME 0x00008000
- SSH_FILEXFER_ATTR_EXTENDED 0x80000000
-
- 0x00000002 was used in a previous version of this protocol. It is
- now a reserved value and MUST NOT appear in the mask. Some future
- version of this protocol may reuse this value.
-
-7.2. Type
-
- The type field is always present. The following types are defined:
-
- SSH_FILEXFER_TYPE_REGULAR 1
- SSH_FILEXFER_TYPE_DIRECTORY 2
- SSH_FILEXFER_TYPE_SYMLINK 3
- SSH_FILEXFER_TYPE_SPECIAL 4
- SSH_FILEXFER_TYPE_UNKNOWN 5
- SSH_FILEXFER_TYPE_SOCKET 6
- SSH_FILEXFER_TYPE_CHAR_DEVICE 7
- SSH_FILEXFER_TYPE_BLOCK_DEVICE 8
- SSH_FILEXFER_TYPE_FIFO 9
-
- On a POSIX system, these values would be derived from the mode field
- of the stat structure. SPECIAL should be used for files that are of
- a known type which cannot be expressed in the protocol. UNKNOWN
- should be used if the type is not known.
-
-7.3. Size
-
- The 'size' field specifies the number of bytes that can be read from
- the file, or in other words, the location of the end-of-file.
-
- If this field is present during file creation, it indicates the
- number of bytes the client intends to transfer, but SHOULD NOT affect
- the creation of the file. If the file is a text-file, then the bytes
-
-
-
-Galbraith & Saarenmaa Expires January 11, 2007 [Page 18]
-
-Internet-Draft SSH File Transfer Protocol July 2006
-
-
- are 'as encoded on the wire.' The server can use this information to
- determine if the client sent all the intended data and the file was
- transfered in its entirity.
-
- If this field is present during a setstat operation, the file MUST be
- extended or truncated to the specified size. If the file is
- extended, the semantics are to write the byte value 0x00 from the
- previous end of file to the new offset.
-
- Files opened with the SSH_FXF_TEXT flag may have a size that is
- greater or less than the value of the size field. The server MAY
- fail setstat operations specifying size for files opened with the
- SSH_FXF_TEXT flag.
-
-7.4. allocation-size
-
- The 'allocation-size' field specifies the number of bytes that the
- file consumes on disk. This field MAY be less than the 'size' field
- if the file is 'sparse' (Section 7.9). It will usually be larger
- than the 'size' field, however, as most file-systems allocate space
- to files in units that are larger than a single byte.
-
- When present during file creation, the file SHOULD be created and the
- specified number of bytes preallocated. If the preallocation fails,
- the file should be removed (if it was created) and an error returned.
-
- If this field is present during a setstat operation, the file
- allocation SHOULD be changed to the specified size. If the
- allocation size is increased, additional space is allocated to the
- file, but the 'size' is not changed (the end-of-file marker is not
- move.) If the new allocation size is smaller, than the operation is
- effectively a truncation.
-
- Querying the 'allocation-size' after setting it MUST return a value
- that is greater-than or equal to the value set, but it MAY not return
- the precise value set.
-
- If both 'size' and 'allocation-size' are set during a setstat
- operation, and 'allocation-size' is less than 'size', the server MUST
- return SSH_FX_INVALID_PARAMETER.
-
-7.5. Owner and Group
-
- The 'owner' and 'group' fields are represented as UTF-8 strings; this
- is the form used by NFS v4. See NFS version 4 Protocol [RFC3010].
- The following text is selected quotations from section 5.6.
-
- To avoid a representation that is tied to a particular underlying
-
-
-
-Galbraith & Saarenmaa Expires January 11, 2007 [Page 19]
-
-Internet-Draft SSH File Transfer Protocol July 2006
-
-
- implementation at the client or server, the use of UTF-8 strings has
- been chosen. The string should be of the form "user@dns_domain".
- This will allow for a client and server that do not use the same
- local representation the ability to translate to a common syntax that
- can be interpreted by both. In the case where there is no
- translation available to the client or server, the attribute value
- must be constructed without the "@". Therefore, the absence of the @
- from the owner or owner_group attribute signifies that no translation
- was available and the receiver of the attribute should not place any
- special meaning on the attribute value. Even though the attribute
- value cannot be translated, it may still be useful. In the case of a
- client, the attribute string may be used for local display of
- ownership.
-
- user@localhost represents a user in the context of the server.
-
- If either the owner or group field is zero length, the field should
- be considered absent, and no change should be made to that specific
- field during a modification operation.
-
-7.6. Permissions
-
- The 'permissions' field contains a bit mask specifying file
- permissions. These permissions correspond to the st_mode field of
- the stat structure defined by POSIX [IEEE.1003-1.1996].
-
- This protocol uses the following values for the symbols declared in
- the POSIX standard.
-
- S_IRUSR 0000400 (octal)
- S_IWUSR 0000200
- S_IXUSR 0000100
- S_IRGRP 0000040
- S_IWGRP 0000020
- S_IXGRP 0000010
- S_IROTH 0000004
- S_IWOTH 0000002
- S_IXOTH 0000001
- S_ISUID 0004000
- S_ISGID 0002000
- S_ISVTX 0001000
-
- Implementations MUST NOT send bits that are not defined.
-
- The server SHOULD NOT apply a 'umask' to the mode bits; but should
- set the mode bits as specified by the client. The client MUST apply
- an appropriate 'umask' to the mode bits before sending them.
-
-
-
-
-Galbraith & Saarenmaa Expires January 11, 2007 [Page 20]
-
-Internet-Draft SSH File Transfer Protocol July 2006
-
-
-7.7. Times
-
- The 'atime' field contains the last access time of the file. Many
- operating systems either don't have this field, only optionally
- maintain it, or maintain it with less resolution than other fields.
-
- The 'mtime' contains the last time the file was written.
-
- 'createtime' contains the creation time of the file.
-
- 'ctime' contains the last time the file attributes were changed. The
- exact meaning of this field depends on the server.
-
- All times are represented as seconds from Jan 1, 1970 in UTC. A
- negative value indicates number of seconds before Jan 1, 1970. In
- both cases, if the SSH_FILEXFER_ATTR_SUBSECOND_TIMES flag is set, the
- nseconds field is to be added to the seconds field for the final time
- representation. For example, if the time to be represented is one-
- half second before 0 hour January 1, 1970, the seconds field would
- have a value of negative one (-1) and the nseconds fields would have
- a value of one-half second (500000000). Values greater than
- 999,999,999 for nseconds are considered invalid.
-
-7.8. ACL
-
- The 'ACL' field contains an ACL similar to that defined in section
- 5.9 of NFS version 4 Protocol [RFC3010].
-
- The structure of the ACL is:
-
- uint32 acl-flags
- uint32 ace-count
- ACE ace[ace-count]
-
- The ACE data structure is composes as follows:
-
- uint32 ace-type
- uint32 ace-flag
- uint32 ace-mask
- string who [UTF-8]
-
- acl-flags
-
-
- SFX_ACL_CONTROL_INCLUDED 0x00000001
- SFX_ACL_CONTROL_PRESENT 0x00000002
- SFX_ACL_CONTROL_INHERITED 0x00000004
- SFX_ACL_AUDIT_ALARM_INCLUDED 0x00000010
-
-
-
-Galbraith & Saarenmaa Expires January 11, 2007 [Page 21]
-
-Internet-Draft SSH File Transfer Protocol July 2006
-
-
- SFX_ACL_AUDIT_ALARM_INHERITED 0x00000020
-
- SFX_ACL_CONTROL_INCLUDED
- SFX_ACL_CONTROL_PRESENT
- SFX_ACL_CONTROL_INHERITED
- If INCLUDED is set during a setstat operation, then the client
- intends to modify the ALLOWED/DENIED entries of the ACL.
- Otherwise, the client intends for these entries to be
- preserved.
-
- If the PRESENT bit is not set, then the client wishes to remove
- control entries. If the server doesn't support separate
- control and audit information, the client MUST not clear this
- bit without also clearing the AUDIT_ALARM_PRESENT bit.
-
- If the PRESENT bit is clear, then control of the file MAY be
- through the permissions mask. The server MAY also grant full
- access to the file.
-
- If the both the INCLUDE and the PRESENT bit are set, but their
- are no ALLOW/DENY entries in the list, the client wishes to
- deny all access to the file or directory. The server may have
- to transform this into a ACL with a deny entry to implement it.
-
- If INHERITED is set, then ALLOW/DENY ACEs MAY be inherited from
- the parent directory. If it is off, then they MUST not be
- INHERITED. If the server does not support controlling
- inheritance, then the client MUST clear this bit; in this case
- the inheritance properties of the server are undefined.
-
- SFX_ACL_AUDIT_ALARM_INCLUDED
- SFX_ACL_AUDIT_ALARM_INHERITED
- If INCLUDE is set during a setstat operation, then the client
- intends to modify the AUDIT/ALARM entries of the ACL.
- Otherwise, the client intends for these entries to be
- preserved.
-
- If INHERITED is set, then AUDIT/ALARM ACEs MAY be inherited
- from the parent directory. If it is off, then they MUST not be
- INHERITED. If the server does not support controlling
- inheritance, then the client MUST clear this bit; in this case
- the inheritance properties of the server are undefined.
-
- Because some server require special permissions / privileges in
- order to modify the AUDIT/ALARM entries in the ACL, it is
- important to communicate to the server the clients intent to
- modify these entries. The client MUST both use the
- ACCESS_AUDIT_ALARM_ATTRIBUTES bit in the desired attribute of the
-
-
-
-Galbraith & Saarenmaa Expires January 11, 2007 [Page 22]
-
-Internet-Draft SSH File Transfer Protocol July 2006
-
-
- open request and must set the SFX_ACL_AUDIT_ALARM_INCLUDED during
- the setstat operation.
-
- Clients that do not intend specifically to modify the AUDIT or
- ALARM entries SHOULD NOT set SSH_FXF_ACCESS_AUDIT_ALARM_INFO in
- the open-flags and SHOULD NOT set the SFX_ACL_AUDIT_ALARM_INCLUDED
- bit because these operations are often privileged and will fail.
-
- If the SFX_ACL_AUDIT_ALARM_INCLUDED is set, and the requested
- change can not be made, the server MUST fail the request.
-
- Servers that do not seperate control and audit/alarm information
- may have to read the existing ACL and merge in enteries not
- included by the client. The server must take this into account
- when opening files with the ACE4_WRITE_ACL permission requested.
-
- ace-type
- one of the following four values (taken from NFS Version 4
- Protocol [RFC3010]:
-
-
-
- ACE4_ACCESS_ALLOWED_ACE_TYPE 0x00000000
- ACE4_ACCESS_DENIED_ACE_TYPE 0x00000001
- ACE4_SYSTEM_AUDIT_ACE_TYPE 0x00000002
- ACE4_SYSTEM_ALARM_ACE_TYPE 0x00000003
-
- ace-flag
- A combination of the following flag values. See NFS Version 4
- Protocol [RFC3010] section 5.9.2:
-
-
-
- ACE4_FILE_INHERIT_ACE 0x00000001
- ACE4_DIRECTORY_INHERIT_ACE 0x00000002
- ACE4_NO_PROPAGATE_INHERIT_ACE 0x00000004
- ACE4_INHERIT_ONLY_ACE 0x00000008
- ACE4_SUCCESSFUL_ACCESS_ACE_FLAG 0x00000010
- ACE4_FAILED_ACCESS_ACE_FLAG 0x00000020
- ACE4_IDENTIFIER_GROUP 0x00000040
-
- ace-mask
- Combination of the following flags (taken from [RFC3010], section
- 5.9.3. The semantic meaning of these flags is also given in
- [RFC3010].
-
-
-
-
-
-
-Galbraith & Saarenmaa Expires January 11, 2007 [Page 23]
-
-Internet-Draft SSH File Transfer Protocol July 2006
-
-
-
-
- ACE4_READ_DATA 0x00000001
- ACE4_LIST_DIRECTORY 0x00000001
- ACE4_WRITE_DATA 0x00000002
- ACE4_ADD_FILE 0x00000002
- ACE4_APPEND_DATA 0x00000004
- ACE4_ADD_SUBDIRECTORY 0x00000004
- ACE4_READ_NAMED_ATTRS 0x00000008
- ACE4_WRITE_NAMED_ATTRS 0x00000010
- ACE4_EXECUTE 0x00000020
- ACE4_DELETE_CHILD 0x00000040
- ACE4_READ_ATTRIBUTES 0x00000080
- ACE4_WRITE_ATTRIBUTES 0x00000100
- ACE4_DELETE 0x00010000
- ACE4_READ_ACL 0x00020000
- ACE4_WRITE_ACL 0x00040000
- ACE4_WRITE_OWNER 0x00080000
- ACE4_SYNCHRONIZE 0x00100000
-
- who
- UTF-8 string of the form described in 'Owner and Group'
- (Section 7.5)
- Also, as per '5.9.4 ACE who' [RFC3010] there are several
- identifiers that need to be understood universally. Some of these
- identifiers cannot be understood when an client access the server,
- but have meaning when a local process accesses the file. The
- ability to display and modify these permissions is permitted over
- SFTP.
-
- OWNER The owner of the file.
- GROUP The group associated with the file.
- EVERYONE The world.
- INTERACTIVE Accessed from an interactive terminal.
- NETWORK Accessed via the network.
- DIALUP Accessed as a dialup user to the server.
- BATCH Accessed from a batch job.
- ANONYMOUS Accessed without any authentication.
- AUTHENTICATED Any authenticated user (opposite of ANONYMOUS).
- SERVICE Access from a system service.
- To avoid conflict, these special identifiers are distinguish by an
- appended "@". For example: ANONYMOUS@.
-
-7.9. attrib-bits and attrib-bits-valid
-
- These fields, taken together, reflect various attributes of the file
- or directory, on the server.
-
-
-
-
-Galbraith & Saarenmaa Expires January 11, 2007 [Page 24]
-
-Internet-Draft SSH File Transfer Protocol July 2006
-
-
- Bits not set in 'attrib-bits-valid' MUST be ignored in the 'attrib-
- bits' field. This allows both the server and the client to
- communicate only the bits they knows about without inadvertently
- twiddling bits they don't understand.
-
- The following attrib-bits are defined:
-
- SSH_FILEXFER_ATTR_FLAGS_READONLY 0x00000001
- SSH_FILEXFER_ATTR_FLAGS_SYSTEM 0x00000002
- SSH_FILEXFER_ATTR_FLAGS_HIDDEN 0x00000004
- SSH_FILEXFER_ATTR_FLAGS_CASE_INSENSITIVE 0x00000008
- SSH_FILEXFER_ATTR_FLAGS_ARCHIVE 0x00000010
- SSH_FILEXFER_ATTR_FLAGS_ENCRYPTED 0x00000020
- SSH_FILEXFER_ATTR_FLAGS_COMPRESSED 0x00000040
- SSH_FILEXFER_ATTR_FLAGS_SPARSE 0x00000080
- SSH_FILEXFER_ATTR_FLAGS_APPEND_ONLY 0x00000100
- SSH_FILEXFER_ATTR_FLAGS_IMMUTABLE 0x00000200
- SSH_FILEXFER_ATTR_FLAGS_SYNC 0x00000400
- SSH_FILEXFER_ATTR_FLAGS_TRANSLATION_ERR 0x00000800
-
- SSH_FILEXFER_ATTR_FLAGS_READONLY
- Advisory, read-only bit. This bit is not part of the access
- control information on the file, but is rather an advisory field
- indicating that the file should not be written.
-
- SSH_FILEXFER_ATTR_FLAGS_SYSTEM
- The file is part of the operating system.
-
- SSH_FILEXFER_ATTR_FLAGS_HIDDEN
- File SHOULD NOT be shown to user unless specifically requested.
- For example, most UNIX systems SHOULD set this bit if the filename
- begins with a 'period'. This bit may be read-only (Section 5.4).
- Most UNIX systems will not allow this to be changed.
-
- SSH_FILEXFER_ATTR_FLAGS_CASE_INSENSITIVE
- This attribute applies only to directories. This attribute is
- always read-only, and cannot be modified. This attribute means
- that files and directory names in this directory should be
- compared without regard to case.
-
- It is recommended that where possible, the server's filesystem be
- allowed to do comparisons. For example, if a client wished to
- prompt a user before overwriting a file, it should not compare the
- new name with the previously retrieved list of names in the
- directory. Rather, it should first try to create the new file by
- specifying SSH_FXF_CREATE_NEW flag. Then, if this fails and
- returns SSH_FX_FILE_ALREADY_EXISTS, it should prompt the user and
- then retry the create specifying SSH_FXF_CREATE_TRUNCATE.
-
-
-
-Galbraith & Saarenmaa Expires January 11, 2007 [Page 25]
-
-Internet-Draft SSH File Transfer Protocol July 2006
-
-
- Unless otherwise specified, filenames are assumed to be case
- sensitive.
-
- SSH_FILEXFER_ATTR_FLAGS_ARCHIVE
- The file should be included in backup / archive operations.
-
- SSH_FILEXFER_ATTR_FLAGS_ENCRYPTED
- The file is stored on disk using file-system level transparent
- encryption. This flag does not affect the file data on the wire
- (for either READ or WRITE requests.)
-
- SSH_FILEXFER_ATTR_FLAGS_COMPRESSED
- The file is stored on disk using file-system level transparent
- compression. This flag does not affect the file data on the wire.
-
- SSH_FILEXFER_ATTR_FLAGS_SPARSE
- The file is a sparse file; this means that file blocks that have
- not been explicitly written are not stored on disk. For example,
- if a client writes a buffer at 10 M from the beginning of the
- file, the blocks between the previous EOF marker and the 10 M
- offset would not consume physical disk space.
-
- Some servers may store all files as sparse files, in which case
- this bit will be unconditionally set. Other servers may not have
- a mechanism for determining if the file is sparse, and so the file
- MAY be stored sparse even if this flag is not set.
-
- SSH_FILEXFER_ATTR_FLAGS_APPEND_ONLY
- Opening the file without either the SSH_FXF_APPEND_DATA or the
- SSH_FXF_APPEND_DATA_ATOMIC flag (Section 8.1.1.3) MUST result in
- an SSH_FX_INVALID_PARAMETER error.
-
- SSH_FILEXFER_ATTR_FLAGS_IMMUTABLE
- The file cannot be deleted or renamed, no hard link can be created
- to this file, and no data can be written to the file.
-
- This bit implies a stronger level of protection than
- SSH_FILEXFER_ATTR_FLAGS_READONLY, the file permission mask or
- ACLs. Typically even the superuser cannot write to immutable
- files, and only the superuser can set or remove the bit.
-
- SSH_FILEXFER_ATTR_FLAGS_SYNC
- When the file is modified, the changes are written synchronously
- to the disk.
-
-
-
-
-
-
-
-Galbraith & Saarenmaa Expires January 11, 2007 [Page 26]
-
-Internet-Draft SSH File Transfer Protocol July 2006
-
-
- SSH_FILEXFER_ATTR_FLAGS_TRANSLATION_ERR
- The server MAY include this bit in a directory listing or realpath
- response. It indicates there was a failure in the translation to
- UTF-8. If this flag is included, the server SHOULD also include
- the UNTRANSLATED_NAME attribute.
-
-
-7.10. text-hint
-
- The value is one of the following enumerations, and indicates what
- the server knows about the content of the file.
-
- SSH_FILEXFER_ATTR_KNOWN_TEXT 0x00
- SSH_FILEXFER_ATTR_GUESSED_TEXT 0x01
- SSH_FILEXFER_ATTR_KNOWN_BINARY 0x02
- SSH_FILEXFER_ATTR_GUESSED_BINARY 0x03
-
- SSH_FILEXFER_ATTR_KNOWN_TEXT
- The server knows the file is a text file, and should be opened
- using the SSH_FXF_TEXT_MODE flag.
-
- SSH_FILEXFER_ATTR_GUESSED_TEXT
- The server has applied a heuristic or other mechanism and believes
- that the file should be opened with the SSH_FXF_TEXT_MODE flag.
-
- SSH_FILEXFER_ATTR_KNOWN_BINARY
- The server knows the file has binary content.
-
- SSH_FILEXFER_ATTR_GUESSED_BINARY
- The server has applied a heuristic or other mechanism and believes
- has binary content, and should not be opened with the
- SSH_FXF_TEXT_MODE flag.
-
-
- This flag MUST NOT be present during either a setstat or a fsetstat
- operation.
-
-7.11. mime-type
-
- The 'mime-type' field contains the mime-type [RFC1521] string. Most
- servers will not know this information and should not set the bit in
- their supported-attribute-mask.
-
-7.12. link-count
-
- This field contains the hard link count of the file. This attribute
- MUST NOT be present during a setstat operation.
-
-
-
-
-Galbraith & Saarenmaa Expires January 11, 2007 [Page 27]
-
-Internet-Draft SSH File Transfer Protocol July 2006
-
-
-7.13. untranslated-name
-
- This field contains the name before filename translation was attempt.
- It MUST NOT be included unless the server also set the
- SSH_FILEXFER_ATTR_FLAGS_TRANSLATION_ERR (Section 7.9) bit in the
- attrib-bits field.
-
-7.14. Extended Attributes
-
- The SSH_FILEXFER_ATTR_EXTENDED flag provides a general extension
- mechanism for the attrib structure. If the flag is specified, then
- the 'extended_count' field is present. It specifies the number of
- 'extension-pair' items that follow. Each of these items specifies an
- extended attribute. Implementations MUST return SSH_FX_UNSUPPORTED
- if there are any unrecognized extensions. Clients can avoid sending
- unsupported extensions by examining the attrib-extension-names of the
- "supported2" extension attrib-extension-names (Section 5.4).
-
- Additional fields can be added to the attributes by either defining
- additional bits to the flags field to indicate their presence, or by
- defining extended attributes for them. The extended attributes
- mechanism is recommended for most purposes; additional flags bits
- should be defined only by an IETF standards action that also
- increments the protocol version number. The use of such new fields
- MUST be negotiated by the version number in the protocol exchange.
- It is a protocol error if a packet with unsupported protocol bits is
- received.
-
-
-8. Requests From the Client to the Server
-
- Requests from the client to the server represent the various file
- system operations.
-
-8.1. Opening and Closing Files and Directories
-
- Many operations in the protocol operate on open files. The
- SSH_FXP_OPEN and SSH_FXP_OPENDIR requests return a handle (which is
- an opaque variable-length string) which may be used to access the
- file or directory later. The client MUST NOT send requests to the
- server with bogus or closed handles. However, the server MUST
- perform adequate checks on the handle in order to avoid security
- risks due to fabricated handles.
-
- This design allows either stateful and stateless server
- implementation, as well as an implementation which caches state
- between requests but may also flush it. The contents of the file
- handle string are entirely up to the server and its design. The
-
-
-
-Galbraith & Saarenmaa Expires January 11, 2007 [Page 28]
-
-Internet-Draft SSH File Transfer Protocol July 2006
-
-
- client should not modify or attempt to interpret the file handle
- strings.
-
- The file handle strings MUST NOT be longer than 256 bytes.
-
-8.1.1. Opening a File
-
- Files are opened and created using the SSH_FXP_OPEN message.
-
- byte SSH_FXP_OPEN
- uint32 request-id
- string filename [UTF-8]
- uint32 desired-access
- uint32 flags
- ATTRS attrs
-
- The response to this message will be either SSH_FXP_HANDLE (if the
- operation is successful) or SSH_FXP_STATUS (if the operation fails.)
-
-8.1.1.1. filename
-
- The 'filename' field specifies the file name. See Section ''File
- Names'' for more information. If 'filename' is a directory file, the
- server MUST return an SSH_FX_FILE_IS_A_DIRECTORY error.
-
-8.1.1.2. desired-access
-
- The 'desired-access' field is a bitmask containing a combination of
- values from the ace-mask flags (Section 7.8). Note that again, the
- meaning of these flags is given in [RFC3010].
-
- The server MUST be prepared to translate the SFTP access flags into
- its local equivalents. If the server cannot grant the access
- desired, it MUST return SSH_FX_PERMISSION_DENIED.
-
- The server MAY open the file with greater access than requested if
- the user has such access and the server implementation requires it.
- For example, a server that does not distinguish between
- READ_ATTRIBUTE and READ_DATA will have to request full 'read' access
- to the file when the client only requested READ_ATTRIBUTE, resulting
- in greater access than the client originally requested.
-
- In such cases, it is possible, and permissible in the protocol, that
- the client could open a file requesting some limited access, and then
- access the file in a way not permitted by that limited access and the
- server would permit such action. However, the server MUST NOT ever
- grant access to the file that the client does not actually have the
- rights to.
-
-
-
-Galbraith & Saarenmaa Expires January 11, 2007 [Page 29]
-
-Internet-Draft SSH File Transfer Protocol July 2006
-
-
-8.1.1.3. flags
-
- The 'flags' field controls various aspects of the operation,
- including whether or not the file is created and the kind of locking
- desired.
-
- The following 'flags' are defined:
-
- SSH_FXF_ACCESS_DISPOSITION = 0x00000007
- SSH_FXF_CREATE_NEW = 0x00000000
- SSH_FXF_CREATE_TRUNCATE = 0x00000001
- SSH_FXF_OPEN_EXISTING = 0x00000002
- SSH_FXF_OPEN_OR_CREATE = 0x00000003
- SSH_FXF_TRUNCATE_EXISTING = 0x00000004
- SSH_FXF_APPEND_DATA = 0x00000008
- SSH_FXF_APPEND_DATA_ATOMIC = 0x00000010
- SSH_FXF_TEXT_MODE = 0x00000020
- SSH_FXF_BLOCK_READ = 0x00000040
- SSH_FXF_BLOCK_WRITE = 0x00000080
- SSH_FXF_BLOCK_DELETE = 0x00000100
- SSH_FXF_BLOCK_ADVISORY = 0x00000200
- SSH_FXF_NOFOLLOW = 0x00000400
- SSH_FXF_DELETE_ON_CLOSE = 0x00000800
- SSH_FXF_ACCESS_AUDIT_ALARM_INFO = 0x00001000
- SSH_FXF_ACCESS_BACKUP = 0x00002000
- SSH_FXF_BACKUP_STREAM = 0x00004000
- SSH_FXF_OVERRIDE_OWNER = 0x00008000
-
- SSH_FXF_ACCESS_DISPOSITION
- Disposition is a 3 bit field that controls how the file is opened.
- The server MUST support these bits. Any one of the following
- enumeration is allowed:
-
- SSH_FXF_CREATE_NEW
- A new file is created; if the file already exists, the server
- MUST return status SSH_FX_FILE_ALREADY_EXISTS.
-
- SSH_FXF_CREATE_TRUNCATE
- A new file is created; if the file already exists, it is opened
- and truncated.
-
- SSH_FXF_OPEN_EXISTING
- An existing file is opened. If the file does not exist, the
- server MUST return SSH_FX_NO_SUCH_FILE. If a directory in the
- path does not exist, the server SHOULD return
- SSH_FX_NO_SUCH_PATH. It is also acceptable if the server
- returns SSH_FX_NO_SUCH_FILE in this case.
-
-
-
-
-Galbraith & Saarenmaa Expires January 11, 2007 [Page 30]
-
-Internet-Draft SSH File Transfer Protocol July 2006
-
-
- SSH_FXF_OPEN_OR_CREATE
- If the file exists, it is opened. If the file does not exist,
- it is created.
-
- SSH_FXF_TRUNCATE_EXISTING
- An existing file is opened and truncated. If the file does not
- exist, the server MUST return the same error codes as defined
- for SSH_FXF_OPEN_EXISTING.
-
- SSH_FXF_APPEND_DATA
- Data is always written at the end of the file. The offset field
- of SSH_FXP_WRITE requests is ignored.
-
- Data is not required to be appended atomically. This means that
- if multiple writers attempt to append data simultaneously, data
- from the first may be lost. However, data MAY be appended
- atomically.
-
- SSH_FXF_APPEND_DATA_ATOMIC
- Data is always written at the end of the file. The offset field
- of the SSH_FXP_WRITE requests are ignored.
-
- Data MUST be written atomically so that there is no chance that
- multiple appenders can collide and result in data being lost.
-
- If both append flags are specified, the server SHOULD use atomic
- append if it is available, but SHOULD use non-atomic appends
- otherwise. The server SHOULD NOT fail the request in this case.
-
- SSH_FXF_TEXT_MODE
- Indicates that the server should treat the file as text and
- convert it to the canonical newline convention in use. (See
- Determining Server Newline Convention. (Section 5.3)
-
- When a file is opened with this flag, the offset field in the read
- and write functions is ignored.
-
- Servers MUST process multiple, parallel reads and writes correctly
- in this mode. Naturally, it is permissible for them to do this by
- serializing the requests.
-
- Clients SHOULD use the SSH_FXF_APPEND_DATA flag to append data to
- a text file rather then using write with a calculated offset.
-
-
-
-
-
-
-
-
-Galbraith & Saarenmaa Expires January 11, 2007 [Page 31]
-
-Internet-Draft SSH File Transfer Protocol July 2006
-
-
- To support seeks on text files the following SSH_FXP_EXTENDED
- packet is defined.
-
-
- string "text-seek"
- string file-handle
- uint64 line-number
-
- line-number is the index of the line number to seek to, where byte
- 0 in the file is line number 0, and the byte directly following
- the first newline sequence in the file is line number 1 and so on.
-
- The response to a "text-seek" request is an SSH_FXP_STATUS
- message.
-
- An attempt to seek past the end-of-file should result in a
- SSH_FX_EOF status.
-
- Servers SHOULD support at least one "text-seek" in order to
- support resume. However, a client MUST be prepared to receive
- SSH_FX_OP_UNSUPPORTED when attempting a "text-seek" operation.
- The client can then try a fall-back strategy, if it has one.
-
- SSH_FXF_BLOCK_READ
- The server MUST guarantee that no other handle has been opened
- with ACE4_READ_DATA access, and that no other handle will be
- opened with ACE4_READ_DATA access until the client closes the
- handle. (This MUST apply both to other clients and to other
- processes on the server.)
-
- If there is a conflicting lock the server MUST return
- SSH_FX_LOCK_CONFLICT. If the server cannot make the locking
- guarantee, it MUST return SSH_FX_OP_UNSUPPORTED.
-
- Other handles MAY be opened for ACE4_WRITE_DATA or any other
- combination of accesses, as long as ACE4_READ_DATA is not included
- in the mask.
-
- SSH_FXF_BLOCK_WRITE
- The server MUST guarantee that no other handle has been opened
- with ACE4_WRITE_DATA or ACE4_APPEND_DATA access, and that no other
- handle will be opened with ACE4_WRITE_DATA or ACE4_APPEND_DATA
- access until the client closes the handle. (This MUST apply both
- to other clients and to other processes on the server.)
-
-
-
-
-
-
-
-Galbraith & Saarenmaa Expires January 11, 2007 [Page 32]
-
-Internet-Draft SSH File Transfer Protocol July 2006
-
-
- If there is a conflicting lock the server MUST return
- SSH_FX_LOCK_CONFLICT. If the server cannot make the locking
- guarantee, it MUST return SSH_FX_OP_UNSUPPORTED.
-
- Other handles MAY be opened for ACE4_READ_DATA or any other
- combination of accesses, as long as neither ACE4_WRITE_DATA nor
- ACE4_APPEND_DATA are included in the mask.
-
- SSH_FXF_BLOCK_DELETE
- The server MUST guarantee that no other handle has been opened
- with ACE4_DELETE access, opened with the SSH_FXF_DELETE_ON_CLOSE
- flag set, and that no other handle will be opened with ACE4_DELETE
- access or with the SSH_FXF_DELETE_ON_CLOSE flag set, and that the
- file itself is not deleted in any other way until the client
- closes the handle.
-
- If there is a conflicting lock the server MUST return
- SSH_FX_LOCK_CONFLICT. If the server cannot make the locking
- guarantee, it MUST return SSH_FX_OP_UNSUPPORTED.
-
- SSH_FXF_BLOCK_ADVISORY
- If this bit is set, the above BLOCK modes are advisory. In
- advisory mode, only other accesses that specify a BLOCK mode need
- be considered when determining whether the BLOCK can be granted,
- and the server need not prevent I/O operations that violate the
- block mode.
-
- The server MAY perform mandatory locking even if the
- BLOCK_ADVISORY bit is set.
-
- SSH_FXF_NOFOLLOW
- If the final component of the path is a symlink, then the open
- MUST fail, and the error SSH_FX_LINK_LOOP MUST be returned.
-
- SSH_FXF_DELETE_ON_CLOSE
- The file should be deleted when the last handle to it is closed.
- (The last handle may not be an sftp-handle.) This MAY be emulated
- by a server if the OS doesn't support it by deleting the file when
- this handle is closed.
-
- It is implementation specific whether the directory entry is
- removed immediately or when the handle is closed.
-
- SSH_FXF_ACCESS_AUDIT_ALARM_INFO
- The client wishes the server to enable any privileges or extra
- capabilities that the user may have in to allow the reading and
- writing of AUDIT or ALARM access control entries.
-
-
-
-
-Galbraith & Saarenmaa Expires January 11, 2007 [Page 33]
-
-Internet-Draft SSH File Transfer Protocol July 2006
-
-
- SSH_FXF_ACCESS_BACKUP
- The client wishes the server to enable any privileges or extra
- capabilities that the user may have in order to bypass normal
- access checks for the purpose of backing up or restoring files.
-
- SSH_FXF_BACKUP_STREAM
- This bit indicates that the client wishes to read or write a
- backup stream. A backup stream is a system dependent structured
- data stream that encodes all the information that must be
- preserved in order to restore the file from backup medium.
-
- The only well defined use for backup stream data read in this
- fashion is to write it to the same server to a file also opened
- using the BACKUP_STREAM flag. However, if the server has a well
- defined backup stream format, there may be other uses for this
- data outside the scope of this protocol.
-
- ACCESS_OVERRIDE_OWNER
- This bit indicates that the client wishes the server to enable any
- privileges or extra capabilities that the user may have in order
- to gain access to the file with WRITE_OWNER permission.
-
- This bit MUST always be specified in combination with
- ACE4_WRITE_OWNER.
-
-
- The 'attrs' field specifies the initial attributes for the file.
- Default values MUST be supplied by the server for those attributes
- that are not specified. See Section ''File Attributes'' for more
- information.
-
- The 'attrs' field is ignored if an existing file is opened.
-
- The following table is provided to assist in mapping POSIX semantics
- to equivalent SFTP file open parameters:
-
- O_RDONLY
- desired-access = READ_DATA|READ_ATTRIBUTES
-
- O_WRONLY
- desired-access = WRITE_DATA|WRITE_ATTRIBUTES
-
- O_RDWR
- desired-access = READ_DATA|READ_ATTRIBUTES|WRITE_DATA|
- WRITE_ATTRIBUTES
-
-
-
-
-
-
-Galbraith & Saarenmaa Expires January 11, 2007 [Page 34]
-
-Internet-Draft SSH File Transfer Protocol July 2006
-
-
- O_APPEND
- desired-access = WRITE_DATA|WRITE_ATTRIBUTES|APPEND_DATA
- flags = SSH_FXF_APPEND_DATA and or SSH_FXF_APPEND_DATA_ATOMIC
-
- O_CREAT
- flags = SSH_FXF_OPEN_OR_CREATE
-
- O_TRUNC
- flags = SSH_FXF_TRUNCATE_EXISTING
-
- O_TRUNC|O_CREATE
- flags = SSH_FXF_CREATE_TRUNCATE
-
-8.1.2. Opening a Directory
-
- To enumerate a directory, the client first obtains a handle and then
- issues directory read requests. When enumeration is complete, the
- handle MUST be closed.
-
- byte SSH_FXP_OPENDIR
- uint32 request-id
- string path [UTF-8]
-
- path
- The 'path' field is the path name of the directory to be listed
- (without any trailing slash). See Section 'File Names' for more
- information on file names.
-
- If 'path' does not refer to a directory, the server MUST return
- SSH_FX_NOT_A_DIRECTORY.
-
-
- The response to this message will be either SSH_FXP_HANDLE (if the
- operation is successful) or SSH_FXP_STATUS (if the operation fails).
-
-8.1.3. Closing Handles
-
- A handle is closed using the following request.
-
- byte SSH_FXP_CLOSE
- uint32 request-id
- string handle
-
- handle
- 'handle' is a handle previously returned in the response to
- SSH_FXP_OPEN or SSH_FXP_OPENDIR. The handle becomes invalid
- immediately after this request has been sent.
-
-
-
-
-Galbraith & Saarenmaa Expires January 11, 2007 [Page 35]
-
-Internet-Draft SSH File Transfer Protocol July 2006
-
-
- The response to this request will be a SSH_FXP_STATUS message. Note
- that on some server platforms even a close can fail. For example, if
- the server operating system caches writes, and an error occurs while
- flushing cached writes, the close operation may fail.
-
- Note that the handle is invalid regardless of the SSH_FXP_STATUS
- result. There is no way for the client to recover a handle that
- fails to close. The client MUST release all resources associated
- with the handle regardless of the status. The server SHOULD take
- whatever steps it can to recover from a close failure and to ensure
- that all resources associated with the handle on the server are
- correctly released.
-
-8.2. Reading and Writing
-
-8.2.1. Reading Files
-
- The following request can be used to read file data:
-
- byte SSH_FXP_READ
- uint32 request-id
- string handle
- uint64 offset
- uint32 length
-
- handle
- 'handle' is an open file handle returned by SSH_FXP_OPEN. If
- 'handle' is not a handle returned by SSH_FXP_OPEN, the server MUST
- return SSH_FX_INVALID_HANDLE.
-
- offset
- The offset (in bytes) relative to the beginning of the file that
- the read MUST start at. This field is ignored if
- SSH_FXF_TEXT_MODE was specified during the open.
-
- length
- 'length' is the maximum number of bytes to read.
-
- The server MUST not respond with more data than is specified by
- the 'length' parameter. However, the server MAY respond with less
- data if EOF is reached, an error is encountered, or the servers
- internal buffers can not handle such a large request.
-
- If the server specified a non-zero 'max-read-size' in its
- 'supported2' (Section 5.4) extension and 'length' is <= 'max-read-
- size', then failure to return 'length' bytes indicates that EOF or
- an error occurred.
-
-
-
-
-Galbraith & Saarenmaa Expires January 11, 2007 [Page 36]
-
-Internet-Draft SSH File Transfer Protocol July 2006
-
-
-8.2.2. Reading Directories
-
- In order to retrieve a directory listing, the client issues one or
- more SSH_FXP_READDIR requests. In order to obtain a complete
- directory listing, the client MUST issue repeated SSH_FXP_READDIR
- requests until the server responds with an SSH_FXP_STATUS message.
-
- byte SSH_FXP_READDIR
- uint32 request-id
- string handle
-
- handle
- 'handle' is a handle returned by SSH_FXP_OPENDIR. If 'handle' is
- an ordinary file handle returned by SSH_FXP_OPEN, the server MUST
- return SSH_FX_INVALID_HANDLE.
-
-
- The server responds to this request with either a SSH_FXP_NAME or a
- SSH_FXP_STATUS message. One or more names may be returned at a time.
- Full status information is returned for each name in order to speed
- up typical directory listings.
-
- If there are no more names available to be read, the server MUST
- respond with a SSH_FXP_STATUS message with error code of SSH_FX_EOF.
-
-8.2.3. Writing Files
-
- Writing to a file is achieved using the following message:
-
- byte SSH_FXP_WRITE
- uint32 request-id
- string handle
- uint64 offset
- string data
-
- handle
- 'handle' is an open file handle returned by SSH_FXP_OPEN. If
- 'handle' is not a handle returned by SSH_FXP_OPEN, the server MUST
- return SSH_FX_INVALID_HANDLE.
-
- offset
- The offset (in bytes) relative to the beginning of the file that
- the write MUST start at. This field is ignored if
- SSH_FXF_TEXT_MODE was specified during the open.
-
-
-
-
-
-
-
-Galbraith & Saarenmaa Expires January 11, 2007 [Page 37]
-
-Internet-Draft SSH File Transfer Protocol July 2006
-
-
- The write will extend the file if writing beyond the end of the
- file. It is legal to write to an offset that extends beyond the
- end of the file; the semantics are to write the byte value 0x00
- from the end of the file to the specified offset and then the
- data. On most operating systems, such writes do not allocate disk
- space but instead create a sparse file.
-
- data
- The data to write to the file.
-
- The server responds to a write request with a SSH_FXP_STATUS message.
-
-8.3. Removing and Renaming Files
-
- The following request can be used to remove a file:
-
- byte SSH_FXP_REMOVE
- uint32 request-id
- string filename [UTF-8]
-
- filename
- 'filename' is the name of the file to be removed. See Section
- 'File Names' for more information.
-
- If 'filename' is a symbolic link, the link is removed, not the
- file it points to.
- This request cannot be used to remove directories. The server
- MUST return SSH_FX_FILE_IS_A_DIRECTORY in this case.
-
-
- The server will respond to this request with a SSH_FXP_STATUS
- message.
-
- Files (and directories) can be renamed using the SSH_FXP_RENAME
- message.
-
- byte SSH_FXP_RENAME
- uint32 request-id
- string oldpath [UTF-8]
- string newpath [UTF-8]
- uint32 flags
-
- where 'request-id' is the request identifier, 'oldpath' is the name
- of an existing file or directory, and 'newpath' is the new name for
- the file or directory.
-
- 'flags' is 0 or a combination of:
-
-
-
-
-Galbraith & Saarenmaa Expires January 11, 2007 [Page 38]
-
-Internet-Draft SSH File Transfer Protocol July 2006
-
-
- SSH_FXF_RENAME_OVERWRITE 0x00000001
- SSH_FXF_RENAME_ATOMIC 0x00000002
- SSH_FXF_RENAME_NATIVE 0x00000004
-
- If the server cannot support the requested mode of operation, it must
- return SSH_FX_OP_UNSUPPORTED.
-
- If flags does not include SSH_FXP_RENAME_OVERWRITE, and there already
- exists a file with the name specified by newpath, the server MUST
- respond with SSH_FX_FILE_ALREADY_EXISTS.
-
- If flags includes SSH_FXP_RENAME_ATOMIC, and the destination file
- already exists, it is replaced in an atomic fashion. I.e., there is
- no observable instant in time where the name does not refer to either
- the old or the new file. SSH_FXP_RENAME_ATOMIC implies
- SSH_FXP_RENAME_OVERWRITE.
-
- If 'SSH_FXP_RENAME_OVERWRITE' is not present, and the server does not
- support this mode natively, it MAY emulate it by checking for the
- existance of a file before executing the rename operation.
-
- If the 'SSH_FXF_RENAME_ATOMIC' is specified without the the
- 'SSH_FXP_RENAME_OVERWRITE', then the server MUST be able to perform
- the check and rename operation atomically.
-
- Because some servers cannot provide atomic rename, clients should
- only specify atomic rename if correct operation requires it. If
- SSH_FXP_RENAME_OVERWRITE is specified, the server MAY perform an
- atomic rename even if it is not requested.
-
- If flags includes SSH_FXP_RENAME_NATIVE, the server is free to do the
- rename operation in whatever fashion it deems appropriate. Other
- flag values are considered hints as to desired behavior, but not
- requirements.
-
- The server will respond to this request with a SSH_FXP_STATUS
- message.
-
-8.4. Creating and Deleting Directories
-
- New directories can be created using the SSH_FXP_MKDIR request. It
- has the following format:
-
- byte SSH_FXP_MKDIR
- uint32 request-id
- string path [UTF-8]
- ATTRS attrs
-
-
-
-
-Galbraith & Saarenmaa Expires January 11, 2007 [Page 39]
-
-Internet-Draft SSH File Transfer Protocol July 2006
-
-
- where 'request-id' is the request identifier.
-
- 'path' specifies the directory to be created. See Section ''File
- Names'' for more information on file names.
-
- 'attrs' specifies the attributes that should be applied to it upon
- creation. Attributes are discussed in more detail in Section ''File
- Attributes''.
-
- The server will respond to this request with a SSH_FXP_STATUS
- message. If a file or directory with the specified path already
- exists, an error will be returned.
-
- Directories can be removed using the SSH_FXP_RMDIR request, which has
- the following format:
-
- byte SSH_FXP_RMDIR
- uint32 request-id
- string path [UTF-8]
-
- where 'request-id' is the request identifier, and 'path' specifies
- the directory to be removed. See Section ''File Names'' for more
- information on file names.
-
- The server responds to this request with a SSH_FXP_STATUS message.
-
-8.5. Retrieving File Attributes
-
- Very often, file attributes are automatically returned by
- SSH_FXP_READDIR. However, sometimes there is need to specifically
- retrieve the attributes for a named file. This can be done using the
- SSH_FXP_STAT, SSH_FXP_LSTAT and SSH_FXP_FSTAT requests.
-
- SSH_FXP_STAT and SSH_FXP_LSTAT only differ in that SSH_FXP_STAT
- follows symbolic links on the server, whereas SSH_FXP_LSTAT does not
- follow symbolic links. Both have the same format:
-
- byte SSH_FXP_STAT or SSH_FXP_LSTAT
- uint32 request-id
- string path [UTF-8]
- uint32 flags
-
- where 'request-id' is the request identifier, and 'path' specifies
- the file system object for which status is to be returned. The
- server responds to this request with either SSH_FXP_ATTRS or
- SSH_FXP_STATUS.
-
- The flags field specify the attribute flags in which the client has
-
-
-
-Galbraith & Saarenmaa Expires January 11, 2007 [Page 40]
-
-Internet-Draft SSH File Transfer Protocol July 2006
-
-
- particular interest. This is a hint to the server. For example,
- because retrieving owner / group and acl information can be an
- expensive operation under some operating systems, the server may
- choose not to retrieve this information unless the client expresses a
- specific interest in it.
-
- The client has no guarantee the server will provide all the fields
- that it has expressed an interest in.
-
- SSH_FXP_FSTAT differs from the others in that it returns status
- information for an open file (identified by the file handle).
-
- byte SSH_FXP_FSTAT
- uint32 request-id
- string handle
- uint32 flags
-
- handle
- 'handle' is an open file handle from either SSH_FXP_OPEN or
- SSH_FXP_OPENDIR.
-
-
- The server responds to this request with SSH_FXP_ATTRS or
- SSH_FXP_STATUS.
-
-8.6. Setting File Attributes
-
- File attributes may be modified using the SSH_FXP_SETSTAT and
- SSH_FXP_FSETSTAT requests.
-
- byte SSH_FXP_SETSTAT
- uint32 request-id
- string path [UTF-8]
- ATTRS attrs
-
-
- byte SSH_FXP_FSETSTAT
- uint32 request-id
- string handle
- ATTRS attrs
-
- path
- The file system object (e.g. file or directory) whose attributes
- are to be modified. If this object does not exist, or the user
- does not have sufficient access to write the attributes, the
- request MUST fail.
-
-
-
-
-
-Galbraith & Saarenmaa Expires January 11, 2007 [Page 41]
-
-Internet-Draft SSH File Transfer Protocol July 2006
-
-
- handle
- 'handle' is an open file handle from either SSH_FXP_OPEN or
- SSH_FXP_OPENDIR. If the handle was not opened with sufficient
-
<TRUNCATED>
[5/9] Remove third party documents from scm
Posted by gn...@apache.org.
http://git-wip-us.apache.org/repos/asf/mina-sshd/blob/46ea0930/sshd-core/src/docs/rfc4251.txt
----------------------------------------------------------------------
diff --git a/sshd-core/src/docs/rfc4251.txt b/sshd-core/src/docs/rfc4251.txt
deleted file mode 100644
index ffc33ea..0000000
--- a/sshd-core/src/docs/rfc4251.txt
+++ /dev/null
@@ -1,1683 +0,0 @@
-
-
-
-
-
-
-Network Working Group T. Ylonen
-Request for Comments: 4251 SSH Communications Security Corp
-Category: Standards Track C. Lonvick, Ed.
- Cisco Systems, Inc.
- January 2006
-
-
- The Secure Shell (SSH) Protocol Architecture
-
-Status of This Memo
-
- This document specifies an Internet standards track protocol for the
- Internet community, and requests discussion and suggestions for
- improvements. Please refer to the current edition of the "Internet
- Official Protocol Standards" (STD 1) for the standardization state
- and status of this protocol. Distribution of this memo is unlimited.
-
-Copyright Notice
-
- Copyright (C) The Internet Society (2006).
-
-Abstract
-
- The Secure Shell (SSH) Protocol is a protocol for secure remote login
- and other secure network services over an insecure network. This
- document describes the architecture of the SSH protocol, as well as
- the notation and terminology used in SSH protocol documents. It also
- discusses the SSH algorithm naming system that allows local
- extensions. The SSH protocol consists of three major components: The
- Transport Layer Protocol provides server authentication,
- confidentiality, and integrity with perfect forward secrecy. The
- User Authentication Protocol authenticates the client to the server.
- The Connection Protocol multiplexes the encrypted tunnel into several
- logical channels. Details of these protocols are described in
- separate documents.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Ylonen & Lonvick Standards Track [Page 1]
-
-RFC 4251 SSH Protocol Architecture January 2006
-
-
-Table of Contents
-
- 1. Introduction ....................................................3
- 2. Contributors ....................................................3
- 3. Conventions Used in This Document ...............................4
- 4. Architecture ....................................................4
- 4.1. Host Keys ..................................................4
- 4.2. Extensibility ..............................................6
- 4.3. Policy Issues ..............................................6
- 4.4. Security Properties ........................................7
- 4.5. Localization and Character Set Support .....................7
- 5. Data Type Representations Used in the SSH Protocols .............8
- 6. Algorithm and Method Naming ....................................10
- 7. Message Numbers ................................................11
- 8. IANA Considerations ............................................12
- 9. Security Considerations ........................................13
- 9.1. Pseudo-Random Number Generation ...........................13
- 9.2. Control Character Filtering ...............................14
- 9.3. Transport .................................................14
- 9.3.1. Confidentiality ....................................14
- 9.3.2. Data Integrity .....................................16
- 9.3.3. Replay .............................................16
- 9.3.4. Man-in-the-middle ..................................17
- 9.3.5. Denial of Service ..................................19
- 9.3.6. Covert Channels ....................................20
- 9.3.7. Forward Secrecy ....................................20
- 9.3.8. Ordering of Key Exchange Methods ...................20
- 9.3.9. Traffic Analysis ...................................21
- 9.4. Authentication Protocol ...................................21
- 9.4.1. Weak Transport .....................................21
- 9.4.2. Debug Messages .....................................22
- 9.4.3. Local Security Policy ..............................22
- 9.4.4. Public Key Authentication ..........................23
- 9.4.5. Password Authentication ............................23
- 9.4.6. Host-Based Authentication ..........................23
- 9.5. Connection Protocol .......................................24
- 9.5.1. End Point Security .................................24
- 9.5.2. Proxy Forwarding ...................................24
- 9.5.3. X11 Forwarding .....................................24
- 10. References ....................................................26
- 10.1. Normative References .....................................26
- 10.2. Informative References ...................................26
- Authors' Addresses ................................................29
- Trademark Notice ..................................................29
-
-
-
-
-
-
-
-Ylonen & Lonvick Standards Track [Page 2]
-
-RFC 4251 SSH Protocol Architecture January 2006
-
-
-1. Introduction
-
- Secure Shell (SSH) is a protocol for secure remote login and other
- secure network services over an insecure network. It consists of
- three major components:
-
- o The Transport Layer Protocol [SSH-TRANS] provides server
- authentication, confidentiality, and integrity. It may optionally
- also provide compression. The transport layer will typically be
- run over a TCP/IP connection, but might also be used on top of any
- other reliable data stream.
-
- o The User Authentication Protocol [SSH-USERAUTH] authenticates the
- client-side user to the server. It runs over the transport layer
- protocol.
-
- o The Connection Protocol [SSH-CONNECT] multiplexes the encrypted
- tunnel into several logical channels. It runs over the user
- authentication protocol.
-
- The client sends a service request once a secure transport layer
- connection has been established. A second service request is sent
- after user authentication is complete. This allows new protocols to
- be defined and coexist with the protocols listed above.
-
- The connection protocol provides channels that can be used for a wide
- range of purposes. Standard methods are provided for setting up
- secure interactive shell sessions and for forwarding ("tunneling")
- arbitrary TCP/IP ports and X11 connections.
-
-2. Contributors
-
- The major original contributors of this set of documents have been:
- Tatu Ylonen, Tero Kivinen, Timo J. Rinne, Sami Lehtinen (all of SSH
- Communications Security Corp), and Markku-Juhani O. Saarinen
- (University of Jyvaskyla). Darren Moffat was the original editor of
- this set of documents and also made very substantial contributions.
-
- Many people contributed to the development of this document over the
- years. People who should be acknowledged include Mats Andersson, Ben
- Harris, Bill Sommerfeld, Brent McClure, Niels Moller, Damien Miller,
- Derek Fawcus, Frank Cusack, Heikki Nousiainen, Jakob Schlyter, Jeff
- Van Dyke, Jeffrey Altman, Jeffrey Hutzelman, Jon Bright, Joseph
- Galbraith, Ken Hornstein, Markus Friedl, Martin Forssen, Nicolas
- Williams, Niels Provos, Perry Metzger, Peter Gutmann, Simon
- Josefsson, Simon Tatham, Wei Dai, Denis Bider, der Mouse, and
- Tadayoshi Kohno. Listing their names here does not mean that they
- endorse this document, but that they have contributed to it.
-
-
-
-Ylonen & Lonvick Standards Track [Page 3]
-
-RFC 4251 SSH Protocol Architecture January 2006
-
-
-3. Conventions Used in This Document
-
- All documents related to the SSH protocols shall use the keywords
- "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
- "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" to describe
- requirements. These keywords are to be interpreted as described in
- [RFC2119].
-
- The keywords "PRIVATE USE", "HIERARCHICAL ALLOCATION", "FIRST COME
- FIRST SERVED", "EXPERT REVIEW", "SPECIFICATION REQUIRED", "IESG
- APPROVAL", "IETF CONSENSUS", and "STANDARDS ACTION" that appear in
- this document when used to describe namespace allocation are to be
- 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. Architecture
-
-4.1. Host Keys
-
- Each server host SHOULD have a host key. Hosts MAY have multiple
- host keys using multiple different algorithms. Multiple hosts MAY
- share the same host key. If a host has keys at all, it MUST have at
- least one key that uses each REQUIRED public key algorithm (DSS
- [FIPS-186-2]).
-
- The server host key is used during key exchange to verify that the
- client is really talking to the correct server. For this to be
- possible, the client must have a priori knowledge of the server's
- public host key.
-
- Two different trust models can be used:
-
- o The client has a local database that associates each host name (as
- typed by the user) with the corresponding public host key. This
- method requires no centrally administered infrastructure, and no
-
-
-
-Ylonen & Lonvick Standards Track [Page 4]
-
-RFC 4251 SSH Protocol Architecture January 2006
-
-
- third-party coordination. The downside is that the database of
- name-to-key associations may become burdensome to maintain.
-
- o The host name-to-key association is certified by a trusted
- certification authority (CA). The client only knows the CA root
- key, and can verify the validity of all host keys certified by
- accepted CAs.
-
- The second alternative eases the maintenance problem, since ideally
- only a single CA key needs to be securely stored on the client. On
- the other hand, each host key must be appropriately certified by a
- central authority before authorization is possible. Also, a lot of
- trust is placed on the central infrastructure.
-
- The protocol provides the option that the server name - host key
- association is not checked when connecting to the host for the first
- time. This allows communication without prior communication of host
- keys or certification. The connection still provides protection
- against passive listening; however, it becomes vulnerable to active
- man-in-the-middle attacks. Implementations SHOULD NOT normally allow
- such connections by default, as they pose a potential security
- problem. However, as there is no widely deployed key infrastructure
- available on the Internet at the time of this writing, this option
- makes the protocol much more usable during the transition time until
- such an infrastructure emerges, while still providing a much higher
- level of security than that offered by older solutions (e.g., telnet
- [RFC0854] and rlogin [RFC1282]).
-
- Implementations SHOULD try to make the best effort to check host
- keys. An example of a possible strategy is to only accept a host key
- without checking the first time a host is connected, save the key in
- a local database, and compare against that key on all future
- connections to that host.
-
- Implementations MAY provide additional methods for verifying the
- correctness of host keys, e.g., a hexadecimal fingerprint derived
- from the SHA-1 hash [FIPS-180-2] of the public key. Such
- fingerprints can easily be verified by using telephone or other
- external communication channels.
-
- All implementations SHOULD provide an option not to accept host keys
- that cannot be verified.
-
- The members of this Working Group believe that 'ease of use' is
- critical to end-user acceptance of security solutions, and no
- improvement in security is gained if the new solutions are not used.
- Thus, providing the option not to check the server host key is
-
-
-
-
-Ylonen & Lonvick Standards Track [Page 5]
-
-RFC 4251 SSH Protocol Architecture January 2006
-
-
- believed to improve the overall security of the Internet, even though
- it reduces the security of the protocol in configurations where it is
- allowed.
-
-4.2. Extensibility
-
- We believe that the protocol will evolve over time, and some
- organizations will want to use their own encryption, authentication,
- and/or key exchange methods. Central registration of all extensions
- is cumbersome, especially for experimental or classified features.
- On the other hand, having no central registration leads to conflicts
- in method identifiers, making interoperability difficult.
-
- We have chosen to identify algorithms, methods, formats, and
- extension protocols with textual names that are of a specific format.
- DNS names are used to create local namespaces where experimental or
- classified extensions can be defined without fear of conflicts with
- other implementations.
-
- One design goal has been to keep the base protocol as simple as
- possible, and to require as few algorithms as possible. However, all
- implementations MUST support a minimal set of algorithms to ensure
- interoperability (this does not imply that the local policy on all
- hosts would necessarily allow these algorithms). The mandatory
- algorithms are specified in the relevant protocol documents.
-
- Additional algorithms, methods, formats, and extension protocols can
- be defined in separate documents. See Section 6, Algorithm Naming,
- for more information.
-
-4.3. Policy Issues
-
- The protocol allows full negotiation of encryption, integrity, key
- exchange, compression, and public key algorithms and formats.
- Encryption, integrity, public key, and compression algorithms can be
- different for each direction.
-
- The following policy issues SHOULD be addressed in the configuration
- mechanisms of each implementation:
-
- o Encryption, integrity, and compression algorithms, separately for
- each direction. The policy MUST specify which is the preferred
- algorithm (e.g., the first algorithm listed in each category).
-
- o Public key algorithms and key exchange method to be used for host
- authentication. The existence of trusted host keys for different
- public key algorithms also affects this choice.
-
-
-
-
-Ylonen & Lonvick Standards Track [Page 6]
-
-RFC 4251 SSH Protocol Architecture January 2006
-
-
- o The authentication methods that are to be required by the server
- for each user. The server's policy MAY require multiple
- authentication for some or all users. The required algorithms MAY
- depend on the location from where the user is trying to gain
- access.
-
- o The operations that the user is allowed to perform using the
- connection protocol. Some issues are related to security; for
- example, the policy SHOULD NOT allow the server to start sessions
- or run commands on the client machine, and MUST NOT allow
- connections to the authentication agent unless forwarding such
- connections has been requested. Other issues, such as which
- TCP/IP ports can be forwarded and by whom, are clearly issues of
- local policy. Many of these issues may involve traversing or
- bypassing firewalls, and are interrelated with the local security
- policy.
-
-4.4. Security Properties
-
- The primary goal of the SSH protocol is to improve security on the
- Internet. It attempts to do this in a way that is easy to deploy,
- even at the cost of absolute security.
-
- o All encryption, integrity, and public key algorithms used are
- well-known, well-established algorithms.
-
- o All algorithms are used with cryptographically sound key sizes
- that are believed to provide protection against even the strongest
- cryptanalytic attacks for decades.
-
- o All algorithms are negotiated, and in case some algorithm is
- broken, it is easy to switch to some other algorithm without
- modifying the base protocol.
-
- Specific concessions were made to make widespread, fast deployment
- easier. The particular case where this comes up is verifying that
- the server host key really belongs to the desired host; the protocol
- allows the verification to be left out, but this is NOT RECOMMENDED.
- This is believed to significantly improve usability in the short
- term, until widespread Internet public key infrastructures emerge.
-
-4.5. Localization and Character Set Support
-
- For the most part, the SSH protocols do not directly pass text that
- would be displayed to the user. However, there are some places where
- such data might be passed. When applicable, the character set for
-
-
-
-
-
-Ylonen & Lonvick Standards Track [Page 7]
-
-RFC 4251 SSH Protocol Architecture January 2006
-
-
- the data MUST be explicitly specified. In most places, ISO-10646
- UTF-8 encoding is used [RFC3629]. When applicable, a field is also
- provided for a language tag [RFC3066].
-
- One big issue is the character set of the interactive session. There
- is no clear solution, as different applications may display data in
- different formats. Different types of terminal emulation may also be
- employed in the client, and the character set to be used is
- effectively determined by the terminal emulation. Thus, no place is
- provided for directly specifying the character set or encoding for
- terminal session data. However, the terminal emulation type (e.g.,
- "vt100") is transmitted to the remote site, and it implicitly
- specifies the character set and encoding. Applications typically use
- the terminal type to determine what character set they use, or the
- character set is determined using some external means. The terminal
- emulation may also allow configuring the default character set. In
- any case, the character set for the terminal session is considered
- primarily a client local issue.
-
- Internal names used to identify algorithms or protocols are normally
- never displayed to users, and must be in US-ASCII.
-
- The client and server user names are inherently constrained by what
- the server is prepared to accept. They might, however, occasionally
- be displayed in logs, reports, etc. They MUST be encoded using ISO
- 10646 UTF-8, but other encodings may be required in some cases. It
- is up to the server to decide how to map user names to accepted user
- names. Straight bit-wise, binary comparison is RECOMMENDED.
-
- For localization purposes, the protocol attempts to minimize the
- number of textual messages transmitted. When present, such messages
- typically relate to errors, debugging information, or some externally
- configured data. For data that is normally displayed, it SHOULD be
- possible to fetch a localized message instead of the transmitted
- message by using a numerical code. The remaining messages SHOULD be
- configurable.
-
-5. Data Type Representations Used in the SSH Protocols
-
- byte
-
- A byte represents an arbitrary 8-bit value (octet). Fixed length
- data is sometimes represented as an array of bytes, written
- byte[n], where n is the number of bytes in the array.
-
-
-
-
-
-
-
-Ylonen & Lonvick Standards Track [Page 8]
-
-RFC 4251 SSH Protocol Architecture January 2006
-
-
- boolean
-
- A boolean value is stored as a single byte. The value 0
- represents FALSE, and the value 1 represents TRUE. All non-zero
- values MUST be interpreted as TRUE; however, applications MUST NOT
- store values other than 0 and 1.
-
- uint32
-
- Represents a 32-bit unsigned integer. Stored as four bytes in the
- order of decreasing significance (network byte order). For
- example: the value 699921578 (0x29b7f4aa) is stored as 29 b7 f4
- aa.
-
- uint64
-
- Represents a 64-bit unsigned integer. Stored as eight bytes in
- the order of decreasing significance (network byte order).
-
- string
-
- Arbitrary length binary string. Strings are allowed to contain
- arbitrary binary data, including null characters and 8-bit
- characters. They are stored as a uint32 containing its length
- (number of bytes that follow) and zero (= empty string) or more
- bytes that are the value of the string. Terminating null
- characters are not used.
-
- Strings are also used to store text. In that case, US-ASCII is
- used for internal names, and ISO-10646 UTF-8 for text that might
- be displayed to the user. The terminating null character SHOULD
- NOT normally be stored in the string. For example: the US-ASCII
- string "testing" is represented as 00 00 00 07 t e s t i n g. The
- UTF-8 mapping does not alter the encoding of US-ASCII characters.
-
- mpint
-
- Represents multiple precision integers in two's complement format,
- stored as a string, 8 bits per byte, MSB first. Negative numbers
- have the value 1 as the most significant bit of the first byte of
- the data partition. If the most significant bit would be set for
- a positive number, the number MUST be preceded by a zero byte.
- Unnecessary leading bytes with the value 0 or 255 MUST NOT be
- included. The value zero MUST be stored as a string with zero
- bytes of data.
-
- By convention, a number that is used in modular computations in
- Z_n SHOULD be represented in the range 0 <= x < n.
-
-
-
-Ylonen & Lonvick Standards Track [Page 9]
-
-RFC 4251 SSH Protocol Architecture January 2006
-
-
- Examples:
-
- value (hex) representation (hex)
- ----------- --------------------
- 0 00 00 00 00
- 9a378f9b2e332a7 00 00 00 08 09 a3 78 f9 b2 e3 32 a7
- 80 00 00 00 02 00 80
- -1234 00 00 00 02 ed cc
- -deadbeef 00 00 00 05 ff 21 52 41 11
-
- name-list
-
- A string containing a comma-separated list of names. A name-list
- is represented as a uint32 containing its length (number of bytes
- that follow) followed by a comma-separated list of zero or more
- names. A name MUST have a non-zero length, and it MUST NOT
- contain a comma (","). As this is a list of names, all of the
- elements contained are names and MUST be in US-ASCII. Context may
- impose additional restrictions on the names. For example, the
- names in a name-list may have to be a list of valid algorithm
- identifiers (see Section 6 below), or a list of [RFC3066] language
- tags. The order of the names in a name-list may or may not be
- significant. Again, this depends on the context in which the list
- is used. Terminating null characters MUST NOT be used, neither
- for the individual names, nor for the list as a whole.
-
- Examples:
-
- value representation (hex)
- ----- --------------------
- (), the empty name-list 00 00 00 00
- ("zlib") 00 00 00 04 7a 6c 69 62
- ("zlib,none") 00 00 00 09 7a 6c 69 62 2c 6e 6f 6e 65
-
-6. Algorithm and Method Naming
-
- The SSH protocols refer to particular hash, encryption, integrity,
- compression, and key exchange algorithms or methods by name. There
- are some standard algorithms and methods that all implementations
- MUST support. There are also algorithms and methods that are defined
- in the protocol specification, but are OPTIONAL. Furthermore, it is
- expected that some organizations will want to use their own
- algorithms or methods.
-
- In this protocol, all algorithm and method identifiers MUST be
- printable US-ASCII, non-empty strings no longer than 64 characters.
- Names MUST be case-sensitive.
-
-
-
-
-Ylonen & Lonvick Standards Track [Page 10]
-
-RFC 4251 SSH Protocol Architecture January 2006
-
-
- There are two formats for algorithm and method names:
-
- o Names that do not contain an at-sign ("@") are reserved to be
- assigned by IETF CONSENSUS. Examples include "3des-cbc", "sha-1",
- "hmac-sha1", and "zlib" (the doublequotes are not part of the
- name). Names of this format are only valid if they are first
- registered with the IANA. Registered names MUST NOT contain an
- at-sign ("@"), comma (","), whitespace, control characters (ASCII
- codes 32 or less), or the ASCII code 127 (DEL). Names are case-
- sensitive, and MUST NOT be longer than 64 characters.
-
- o Anyone can define additional algorithms or methods by using names
- in the format name@domainname, e.g., "ourcipher-cbc@example.com".
- The format of the part preceding the at-sign is not specified;
- however, these names MUST be printable US-ASCII strings, and MUST
- NOT contain the comma character (","), whitespace, control
- characters (ASCII codes 32 or less), or the ASCII code 127 (DEL).
- They MUST have only a single at-sign in them. The part following
- the at-sign MUST be a valid, fully qualified domain name [RFC1034]
- controlled by the person or organization defining the name. Names
- are case-sensitive, and MUST NOT be longer than 64 characters. It
- is up to each domain how it manages its local namespace. It
- should be noted that these names resemble STD 11 [RFC0822] email
- addresses. This is purely coincidental and has nothing to do with
- STD 11 [RFC0822].
-
-7. Message Numbers
-
- SSH packets have message numbers in the range 1 to 255. These
- numbers have been allocated as follows:
-
- Transport layer protocol:
-
- 1 to 19 Transport layer generic (e.g., disconnect, ignore,
- debug, etc.)
- 20 to 29 Algorithm negotiation
- 30 to 49 Key exchange method specific (numbers can be reused
- for different authentication methods)
-
- User authentication protocol:
-
- 50 to 59 User authentication generic
- 60 to 79 User authentication method specific (numbers can be
- reused for different authentication methods)
-
-
-
-
-
-
-
-Ylonen & Lonvick Standards Track [Page 11]
-
-RFC 4251 SSH Protocol Architecture January 2006
-
-
- Connection protocol:
-
- 80 to 89 Connection protocol generic
- 90 to 127 Channel related messages
-
- Reserved for client protocols:
-
- 128 to 191 Reserved
-
- Local extensions:
-
- 192 to 255 Local extensions
-
-8. IANA Considerations
-
- This document is part of a set. The instructions for the IANA for
- the SSH protocol, as defined in this document, [SSH-USERAUTH],
- [SSH-TRANS], and [SSH-CONNECT], are detailed in [SSH-NUMBERS]. The
- following is a brief summary for convenience, but note well that
- [SSH-NUMBERS] contains the actual instructions to the IANA, which may
- be superseded in the future.
-
- Allocation of the following types of names in the SSH protocols is
- assigned by IETF consensus:
-
- o Service Names
- * Authentication Methods
- * Connection Protocol Channel Names
- * Connection Protocol Global Request Names
- * Connection Protocol Channel Request Names
-
- o Key Exchange Method Names
-
- o Assigned Algorithm Names
- * Encryption Algorithm Names
- * MAC Algorithm Names
- * Public Key Algorithm Names
- * Compression Algorithm Names
-
- These names MUST be printable US-ASCII strings, and MUST NOT contain
- the characters at-sign ("@"), comma (","), whitespace, control
- characters (ASCII codes 32 or less), or the ASCII code 127 (DEL).
- Names are case-sensitive, and MUST NOT be longer than 64 characters.
-
- Names with the at-sign ("@") are locally defined extensions and are
- not controlled by the IANA.
-
-
-
-
-
-Ylonen & Lonvick Standards Track [Page 12]
-
-RFC 4251 SSH Protocol Architecture January 2006
-
-
- Each category of names listed above has a separate namespace.
- However, using the same name in multiple categories SHOULD be avoided
- to minimize confusion.
-
- Message numbers (see Section 7) in the range of 0 to 191 are
- allocated via IETF CONSENSUS, as described in [RFC2434]. Message
- numbers in the 192 to 255 range (local extensions) are reserved for
- PRIVATE USE, also as described in [RFC2434].
-
-9. Security Considerations
-
- In order to make the entire body of Security Considerations more
- accessible, Security Considerations for the transport,
- authentication, and connection documents have been gathered here.
-
- The transport protocol [SSH-TRANS] provides a confidential channel
- over an insecure network. It performs server host authentication,
- key exchange, encryption, and integrity protection. It also derives
- a unique session id that may be used by higher-level protocols.
-
- The authentication protocol [SSH-USERAUTH] provides a suite of
- mechanisms that can be used to authenticate the client user to the
- server. Individual mechanisms specified in the authentication
- protocol use the session id provided by the transport protocol and/or
- depend on the security and integrity guarantees of the transport
- protocol.
-
- The connection protocol [SSH-CONNECT] specifies a mechanism to
- multiplex multiple streams (channels) of data over the confidential
- and authenticated transport. It also specifies channels for
- accessing an interactive shell, for proxy-forwarding various external
- protocols over the secure transport (including arbitrary TCP/IP
- protocols), and for accessing secure subsystems on the server host.
-
-9.1. Pseudo-Random Number Generation
-
- This protocol binds each session key to the session by including
- random, session specific data in the hash used to produce session
- keys. Special care should be taken to ensure that all of the random
- numbers are of good quality. If the random data here (e.g., Diffie-
- Hellman (DH) parameters) are pseudo-random, then the pseudo-random
- number generator should be cryptographically secure (i.e., its next
- output not easily guessed even when knowing all previous outputs)
- and, furthermore, proper entropy needs to be added to the pseudo-
- random number generator. [RFC4086] offers suggestions for sources of
- random numbers and entropy. Implementers should note the importance
- of entropy and the well-meant, anecdotal warning about the difficulty
- in properly implementing pseudo-random number generating functions.
-
-
-
-Ylonen & Lonvick Standards Track [Page 13]
-
-RFC 4251 SSH Protocol Architecture January 2006
-
-
- The amount of entropy available to a given client or server may
- sometimes be less than what is required. In this case, one must
- either resort to pseudo-random number generation regardless of
- insufficient entropy or refuse to run the protocol. The latter is
- preferable.
-
-9.2. Control Character Filtering
-
- When displaying text to a user, such as error or debug messages, the
- client software SHOULD replace any control characters (except tab,
- carriage return, and newline) with safe sequences to avoid attacks by
- sending terminal control characters.
-
-9.3. Transport
-
-9.3.1. Confidentiality
-
- It is beyond the scope of this document and the Secure Shell Working
- Group to analyze or recommend specific ciphers other than the ones
- that have been established and accepted within the industry. At the
- time of this writing, commonly used ciphers include 3DES, ARCFOUR,
- twofish, serpent, and blowfish. AES has been published by The US
- Federal Information Processing Standards as [FIPS-197], and the
- cryptographic community has accepted AES as well. As always,
- implementers and users should check current literature to ensure that
- no recent vulnerabilities have been found in ciphers used within
- products. Implementers should also check to see which ciphers are
- considered to be relatively stronger than others and should recommend
- their use to users over relatively weaker ciphers. It would be
- considered good form for an implementation to politely and
- unobtrusively notify a user that a stronger cipher is available and
- should be used when a weaker one is actively chosen.
-
- The "none" cipher is provided for debugging and SHOULD NOT be used
- except for that purpose. Its cryptographic properties are
- sufficiently described in [RFC2410], which will show that its use
- does not meet the intent of this protocol.
-
- The relative merits of these and other ciphers may also be found in
- current literature. Two references that may provide information on
- the subject are [SCHNEIER] and [KAUFMAN]. Both of these describe the
- CBC mode of operation of certain ciphers and the weakness of this
- scheme. Essentially, this mode is theoretically vulnerable to chosen
- cipher-text attacks because of the high predictability of the start
- of packet sequence. However, this attack is deemed difficult and not
- considered fully practicable, especially if relatively long block
- sizes are used.
-
-
-
-
-Ylonen & Lonvick Standards Track [Page 14]
-
-RFC 4251 SSH Protocol Architecture January 2006
-
-
- Additionally, another CBC mode attack may be mitigated through the
- insertion of packets containing SSH_MSG_IGNORE. Without this
- technique, a specific attack may be successful. For this attack
- (commonly known as the Rogaway attack [ROGAWAY], [DAI], [BELLARE]) to
- work, the attacker would need to know the Initialization Vector (IV)
- of the next block that is going to be encrypted. In CBC mode that is
- the output of the encryption of the previous block. If the attacker
- does not have any way to see the packet yet (i.e., it is in the
- internal buffers of the SSH implementation or even in the kernel),
- then this attack will not work. If the last packet has been sent out
- to the network (i.e., the attacker has access to it), then he can use
- the attack.
-
- In the optimal case, an implementer would need to add an extra packet
- only if the packet has been sent out onto the network and there are
- no other packets waiting for transmission. Implementers may wish to
- check if there are any unsent packets awaiting transmission;
- unfortunately, it is not normally easy to obtain this information
- from the kernel or buffers. If there are no unsent packets, then a
- packet containing SSH_MSG_IGNORE SHOULD be sent. If a new packet is
- added to the stream every time the attacker knows the IV that is
- supposed to be used for the next packet, then the attacker will not
- be able to guess the correct IV, thus the attack will never be
- successful.
-
- As an example, consider the following case:
-
- Client Server
- ------ ------
- TCP(seq=x, len=500) ---->
- contains Record 1
-
- [500 ms passes, no ACK]
-
- TCP(seq=x, len=1000) ---->
- contains Records 1,2
-
- ACK
-
- 1. The Nagle algorithm + TCP retransmits mean that the two records
- get coalesced into a single TCP segment.
-
- 2. Record 2 is not at the beginning of the TCP segment and never will
- be because it gets ACKed.
-
- 3. Yet, the attack is possible because Record 1 has already been
- seen.
-
-
-
-
-Ylonen & Lonvick Standards Track [Page 15]
-
-RFC 4251 SSH Protocol Architecture January 2006
-
-
- As this example indicates, it is unsafe to use the existence of
- unflushed data in the TCP buffers proper as a guide to whether an
- empty packet is needed, since when the second write() is performed
- the buffers will contain the un-ACKed Record 1.
-
- On the other hand, it is perfectly safe to have the following
- situation:
-
- Client Server
- ------ ------
- TCP(seq=x, len=500) ---->
- contains SSH_MSG_IGNORE
-
- TCP(seq=y, len=500) ---->
- contains Data
-
- Provided that the IV for the second SSH Record is fixed after the
- data for the Data packet is determined, then the following should
- be performed:
-
- read from user
- encrypt null packet
- encrypt data packet
-
-9.3.2. Data Integrity
-
- This protocol does allow the Data Integrity mechanism to be disabled.
- Implementers SHOULD be wary of exposing this feature for any purpose
- other than debugging. Users and administrators SHOULD be explicitly
- warned anytime the "none" MAC is enabled.
-
- So long as the "none" MAC is not used, this protocol provides data
- integrity.
-
- Because MACs use a 32-bit sequence number, they might start to leak
- information after 2**32 packets have been sent. However, following
- the rekeying recommendations should prevent this attack. The
- transport protocol [SSH-TRANS] recommends rekeying after one gigabyte
- of data, and the smallest possible packet is 16 bytes. Therefore,
- rekeying SHOULD happen after 2**28 packets at the very most.
-
-9.3.3. Replay
-
- The use of a MAC other than "none" provides integrity and
- authentication. In addition, the transport protocol provides a
- unique session identifier (bound in part to pseudo-random data that
- is part of the algorithm and key exchange process) that can be used
- by higher level protocols to bind data to a given session and prevent
-
-
-
-Ylonen & Lonvick Standards Track [Page 16]
-
-RFC 4251 SSH Protocol Architecture January 2006
-
-
- replay of data from prior sessions. For example, the authentication
- protocol ([SSH-USERAUTH]) uses this to prevent replay of signatures
- from previous sessions. Because public key authentication exchanges
- are cryptographically bound to the session (i.e., to the initial key
- exchange), they cannot be successfully replayed in other sessions.
- Note that the session id can be made public without harming the
- security of the protocol.
-
- If two sessions have the same session id (hash of key exchanges),
- then packets from one can be replayed against the other. It must be
- stressed that the chances of such an occurrence are, needless to say,
- minimal when using modern cryptographic methods. This is all the
- more true when specifying larger hash function outputs and DH
- parameters.
-
- Replay detection using monotonically increasing sequence numbers as
- input to the MAC, or HMAC in some cases, is described in [RFC2085],
- [RFC2246], [RFC2743], [RFC1964], [RFC2025], and [RFC4120]. The
- underlying construct is discussed in [RFC2104]. Essentially, a
- different sequence number in each packet ensures that at least this
- one input to the MAC function will be unique and will provide a
- nonrecurring MAC output that is not predictable to an attacker. If
- the session stays active long enough, however, this sequence number
- will wrap. This event may provide an attacker an opportunity to
- replay a previously recorded packet with an identical sequence number
- but only if the peers have not rekeyed since the transmission of the
- first packet with that sequence number. If the peers have rekeyed,
- then the replay will be detected since the MAC check will fail. For
- this reason, it must be emphasized that peers MUST rekey before a
- wrap of the sequence numbers. Naturally, if an attacker does attempt
- to replay a captured packet before the peers have rekeyed, then the
- receiver of the duplicate packet will not be able to validate the MAC
- and it will be discarded. The reason that the MAC will fail is
- because the receiver will formulate a MAC based upon the packet
- contents, the shared secret, and the expected sequence number. Since
- the replayed packet will not be using that expected sequence number
- (the sequence number of the replayed packet will have already been
- passed by the receiver), the calculated MAC will not match the MAC
- received with the packet.
-
-9.3.4. Man-in-the-middle
-
- This protocol makes no assumptions or provisions for an
- infrastructure or means for distributing the public keys of hosts.
- It is expected that this protocol will sometimes be used without
- first verifying the association between the server host key and the
- server host name. Such usage is vulnerable to man-in-the-middle
- attacks. This section describes this and encourages administrators
-
-
-
-Ylonen & Lonvick Standards Track [Page 17]
-
-RFC 4251 SSH Protocol Architecture January 2006
-
-
- and users to understand the importance of verifying this association
- before any session is initiated.
-
- There are three cases of man-in-the-middle attacks to consider. The
- first is where an attacker places a device between the client and the
- server before the session is initiated. In this case, the attack
- device is trying to mimic the legitimate server and will offer its
- public key to the client when the client initiates a session. If it
- were to offer the public key of the server, then it would not be able
- to decrypt or sign the transmissions between the legitimate server
- and the client unless it also had access to the private key of the
- host. The attack device will also, simultaneously to this, initiate
- a session to the legitimate server, masquerading itself as the
- client. If the public key of the server had been securely
- distributed to the client prior to that session initiation, the key
- offered to the client by the attack device will not match the key
- stored on the client. In that case, the user SHOULD be given a
- warning that the offered host key does not match the host key cached
- on the client. As described in Section 4.1, the user may be free to
- accept the new key and continue the session. It is RECOMMENDED that
- the warning provide sufficient information to the user of the client
- device so the user may make an informed decision. If the user
- chooses to continue the session with the stored public key of the
- server (not the public key offered at the start of the session), then
- the session-specific data between the attacker and server will be
- different between the client-to-attacker session and the attacker-
- to-server sessions due to the randomness discussed above. From this,
- the attacker will not be able to make this attack work since the
- attacker will not be able to correctly sign packets containing this
- session-specific data from the server, since he does not have the
- private key of that server.
-
- The second case that should be considered is similar to the first
- case in that it also happens at the time of connection, but this case
- points out the need for the secure distribution of server public
- keys. If the server public keys are not securely distributed, then
- the client cannot know if it is talking to the intended server. An
- attacker may use social engineering techniques to pass off server
- keys to unsuspecting users and may then place a man-in-the-middle
- attack device between the legitimate server and the clients. If this
- is allowed to happen, then the clients will form client-to-attacker
- sessions, and the attacker will form attacker-to-server sessions and
- will be able to monitor and manipulate all of the traffic between the
- clients and the legitimate servers. Server administrators are
- encouraged to make host key fingerprints available for checking by
- some means whose security does not rely on the integrity of the
- actual host keys. Possible mechanisms are discussed in Section 4.1
- and may also include secured Web pages, physical pieces of paper,
-
-
-
-Ylonen & Lonvick Standards Track [Page 18]
-
-RFC 4251 SSH Protocol Architecture January 2006
-
-
- etc. Implementers SHOULD provide recommendations on how best to do
- this with their implementation. Because the protocol is extensible,
- future extensions to the protocol may provide better mechanisms for
- dealing with the need to know the server's host key before
- connecting. For example, making the host key fingerprint available
- through a secure DNS lookup, or using Kerberos ([RFC4120]) over
- GSS-API ([RFC1964]) during key exchange to authenticate the server
- are possibilities.
-
- In the third man-in-the-middle case, attackers may attempt to
- manipulate packets in transit between peers after the session has
- been established. As described in Section 9.3.3, a successful attack
- of this nature is very improbable. As in Section 9.3.3, this
- reasoning does assume that the MAC is secure and that it is
- infeasible to construct inputs to a MAC algorithm to give a known
- output. This is discussed in much greater detail in Section 6 of
- [RFC2104]. If the MAC algorithm has a vulnerability or is weak
- enough, then the attacker may be able to specify certain inputs to
- yield a known MAC. With that, they may be able to alter the contents
- of a packet in transit. Alternatively, the attacker may be able to
- exploit the algorithm vulnerability or weakness to find the shared
- secret by reviewing the MACs from captured packets. In either of
- those cases, an attacker could construct a packet or packets that
- could be inserted into an SSH stream. To prevent this, implementers
- are encouraged to utilize commonly accepted MAC algorithms, and
- administrators are encouraged to watch current literature and
- discussions of cryptography to ensure that they are not using a MAC
- algorithm that has a recently found vulnerability or weakness.
-
- In summary, the use of this protocol without a reliable association
- of the binding between a host and its host keys is inherently
- insecure and is NOT RECOMMENDED. However, it may be necessary in
- non-security-critical environments, and will still provide protection
- against passive attacks. Implementers of protocols and applications
- running on top of this protocol should keep this possibility in mind.
-
-9.3.5. Denial of Service
-
- This protocol is designed to be used over a reliable transport. If
- transmission errors or message manipulation occur, the connection is
- closed. The connection SHOULD be re-established if this occurs.
- Denial of service attacks of this type (wire cutter) are almost
- impossible to avoid.
-
- In addition, this protocol is vulnerable to denial of service attacks
- because an attacker can force the server to go through the CPU and
- memory intensive tasks of connection setup and key exchange without
- authenticating. Implementers SHOULD provide features that make this
-
-
-
-Ylonen & Lonvick Standards Track [Page 19]
-
-RFC 4251 SSH Protocol Architecture January 2006
-
-
- more difficult, for example, only allowing connections from a subset
- of clients known to have valid users.
-
-9.3.6. Covert Channels
-
- The protocol was not designed to eliminate covert channels. For
- example, the padding, SSH_MSG_IGNORE messages, and several other
- places in the protocol can be used to pass covert information, and
- the recipient has no reliable way of verifying whether such
- information is being sent.
-
-9.3.7. Forward Secrecy
-
- It should be noted that the Diffie-Hellman key exchanges may provide
- perfect forward secrecy (PFS). PFS is essentially defined as the
- cryptographic property of a key-establishment protocol in which the
- compromise of a session key or long-term private key after a given
- session does not cause the compromise of any earlier session
- [ANSI-T1.523-2001]. SSH sessions resulting from a key exchange using
- the diffie-hellman methods described in the section Diffie-Hellman
- Key Exchange of [SSH-TRANS] (including "diffie-hellman-group1-sha1"
- and "diffie-hellman-group14-sha1") are secure even if private
- keying/authentication material is later revealed, but not if the
- session keys are revealed. So, given this definition of PFS, SSH
- does have PFS. However, this property is not commuted to any of the
- applications or protocols using SSH as a transport. The transport
- layer of SSH provides confidentiality for password authentication and
- other methods that rely on secret data.
-
- Of course, if the DH private parameters for the client and server are
- revealed, then the session key is revealed, but these items can be
- thrown away after the key exchange completes. It's worth pointing
- out that these items should not be allowed to end up on swap space
- and that they should be erased from memory as soon as the key
- exchange completes.
-
-9.3.8. Ordering of Key Exchange Methods
-
- As stated in the section on Algorithm Negotiation of [SSH-TRANS],
- each device will send a list of preferred methods for key exchange.
- The most-preferred method is the first in the list. It is
- RECOMMENDED that the algorithms be sorted by cryptographic strength,
- strongest first. Some additional guidance for this is given in
- [RFC3766].
-
-
-
-
-
-
-
-Ylonen & Lonvick Standards Track [Page 20]
-
-RFC 4251 SSH Protocol Architecture January 2006
-
-
-9.3.9. Traffic Analysis
-
- Passive monitoring of any protocol may give an attacker some
- information about the session, the user, or protocol specific
- information that they would otherwise not be able to garner. For
- example, it has been shown that traffic analysis of an SSH session
- can yield information about the length of the password - [Openwall]
- and [USENIX]. Implementers should use the SSH_MSG_IGNORE packet,
- along with the inclusion of random lengths of padding, to thwart
- attempts at traffic analysis. Other methods may also be found and
- implemented.
-
-9.4. Authentication Protocol
-
- The purpose of this protocol is to perform client user
- authentication. It assumes that this runs over a secure transport
- layer protocol, which has already authenticated the server machine,
- established an encrypted communications channel, and computed a
- unique session identifier for this session.
-
- Several authentication methods with different security
- characteristics are allowed. It is up to the server's local policy
- to decide which methods (or combinations of methods) it is willing to
- accept for each user. Authentication is no stronger than the weakest
- combination allowed.
-
- The server may go into a sleep period after repeated unsuccessful
- authentication attempts to make key search more difficult for
- attackers. Care should be taken so that this doesn't become a self-
- denial of service vector.
-
-9.4.1. Weak Transport
-
- If the transport layer does not provide confidentiality,
- authentication methods that rely on secret data SHOULD be disabled.
- If it does not provide strong integrity protection, requests to
- change authentication data (e.g., a password change) SHOULD be
- disabled to prevent an attacker from modifying the ciphertext without
- being noticed, or rendering the new authentication data unusable
- (denial of service).
-
- The assumption stated above, that the Authentication Protocol only
- runs over a secure transport that has previously authenticated the
- server, is very important to note. People deploying SSH are reminded
- of the consequences of man-in-the-middle attacks if the client does
- not have a very strong a priori association of the server with the
- host key of that server. Specifically, for the case of the
- Authentication Protocol, the client may form a session to a man-in-
-
-
-
-Ylonen & Lonvick Standards Track [Page 21]
-
-RFC 4251 SSH Protocol Architecture January 2006
-
-
- the-middle attack device and divulge user credentials such as their
- username and password. Even in the cases of authentication where no
- user credentials are divulged, an attacker may still gain information
- they shouldn't have by capturing key-strokes in much the same way
- that a honeypot works.
-
-9.4.2. Debug Messages
-
- Special care should be taken when designing debug messages. These
- messages may reveal surprising amounts of information about the host
- if not properly designed. Debug messages can be disabled (during
- user authentication phase) if high security is required.
- Administrators of host machines should make all attempts to
- compartmentalize all event notification messages and protect them
- from unwarranted observation. Developers should be aware of the
- sensitive nature of some of the normal event and debug messages, and
- may want to provide guidance to administrators on ways to keep this
- information away from unauthorized people. Developers should
- consider minimizing the amount of sensitive information obtainable by
- users during the authentication phase, in accordance with the local
- policies. For this reason, it is RECOMMENDED that debug messages be
- initially disabled at the time of deployment and require an active
- decision by an administrator to allow them to be enabled. It is also
- RECOMMENDED that a message expressing this concern be presented to
- the administrator of a system when the action is taken to enable
- debugging messages.
-
-9.4.3. Local Security Policy
-
- The implementer MUST ensure that the credentials provided validate
- the professed user and also MUST ensure that the local policy of the
- server permits the user the access requested. In particular, because
- of the flexible nature of the SSH connection protocol, it may not be
- possible to determine the local security policy, if any, that should
- apply at the time of authentication because the kind of service being
- requested is not clear at that instant. For example, local policy
- might allow a user to access files on the server, but not start an
- interactive shell. However, during the authentication protocol, it
- is not known whether the user will be accessing files, attempting to
- use an interactive shell, or even both. In any event, where local
- security policy for the server host exists, it MUST be applied and
- enforced correctly.
-
- Implementers are encouraged to provide a default local policy and
- make its parameters known to administrators and users. At the
- discretion of the implementers, this default policy may be along the
- lines of anything-goes where there are no restrictions placed upon
- users, or it may be along the lines of excessively-restrictive, in
-
-
-
-Ylonen & Lonvick Standards Track [Page 22]
-
-RFC 4251 SSH Protocol Architecture January 2006
-
-
- which case, the administrators will have to actively make changes to
- the initial default parameters to meet their needs. Alternatively,
- it may be some attempt at providing something practical and
- immediately useful to the administrators of the system so they don't
- have to put in much effort to get SSH working. Whatever choice is
- made must be applied and enforced as required above.
-
-9.4.4 Public Key Authentication
-
- The use of public key authentication assumes that the client host has
- not been compromised. It also assumes that the private key of the
- server host has not been compromised.
-
- This risk can be mitigated by the use of passphrases on private keys;
- however, this is not an enforceable policy. The use of smartcards,
- or other technology to make passphrases an enforceable policy is
- suggested.
-
- The server could require both password and public key authentication;
- however, this requires the client to expose its password to the
- server (see the section on Password Authentication below.)
-
-9.4.5. Password Authentication
-
- The password mechanism, as specified in the authentication protocol,
- assumes that the server has not been compromised. If the server has
- been compromised, using password authentication will reveal a valid
- username/password combination to the attacker, which may lead to
- further compromises.
-
- This vulnerability can be mitigated by using an alternative form of
- authentication. For example, public key authentication makes no
- assumptions about security on the server.
-
-9.4.6. Host-Based Authentication
-
- Host-based authentication assumes that the client has not been
- compromised. There are no mitigating strategies, other than to use
- host-based authentication in combination with another authentication
- method.
-
-
-
-
-
-
-
-
-
-
-
-Ylonen & Lonvick Standards Track [Page 23]
-
-RFC 4251 SSH Protocol Architecture January 2006
-
-
-9.5. Connection Protocol
-
-9.5.1. End Point Security
-
- End point security is assumed by the connection protocol. If the
- server has been compromised, any terminal sessions, port forwarding,
- or systems accessed on the host are compromised. There are no
- mitigating factors for this.
-
- If the client has been compromised, and the server fails to stop the
- attacker at the authentication protocol, all services exposed (either
- as subsystems or through forwarding) will be vulnerable to attack.
- Implementers SHOULD provide mechanisms for administrators to control
- which services are exposed to limit the vulnerability of other
- services. These controls might include controlling which machines
- and ports can be targeted in port-forwarding operations, which users
- are allowed to use interactive shell facilities, or which users are
- allowed to use exposed subsystems.
-
-9.5.2. Proxy Forwarding
-
- The SSH connection protocol allows for proxy forwarding of other
- protocols such as SMTP, POP3, and HTTP. This may be a concern for
- network administrators who wish to control the access of certain
- applications by users located outside of their physical location.
- Essentially, the forwarding of these protocols may violate site-
- specific security policies, as they may be undetectably tunneled
- through a firewall. Implementers SHOULD provide an administrative
- mechanism to control the proxy forwarding functionality so that
- site-specific security policies may be upheld.
-
- In addition, a reverse proxy forwarding functionality is available,
- which, again, can be used to bypass firewall controls.
-
- As indicated above, end-point security is assumed during proxy
- forwarding operations. Failure of end-point security will compromise
- all data passed over proxy forwarding.
-
-9.5.3. X11 Forwarding
-
- Another form of proxy forwarding provided by the SSH connection
- protocol is the forwarding of the X11 protocol. If end-point
- security has been compromised, X11 forwarding may allow attacks
- against the X11 server. Users and administrators should, as a matter
- of course, use appropriate X11 security mechanisms to prevent
- unauthorized use of the X11 server. Implementers, administrators,
- and users who wish to further explore the security mechanisms of X11
- are invited to read [SCHEIFLER] and analyze previously reported
-
-
-
-Ylonen & Lonvick Standards Track [Page 24]
-
-RFC 4251 SSH Protocol Architecture January 2006
-
-
- problems with the interactions between SSH forwarding and X11 in CERT
- vulnerabilities VU#363181 and VU#118892 [CERT].
-
- X11 display forwarding with SSH, by itself, is not sufficient to
- correct well known problems with X11 security [VENEMA]. However, X11
- display forwarding in SSH (or other secure protocols), combined with
- actual and pseudo-displays that accept connections only over local
- IPC mechanisms authorized by permissions or access control lists
- (ACLs), does correct many X11 security problems, as long as the
- "none" MAC is not used. It is RECOMMENDED that X11 display
- implementations default to allow the display to open only over local
- IPC. It is RECOMMENDED that SSH server implementations that support
- X11 forwarding default to allow the display to open only over local
- IPC. On single-user systems, it might be reasonable to default to
- allow the local display to open over TCP/IP.
-
- Implementers of the X11 forwarding protocol SHOULD implement the
- magic cookie access-checking spoofing mechanism, as described in
- [SSH-CONNECT], as an additional mechanism to prevent unauthorized use
- of the proxy.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Ylonen & Lonvick Standards Track [Page 25]
-
-RFC 4251 SSH Protocol Architecture January 2006
-
-
-10. References
-
-10.1. Normative References
-
- [SSH-TRANS] Ylonen, T. and C. Lonvick, Ed., "The Secure Shell
- (SSH) Transport Layer Protocol", RFC 4253, January
- 2006.
-
- [SSH-USERAUTH] Ylonen, T. and C. Lonvick, Ed., "The Secure Shell
- (SSH) Authentication Protocol", RFC 4252, January
- 2006.
-
- [SSH-CONNECT] Ylonen, T. and C. Lonvick, Ed., "The Secure Shell
- (SSH) Connection Protocol", RFC 4254, January
- 2006.
-
- [SSH-NUMBERS] Lehtinen, S. and C. Lonvick, Ed., "The Secure
- Shell (SSH) Protocol Assigned Numbers", RFC 4250,
- January 2006.
-
- [RFC2119] Bradner, S., "Key words for use in RFCs to
- Indicate Requirement Levels", BCP 14, RFC 2119,
- March 1997.
-
- [RFC2434] Narten, T. and H. Alvestrand, "Guidelines for
- Writing an IANA Considerations Section in RFCs",
- BCP 26, RFC 2434, October 1998.
-
- [RFC3066] Alvestrand, H., "Tags for the Identification of
- Languages", BCP 47, RFC 3066, January 2001.
-
- [RFC3629] Yergeau, F., "UTF-8, a transformation format of
- ISO 10646", STD 63, RFC 3629, November 2003.
-
-10.2. Informative References
-
- [RFC0822] Crocker, D., "Standard for the format of ARPA
- Internet text messages", STD 11, RFC 822, August
- 1982.
-
- [RFC0854] Postel, J. and J. Reynolds, "Telnet Protocol
- Specification", STD 8, RFC 854, May 1983.
-
- [RFC1034] Mockapetris, P., "Domain names - concepts and
- facilities", STD 13, RFC 1034, November 1987.
-
-
-
-
-
-
-Ylonen & Lonvick Standards Track [Page 26]
-
-RFC 4251 SSH Protocol Architecture January 2006
-
-
- [RFC1282] Kantor, B., "BSD Rlogin", RFC 1282, December 1991.
-
- [RFC4120] Neuman, C., Yu, T., Hartman, S., and K. Raeburn,
- "The Kerberos Network Authentication Service
- (V5)", RFC 4120, July 2005.
-
- [RFC1964] Linn, J., "The Kerberos Version 5 GSS-API
- Mechanism", RFC 1964, June 1996.
-
- [RFC2025] Adams, C., "The Simple Public-Key GSS-API
- Mechanism (SPKM)", RFC 2025, October 1996.
-
- [RFC2085] Oehler, M. and R. Glenn, "HMAC-MD5 IP
- Authentication with Replay Prevention", RFC 2085,
- February 1997.
-
- [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC:
- Keyed-Hashing for Message Authentication", RFC
- 2104, February 1997.
-
- [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version
- 1.0", RFC 2246, January 1999.
-
- [RFC2410] Glenn, R. and S. Kent, "The NULL Encryption
- Algorithm and Its Use With IPsec", RFC 2410,
- November 1998.
-
- [RFC2743] Linn, J., "Generic Security Service Application
- Program Interface Version 2, Update 1", RFC 2743,
- January 2000.
-
- [RFC3766] Orman, H. and P. Hoffman, "Determining Strengths
- For Public Keys Used For Exchanging Symmetric
- Keys", BCP 86, RFC 3766, April 2004.
-
- [RFC4086] Eastlake, D., 3rd, Schiller, J., and S. Crocker,
- "Randomness Requirements for Security", BCP 106,
- RFC 4086, June 2005.
-
- [FIPS-180-2] US National Institute of Standards and Technology,
- "Secure Hash Standard (SHS)", Federal Information
- Processing Standards Publication 180-2, August
- 2002.
-
- [FIPS-186-2] US National Institute of Standards and Technology,
- "Digital Signature Standard (DSS)", Federal
- Information Processing Standards Publication 186-
- 2, January 2000.
-
-
-
-Ylonen & Lonvick Standards Track [Page 27]
-
-RFC 4251 SSH Protocol Architecture January 2006
-
-
- [FIPS-197] US National Institute of Standards and Technology,
- "Advanced Encryption Standard (AES)", Federal
- Information Processing Standards Publication 197,
- November 2001.
-
- [ANSI-T1.523-2001] American National Standards Institute, Inc.,
- "Telecom Glossary 2000", ANSI T1.523-2001,
- February 2001.
-
- [SCHNEIER] Schneier, B., "Applied Cryptography Second
- Edition: protocols algorithms and source in code
- in C", John Wiley and Sons, New York, NY, 1996.
-
- [SCHEIFLER] Scheifler, R., "X Window System : The Complete
- Reference to Xlib, X Protocol, Icccm, Xlfd, 3rd
- edition.", Digital Press, ISBN 1555580882,
- February 1992.
-
- [KAUFMAN] Kaufman, C., Perlman, R., and M. Speciner,
- "Network Security: PRIVATE Communication in a
- PUBLIC World", Prentice Hall Publisher, 1995.
-
- [CERT] CERT Coordination Center, The.,
- "http://www.cert.org/nav/index_red.html".
-
- [VENEMA] Venema, W., "Murphy's Law and Computer Security",
- Proceedings of 6th USENIX Security Symposium, San
- Jose CA
- http://www.usenix.org/publications/library/
- proceedings/sec96/venema.html, July 1996.
-
- [ROGAWAY] Rogaway, P., "Problems with Proposed IP
- Cryptography", Unpublished paper
- http://www.cs.ucdavis.edu/~rogaway/ papers/draft-
- rogaway-ipsec-comments-00.txt, 1996.
-
- [DAI] Dai, W., "An attack against SSH2 protocol", Email
- to the SECSH Working Group ietf-ssh@netbsd.org
- ftp:// ftp.ietf.org/ietf-mail-archive/secsh/2002-
- 02.mail, Feb 2002.
-
- [BELLARE] Bellaire, M., Kohno, T., and C. Namprempre,
- "Authenticated Encryption in SSH: Fixing the SSH
- Binary Packet Protocol", Proceedings of the 9th
- ACM Conference on Computer and Communications
- Security, Sept 2002.
-
-
-
-
-
-Ylonen & Lonvick Standards Track [Page 28]
-
-RFC 4251 SSH Protocol Architecture January 2006
-
-
- [Openwall] Solar Designer and D. Song, "SSH Traffic Analysis
- Attacks", Presentation given at HAL2001 and
- NordU2002 Conferences, Sept 2001.
-
- [USENIX] Song, X.D., Wagner, D., and X. Tian, "Timing
- Analysis of Keystrokes and SSH Timing Attacks",
- Paper given at 10th USENIX Security Symposium,
- 2001.
-
-Authors' Addresses
-
- Tatu Ylonen
- SSH Communications Security Corp
- Valimotie 17
- 00380 Helsinki
- Finland
-
- EMail: ylo@ssh.com
-
-
- Chris Lonvick (editor)
- Cisco Systems, Inc.
- 12515 Research Blvd.
- Austin 78759
- USA
-
- EMail: clonvick@cisco.com
-
-Trademark Notice
-
- "ssh" is a registered trademark in the United States and/or other
- countries.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Ylonen & Lonvick Standards Track [Page 29]
-
-RFC 4251 SSH Protocol Architecture January 2006
-
-
-Full Copyright Statement
-
- Copyright (C) The Internet Society (2006).
-
- This document is subject to the rights, licenses and restrictions
- contained in BCP 78, and except as set forth therein, the authors
- retain all their rights.
-
- This document and the information contained herein are provided on an
- "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
- OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
- ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
- INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
- INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
- WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
-
-Intellectual Property
-
- The IETF takes no position regarding the validity or scope of any
- Intellectual Property Rights or other rights that might be claimed to
- pertain to the implementation or use of the technology described in
- this document or the extent to which any license under such rights
- might or might not be available; nor does it represent that it has
- made any independent effort to identify any such rights. Information
- on the procedures with respect to rights in RFC documents can be
- found in BCP 78 and BCP 79.
-
- Copies of IPR disclosures made to the IETF Secretariat and any
- assurances of licenses to be made available, or the result of an
- attempt made to obtain a general license or permission for the use of
- such proprietary rights by implementers or users of this
- specification can be obtained from the IETF on-line IPR repository at
- http://www.ietf.org/ipr.
-
- The IETF invites any interested party to bring to its attention any
- copyrights, patents or patent applications, or other proprietary
- rights that may cover technology that may be required to implement
- this standard. Please address the information to the IETF at
- ietf-ipr@ietf.org.
-
-Acknowledgement
-
- Funding for the RFC Editor function is provided by the IETF
- Administrative Support Activity (IASA).
-
-
-
-
-
-
-
-Ylonen & Lonvick Standards Track [Page 30]
-
[9/9] git commit: Remove third party documents from scm
Posted by gn...@apache.org.
Remove third party documents from scm
Project: http://git-wip-us.apache.org/repos/asf/mina-sshd/repo
Commit: http://git-wip-us.apache.org/repos/asf/mina-sshd/commit/46ea0930
Tree: http://git-wip-us.apache.org/repos/asf/mina-sshd/tree/46ea0930
Diff: http://git-wip-us.apache.org/repos/asf/mina-sshd/diff/46ea0930
Branch: refs/heads/master
Commit: 46ea09302ec1556b95474ae36337369e9c973c36
Parents: 5bd7629
Author: Guillaume Nodet <gn...@apache.org>
Authored: Fri Jul 26 15:30:42 2013 +0200
Committer: Guillaume Nodet <gn...@apache.org>
Committed: Fri Jul 26 15:30:42 2013 +0200
----------------------------------------------------------------------
.../src/docs/draft-ietf-secsh-agent-02.txt | 768 ----
.../src/docs/draft-ietf-secsh-filexfer-02.txt | 1626 ---------
.../src/docs/draft-ietf-secsh-filexfer-04.txt | 2130 -----------
.../src/docs/draft-ietf-secsh-filexfer-05.txt | 2802 ---------------
.../src/docs/draft-ietf-secsh-filexfer-13.txt | 3362 ------------------
sshd-core/src/docs/rfc4251.txt | 1683 ---------
sshd-core/src/docs/rfc4252.txt | 955 -----
sshd-core/src/docs/rfc4253.txt | 1795 ----------
sshd-core/src/docs/rfc4254.txt | 1347 -------
sshd-core/src/docs/rfc4255.txt | 507 ---
sshd-core/src/docs/rfc4256.txt | 675 ----
sshd-core/src/docs/rfc4345.txt | 283 --
sshd-core/src/docs/rfc4419.txt | 563 ---
13 files changed, 18496 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/mina-sshd/blob/46ea0930/sshd-core/src/docs/draft-ietf-secsh-agent-02.txt
----------------------------------------------------------------------
diff --git a/sshd-core/src/docs/draft-ietf-secsh-agent-02.txt b/sshd-core/src/docs/draft-ietf-secsh-agent-02.txt
deleted file mode 100644
index 6af78af..0000000
--- a/sshd-core/src/docs/draft-ietf-secsh-agent-02.txt
+++ /dev/null
@@ -1,768 +0,0 @@
-
-
-Network Working Group Tatu Ylonen
-INTERNET-DRAFT Timo J. Rinne
-draft-ietf-secsh-agent-02.txt Sami Lehtinen
-Expires: July 30, 2004 SSH Communications Security
- 30 January, 2004
-
-
-
- Secure Shell Authentication Agent Protocol
-
-Status of This Memo
-
-This document is an Internet-Draft and is in full conformance
-with all provisions of Section 10 of RFC2026.
-
-Internet-Drafts are working documents of the Internet Engineering
-Task Force (IETF), its areas, and its working groups. Note that
-other groups may also distribute working documents as
-Internet-Drafts.
-
-Internet-Drafts are draft documents valid for a maximum of six
-months and may be updated, replaced, or obsoleted by other
-documents at any time. It is inappropriate to use Internet-
-Drafts as reference material or to cite them other than as
-"work in progress."
-
-The list of current Internet-Drafts can be accessed at
-http://www.ietf.org/ietf/1id-abstracts.txt
-
-The list of Internet-Draft Shadow Directories can be accessed at
-http://www.ietf.org/shadow.html.
-
-Abstract
-
-This document describes the Secure Shell authentication agent protocol
-(i.e., the protocol used between a client requesting authentication and
-the authentication agent). This protocol usually runs in a machine-spe-
-cific local channel or over a forwarded authentication channel. It is
-assumed that the channel is trusted, so no protection for the communica-
-tions channel is provided by this protocol.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Tatu Ylonen, Timo J. Rinne and Sami Lehtinen [page 1]
-
-INTERNET-DRAFT 30 January, 2004
-
-Table of Contents
-
-1. Authentication Agent Protocol . . . . . . . . . . . . . . . . . 2
- 1.1. Packet Format . . . . . . . . . . . . . . . . . . . . . . . 3
- 1.2. Forwarding Notices . . . . . . . . . . . . . . . . . . . . . 3
- 1.3. Requesting Version Number . . . . . . . . . . . . . . . . . 4
- 1.4. Adding Keys to the Agent . . . . . . . . . . . . . . . . . . 4
- 1.4.1. Key types . . . . . . . . . . . . . . . . . . . . . . . 5
- 1.4.2. Forwarding constraints . . . . . . . . . . . . . . . . . 5
- 1.5. Deleting Keys from the Agent . . . . . . . . . . . . . . . . 7
- 1.6. Deleting specific key from the Agent . . . . . . . . . . . . 7
- 1.7. Listing the Keys that the Agent Can Use . . . . . . . . . . 7
-2. Performing Private Key Operations . . . . . . . . . . . . . . . 7
- 2.1. Signing . . . . . . . . . . . . . . . . . . . . . . . . . . 8
- 2.2. Decrypting . . . . . . . . . . . . . . . . . . . . . . . . . 8
- 2.3. Secure Shell Challenge-Response Authentication . . . . . . . 8
-3. Administrative Messages . . . . . . . . . . . . . . . . . . . . 9
- 3.1. Locking and unlocking the agent . . . . . . . . . . . . . . 9
- 3.2. Miscellaneous Agent Commands . . . . . . . . . . . . . . . . 9
-4. Agent Forwarding With Secure Shell . . . . . . . . . . . . . . . 10
- 4.1. Requesting Agent Forwarding . . . . . . . . . . . . . . . . 10
- 4.2. Agent Forwarding Channels . . . . . . . . . . . . . . . . . 10
-5. Vendor-Specific Extensions . . . . . . . . . . . . . . . . . . . 10
-6. Security Considerations . . . . . . . . . . . . . . . . . . . . 11
-7. Intellectual Property . . . . . . . . . . . . . . . . . . . . . 12
-8. Additional Information . . . . . . . . . . . . . . . . . . . . . 12
-9. Changes from previous versions . . . . . . . . . . . . . . . . . 12
- 9.1. Changes between versions 3 and 2 . . . . . . . . . . . . . . 12
-10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 12
-11. Address of Authors . . . . . . . . . . . . . . . . . . . . . . 13
-
-
-
-1. Authentication Agent Protocol
-
-The authentication agent is a piece of software that runs in a user's
-local workstation, laptop, or other trusted device. It is used to
-implement single sign-on. It holds the user's private keys in its own
-storage, and can perform requested operations using the private key. It
-allows the keys to be kept on a smartcard or other special hardware that
-can perform cryptographic operations.
-
-The authentication agent protocol is used to communicate between the
-authentication agent and clients wanting to authenticate something or
-wanting to perform private key operations.
-
-The actual communication between the client and the agent happens using
-a machine-dependent trusted communications channel. This channel would
-typically be a local socket, named pipe, or some kind of secure
-messaging system that works inside the local machine.
-
-The protocol works by the client sending requests to the agent, and the
-agent responding to these requests.
-
-
-Tatu Ylonen, Timo J. Rinne and Sami Lehtinen [page 2]
-
-INTERNET-DRAFT 30 January, 2004
-
-1.1. Packet Format
-
-All messages passed to/from the authentication agent have the following
-format:
-
- uint32 length
- byte type
- data[length -1] data payload
-
-The following packet types are currently defined:
-
- /* Messages sent by the client. */
- #define SSH_AGENT_REQUEST_VERSION 1
- #define SSH_AGENT_ADD_KEY 202
- #define SSH_AGENT_DELETE_ALL_KEYS 203
- #define SSH_AGENT_LIST_KEYS 204
- #define SSH_AGENT_PRIVATE_KEY_OP 205
- #define SSH_AGENT_FORWARDING_NOTICE 206
- #define SSH_AGENT_DELETE_KEY 207
- #define SSH_AGENT_LOCK 208
- #define SSH_AGENT_UNLOCK 209
- #define SSH_AGENT_PING 212
- #define SSH_AGENT_RANDOM 213
-
- #define SSH_AGENT_EXTENSION 301
-
- /* Messages sent by the agent. */
- #define SSH_AGENT_SUCCESS 101
- #define SSH_AGENT_FAILURE 102
- #define SSH_AGENT_VERSION_RESPONSE 103
- #define SSH_AGENT_KEY_LIST 104
- #define SSH_AGENT_OPERATION_COMPLETE 105
- #define SSH_AGENT_RANDOM_DATA 106
- #define SSH_AGENT_ALIVE 150
-
-1.2. Forwarding Notices
-
-If the agent connection is forwarded through intermediate hosts (using
-the SSH Connection Protocol agent forwarding feature (described in
-Section ``Agent Forwarding With Secure Shell'' of this document), or
-some other means), each intermediate node (Secure Shell client) should
-insert the following message into the agent channel before forwarding
-any other messages. The real agent will then receive these messages in
-sequence the nearest node first, and can determine whether the
-connection is from a local machine and if not, can log the path where
-the connection came from. These messages must be wrapped in the
-appropriate header.
-
- byte SSH_AGENT_FORWARDING_NOTICE
- string remote host name (as typed by the user, preferably)
- string remote host ip
- uint32 remote host port
-
-
-
-Tatu Ylonen, Timo J. Rinne and Sami Lehtinen [page 3]
-
-INTERNET-DRAFT 30 January, 2004
-
-1.3. Requesting Version Number
-
-When the client opens a connection, it must send the following message
-to the server. This must be the first message sent. The real agent
-will receive this after zero or more forwarding notice messages.
-
- byte SSH_AGENT_REQUEST_VERSION
- string version string of the application sending the request
- (optional)
-
-If the agent follows this protocol, it will respond with
-
- byte SSH_AGENT_VERSION_RESPONSE
- uint32 version number, 3 for this protocol
- <extension data>
-
-If the version number request is ever sent to the Secure Shell 1.x
-agent, it will interpret it as a request to list identities. It will
-then respond with a message whose first byte is 2. This can be used to
-determine the version of the agent if compatibility with Secure Shell
-1.x is desired.
-
-If the version string query arrives without trailing string identifying
-the client software version, it can be translated list identities
-request sent by Secure Shell 1.x and handled accordingly. If agent
-software does not support the agent protocol of Secure Shell 1.x, it MAY
-also interpret this query as valid SSH_AGENT_REQUEST_VERSION packet.
-
-The extension data in the SSH_AGENT_VERSION_RESPONSE may be empty, or
-may be a sequence of
-
- string extension_name
- string extension_data
-
-pairs (both strings MUST always be present if one is, but the `exten-
-sion_data' string may be of zero length). If present, these strings
-indicate extensions to the baseline protocol. The `extension_name'
-field(s) identify the name of the extension. The name should be of the
-form "name@domain", where the domain is the DNS domain name of the orga-
-nization defining the extension. Additional names that are not of this
-format may be defined later by the IETF. Implementations MUST silently
-ignore any extensions whose name they do not recognize.
-
-1.4. Adding Keys to the Agent
-
-The client can add a new private key to the agent with the following
-message. Using this message over the net has security implications, and
-the implementation SHOULD warn the user before decryption or sending the
-private key. (XXX how does ssh-add detect this condition?)
-
- byte SSH_AGENT_ADD_KEY
- string private key encoding
- string private key blob
-
-
-Tatu Ylonen, Timo J. Rinne and Sami Lehtinen [page 4]
-
-INTERNET-DRAFT 30 January, 2004
-
- string public key encoding
- string public key and/or certificates for it
- string description of the key
- ... 0, 1 or several constraints follow
-
-1.4.1. Key types
-
-Key blobs are preceeded by the encoding field, which defines how the
-blob should be interpreted. Defined values for public key encoding are
-"ssh-dss" and "ssh-rsa". Additional key types may be defined as
-specified in [SECSH-ARCH], under Section IANA Considerations (Section
-8).
-
-"ssh-dss" and "ssh-rsa" public key format encodings are defined in
-[SECSH-TRANS].
-
-The "ssh-dss" private key format has the following specific encoding:
-
- string "ssh-dss"
- mpint p
- mpint q
- mpint g
- mpint y
- mpint x
-
-The "ssh-rsa" private key format has the following specific encoding:
-
- string "ssh-rsa"
- mpint e
- mpint d
- mpint n
- mpint u
- mpint p
- mpint q
-
-XXX Additional key-types (for private keys), for example "ssh-rsa-
-encrypted"?
-
-1.4.2. Forwarding constraints
-
-All constraints are pairs of following format:
-
- byte SSH_AGENT_CONSTRAINT_*
- variable argument for the constraint
-
-The type of the argument is dependent on the constraint type. Following
-constraint types are currently defined:
-
- /* Constraints 50-99 have a uint32 argument */
-
- /* Argument is uint32 defining key expiration time-out in
- seconds. After this timeout expires, the key can't be used.
- 0 == no timeout */
-
-
-Tatu Ylonen, Timo J. Rinne and Sami Lehtinen [page 5]
-
-INTERNET-DRAFT 30 January, 2004
-
- #define SSH_AGENT_CONSTRAINT_TIMEOUT 50
-
- /* Argument is uint32 defining the number of operations that can
- be performed with this key. 0xffffffff == no limit */
- #define SSH_AGENT_CONSTRAINT_USE_LIMIT 51
-
- /* Argument is uint32 defining the number of forwarding steps that
- this key can be forwarded. 0xffffffff == no limit */
- #define SSH_AGENT_CONSTRAINT_FORWARDING_STEPS 52
-
- /* Constraints 100-149 have a string argument */
-
- /* Argument is string defining the allowed forwarding steps for
- this key. XXX define this. */
- #define SSH_AGENT_CONSTRAINT_FORWARDING_PATH 100
-
- /* Constraints 150-199 have a boolean argument */
-
- /* Argument is a boolean telling whether the key can be used
- in Secure Shell 1.x compatibility operations. */
-
- #define SSH_AGENT_CONSTRAINT_SSH1_COMPAT 150
-
- /* Argument is a boolean telling whether operations performed
- with this key should be confirmed interactively by the user
- or not. */
- #define SSH_AGENT_CONSTRAINT_NEED_USER_VERIFICATION 151
-
-Message can contain zero, one or multiple constraints.
-
-If the operation is successful, the agent will respond with the
-following message.
-
- byte SSH_AGENT_SUCCESS
-
-If the operation fails for some reason, the following message will be
-returned instead.
-
- byte SSH_AGENT_FAILURE
- uint32 error code
- string additional textual information (ISO-10646 UTF-8
- [RFC-2279])
- string language tag (as defined in [RFC-1766])
-
-The last two fields are optional; they don't need to be present in
-SSH_AGENT_FAILURE message. However, both MUST be provided if they are to
-be used. If client is version 2, the agent SHOULD NOT use these fields.
-
-The error code is one of the following:
-
- #define SSH_AGENT_ERROR_TIMEOUT 1
- #define SSH_AGENT_ERROR_KEY_NOT_FOUND 2
- #define SSH_AGENT_ERROR_DECRYPT_FAILED 3
-
-
-Tatu Ylonen, Timo J. Rinne and Sami Lehtinen [page 6]
-
-INTERNET-DRAFT 30 January, 2004
-
- #define SSH_AGENT_ERROR_SIZE_ERROR 4
- #define SSH_AGENT_ERROR_KEY_NOT_SUITABLE 5
- #define SSH_AGENT_ERROR_DENIED 6
- #define SSH_AGENT_ERROR_FAILURE 7
- #define SSH_AGENT_ERROR_UNSUPPORTED_OP 8
-
-1.5. Deleting Keys from the Agent
-
-All keys that are in possession of the agent can be deleted with the
-following message. (The client is allowed to ignore this for some keys
-if desired.)
-
- byte SSH_AGENT_DELETE_ALL_KEYS
-
-The agent responds with either SSH_AGENT_SUCCESS or SSH_AGENT_FAILURE.
-
-1.6. Deleting specific key from the Agent
-
-The client can delete a specific key with given public key with
-following message.
-
- byte SSH_AGENT_DELETE_KEY
- string public key and/or certificates for it
- string description of the key
-
-The agent responds with either SSH_AGENT_SUCCESS or SSH_AGENT_FAILURE.
-
-1.7. Listing the Keys that the Agent Can Use
-
-The following message requests a list of all keys that the agent can
-use.
-
- byte SSH_AGENT_LIST_KEYS
-
-The agent will respond with the following message.
-
- byte SSH_AGENT_KEY_LIST
- uint32 number_of_keys
- repeats number_of_keys times:
- string public key blob or certificates
- string description
-
-2. Performing Private Key Operations
-
-The real purpose of the agent is to perform private key operations.
-Such operations are performed with the following message.
-
- byte SSH_AGENT_PRIVATE_KEY_OP
- string operation name
- string key or certificates, as returned in SSH_AGENT_KEY_LIST
- ... operation-specific data follows
-
-The operation to be performed is identified by a name (string). Custom
-
-
-Tatu Ylonen, Timo J. Rinne and Sami Lehtinen [page 7]
-
-INTERNET-DRAFT 30 January, 2004
-
-operations can be added by suffixing the operation name by the fully
-qualified domain name of the person/organization adding the new
-operation.
-
-When the operation is complete, the agent will respond with either
-SSH_AGENT_FAILURE or with the following message if the operation is
-successful:
-
- byte SSH_AGENT_OPERATION_COMPLETE
- string resulting data
-
-If an operation is attempted that is not supported by the agent, the
-agent will respond with SSH_AGENT_FAILURE with error code set to
-SSH_AGENT_ERROR_UNSUPPORTED_OP.
-
-The standard operations are defined below.
-
-2.1. Signing
-
-The agent can be used to create a digital signature using a key held by
-the agent. The operation name is "sign", and data in is a hash
-(suitable for the key) that is to be signed. This normally performs the
-raw private key operation, without hashing data first. The resulting
-data will be a binary representation of the output of the private key
-operation. The exact details of the operations to be performed depend
-on the key being used.
-
-The operation-specific data has the following format:
-
- string data to be signed
-
-Alternatively, it is possible to give the actual data to be signed to
-the agent. This is done using the operation "hash-and-sign". This is
-otherwise equal, but performs key-dependent hashing before signing.
-
-If the requested operation is not legal for the key, SSH_AGENT_FAILURE
-will be returned with error code set to
-SSH_AGENT_ERROR_KEY_NOT_SUITABLE.
-
-2.2. Decrypting
-
-The agent can be used to decrypt a public key encrypted message with the
-operation "decrypt". This takes in raw public-key encrypted data, and
-returns the resulting decrypted data.
-
-This may also fail. If the requested operation is not legal for the
-key, error code is set to SSH_AGENT_ERROR_KEY_NOT_SUITABLE.
-
-The operation-specific data has the following format:
-
- string data to be decrypted
-
-
-
-
-Tatu Ylonen, Timo J. Rinne and Sami Lehtinen [page 8]
-
-INTERNET-DRAFT 30 January, 2004
-
-2.3. Secure Shell Challenge-Response Authentication
-
-Performs Secure Shell challenge-response authentication. This operation
-has the name "ssh1-challenge-response".
-
-This operation works by first decrypting the challenge, then computing
-MD5 of the concatenation of the decrypted challenge and the session id
-(in this order), and returns the resulting 16 byte hash. The operation-
-specific data is in the following format:
-
- string challenge encrypted using the public key
- string session id
-
-Normally, the length of the challenge before encryption will be 32 bytes
-and the length of the session id 16 bytes. The length of the encrypted
-challenge depends on the key and algorithm used.
-
-3. Administrative Messages
-
-There are also a number of messages that are only used to administer the
-agent. These might e.g. be used by a user interface for the agent. The
-agent should only allow these messages from local connection (i.e., if
-no forwarding notice messages were received before the version number
-request).
-
-3.1. Locking and unlocking the agent
-
-The agent can be temporarily locked by message:
-
- byte SSH_AGENT_LOCK
- string locking password
-
-The agent responds with either SSH_AGENT_SUCCESS or SSH_AGENT_FAILURE.
-Particularily SSH_AGENT_FAILURE is sent, if agent is already locked.
-After this message, agent responds to all commands with
-SSH_AGENT_FAILURE until it receives a following command.
-
- byte SSH_AGENT_UNLOCK
- string locking password
-
-The agent responds with either SSH_AGENT_SUCCESS or SSH_AGENT_FAILURE.
-Particularily SSH_AGENT_FAILURE is sent, if agent is not locked or if
-the submitted password does not match with one given with SSH_AGENT_LOCK
-message.
-
-3.2. Miscellaneous Agent Commands
-
- byte SSH_AGENT_PING
- ... arbitrary padding data
-
-Any agent or client receiving this message, should respond with
-
- byte SSH_AGENT_ALIVE
-
-
-Tatu Ylonen, Timo J. Rinne and Sami Lehtinen [page 9]
-
-INTERNET-DRAFT 30 January, 2004
-
- ... padding data from the SSH_AGENT_PING request
-
-where the padding data is identical to the data sent with
-SSH_AGENT_PING.
-
- byte SSH_AGENT_RANDOM
- uint32 the length of the requested random buffer
-
-Client can request random data from the agent by this message. Agent
-responds either with SSH_AGENT_RANDOM_DATA or SSH_AGENT_FAILURE message.
-
- byte SSH_AGENT_RANDOM_DATA
- string random data
-
-This message is a successful response to SSH_AGENT_RANDOM message.
-Message contains the random string of requested length.
-
-4. Agent Forwarding With Secure Shell
-
-The agent connection is typically forwarded over a Secure Shell
-connection. This requires small additions to the SSH Connection Protocol
-[SSH-CONN].
-
-4.1. Requesting Agent Forwarding
-
-Agent forwarding may be requested for a session by sending
-
- byte SSH_MSG_CHANNEL_REQUEST
- uint32 recipient channel
- string "auth-agent-req"
- boolean want reply
-
-This will, on success, create an agent listener to the remote end.
-
-4.2. Agent Forwarding Channels
-
-When a connection comes to the forwarded agent listener, a channel is
-opened to forward the connection to the other side.
-
- byte SSH_MSG_CHANNEL_OPEN
- string "auth-agent"
- uint32 sender channel
- uint32 initial window size
- uint32 maximum packet size
-
-Implementations MUST reject these messages unless they have previously
-requested agent forwarding.
-
-Forwarded agent channels are independent of any sessions, and closing a
-session channel does not in any way imply that forwarded connections
-should be closed.
-
-
-
-
-Tatu Ylonen, Timo J. Rinne and Sami Lehtinen [page 10]
-
-INTERNET-DRAFT 30 January, 2004
-
-5. Vendor-Specific Extensions
-
-The SSH_AGENT_EXTENSION request provides a generic extension mechanism
-for adding vendor-specific commands. The request has the following
-format:
- byte SSH_AGENT_EXTENSION
- string extension_id
- ... extension-specific data follows ...
-
-`extension_id' is a string of the format "name@domain", where domain is
-an internet domain name of the vendor defining the request. The rest of
-the request is completely vendor-specific, and servers should only
-attempt to interpret it if they recognize the `extension_id' name.
-
-These messages can be sent to either direction. However, the agent MUST
-send these messages only as responses to the client's requests. As an
-implementation note, the agent should use the standard responses if at
-all possible.
-
-If the agent sees an extension message it doesn't understand, it should
-respond with SSH_AGENT_FAILURE with error
-SSH_AGENT_ERROR_UNSUPPORTED_OP.
-
-6. Security Considerations
-
-The authentication agent is used to control security-sensitive
-operations, and is used to implement single sign-on.
-
-Anyone with access to the authentication agent can perform private key
-operations with the agent. This is a power equivalent to possession of
-the private key as long as the connection to the key is maintained. It
-is not possible to retrieve the key from the agent.
-
-It is recommended that agent implementations allow and perform some form
-of logging and access control. This access control may utilize
-information about the path through which the connection was received (as
-collected with SSH_AGENT_FORWARDING_NOTICE messages; however, the path
-is reliable only up to and including the first unreliable machine.).
-Implementations should also allow restricting the operations that can be
-performed with keys - e.g., limiting them to challenge-response only.
-
-One should note that a local superuser will be able to obtain access to
-agents running on the local machine. This cannot be prevented; in most
-operating systems, a user with sufficient privileges will be able to
-read the keys from the physical memory.
-
-The authentication agent should not be run or forwarded to machine whose
-integrity is not trusted, as security on such machines might be
-compromised and might allow an attacker to obtain unauthorized access to
-the agent.
-
-Adding a key with SSH_AGENT_ADD_KEY over the net (especially over the
-Internet) is generally not recommended, because at present the private
-
-
-Tatu Ylonen, Timo J. Rinne and Sami Lehtinen [page 11]
-
-INTERNET-DRAFT 30 January, 2004
-
-key has to be moved unencrypted. Implementations SHOULD warn the user of
-the implications. Even moving the key in encrypted form could be
-considered unwise.
-
-7. Intellectual Property
-
-The IETF takes no position regarding the validity or scope of any
-intellectual property or other rights that might be claimed to pertain
-to the implementation or use of the technology described in this
-document or the extent to which any license under such rights might or
-might not be available; neither does it represent that it has made any
-effort to identify any such rights. Information on the IETF's
-procedures with respect to rights in standards-track and standards-
-related documentation can be found in BCP-11. Copies of claims of
-rights made available for publication and any assurances of licenses to
-be made available, or the result of an attempt made to obtain a general
-license or permission for the use of such proprietary rights by
-implementers or users of this specification can be obtained from the
-IETF Secretariat.
-
-The IETF has been notified of intellectual property rights claimed in
-regard to some or all of the specification contained in this document.
-For more information consult the online list of claimed rights.
-
-8. Additional Information
-
-The current document editor is: Sami Lehtinen <sj...@ssh.com>. Comments
-on this Internet-Draft should be sent to the IETF SECSH working group,
-details at: http://ietf.org/html.charters/secsh-charter.html
-
-9. Changes from previous versions
-
-9.1. Changes between versions 3 and 2
-
-o Added error message and language tag to SSH_AGENT_FAILURE.
-
-o Added SSH_AGENT_EXTENSION.
-
-o Added extension data to SSH_AGENT_VERSION_RESPONSE.
-
-o Defined SSH_AGENT_ADD_KEY message better (previous version was
- underspecified).
-
-10. References
-
-Normative:
-
-[SECSH-CONNECT] Ylonen, T., et al: "Secure Shell Connection Protocol",
-Internet-Draft, draft-ietf-secsh-connect-16.txt
-
-[SECSH-TRANS] Ylonen, T., et al: "Secure Shell Transport Layer
-Protocol", Internet-Draft, draft-ietf-secsh-transport-10.txt
-
-
-
-Tatu Ylonen, Timo J. Rinne and Sami Lehtinen [page 12]
-
-INTERNET-DRAFT 30 January, 2004
-
-[RFC-2279] Yergeau, F: "UTF-8, a transformation format of ISO 10646",
-January 1998.
-
-[RFC-1766] Alvestrand, H: "Tags for the Identification of Languages",
-March 1995.
-
-Informative:
-
-11. Address of Authors
-
- Tatu Ylonen
- SSH Communications Security Corp
- Fredrikinkatu 42
- FIN-00100 HELSINKI
- Finland
- E-mail: ylo@ssh.com
-
- Timo J. Rinne
- SSH Communications Security Corp
- Fredrikinkatu 42
- FIN-00100 HELSINKI
- Finland
- E-mail: tri@ssh.com
-
- Sami Lehtinen
- SSH Communications Security Corp
- Fredrikinkatu 42
- FIN-00100 HELSINKI
- Finland
- E-mail: sjl@ssh.com
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Tatu Ylonen, Timo J. Rinne and Sami Lehtinen [page 13]
-
http://git-wip-us.apache.org/repos/asf/mina-sshd/blob/46ea0930/sshd-core/src/docs/draft-ietf-secsh-filexfer-02.txt
----------------------------------------------------------------------
diff --git a/sshd-core/src/docs/draft-ietf-secsh-filexfer-02.txt b/sshd-core/src/docs/draft-ietf-secsh-filexfer-02.txt
deleted file mode 100644
index 45e979e..0000000
--- a/sshd-core/src/docs/draft-ietf-secsh-filexfer-02.txt
+++ /dev/null
@@ -1,1626 +0,0 @@
-
-
-Network Working Group T. Ylonen
-Internet-Draft S. Lehtinen
-Expires: April 1, 2002 SSH Communications Security Corp
- October 2001
-
-
- SSH File Transfer Protocol
- draft-ietf-secsh-filexfer-02.txt
-
-Status of this Memo
-
- This document is an Internet-Draft and is in full conformance with
- all provisions of Section 10 of RFC2026.
-
- Internet-Drafts are working documents of the Internet Engineering
- Task Force (IETF), its areas, and its working groups. Note that
- other groups may also distribute working documents as Internet-
- Drafts.
-
- Internet-Drafts are draft documents valid for a maximum of six months
- and may be updated, replaced, or obsoleted by other documents at any
- time. It is inappropriate to use Internet-Drafts as reference
- material or to cite them other than as "work in progress."
-
- The list of current Internet-Drafts can be accessed at http://
- www.ietf.org/ietf/1id-abstracts.txt.
-
- The list of Internet-Draft Shadow Directories can be accessed at
- http://www.ietf.org/shadow.html.
-
- This Internet-Draft will expire on April 1, 2002.
-
-Copyright Notice
-
- Copyright (C) The Internet Society (2001). All Rights Reserved.
-
-Abstract
-
- The SSH File Transfer Protocol provides secure file transfer
- functionality over any reliable data stream. It is the standard file
- transfer protocol for use with the SSH2 protocol. This document
- describes the file transfer protocol and its interface to the SSH2
- protocol suite.
-
-
-
-
-
-
-
-
-
-Ylonen & Lehtinen Expires April 1, 2002 [Page 1]
-
-Internet-Draft SSH File Transfer Protocol October 2001
-
-
-Table of Contents
-
- 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
- 2. Use with the SSH Connection Protocol . . . . . . . . . . . . 4
- 3. General Packet Format . . . . . . . . . . . . . . . . . . . 5
- 4. Protocol Initialization . . . . . . . . . . . . . . . . . . 7
- 5. File Attributes . . . . . . . . . . . . . . . . . . . . . . 8
- 6. Requests From the Client to the Server . . . . . . . . . . . 10
- 6.1 Request Synchronization and Reordering . . . . . . . . . . . 10
- 6.2 File Names . . . . . . . . . . . . . . . . . . . . . . . . . 11
- 6.3 Opening, Creating, and Closing Files . . . . . . . . . . . . 11
- 6.4 Reading and Writing . . . . . . . . . . . . . . . . . . . . 13
- 6.5 Removing and Renaming Files . . . . . . . . . . . . . . . . 14
- 6.6 Creating and Deleting Directories . . . . . . . . . . . . . 15
- 6.7 Scanning Directories . . . . . . . . . . . . . . . . . . . . 15
- 6.8 Retrieving File Attributes . . . . . . . . . . . . . . . . . 16
- 6.9 Setting File Attributes . . . . . . . . . . . . . . . . . . 17
- 6.10 Dealing with Symbolic links . . . . . . . . . . . . . . . . 18
- 6.11 Canonicalizing the Server-Side Path Name . . . . . . . . . . 18
- 7. Responses from the Server to the Client . . . . . . . . . . 20
- 8. Vendor-Specific Extensions . . . . . . . . . . . . . . . . . 24
- 9. Security Considerations . . . . . . . . . . . . . . . . . . 25
- 10. Changes from previous protocol versions . . . . . . . . . . 26
- 10.1 Changes between versions 3 and 2 . . . . . . . . . . . . . . 26
- 10.2 Changes between versions 2 and 1 . . . . . . . . . . . . . . 26
- 10.3 Changes between versions 1 and 0 . . . . . . . . . . . . . . 26
- 11. Trademark Issues . . . . . . . . . . . . . . . . . . . . . . 27
- References . . . . . . . . . . . . . . . . . . . . . . . . . 28
- Authors' Addresses . . . . . . . . . . . . . . . . . . . . . 28
- Full Copyright Statement . . . . . . . . . . . . . . . . . . 29
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Ylonen & Lehtinen Expires April 1, 2002 [Page 2]
-
-Internet-Draft SSH File Transfer Protocol October 2001
-
-
-1. Introduction
-
- This protocol provides secure file transfer (and more generally file
- system access) functionality over a reliable data stream, such as a
- channel in the SSH2 protocol [3].
-
- This protocol is designed so that it could be used to implement a
- secure remote file system service, as well as a secure file transfer
- service.
-
- This protocol assumes that it runs over a secure channel, and that
- the server has already authenticated the user at the client end, and
- that the identity of the client user is externally available to the
- server implementation.
-
- In general, this protocol follows a simple request-response model.
- Each request and response contains a sequence number and multiple
- requests may be pending simultaneously. There are a relatively large
- number of different request messages, but a small number of possible
- response messages. Each request has one or more response messages
- that may be returned in result (e.g., a read either returns data or
- reports error status).
-
- The packet format descriptions in this specification follow the
- notation presented in the secsh architecture draft.[3].
-
- Even though this protocol is described in the context of the SSH2
- protocol, this protocol is general and independent of the rest of the
- SSH2 protocol suite. It could be used in a number of different
- applications, such as secure file transfer over TLS RFC 2246 [1] and
- transfer of management information in VPN applications.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Ylonen & Lehtinen Expires April 1, 2002 [Page 3]
-
-Internet-Draft SSH File Transfer Protocol October 2001
-
-
-2. Use with the SSH Connection Protocol
-
- When used with the SSH2 Protocol suite, this protocol is intended to
- be used from the SSH Connection Protocol [5] as a subsystem, as
- described in section ``Starting a Shell or a Command''. The
- subsystem name used with this protocol is "sftp".
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Ylonen & Lehtinen Expires April 1, 2002 [Page 4]
-
-Internet-Draft SSH File Transfer Protocol October 2001
-
-
-3. General Packet Format
-
- All packets transmitted over the secure connection are of the
- following format:
-
- uint32 length
- byte type
- byte[length - 1] data payload
-
- That is, they are just data preceded by 32-bit length and 8-bit type
- fields. The `length' is the length of the data area, and does not
- include the `length' field itself. The format and interpretation of
- the data area depends on the packet type.
-
- All packet descriptions below only specify the packet type and the
- data that goes into the data field. Thus, they should be prefixed by
- the `length' and `type' fields.
-
- The maximum size of a packet is in practice determined by the client
- (the maximum size of read or write requests that it sends, plus a few
- bytes of packet overhead). All servers SHOULD support packets of at
- least 34000 bytes (where the packet size refers to the full length,
- including the header above). This should allow for reads and writes
- of at most 32768 bytes.
-
- There is no limit on the number of outstanding (non-acknowledged)
- requests that the client may send to the server. In practice this is
- limited by the buffering available on the data stream and the queuing
- performed by the server. If the server's queues are full, it should
- not read any more data from the stream, and flow control will prevent
- the client from sending more requests. Note, however, that while
- there is no restriction on the protocol level, the client's API may
- provide a limit in order to prevent infinite queuing of outgoing
- requests at the client.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Ylonen & Lehtinen Expires April 1, 2002 [Page 5]
-
-Internet-Draft SSH File Transfer Protocol October 2001
-
-
- The following values are defined for packet types.
-
- #define SSH_FXP_INIT 1
- #define SSH_FXP_VERSION 2
- #define SSH_FXP_OPEN 3
- #define SSH_FXP_CLOSE 4
- #define SSH_FXP_READ 5
- #define SSH_FXP_WRITE 6
- #define SSH_FXP_LSTAT 7
- #define SSH_FXP_FSTAT 8
- #define SSH_FXP_SETSTAT 9
- #define SSH_FXP_FSETSTAT 10
- #define SSH_FXP_OPENDIR 11
- #define SSH_FXP_READDIR 12
- #define SSH_FXP_REMOVE 13
- #define SSH_FXP_MKDIR 14
- #define SSH_FXP_RMDIR 15
- #define SSH_FXP_REALPATH 16
- #define SSH_FXP_STAT 17
- #define SSH_FXP_RENAME 18
- #define SSH_FXP_READLINK 19
- #define SSH_FXP_SYMLINK 20
- #define SSH_FXP_STATUS 101
- #define SSH_FXP_HANDLE 102
- #define SSH_FXP_DATA 103
- #define SSH_FXP_NAME 104
- #define SSH_FXP_ATTRS 105
- #define SSH_FXP_EXTENDED 200
- #define SSH_FXP_EXTENDED_REPLY 201
-
- Additional packet types should only be defined if the protocol
- version number (see Section ``Protocol Initialization'') is
- incremented, and their use MUST be negotiated using the version
- number. However, the SSH_FXP_EXTENDED and SSH_FXP_EXTENDED_REPLY
- packets can be used to implement vendor-specific extensions. See
- Section ``Vendor-Specific-Extensions'' for more details.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Ylonen & Lehtinen Expires April 1, 2002 [Page 6]
-
-Internet-Draft SSH File Transfer Protocol October 2001
-
-
-4. Protocol Initialization
-
- When the file transfer protocol starts, it first sends a SSH_FXP_INIT
- (including its version number) packet to the server. The server
- responds with a SSH_FXP_VERSION packet, supplying the lowest of its
- own and the client's version number. Both parties should from then
- on adhere to particular version of the protocol.
-
- The SSH_FXP_INIT packet (from client to server) has the following
- data:
-
- uint32 version
- <extension data>
-
- The SSH_FXP_VERSION packet (from server to client) has the following
- data:
-
- uint32 version
- <extension data>
-
- The version number of the protocol specified in this document is 3.
- The version number should be incremented for each incompatible
- revision of this protocol.
-
- The extension data in the above packets may be empty, or may be a
- sequence of
-
- string extension_name
- string extension_data
-
- pairs (both strings MUST always be present if one is, but the
- `extension_data' string may be of zero length). If present, these
- strings indicate extensions to the baseline protocol. The
- `extension_name' field(s) identify the name of the extension. The
- name should be of the form "name@domain", where the domain is the DNS
- domain name of the organization defining the extension. Additional
- names that are not of this format may be defined later by the IETF.
- Implementations MUST silently ignore any extensions whose name they
- do not recognize.
-
-
-
-
-
-
-
-
-
-
-
-
-Ylonen & Lehtinen Expires April 1, 2002 [Page 7]
-
-Internet-Draft SSH File Transfer Protocol October 2001
-
-
-5. File Attributes
-
- A new compound data type is defined for encoding file attributes. It
- is basically just a combination of elementary types, but is defined
- once because of the non-trivial description of the fields and to
- ensure maintainability.
-
- The same encoding is used both when returning file attributes from
- the server and when sending file attributes to the server. When
- sending it to the server, the flags field specifies which attributes
- are included, and the server will use default values for the
- remaining attributes (or will not modify the values of remaining
- attributes). When receiving attributes from the server, the flags
- specify which attributes are included in the returned data. The
- server normally returns all attributes it knows about.
-
- uint32 flags
- uint64 size present only if flag SSH_FILEXFER_ATTR_SIZE
- uint32 uid present only if flag SSH_FILEXFER_ATTR_UIDGID
- uint32 gid present only if flag SSH_FILEXFER_ATTR_UIDGID
- uint32 permissions present only if flag SSH_FILEXFER_ATTR_PERMISSIONS
- uint32 atime present only if flag SSH_FILEXFER_ACMODTIME
- uint32 mtime present only if flag SSH_FILEXFER_ACMODTIME
- uint32 extended_count present only if flag SSH_FILEXFER_ATTR_EXTENDED
- string extended_type
- string extended_data
- ... more extended data (extended_type - extended_data pairs),
- so that number of pairs equals extended_count
-
- The `flags' specify which of the fields are present. Those fields
- for which the corresponding flag is not set are not present (not
- included in the packet). New flags can only be added by incrementing
- the protocol version number (or by using the extension mechanism
- described below).
-
- The `size' field specifies the size of the file in bytes.
-
- The `uid' and `gid' fields contain numeric Unix-like user and group
- identifiers, respectively.
-
- The `permissions' field contains a bit mask of file permissions as
- defined by posix [1].
-
- The `atime' and `mtime' contain the access and modification times of
- the files, respectively. They are represented as seconds from Jan 1,
- 1970 in UTC.
-
- The SSH_FILEXFER_ATTR_EXTENDED flag provides a general extension
-
-
-
-Ylonen & Lehtinen Expires April 1, 2002 [Page 8]
-
-Internet-Draft SSH File Transfer Protocol October 2001
-
-
- mechanism for vendor-specific extensions. If the flag is specified,
- then the `extended_count' field is present. It specifies the number
- of extended_type-extended_data pairs that follow. Each of these
- pairs specifies an extended attribute. For each of the attributes,
- the extended_type field should be a string of the format
- "name@domain", where "domain" is a valid, registered domain name and
- "name" identifies the method. The IETF may later standardize certain
- names that deviate from this format (e.g., that do not contain the
- "@" sign). The interpretation of `extended_data' depends on the
- type. Implementations SHOULD ignore extended data fields that they
- do not understand.
-
- Additional fields can be added to the attributes by either defining
- additional bits to the flags field to indicate their presence, or by
- defining extended attributes for them. The extended attributes
- mechanism is recommended for most purposes; additional flags bits
- should only be defined by an IETF standards action that also
- increments the protocol version number. The use of such new fields
- MUST be negotiated by the version number in the protocol exchange.
- It is a protocol error if a packet with unsupported protocol bits is
- received.
-
- The flags bits are defined to have the following values:
-
- #define SSH_FILEXFER_ATTR_SIZE 0x00000001
- #define SSH_FILEXFER_ATTR_UIDGID 0x00000002
- #define SSH_FILEXFER_ATTR_PERMISSIONS 0x00000004
- #define SSH_FILEXFER_ATTR_ACMODTIME 0x00000008
- #define SSH_FILEXFER_ATTR_EXTENDED 0x80000000
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Ylonen & Lehtinen Expires April 1, 2002 [Page 9]
-
-Internet-Draft SSH File Transfer Protocol October 2001
-
-
-6. Requests From the Client to the Server
-
- Requests from the client to the server represent the various file
- system operations. Each request begins with an `id' field, which is
- a 32-bit identifier identifying the request (selected by the client).
- The same identifier will be returned in the response to the request.
- One possible implementation of it is a monotonically increasing
- request sequence number (modulo 2^32).
-
- Many operations in the protocol operate on open files. The
- SSH_FXP_OPEN request can return a file handle (which is an opaque
- variable-length string) which may be used to access the file later
- (e.g. in a read operation). The client MUST NOT send requests the
- server with bogus or closed handles. However, the server MUST
- perform adequate checks on the handle in order to avoid security
- risks due to fabricated handles.
-
- This design allows either stateful and stateless server
- implementation, as well as an implementation which caches state
- between requests but may also flush it. The contents of the file
- handle string are entirely up to the server and its design. The
- client should not modify or attempt to interpret the file handle
- strings.
-
- The file handle strings MUST NOT be longer than 256 bytes.
-
-6.1 Request Synchronization and Reordering
-
- The protocol and implementations MUST process requests relating to
- the same file in the order in which they are received. In other
- words, if an application submits multiple requests to the server, the
- results in the responses will be the same as if it had sent the
- requests one at a time and waited for the response in each case. For
- example, the server may process non-overlapping read/write requests
- to the same file in parallel, but overlapping reads and writes cannot
- be reordered or parallelized. However, there are no ordering
- restrictions on the server for processing requests from two different
- file transfer connections. The server may interleave and parallelize
- them at will.
-
- There are no restrictions on the order in which responses to
- outstanding requests are delivered to the client, except that the
- server must ensure fairness in the sense that processing of no
- request will be indefinitely delayed even if the client is sending
- other requests so that there are multiple outstanding requests all
- the time.
-
-
-
-
-
-Ylonen & Lehtinen Expires April 1, 2002 [Page 10]
-
-Internet-Draft SSH File Transfer Protocol October 2001
-
-
-6.2 File Names
-
- This protocol represents file names as strings. File names are
- assumed to use the slash ('/') character as a directory separator.
-
- File names starting with a slash are "absolute", and are relative to
- the root of the file system. Names starting with any other character
- are relative to the user's default directory (home directory). Note
- that identifying the user is assumed to take place outside of this
- protocol.
-
- Servers SHOULD interpret a path name component ".." as referring to
- the parent directory, and "." as referring to the current directory.
- If the server implementation limits access to certain parts of the
- file system, it must be extra careful in parsing file names when
- enforcing such restrictions. There have been numerous reported
- security bugs where a ".." in a path name has allowed access outside
- the intended area.
-
- An empty path name is valid, and it refers to the user's default
- directory (usually the user's home directory).
-
- Otherwise, no syntax is defined for file names by this specification.
- Clients should not make any other assumptions; however, they can
- splice path name components returned by SSH_FXP_READDIR together
- using a slash ('/') as the separator, and that will work as expected.
-
- It is understood that the lack of well-defined semantics for file
- names may cause interoperability problems between clients and servers
- using radically different operating systems. However, this approach
- is known to work acceptably with most systems, and alternative
- approaches that e.g. treat file names as sequences of structured
- components are quite complicated.
-
-6.3 Opening, Creating, and Closing Files
-
- Files are opened and created using the SSH_FXP_OPEN message, whose
- data part is as follows:
-
- uint32 id
- string filename
- uint32 pflags
- ATTRS attrs
-
- The `id' field is the request identifier as for all requests.
-
- The `filename' field specifies the file name. See Section ``File
- Names'' for more information.
-
-
-
-Ylonen & Lehtinen Expires April 1, 2002 [Page 11]
-
-Internet-Draft SSH File Transfer Protocol October 2001
-
-
- The `pflags' field is a bitmask. The following bits have been
- defined.
-
- #define SSH_FXF_READ 0x00000001
- #define SSH_FXF_WRITE 0x00000002
- #define SSH_FXF_APPEND 0x00000004
- #define SSH_FXF_CREAT 0x00000008
- #define SSH_FXF_TRUNC 0x00000010
- #define SSH_FXF_EXCL 0x00000020
-
- These have the following meanings:
-
- SSH_FXF_READ
- Open the file for reading.
-
- SSH_FXF_WRITE
- Open the file for writing. If both this and SSH_FXF_READ are
- specified, the file is opened for both reading and writing.
-
- SSH_FXF_APPEND
- Force all writes to append data at the end of the file.
-
- SSH_FXF_CREAT
- If this flag is specified, then a new file will be created if one
- does not already exist (if O_TRUNC is specified, the new file will
- be truncated to zero length if it previously exists).
-
- SSH_FXF_TRUNC
- Forces an existing file with the same name to be truncated to zero
- length when creating a file by specifying SSH_FXF_CREAT.
- SSH_FXF_CREAT MUST also be specified if this flag is used.
-
- SSH_FXF_EXCL
- Causes the request to fail if the named file already exists.
- SSH_FXF_CREAT MUST also be specified if this flag is used.
-
- The `attrs' field specifies the initial attributes for the file.
- Default values will be used for those attributes that are not
- specified. See Section ``File Attributes'' for more information.
-
- Regardless the server operating system, the file will always be
- opened in "binary" mode (i.e., no translations between different
- character sets and newline encodings).
-
- The response to this message will be either SSH_FXP_HANDLE (if the
- operation is successful) or SSH_FXP_STATUS (if the operation fails).
-
-
-
-
-
-Ylonen & Lehtinen Expires April 1, 2002 [Page 12]
-
-Internet-Draft SSH File Transfer Protocol October 2001
-
-
- A file is closed by using the SSH_FXP_CLOSE request. Its data field
- has the following format:
-
- uint32 id
- string handle
-
- where `id' is the request identifier, and `handle' is a handle
- previously returned in the response to SSH_FXP_OPEN or
- SSH_FXP_OPENDIR. The handle becomes invalid immediately after this
- request has been sent.
-
- The response to this request will be a SSH_FXP_STATUS message. One
- should note that on some server platforms even a close can fail.
- This can happen e.g. if the server operating system caches writes,
- and an error occurs while flushing cached writes during the close.
-
-6.4 Reading and Writing
-
- Once a file has been opened, it can be read using the SSH_FXP_READ
- message, which has the following format:
-
- uint32 id
- string handle
- uint64 offset
- uint32 len
-
- where `id' is the request identifier, `handle' is an open file handle
- returned by SSH_FXP_OPEN, `offset' is the offset (in bytes) relative
- to the beginning of the file from where to start reading, and `len'
- is the maximum number of bytes to read.
-
- In response to this request, the server will read as many bytes as it
- can from the file (up to `len'), and return them in a SSH_FXP_DATA
- message. If an error occurs or EOF is encountered before reading any
- data, the server will respond with SSH_FXP_STATUS. For normal disk
- files, it is guaranteed that this will read the specified number of
- bytes, or up to end of file. For e.g. device files this may return
- fewer bytes than requested.
-
- Writing to a file is achieved using the SSH_FXP_WRITE message, which
- has the following format:
-
- uint32 id
- string handle
- uint64 offset
- string data
-
- where `id' is a request identifier, `handle' is a file handle
-
-
-
-Ylonen & Lehtinen Expires April 1, 2002 [Page 13]
-
-Internet-Draft SSH File Transfer Protocol October 2001
-
-
- returned by SSH_FXP_OPEN, `offset' is the offset (in bytes) from the
- beginning of the file where to start writing, and `data' is the data
- to be written.
-
- The write will extend the file if writing beyond the end of the file.
- It is legal to write way beyond the end of the file; the semantics
- are to write zeroes from the end of the file to the specified offset
- and then the data. On most operating systems, such writes do not
- allocate disk space but instead leave "holes" in the file.
-
- The server responds to a write request with a SSH_FXP_STATUS message.
-
-6.5 Removing and Renaming Files
-
- Files can be removed using the SSH_FXP_REMOVE message. It has the
- following format:
-
- uint32 id
- string filename
-
- where `id' is the request identifier and `filename' is the name of
- the file to be removed. See Section ``File Names'' for more
- information. This request cannot be used to remove directories.
-
- The server will respond to this request with a SSH_FXP_STATUS
- message.
-
- Files (and directories) can be renamed using the SSH_FXP_RENAME
- message. Its data is as follows:
-
- uint32 id
- string oldpath
- string newpath
-
- where `id' is the request identifier, `oldpath' is the name of an
- existing file or directory, and `newpath' is the new name for the
- file or directory. It is an error if there already exists a file
- with the name specified by newpath. The server may also fail rename
- requests in other situations, for example if `oldpath' and `newpath'
- point to different file systems on the server.
-
- The server will respond to this request with a SSH_FXP_STATUS
- message.
-
-
-
-
-
-
-
-
-Ylonen & Lehtinen Expires April 1, 2002 [Page 14]
-
-Internet-Draft SSH File Transfer Protocol October 2001
-
-
-6.6 Creating and Deleting Directories
-
- New directories can be created using the SSH_FXP_MKDIR request. It
- has the following format:
-
- uint32 id
- string path
- ATTRS attrs
-
- where `id' is the request identifier, `path' and `attrs' specifies
- the modifications to be made to its attributes. See Section ``File
- Names'' for more information on file names. Attributes are discussed
- in more detail in Section ``File Attributes''. specifies the
- directory to be created. An error will be returned if a file or
- directory with the specified path already exists. The server will
- respond to this request with a SSH_FXP_STATUS message.
-
- Directories can be removed using the SSH_FXP_RMDIR request, which
- has the following format:
-
- uint32 id
- string path
-
- where `id' is the request identifier, and `path' specifies the
- directory to be removed. See Section ``File Names'' for more
- information on file names. An error will be returned if no directory
- with the specified path exists, or if the specified directory is not
- empty, or if the path specified a file system object other than a
- directory. The server responds to this request with a SSH_FXP_STATUS
- message.
-
-6.7 Scanning Directories
-
- The files in a directory can be listed using the SSH_FXP_OPENDIR and
- SSH_FXP_READDIR requests. Each SSH_FXP_READDIR request returns one
- or more file names with full file attributes for each file. The
- client should call SSH_FXP_READDIR repeatedly until it has found the
- file it is looking for or until the server responds with a
- SSH_FXP_STATUS message indicating an error (normally SSH_FX_EOF if
- there are no more files in the directory). The client should then
- close the handle using the SSH_FXP_CLOSE request.
-
-
-
-
-
-
-
-
-
-
-Ylonen & Lehtinen Expires April 1, 2002 [Page 15]
-
-Internet-Draft SSH File Transfer Protocol October 2001
-
-
- The SSH_FXP_OPENDIR opens a directory for reading. It has the
- following format:
-
- uint32 id
- string path
-
- where `id' is the request identifier and `path' is the path name of
- the directory to be listed (without any trailing slash). See Section
- ``File Names'' for more information on file names. This will return
- an error if the path does not specify a directory or if the directory
- is not readable. The server will respond to this request with either
- a SSH_FXP_HANDLE or a SSH_FXP_STATUS message.
-
- Once the directory has been successfully opened, files (and
- directories) contained in it can be listed using SSH_FXP_READDIR
- requests. These are of the format
-
- uint32 id
- string handle
-
- where `id' is the request identifier, and `handle' is a handle
- returned by SSH_FXP_OPENDIR. (It is a protocol error to attempt to
- use an ordinary file handle returned by SSH_FXP_OPEN.)
-
- The server responds to this request with either a SSH_FXP_NAME or a
- SSH_FXP_STATUS message. One or more names may be returned at a time.
- Full status information is returned for each name in order to speed
- up typical directory listings.
-
- When the client no longer wishes to read more names from the
- directory, it SHOULD call SSH_FXP_CLOSE for the handle. The handle
- should be closed regardless of whether an error has occurred or not.
-
-6.8 Retrieving File Attributes
-
- Very often, file attributes are automatically returned by
- SSH_FXP_READDIR. However, sometimes there is need to specifically
- retrieve the attributes for a named file. This can be done using the
- SSH_FXP_STAT, SSH_FXP_LSTAT and SSH_FXP_FSTAT requests.
-
- SSH_FXP_STAT and SSH_FXP_LSTAT only differ in that SSH_FXP_STAT
- follows symbolic links on the server, whereas SSH_FXP_LSTAT does not
- follow symbolic links. Both have the same format:
-
- uint32 id
- string path
-
- where `id' is the request identifier, and `path' specifies the file
-
-
-
-Ylonen & Lehtinen Expires April 1, 2002 [Page 16]
-
-Internet-Draft SSH File Transfer Protocol October 2001
-
-
- system object for which status is to be returned. The server
- responds to this request with either SSH_FXP_ATTRS or SSH_FXP_STATUS.
-
- SSH_FXP_FSTAT differs from the others in that it returns status
- information for an open file (identified by the file handle). Its
- format is as follows:
-
- uint32 id
- string handle
-
- where `id' is the request identifier and `handle' is a file handle
- returned by SSH_FXP_OPEN. The server responds to this request with
- SSH_FXP_ATTRS or SSH_FXP_STATUS.
-
-6.9 Setting File Attributes
-
- File attributes may be modified using the SSH_FXP_SETSTAT and
- SSH_FXP_FSETSTAT requests. These requests are used for operations
- such as changing the ownership, permissions or access times, as well
- as for truncating a file.
-
- The SSH_FXP_SETSTAT request is of the following format:
-
- uint32 id
- string path
- ATTRS attrs
-
- where `id' is the request identifier, `path' specifies the file
- system object (e.g. file or directory) whose attributes are to be
- modified, and `attrs' specifies the modifications to be made to its
- attributes. Attributes are discussed in more detail in Section
- ``File Attributes''.
-
- An error will be returned if the specified file system object does
- not exist or the user does not have sufficient rights to modify the
- specified attributes. The server responds to this request with a
- SSH_FXP_STATUS message.
-
- The SSH_FXP_FSETSTAT request modifies the attributes of a file which
- is already open. It has the following format:
-
- uint32 id
- string handle
- ATTRS attrs
-
- where `id' is the request identifier, `handle' (MUST be returned by
- SSH_FXP_OPEN) identifies the file whose attributes are to be
- modified, and `attrs' specifies the modifications to be made to its
-
-
-
-Ylonen & Lehtinen Expires April 1, 2002 [Page 17]
-
-Internet-Draft SSH File Transfer Protocol October 2001
-
-
- attributes. Attributes are discussed in more detail in Section
- ``File Attributes''. The server will respond to this request with
- SSH_FXP_STATUS.
-
-6.10 Dealing with Symbolic links
-
- The SSH_FXP_READLINK request may be used to read the target of a
- symbolic link. It would have a data part as follows:
-
- uint32 id
- string path
-
- where `id' is the request identifier and `path' specifies the path
- name of the symlink to be read.
-
- The server will respond with a SSH_FXP_NAME packet containing only
- one name and a dummy attributes value. The name in the returned
- packet contains the target of the link. If an error occurs, the
- server may respond with SSH_FXP_STATUS.
-
- The SSH_FXP_SYMLINK request will create a symbolic link on the
- server. It is of the following format
-
- uint32 id
- string linkpath
- string targetpath
-
- where `id' is the request identifier, `linkpath' specifies the path
- name of the symlink to be created and `targetpath' specifies the
- target of the symlink. The server shall respond with a
- SSH_FXP_STATUS indicating either success (SSH_FX_OK) or an error
- condition.
-
-6.11 Canonicalizing the Server-Side Path Name
-
- The SSH_FXP_REALPATH request can be used to have the server
- canonicalize any given path name to an absolute path. This is useful
- for converting path names containing ".." components or relative
- pathnames without a leading slash into absolute paths. The format of
- the request is as follows:
-
- uint32 id
- string path
-
- where `id' is the request identifier and `path' specifies the path
- name to be canonicalized. The server will respond with a
- SSH_FXP_NAME packet containing only one name and a dummy attributes
- value. The name is the returned packet will be in canonical form.
-
-
-
-Ylonen & Lehtinen Expires April 1, 2002 [Page 18]
-
-Internet-Draft SSH File Transfer Protocol October 2001
-
-
- If an error occurs, the server may also respond with SSH_FXP_STATUS.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Ylonen & Lehtinen Expires April 1, 2002 [Page 19]
-
-Internet-Draft SSH File Transfer Protocol October 2001
-
-
-7. Responses from the Server to the Client
-
- The server responds to the client using one of a few response
- packets. All requests can return a SSH_FXP_STATUS response upon
- failure. When the operation is successful, any of the responses may
- be returned (depending on the operation). If no data needs to be
- returned to the client, the SSH_FXP_STATUS response with SSH_FX_OK
- status is appropriate. Otherwise, the SSH_FXP_HANDLE message is used
- to return a file handle (for SSH_FXP_OPEN and SSH_FXP_OPENDIR
- requests), SSH_FXP_DATA is used to return data from SSH_FXP_READ,
- SSH_FXP_NAME is used to return one or more file names from a
- SSH_FXP_READDIR or SSH_FXP_REALPATH request, and SSH_FXP_ATTRS is
- used to return file attributes from SSH_FXP_STAT, SSH_FXP_LSTAT, and
- SSH_FXP_FSTAT requests.
-
- Exactly one response will be returned for each request. Each
- response packet contains a request identifier which can be used to
- match each response with the corresponding request. Note that it is
- legal to have several requests outstanding simultaneously, and the
- server is allowed to send responses to them in a different order from
- the order in which the requests were sent (the result of their
- execution, however, is guaranteed to be as if they had been processed
- one at a time in the order in which the requests were sent).
-
- Response packets are of the same general format as request packets.
- Each response packet begins with the request identifier.
-
- The format of the data portion of the SSH_FXP_STATUS response is as
- follows:
-
- uint32 id
- uint32 error/status code
- string error message (ISO-10646 UTF-8 [RFC-2279])
- string language tag (as defined in [RFC-1766])
-
- where `id' is the request identifier, and `error/status code'
- indicates the result of the requested operation. The value SSH_FX_OK
- indicates success, and all other values indicate failure.
-
-
-
-
-
-
-
-
-
-
-
-
-
-Ylonen & Lehtinen Expires April 1, 2002 [Page 20]
-
-Internet-Draft SSH File Transfer Protocol October 2001
-
-
- Currently, the following values are defined (other values may be
- defined by future versions of this protocol):
-
- #define SSH_FX_OK 0
- #define SSH_FX_EOF 1
- #define SSH_FX_NO_SUCH_FILE 2
- #define SSH_FX_PERMISSION_DENIED 3
- #define SSH_FX_FAILURE 4
- #define SSH_FX_BAD_MESSAGE 5
- #define SSH_FX_NO_CONNECTION 6
- #define SSH_FX_CONNECTION_LOST 7
- #define SSH_FX_OP_UNSUPPORTED 8
-
- SSH_FX_OK
- Indicates successful completion of the operation.
-
- SSH_FX_EOF
- indicates end-of-file condition; for SSH_FX_READ it means that no
- more data is available in the file, and for SSH_FX_READDIR it
- indicates that no more files are contained in the directory.
-
- SSH_FX_NO_SUCH_FILE
- is returned when a reference is made to a file which should exist
- but doesn't.
-
- SSH_FX_PERMISSION_DENIED
- is returned when the authenticated user does not have sufficient
- permissions to perform the operation.
-
- SSH_FX_FAILURE
- is a generic catch-all error message; it should be returned if an
- error occurs for which there is no more specific error code
- defined.
-
- SSH_FX_BAD_MESSAGE
- may be returned if a badly formatted packet or protocol
- incompatibility is detected.
-
- SSH_FX_NO_CONNECTION
- is a pseudo-error which indicates that the client has no
- connection to the server (it can only be generated locally by the
- client, and MUST NOT be returned by servers).
-
- SSH_FX_CONNECTION_LOST
- is a pseudo-error which indicates that the connection to the
- server has been lost (it can only be generated locally by the
- client, and MUST NOT be returned by servers).
-
-
-
-
-Ylonen & Lehtinen Expires April 1, 2002 [Page 21]
-
-Internet-Draft SSH File Transfer Protocol October 2001
-
-
- SSH_FX_OP_UNSUPPORTED
- indicates that an attempt was made to perform an operation which
- is not supported for the server (it may be generated locally by
- the client if e.g. the version number exchange indicates that a
- required feature is not supported by the server, or it may be
- returned by the server if the server does not implement an
- operation).
-
- The SSH_FXP_HANDLE response has the following format:
-
- uint32 id
- string handle
-
- where `id' is the request identifier, and `handle' is an arbitrary
- string that identifies an open file or directory on the server. The
- handle is opaque to the client; the client MUST NOT attempt to
- interpret or modify it in any way. The length of the handle string
- MUST NOT exceed 256 data bytes.
-
- The SSH_FXP_DATA response has the following format:
-
- uint32 id
- string data
-
- where `id' is the request identifier, and `data' is an arbitrary byte
- string containing the requested data. The data string may be at most
- the number of bytes requested in a SSH_FXP_READ request, but may also
- be shorter if end of file is reached or if the read is from something
- other than a regular file.
-
- The SSH_FXP_NAME response has the following format:
-
- uint32 id
- uint32 count
- repeats count times:
- string filename
- string longname
- ATTRS attrs
-
- where `id' is the request identifier, `count' is the number of names
- returned in this response, and the remaining fields repeat `count'
- times (so that all three fields are first included for the first
- file, then for the second file, etc). In the repeated part,
- `filename' is a file name being returned (for SSH_FXP_READDIR, it
- will be a relative name within the directory, without any path
- components; for SSH_FXP_REALPATH it will be an absolute path name),
- `longname' is an expanded format for the file name, similar to what
- is returned by "ls -l" on Unix systems, and `attrs' is the attributes
-
-
-
-Ylonen & Lehtinen Expires April 1, 2002 [Page 22]
-
-Internet-Draft SSH File Transfer Protocol October 2001
-
-
- of the file as described in Section ``File Attributes''.
-
- The format of the `longname' field is unspecified by this protocol.
- It MUST be suitable for use in the output of a directory listing
- command (in fact, the recommended operation for a directory listing
- command is to simply display this data). However, clients SHOULD NOT
- attempt to parse the longname field for file attributes; they SHOULD
- use the attrs field instead.
-
- The recommended format for the longname field is as follows:
-
- -rwxr-xr-x 1 mjos staff 348911 Mar 25 14:29 t-filexfer
- 1234567890 123 12345678 12345678 12345678 123456789012
-
- Here, the first line is sample output, and the second field indicates
- widths of the various fields. Fields are separated by spaces. The
- first field lists file permissions for user, group, and others; the
- second field is link count; the third field is the name of the user
- who owns the file; the fourth field is the name of the group that
- owns the file; the fifth field is the size of the file in bytes; the
- sixth field (which actually may contain spaces, but is fixed to 12
- characters) is the file modification time, and the seventh field is
- the file name. Each field is specified to be a minimum of certain
- number of character positions (indicated by the second line above),
- but may also be longer if the data does not fit in the specified
- length.
-
- The SSH_FXP_ATTRS response has the following format:
-
- uint32 id
- ATTRS attrs
-
- where `id' is the request identifier, and `attrs' is the returned
- file attributes as described in Section ``File Attributes''.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Ylonen & Lehtinen Expires April 1, 2002 [Page 23]
-
-Internet-Draft SSH File Transfer Protocol October 2001
-
-
-8. Vendor-Specific Extensions
-
- The SSH_FXP_EXTENDED request provides a generic extension mechanism
- for adding vendor-specific commands. The request has the following
- format:
-
- uint32 id
- string extended-request
- ... any request-specific data ...
-
- where `id' is the request identifier, and `extended-request' is a
- string of the format "name@domain", where domain is an internet
- domain name of the vendor defining the request. The rest of the
- request is completely vendor-specific, and servers should only
- attempt to interpret it if they recognize the `extended-request'
- name.
-
- The server may respond to such requests using any of the response
- packets defined in Section ``Responses from the Server to the
- Client''. Additionally, the server may also respond with a
- SSH_FXP_EXTENDED_REPLY packet, as defined below. If the server does
- not recognize the `extended-request' name, then the server MUST
- respond with SSH_FXP_STATUS with error/status set to
- SSH_FX_OP_UNSUPPORTED.
-
- The SSH_FXP_EXTENDED_REPLY packet can be used to carry arbitrary
- extension-specific data from the server to the client. It is of the
- following format:
-
- uint32 id
- ... any request-specific data ...
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Ylonen & Lehtinen Expires April 1, 2002 [Page 24]
-
-Internet-Draft SSH File Transfer Protocol October 2001
-
-
-9. Security Considerations
-
- This protocol assumes that it is run over a secure channel and that
- the endpoints of the channel have been authenticated. Thus, this
- protocol assumes that it is externally protected from network-level
- attacks.
-
- This protocol provides file system access to arbitrary files on the
- server (only constrained by the server implementation). It is the
- responsibility of the server implementation to enforce any access
- controls that may be required to limit the access allowed for any
- particular user (the user being authenticated externally to this
- protocol, typically using the SSH User Authentication Protocol [6].
-
- Care must be taken in the server implementation to check the validity
- of received file handle strings. The server should not rely on them
- directly; it MUST check the validity of each handle before relying on
- it.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Ylonen & Lehtinen Expires April 1, 2002 [Page 25]
-
-Internet-Draft SSH File Transfer Protocol October 2001
-
-
-10. Changes from previous protocol versions
-
- The SSH File Transfer Protocol has changed over time, before it's
- standardization. The following is a description of the incompatible
- changes between different versions.
-
-10.1 Changes between versions 3 and 2
-
- o The SSH_FXP_READLINK and SSH_FXP_SYMLINK messages were added.
-
- o The SSH_FXP_EXTENDED and SSH_FXP_EXTENDED_REPLY messages were
- added.
-
- o The SSH_FXP_STATUS message was changed to include fields `error
- message' and `language tag'.
-
-
-10.2 Changes between versions 2 and 1
-
- o The SSH_FXP_RENAME message was added.
-
-
-10.3 Changes between versions 1 and 0
-
- o Implementation changes, no actual protocol changes.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Ylonen & Lehtinen Expires April 1, 2002 [Page 26]
-
-Internet-Draft SSH File Transfer Protocol October 2001
-
-
-11. Trademark Issues
-
- "ssh" is a registered trademark of SSH Communications Security Corp
- in the United States and/or other countries.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Ylonen & Lehtinen Expires April 1, 2002 [Page 27]
-
-Internet-Draft SSH File Transfer Protocol October 2001
-
-
-References
-
- [1] Dierks, T., Allen, C., Treese, W., Karlton, P., Freier, A. and
- P. Kocher, "The TLS Protocol Version 1.0", RFC 2246, January
- 1999.
-
- [2] Institute of Electrical and Electronics Engineers, "Information
- Technology - Portable Operating System Interface (POSIX) - Part
- 1: System Application Program Interface (API) [C Language]",
- IEEE Standard 1003.2, 1996.
-
- [3] Rinne, T., Ylonen, T., Kivinen, T., Saarinen, M. and S.
- Lehtinen, "SSH Protocol Architecture", draft-ietf-secsh-
- architecture-09 (work in progress), July 2001.
-
- [4] Rinne, T., Ylonen, T., Kivinen, T., Saarinen, M. and S.
- Lehtinen, "SSH Protocol Transport Protocol", draft-ietf-secsh-
- architecture-09 (work in progress), July 2001.
-
- [5] Rinne, T., Ylonen, T., Kivinen, T., Saarinen, M. and S.
- Lehtinen, "SSH Connection Protocol", draft-ietf-secsh-connect-11
- (work in progress), July 2001.
-
- [6] Rinne, T., Ylonen, T., Kivinen, T., Saarinen, M. and S.
- Lehtinen, "SSH Authentication Protocol", draft-ietf-secsh-
- userauth-11 (work in progress), July 2001.
-
-
-Authors' Addresses
-
- Tatu Ylonen
- SSH Communications Security Corp
- Fredrikinkatu 42
- HELSINKI FIN-00100
- Finland
-
- EMail: ylo@ssh.com
-
-
- Sami Lehtinen
- SSH Communications Security Corp
- Fredrikinkatu 42
- HELSINKI FIN-00100
- Finland
-
- EMail: sjl@ssh.com
-
-
-
-
-
-Ylonen & Lehtinen Expires April 1, 2002 [Page 28]
-
-Internet-Draft SSH File Transfer Protocol October 2001
-
-
-Full Copyright Statement
-
- Copyright (C) The Internet Society (2001). All Rights Reserved.
-
- This document and translations of it may be copied and furnished to
- others, and derivative works that comment on or otherwise explain it
- or assist in its implementation may be prepared, copied, published
- and distributed, in whole or in part, without restriction of any
- kind, provided that the above copyright notice and this paragraph are
- included on all such copies and derivative works. However, this
- document itself may not be modified in any way, such as by removing
- the copyright notice or references to the Internet Society or other
- Internet organizations, except as needed for the purpose of
- developing Internet standards in which case the procedures for
- copyrights defined in the Internet Standards process must be
- followed, or as required to translate it into languages other than
- English.
-
- The limited permissions granted above are perpetual and will not be
- revoked by the Internet Society or its successors or assigns.
-
- This document and the information contained herein is provided on an
- "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
- TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
- BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
- HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
- MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
-
-Acknowledgement
-
- Funding for the RFC Editor function is currently provided by the
- Internet Society.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Ylonen & Lehtinen Expires April 1, 2002 [Page 29]
-
-
-
[8/9] Remove third party documents from scm
Posted by gn...@apache.org.
http://git-wip-us.apache.org/repos/asf/mina-sshd/blob/46ea0930/sshd-core/src/docs/draft-ietf-secsh-filexfer-04.txt
----------------------------------------------------------------------
diff --git a/sshd-core/src/docs/draft-ietf-secsh-filexfer-04.txt b/sshd-core/src/docs/draft-ietf-secsh-filexfer-04.txt
deleted file mode 100644
index e469c26..0000000
--- a/sshd-core/src/docs/draft-ietf-secsh-filexfer-04.txt
+++ /dev/null
@@ -1,2130 +0,0 @@
-
-
-
-
-Secure Shell Working Group J. Galbraith
-Internet-Draft VanDyke Software
-Expires: June 18, 2003 T. Ylonen
- S. Lehtinen
- SSH Communications Security Corp
- December 18, 2002
-
-
- SSH File Transfer Protocol
- draft-ietf-secsh-filexfer-04.txt
-
-Status of this Memo
-
- This document is an Internet-Draft and is in full conformance with
- all provisions of Section 10 of RFC2026.
-
- Internet-Drafts are working documents of the Internet Engineering
- Task Force (IETF), its areas, and its working groups. Note that
- other groups may also distribute working documents as
- Internet-Drafts.
-
- Internet-Drafts are draft documents valid for a maximum of six months
- and may be updated, replaced, or obsoleted by other documents at any
- time. It is inappropriate to use Internet-Drafts as reference
- material or to cite them other than as "work in progress."
-
- The list of current Internet-Drafts can be accessed at http://
- www.ietf.org/ietf/1id-abstracts.txt.
-
- The list of Internet-Draft Shadow Directories can be accessed at
- http://www.ietf.org/shadow.html.
-
- This Internet-Draft will expire on June 18, 2003.
-
-Copyright Notice
-
- Copyright (C) The Internet Society (2002). All Rights Reserved.
-
-Abstract
-
- The SSH File Transfer Protocol provides secure file transfer
- functionality over any reliable data stream. It is the standard file
- transfer protocol for use with the SSH2 protocol. This document
- describes the file transfer protocol and its interface to the SSH2
- protocol suite.
-
-
-
-
-
-
-
-Galbraith, et al. Expires June 18, 2003 [Page 1]
-
-Internet-Draft SSH File Transfer Protocol December 2002
-
-
-Table of Contents
-
- 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . 3
- 2. Use with the SSH Connection Protocol . . . . . . . . . . . 4
- 3. General Packet Format . . . . . . . . . . . . . . . . . . 5
- 3.1 The use of stderr in the server . . . . . . . . . . . . . 6
- 4. Protocol Initialization . . . . . . . . . . . . . . . . . 8
- 4.1 Client Initialization . . . . . . . . . . . . . . . . . . 8
- 4.2 Server Initialization . . . . . . . . . . . . . . . . . . 8
- 4.3 Determining Server Newline Convention . . . . . . . . . . 9
- 5. File Attributes . . . . . . . . . . . . . . . . . . . . . 10
- 5.1 Flags . . . . . . . . . . . . . . . . . . . . . . . . . . 10
- 5.2 Type . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
- 5.3 Size . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
- 5.4 Owner and Group . . . . . . . . . . . . . . . . . . . . . 11
- 5.5 Permissions . . . . . . . . . . . . . . . . . . . . . . . 12
- 5.6 Times . . . . . . . . . . . . . . . . . . . . . . . . . . 12
- 5.7 ACL . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
- 5.8 Extended attributes . . . . . . . . . . . . . . . . . . . 14
- 6. Requests From the Client to the Server . . . . . . . . . . 15
- 6.1 Request Synchronization and Reordering . . . . . . . . . . 15
- 6.2 File Names . . . . . . . . . . . . . . . . . . . . . . . . 16
- 6.3 Opening, Creating, and Closing Files . . . . . . . . . . . 16
- 6.4 Reading and Writing . . . . . . . . . . . . . . . . . . . 19
- 6.5 Removing and Renaming Files . . . . . . . . . . . . . . . 20
- 6.6 Creating and Deleting Directories . . . . . . . . . . . . 21
- 6.7 Scanning Directories . . . . . . . . . . . . . . . . . . . 21
- 6.8 Retrieving File Attributes . . . . . . . . . . . . . . . . 22
- 6.9 Setting File Attributes . . . . . . . . . . . . . . . . . 23
- 6.10 Dealing with Symbolic links . . . . . . . . . . . . . . . 24
- 6.11 Canonicalizing the Server-Side Path Name . . . . . . . . . 25
- 6.11.1 Best practice for dealing with paths . . . . . . . . . . . 25
- 7. Responses from the Server to the Client . . . . . . . . . 26
- 8. Vendor-Specific Extensions . . . . . . . . . . . . . . . . 30
- 9. Security Considerations . . . . . . . . . . . . . . . . . 31
- 10. Changes from previous protocol versions . . . . . . . . . 32
- 10.1 Changes between versions 4 and 3 . . . . . . . . . . . . . 32
- 10.2 Changes between versions 3 and 2 . . . . . . . . . . . . . 33
- 10.3 Changes between versions 2 and 1 . . . . . . . . . . . . . 33
- 10.4 Changes between versions 1 and 0 . . . . . . . . . . . . . 33
- 11. Trademark Issues . . . . . . . . . . . . . . . . . . . . . 34
- References . . . . . . . . . . . . . . . . . . . . . . . . 35
- Authors' Addresses . . . . . . . . . . . . . . . . . . . . 35
- Intellectual Property and Copyright Statements . . . . . . 37
-
-
-
-
-
-
-
-Galbraith, et al. Expires June 18, 2003 [Page 2]
-
-Internet-Draft SSH File Transfer Protocol December 2002
-
-
-1. Introduction
-
- This protocol provides secure file transfer (and more generally file
- system access) functionality over a reliable data stream, such as a
- channel in the SSH2 protocol [5].
-
- This protocol is designed so that it could be used to implement a
- secure remote file system service, as well as a secure file transfer
- service.
-
- This protocol assumes that it runs over a secure channel, and that
- the server has already authenticated the user at the client end, and
- that the identity of the client user is externally available to the
- server implementation.
-
- In general, this protocol follows a simple request-response model.
- Each request and response contains a sequence number and multiple
- requests may be pending simultaneously. There are a relatively large
- number of different request messages, but a small number of possible
- response messages. Each request has one or more response messages
- that may be returned in result (e.g., a read either returns data or
- reports error status).
-
- The packet format descriptions in this specification follow the
- notation presented in the secsh architecture draft. [5]
-
- Even though this protocol is described in the context of the SSH2
- protocol, this protocol is general and independent of the rest of the
- SSH2 protocol suite. It could be used in a number of different
- applications, such as secure file transfer over TLS RFC 2246 [1] and
- transfer of management information in VPN applications.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Galbraith, et al. Expires June 18, 2003 [Page 3]
-
-Internet-Draft SSH File Transfer Protocol December 2002
-
-
-2. Use with the SSH Connection Protocol
-
- When used with the SSH2 Protocol suite, this protocol is intended to
- be used from the SSH Connection Protocol [7] as a subsystem, as
- described in section ``Starting a Shell or a Command''. The
- subsystem name used with this protocol is "sftp".
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Galbraith, et al. Expires June 18, 2003 [Page 4]
-
-Internet-Draft SSH File Transfer Protocol December 2002
-
-
-3. General Packet Format
-
- All packets transmitted over the secure connection are of the
- following format:
-
- uint32 length
- byte type
- byte[length - 1] data payload
-
- That is, they are just data preceded by 32-bit length and 8-bit type
- fields. The `length' is the length of the data area, and does not
- include the `length' field itself. The format and interpretation of
- the data area depends on the packet type.
-
- All packet descriptions below only specify the packet type and the
- data that goes into the data field. Thus, they should be prefixed by
- the `length' and `type' fields.
-
- The maximum size of a packet is in practice determined by the client
- (the maximum size of read or write requests that it sends, plus a few
- bytes of packet overhead). All servers SHOULD support packets of at
- least 34000 bytes (where the packet size refers to the full length,
- including the header above). This should allow for reads and writes
- of at most 32768 bytes.
-
- There is no limit on the number of outstanding (non-acknowledged)
- requests that the client may send to the server. In practice this is
- limited by the buffering available on the data stream and the queuing
- performed by the server. If the server's queues are full, it should
- not read any more data from the stream, and flow control will prevent
- the client from sending more requests. Note, however, that while
- there is no restriction on the protocol level, the client's API may
- provide a limit in order to prevent infinite queuing of outgoing
- requests at the client.
-
- The following values are defined for packet types.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Galbraith, et al. Expires June 18, 2003 [Page 5]
-
-Internet-Draft SSH File Transfer Protocol December 2002
-
-
- #define SSH_FXP_INIT 1
- #define SSH_FXP_VERSION 2
- #define SSH_FXP_OPEN 3
- #define SSH_FXP_CLOSE 4
- #define SSH_FXP_READ 5
- #define SSH_FXP_WRITE 6
- #define SSH_FXP_LSTAT 7
- #define SSH_FXP_FSTAT 8
- #define SSH_FXP_SETSTAT 9
- #define SSH_FXP_FSETSTAT 10
- #define SSH_FXP_OPENDIR 11
- #define SSH_FXP_READDIR 12
- #define SSH_FXP_REMOVE 13
- #define SSH_FXP_MKDIR 14
- #define SSH_FXP_RMDIR 15
- #define SSH_FXP_REALPATH 16
- #define SSH_FXP_STAT 17
- #define SSH_FXP_RENAME 18
- #define SSH_FXP_READLINK 19
- #define SSH_FXP_SYMLINK 20
-
- #define SSH_FXP_STATUS 101
- #define SSH_FXP_HANDLE 102
- #define SSH_FXP_DATA 103
- #define SSH_FXP_NAME 104
- #define SSH_FXP_ATTRS 105
-
- #define SSH_FXP_EXTENDED 200
- #define SSH_FXP_EXTENDED_REPLY 201
-
- RESERVED_FOR_EXTENSIONS 210-255
-
- Additional packet types should only be defined if the protocol
- version number (see Section ``Protocol Initialization'') is
- incremented, and their use MUST be negotiated using the version
- number. However, the SSH_FXP_EXTENDED and SSH_FXP_EXTENDED_REPLY
- packets can be used to implement vendor-specific extensions. See
- Section ``Vendor-Specific-Extensions'' for more details.
-
-3.1 The use of stderr in the server
-
- Packets are sent and received on stdout and stdin. Data sent on
- stderr by the server SHOULD be considered debug or supplemental error
- information, and MAY be displayed to the user.
-
- For example, during initialization, there is no client request
- active, so errors or warning information cannot be sent to the client
- as part of the SFTP protocol at this early stage. However, the
-
-
-
-Galbraith, et al. Expires June 18, 2003 [Page 6]
-
-Internet-Draft SSH File Transfer Protocol December 2002
-
-
- errors or warnings MAY be sent as stderr text.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Galbraith, et al. Expires June 18, 2003 [Page 7]
-
-Internet-Draft SSH File Transfer Protocol December 2002
-
-
-4. Protocol Initialization
-
- When the file transfer protocol starts, the client first sends a
- SSH_FXP_INIT (including its version number) packet to the server.
- The server responds with a SSH_FXP_VERSION packet, supplying the
- lowest of its own and the client's version number. Both parties
- should from then on adhere to particular version of the protocol.
-
- The version number of the protocol specified in this document is 4.
- The version number should be incremented for each incompatible
- revision of this protocol.
-
-4.1 Client Initialization
-
- The SSH_FXP_INIT packet (from client to server) has the following
- data:
-
- uint32 version
-
- Version 3 of this protocol allowed clients to include extensions in
- the SSH_FXP_INIT packet; however, this can cause interoperability
- problems with version 1 and version 2 servers because the client must
- send this packet before knowing the servers version.
-
- In this version of the protocol, clients MUST use the
- SSH_FXP_EXTENDED packet to send extensions to the server after
- version exchange has completed. Clients MUST NOT include extensions
- in the version packet. This will prevent interoperability problems
- with older servers
-
-4.2 Server Initialization
-
- The SSH_FXP_VERSION packet (from server to client) has the following
- data:
-
- uint32 version
- <extension data>
-
- 'version' is the lower of the protocol version supported by the
- server and the version number received from the client.
-
- The extension data may be empty, or may be a sequence of
-
- string extension_name
- string extension_data
-
- pairs (both strings MUST always be present if one is, but the
- `extension_data' string may be of zero length). If present, these
-
-
-
-Galbraith, et al. Expires June 18, 2003 [Page 8]
-
-Internet-Draft SSH File Transfer Protocol December 2002
-
-
- strings indicate extensions to the baseline protocol. The
- `extension_name' field(s) identify the name of the extension. The
- name should be of the form "name@domain", where the domain is the DNS
- domain name of the organization defining the extension. Additional
- names that are not of this format may be defined later by the IETF.
- Implementations MUST silently ignore any extensions whose name they
- do not recognize.
-
-4.3 Determining Server Newline Convention
-
- In order to correctly process text files in a cross platform
- compatible way, the newline convention must be converted from that of
- the server to that of the client, or, during an upload, from that of
- the client to that of the server.
-
- Versions 3 and prior of this protocol made no provisions for
- processing text files. Many clients implemented some sort of
- conversion algorithm, but without either a 'canonical' on the wire
- format or knowledge of the servers newline convention, correct
- conversion was not always possible.
-
- Starting with Version 4, the SSH_FXF_TEXT file open flag (Section
- 6.3) makes it possible to request that the server translate a file to
- a 'canonical' on the wire format. This format uses \r\n as the line
- separator.
-
- Servers for systems using multiple newline characters (for example,
- Mac OS X or VMS) or systems using counted records, MUST translate to
- the canonical form.
-
- However, to ease the burden of implementation on servers that use a
- single, simple separator sequence, the following extension allows the
- canonical format to be changed.
-
- string "newline"
- string new-canonical-separator (usually "\r" or "\n" or "\r\n")
-
- All clients MUST support this extension.
-
- When processing text files, clients SHOULD NOT translate any
- character or sequence that is not an exact match of the servers
- newline separator.
-
- In particular, if the newline sequence being used is the canonical
- "\r\n" sequence, a lone \r or a lone \n SHOULD be written through
- without change.
-
-
-
-
-
-Galbraith, et al. Expires June 18, 2003 [Page 9]
-
-Internet-Draft SSH File Transfer Protocol December 2002
-
-
-5. File Attributes
-
- A new compound data type is defined for encoding file attributes.
- The same encoding is used both when returning file attributes from
- the server and when sending file attributes to the server. When
- sending it to the server, the flags field specifies which attributes
- are included, and the server will use default values for the
- remaining attributes (or will not modify the values of remaining
- attributes). When receiving attributes from the server, the flags
- specify which attributes are included in the returned data. The
- server normally returns all attributes it knows about.
-
- uint32 flags
- byte type always present
- uint64 size present only if flag SIZE
- string owner present only if flag OWNERGROUP
- string group present only if flag OWNERGROUP
- uint32 permissions present only if flag PERMISSIONS
- uint64 atime present only if flag ACCESSTIME
- uint32 atime_nseconds present only if flag SUBSECOND_TIMES
- uint64 createtime present only if flag CREATETIME
- uint32 createtime_nseconds present only if flag SUBSECOND_TIMES
- uint64 mtime present only if flag MODIFYTIME
- uint32 mtime_nseconds present only if flag SUBSECOND_TIMES
- string acl present only if flag ACL
- uint32 extended_count present only if flag EXTENDED
- string extended_type
- string extended_data
- ... more extended data (extended_type - extended_data pairs),
- so that number of pairs equals extended_count
-
-
-5.1 Flags
-
- The `flags' specify which of the fields are present. Those fields
- for which the corresponding flag is not set are not present (not
- included in the packet). New flags can only be added by incrementing
- the protocol version number (or by using the extension mechanism
- described below).
-
- The flags bits are defined to have the following values:
-
-
-
-
-
-
-
-
-
-
-Galbraith, et al. Expires June 18, 2003 [Page 10]
-
-Internet-Draft SSH File Transfer Protocol December 2002
-
-
- #define SSH_FILEXFER_ATTR_SIZE 0x00000001
- #define SSH_FILEXFER_ATTR_PERMISSIONS 0x00000040
- #define SSH_FILEXFER_ATTR_ACCESSTIME 0x00000008
- #define SSH_FILEXFER_ATTR_CREATETIME 0x00000010
- #define SSH_FILEXFER_ATTR_MODIFYTIME 0x00000020
- #define SSH_FILEXFER_ATTR_ACL 0x00000040
- #define SSH_FILEXFER_ATTR_OWNERGROUP 0x00000080
- #define SSH_FILEXFER_ATTR_SUBSECOND_TIMES 0x00000100
- #define SSH_FILEXFER_ATTR_EXTENDED 0x80000000
-
- In previous versions of this protocol flags value 0x00000002 was
- SSH_FILEXFER_ATTR_UIDGID. This value is now unused, and OWNERGROUP
- was given a new value in order to ease implementation burden.
- 0x00000002 MUST NOT appear in the mask. Some future version of this
- protocol may reuse flag 0x00000002.
-
-5.2 Type
-
- The type field is always present. The following types are defined:
-
- #define SSH_FILEXFER_TYPE_REGULAR 1
- #define SSH_FILEXFER_TYPE_DIRECTORY 2
- #define SSH_FILEXFER_TYPE_SYMLINK 3
- #define SSH_FILEXFER_TYPE_SPECIAL 4
- #define SSH_FILEXFER_TYPE_UNKNOWN 5
-
- On a POSIX system, these values would be derived from the permission
- field.
-
-5.3 Size
-
- The `size' field specifies the size of the file on disk, in bytes.
- If it is present during file creation, it should be considered a hint
- as to the files eventual size.
-
- Files opened with the SSH_FXF_TEXT flag may have a size that is
- greater or less than the value of the size field.
-
-5.4 Owner and Group
-
- The `owner' and `group' fields are represented as UTF-8 strings; this
- is the form used by NFS v4. See NFS version 4 Protocol. [3] The
- following text is selected quotations from section 5.6.
-
- To avoid a representation that is tied to a particular underlying
- implementation at the client or server, the use of UTF-8 strings has
- been chosen. The string should be of the form user@dns_domain".
- This will allow for a client and server that do not use the same
-
-
-
-Galbraith, et al. Expires June 18, 2003 [Page 11]
-
-Internet-Draft SSH File Transfer Protocol December 2002
-
-
- local representation the ability to translate to a common syntax that
- can be interpreted by both. In the case where there is no
- translation available to the client or server, the attribute value
- must be constructed without the "@". Therefore, the absence of the @
- from the owner or owner_group attribute signifies that no translation
- was available and the receiver of the attribute should not place any
- special meaning with the attribute value. Even though the attribute
- value can not be translated, it may still be useful. In the case of
- a client, the attribute string may be used for local display of
- ownership.
-
-5.5 Permissions
-
- The `permissions' field contains a bit mask of file permissions as
- defined by POSIX [1].
-
-5.6 Times
-
- The 'atime', 'createtime', and 'mtime' contain the access, creation,
- and modification times of the files, respectively. They are
- represented as seconds from Jan 1, 1970 in UTC.
-
- A negative value indicates number of seconds before Jan 1, 1970. In
- both cases, if the SSH_FILEXFER_ATTR_SUBSECOND_TIMES flag is set, the
- nseconds field is to be added to the seconds field for the final time
- representation. For example, if the time to be represented is
- one-half second before 0 hour January 1, 1970, the seconds field
- would have a value of negative one (-1) and the nseconds fields would
- have a value of one-half second (500000000). Values greater than
- 999,999,999 for nseconds are considered invalid.
-
-5.7 ACL
-
- The 'ACL' field contains an ACL similar to that defined in section
- 5.9 of NFS version 4 Protocol [3].
-
- uint32 ace-count
-
- repeated ace-count time:
- uint32 ace-type
- uint32 ace-flag
- uint32 ace-mask
- string who [UTF-8]
-
- ace-type is one of the following four values (taken from NFS Version
- 4 Protocol [3]:
-
-
-
-
-
-Galbraith, et al. Expires June 18, 2003 [Page 12]
-
-Internet-Draft SSH File Transfer Protocol December 2002
-
-
- const ACE4_ACCESS_ALLOWED_ACE_TYPE = 0x00000000;
- const ACE4_ACCESS_DENIED_ACE_TYPE = 0x00000001;
- const ACE4_SYSTEM_AUDIT_ACE_TYPE = 0x00000002;
- const ACE4_SYSTEM_ALARM_ACE_TYPE = 0x00000003;
-
- ace-flag is a combination of the following flag values. See NFS
- Version 4 Protocol [3] section 5.9.2:
-
- const ACE4_FILE_INHERIT_ACE = 0x00000001;
- const ACE4_DIRECTORY_INHERIT_ACE = 0x00000002;
- const ACE4_NO_PROPAGATE_INHERIT_ACE = 0x00000004;
- const ACE4_INHERIT_ONLY_ACE = 0x00000008;
- const ACE4_SUCCESSFUL_ACCESS_ACE_FLAG = 0x00000010;
- const ACE4_FAILED_ACCESS_ACE_FLAG = 0x00000020;
- const ACE4_IDENTIFIER_GROUP = 0x00000040;
-
- ace-mask is any combination of the following flags (taken from NFS
- Version 4 Protocol [3] section 5.9.3:
-
- const ACE4_READ_DATA = 0x00000001;
- const ACE4_LIST_DIRECTORY = 0x00000001;
- const ACE4_WRITE_DATA = 0x00000002;
- const ACE4_ADD_FILE = 0x00000002;
- const ACE4_APPEND_DATA = 0x00000004;
- const ACE4_ADD_SUBDIRECTORY = 0x00000004;
- const ACE4_READ_NAMED_ATTRS = 0x00000008;
- const ACE4_WRITE_NAMED_ATTRS = 0x00000010;
- const ACE4_EXECUTE = 0x00000020;
- const ACE4_DELETE_CHILD = 0x00000040;
- const ACE4_READ_ATTRIBUTES = 0x00000080;
- const ACE4_WRITE_ATTRIBUTES = 0x00000100;
- const ACE4_DELETE = 0x00010000;
- const ACE4_READ_ACL = 0x00020000;
- const ACE4_WRITE_ACL = 0x00040000;
- const ACE4_WRITE_OWNER = 0x00080000;
- const ACE4_SYNCHRONIZE = 0x00100000;
-
- who is a UTF-8 string of the form described in 'Owner and Group'
- (Section 5.4)
-
- Also, as per '5.9.4 ACE who' [3] there are several identifiers that
- need to be understood universally. Some of these identifiers cannot
- be understood when an client access the server, but have meaning when
- a local process accesses the file. The ability to display and modify
- these permissions is permitted over SFTP.
-
- OWNER The owner of the file.
-
-
-
-
-Galbraith, et al. Expires June 18, 2003 [Page 13]
-
-Internet-Draft SSH File Transfer Protocol December 2002
-
-
- GROUP The group associated with the file.
-
- EVERYONE The world.
-
- INTERACTIVE Accessed from an interactive terminal.
-
- NETWORK Accessed via the network.
-
- DIALUP Accessed as a dialup user to the server.
-
- BATCH Accessed from a batch job.
-
- ANONYMOUS Accessed without any authentication.
-
- AUTHENTICATED Any authenticated user (opposite of ANONYMOUS).
-
- SERVICE Access from a system service.
-
- To avoid conflict, these special identifiers are distinguish by an
- appended "@" and should appear in the form "xxxx@" (note: no domain
- name after the "@"). For example: ANONYMOUS@.
-
-5.8 Extended attributes
-
- The SSH_FILEXFER_ATTR_EXTENDED flag provides a general extension
- mechanism for vendor-specific extensions. If the flag is specified,
- then the `extended_count' field is present. It specifies the number
- of extended_type-extended_data pairs that follow. Each of these
- pairs specifies an extended attribute. For each of the attributes,
- the extended_type field should be a string of the format
- "name@domain", where "domain" is a valid, registered domain name and
- "name" identifies the method. The IETF may later standardize certain
- names that deviate from this format (e.g., that do not contain the
- "@" sign). The interpretation of `extended_data' depends on the
- type. Implementations SHOULD ignore extended data fields that they
- do not understand.
-
- Additional fields can be added to the attributes by either defining
- additional bits to the flags field to indicate their presence, or by
- defining extended attributes for them. The extended attributes
- mechanism is recommended for most purposes; additional flags bits
- should only be defined by an IETF standards action that also
- increments the protocol version number. The use of such new fields
- MUST be negotiated by the version number in the protocol exchange.
- It is a protocol error if a packet with unsupported protocol bits is
- received.
-
-
-
-
-
-Galbraith, et al. Expires June 18, 2003 [Page 14]
-
-Internet-Draft SSH File Transfer Protocol December 2002
-
-
-6. Requests From the Client to the Server
-
- Requests from the client to the server represent the various file
- system operations. Each request begins with an `id' field, which is
- a 32-bit identifier identifying the request (selected by the client).
- The same identifier will be returned in the response to the request.
- One possible implementation is a monotonically increasing request
- sequence number (modulo 2^32).
-
- Many operations in the protocol operate on open files. The
- SSH_FXP_OPEN request can return a file handle (which is an opaque
- variable-length string) which may be used to access the file later
- (e.g. in a read operation). The client MUST NOT send requests the
- server with bogus or closed handles. However, the server MUST
- perform adequate checks on the handle in order to avoid security
- risks due to fabricated handles.
-
- This design allows either stateful and stateless server
- implementation, as well as an implementation which caches state
- between requests but may also flush it. The contents of the file
- handle string are entirely up to the server and its design. The
- client should not modify or attempt to interpret the file handle
- strings.
-
- The file handle strings MUST NOT be longer than 256 bytes.
-
-6.1 Request Synchronization and Reordering
-
- The protocol and implementations MUST process requests relating to
- the same file in the order in which they are received. In other
- words, if an application submits multiple requests to the server, the
- results in the responses will be the same as if it had sent the
- requests one at a time and waited for the response in each case. For
- example, the server may process non-overlapping read/write requests
- to the same file in parallel, but overlapping reads and writes cannot
- be reordered or parallelized. However, there are no ordering
- restrictions on the server for processing requests from two different
- file transfer connections. The server may interleave and parallelize
- them at will.
-
- There are no restrictions on the order in which responses to
- outstanding requests are delivered to the client, except that the
- server must ensure fairness in the sense that processing of no
- request will be indefinitely delayed even if the client is sending
- other requests so that there are multiple outstanding requests all
- the time.
-
-
-
-
-
-Galbraith, et al. Expires June 18, 2003 [Page 15]
-
-Internet-Draft SSH File Transfer Protocol December 2002
-
-
-6.2 File Names
-
- This protocol represents file names as strings. File names are
- assumed to use the slash ('/') character as a directory separator.
-
- File names starting with a slash are "absolute", and are relative to
- the root of the file system. Names starting with any other character
- are relative to the user's default directory (home directory). Note
- that identifying the user is assumed to take place outside of this
- protocol.
-
- Servers SHOULD interpret a path name component ".." as referring to
- the parent directory, and "." as referring to the current directory.
- If the server implementation limits access to certain parts of the
- file system, it must be extra careful in parsing file names when
- enforcing such restrictions. There have been numerous reported
- security bugs where a ".." in a path name has allowed access outside
- the intended area.
-
- An empty path name is valid, and it refers to the user's default
- directory (usually the user's home directory).
-
- Otherwise, no syntax is defined for file names by this specification.
- Clients should not make any other assumptions; however, they can
- splice path name components returned by SSH_FXP_READDIR together
- using a slash ('/') as the separator, and that will work as expected.
-
- In order to comply with IETF Policy on Character Sets and Languages
- [2], all filenames are to be encoded in UTF-8. The shortest valid
- UTF-8 encoding of the UNICODE data MUST be used. The server is
- responsible for converting the UNICODE data to whatever canonical
- form it requires.
-
- For example, if the server requires that precomposed characters
- always be used, the server MUST NOT assume the filename as sent by
- the client has this attribute, but must do this normalization itself.
-
- It is understood that the lack of well-defined semantics for file
- names may cause interoperability problems between clients and servers
- using radically different operating systems. However, this approach
- is known to work acceptably with most systems, and alternative
- approaches that e.g. treat file names as sequences of structured
- components are quite complicated.
-
-6.3 Opening, Creating, and Closing Files
-
- Files are opened and created using the SSH_FXP_OPEN message, whose
- data part is as follows:
-
-
-
-Galbraith, et al. Expires June 18, 2003 [Page 16]
-
-Internet-Draft SSH File Transfer Protocol December 2002
-
-
- uint32 id
- string filename [UTF-8]
- uint32 pflags
- ATTRS attrs
-
- The `id' field is the request identifier as for all requests.
-
- The `filename' field specifies the file name. See Section ``File
- Names'' for more information.
-
- The `pflags' field is a bitmask. The following bits have been
- defined.
-
- #define SSH_FXF_READ 0x00000001
- #define SSH_FXF_WRITE 0x00000002
- #define SSH_FXF_APPEND 0x00000004
- #define SSH_FXF_CREAT 0x00000008
- #define SSH_FXF_TRUNC 0x00000010
- #define SSH_FXF_EXCL 0x00000020
- #define SSH_FXF_TEXT 0x00000040
-
- These have the following meanings:
-
- SSH_FXF_READ
- Open the file for reading.
-
- SSH_FXF_WRITE
- Open the file for writing. If both this and SSH_FXF_READ are
- specified, the file is opened for both reading and writing.
-
- SSH_FXF_APPEND
- Force all writes to append data at the end of the file. The
- offset parameter to write will be ignored.
-
- SSH_FXF_CREAT
- If this flag is specified, then a new file will be created if one
- does not already exist (if O_TRUNC is specified, the new file will
- be truncated to zero length if it previously exists).
-
- SSH_FXF_TRUNC
- Forces an existing file with the same name to be truncated to zero
- length when creating a file by specifying SSH_FXF_CREAT.
- SSH_FXF_CREAT MUST also be specified if this flag is used.
-
- SSH_FXF_EXCL
- Causes the request to fail if the named file already exists.
- SSH_FXF_CREAT MUST also be specified if this flag is used.
-
-
-
-
-Galbraith, et al. Expires June 18, 2003 [Page 17]
-
-Internet-Draft SSH File Transfer Protocol December 2002
-
-
- SSH_FXF_TEXT
- Indicates that the server should treat the file as text and
- convert it to the canonical newline convention in use. (See
- Determining Server Newline Convention. (Section 4.3)
-
- When a file is opened with the FXF_TEXT flag, the offset field in
- both the read and write function are ignored.
-
- Servers MUST correctly process multiple parallel reads and writes
- correctly in this mode. Naturally, it is permissible for them to
- do this by serializing the requests. It would not be possible for
- a client to reliably detect a server that does not implement
- parallel writes in time to prevent damage.
-
- Clients SHOULD use the SSH_FXF_APPEND flag to append data to a
- text file rather then using write with a calculated offset.
-
- To support seeks on text file the following SSH_FXP_EXTENDED
- packet is defined.
-
-
-
- string "text-seek"
- string file-handle
- uint64 line-number
-
- line-number is the index of the line number to seek to, where byte
- 0 in the file is line number 0, and the byte directly following
- the first newline sequence in the file is line number 1 and so on.
-
- The response to a "text-seek" request is an SSH_FXP_STATUS
- message.
-
- An attempt to seek past the end-of-file should result in a
- SSH_FX_EOF status.
-
- Servers SHOULD support at least one "text-seek" in order to
- support resume. However, a client MUST be prepared to receive
- SSH_FX_OP_UNSUPPORTED when attempting a "text-seek" operation.
- The client can then try a fall-back strategy, if it has one.
-
- Clients MUST be prepared to handle SSH_FX_OP_UNSUPPORTED returned
- for read or write operations that are not sequential.
-
- The `attrs' field specifies the initial attributes for the file.
- Default values will be used for those attributes that are not
- specified. See Section ``File Attributes'' for more information.
-
-
-
-
-Galbraith, et al. Expires June 18, 2003 [Page 18]
-
-Internet-Draft SSH File Transfer Protocol December 2002
-
-
- The response to this message will be either SSH_FXP_HANDLE (if the
- operation is successful) or SSH_FXP_STATUS (if the operation fails).
-
- A file is closed by using the SSH_FXP_CLOSE request. Its data field
- has the following format:
-
- uint32 id
- string handle
-
- where `id' is the request identifier, and `handle' is a handle
- previously returned in the response to SSH_FXP_OPEN or
- SSH_FXP_OPENDIR. The handle becomes invalid immediately after this
- request has been sent.
-
- The response to this request will be a SSH_FXP_STATUS message. One
- should note that on some server platforms even a close can fail.
- This can happen e.g. if the server operating system caches writes,
- and an error occurs while flushing cached writes during the close.
-
-6.4 Reading and Writing
-
- Once a file has been opened, it can be read using the following
- message:
-
- byte SSH_FXP_READ
- uint32 id
- string handle
- uint64 offset
- uint32 len
-
- where `id' is the request identifier, `handle' is an open file handle
- returned by SSH_FXP_OPEN, `offset' is the offset (in bytes) relative
- to the beginning of the file from where to start reading, and `len'
- is the maximum number of bytes to read.
-
- In response to this request, the server will read as many bytes as it
- can from the file (up to `len'), and return them in a SSH_FXP_DATA
- message. If an error occurs or EOF is encountered before reading any
- data, the server will respond with SSH_FXP_STATUS.
-
- For normal disk files, it is normally guaranteed that this will read
- the specified number of bytes, or up to end of file. However, if the
- read length is very long, the server may truncate it if it doesn't
- support packets of that length. See General Packet Format (Section
- 3).
-
- For e.g. device files this may return fewer bytes than requested.
-
-
-
-
-Galbraith, et al. Expires June 18, 2003 [Page 19]
-
-Internet-Draft SSH File Transfer Protocol December 2002
-
-
- Writing to a file is achieved using the following message:
-
- byte SSH_FXP_WRITE
- uint32 id
- string handle
- uint64 offset
- string data
-
- where `id' is a request identifier, `handle' is a file handle
- returned by SSH_FXP_OPEN, `offset' is the offset (in bytes) from the
- beginning of the file where to start writing, and `data' is the data
- to be written.
-
- The write will extend the file if writing beyond the end of the file.
- It is legal to write way beyond the end of the file; the semantics
- are to write zeroes from the end of the file to the specified offset
- and then the data. On most operating systems, such writes do not
- allocate disk space but instead leave "holes" in the file.
-
- The server responds to a write request with a SSH_FXP_STATUS message.
-
-6.5 Removing and Renaming Files
-
- Files can be removed using the SSH_FXP_REMOVE message. It has the
- following format:
-
- uint32 id
- string filename [UTF-8]
-
- where `id' is the request identifier and `filename' is the name of
- the file to be removed. See Section ``File Names'' for more
- information. This request cannot be used to remove directories.
-
- The server will respond to this request with a SSH_FXP_STATUS
- message.
-
- Files (and directories) can be renamed using the SSH_FXP_RENAME
- message. Its data is as follows:
-
- uint32 id
- string oldpath [UTF-8]
- string newpath [UTF-8]
-
- where `id' is the request identifier, `oldpath' is the name of an
- existing file or directory, and `newpath' is the new name for the
- file or directory. It is an error if there already exists a file
- with the name specified by newpath. The server may also fail rename
- requests in other situations, for example if `oldpath' and `newpath'
-
-
-
-Galbraith, et al. Expires June 18, 2003 [Page 20]
-
-Internet-Draft SSH File Transfer Protocol December 2002
-
-
- point to different file systems on the server.
-
- The server will respond to this request with a SSH_FXP_STATUS
- message.
-
-6.6 Creating and Deleting Directories
-
- New directories can be created using the SSH_FXP_MKDIR request. It
- has the following format:
-
- uint32 id
- string path [UTF-8]
- ATTRS attrs
-
- where `id' is the request identifier.
-
- `path' specifies the directory to be created. See Section ``File
- Names'' for more information on file names.
-
- `attrs' specifies the attributes that should be applied to it upon
- creation. Attributes are discussed in more detail in Section ``File
- Attributes''.
-
- The server will respond to this request with a SSH_FXP_STATUS
- message. If a file or directory with the specified path already
- exists, an error will be returned.
-
- Directories can be removed using the SSH_FXP_RMDIR request, which has
- the following format:
-
- uint32 id
- string path [UTF-8]
-
- where `id' is the request identifier, and `path' specifies the
- directory to be removed. See Section ``File Names'' for more
- information on file names.
-
- The server responds to this request with a SSH_FXP_STATUS message.
- Errors may be returned from this operation for various reasons,
- including, but not limited to, the path does not exist, the path does
- not refer to a directory object, the directory is not empty, or the
- user has insufficient access or permission to perform the requested
- operation.
-
-6.7 Scanning Directories
-
- The files in a directory can be listed using the SSH_FXP_OPENDIR and
- SSH_FXP_READDIR requests. Each SSH_FXP_READDIR request returns one
-
-
-
-Galbraith, et al. Expires June 18, 2003 [Page 21]
-
-Internet-Draft SSH File Transfer Protocol December 2002
-
-
- or more file names with full file attributes for each file. The
- client should call SSH_FXP_READDIR repeatedly until it has found the
- file it is looking for or until the server responds with a
- SSH_FXP_STATUS message indicating an error (normally SSH_FX_EOF if
- there are no more files in the directory). The client should then
- close the handle using the SSH_FXP_CLOSE request.
-
- The SSH_FXP_OPENDIR opens a directory for reading. It has the
- following format:
-
- uint32 id
- string path [UTF-8]
-
- where `id' is the request identifier and `path' is the path name of
- the directory to be listed (without any trailing slash). See Section
- ``File Names'' for more information on file names. This will return
- an error if the path does not specify a directory or if the directory
- is not readable. The server will respond to this request with either
- a SSH_FXP_HANDLE or a SSH_FXP_STATUS message.
-
- Once the directory has been successfully opened, files (and
- directories) contained in it can be listed using SSH_FXP_READDIR
- requests. These are of the format
-
- uint32 id
- string handle
-
- where `id' is the request identifier, and `handle' is a handle
- returned by SSH_FXP_OPENDIR. (It is a protocol error to attempt to
- use an ordinary file handle returned by SSH_FXP_OPEN.)
-
- The server responds to this request with either a SSH_FXP_NAME or a
- SSH_FXP_STATUS message. One or more names may be returned at a time.
- Full status information is returned for each name in order to speed
- up typical directory listings.
-
- If there are no more names available to be read, the server MUST
- respond with a SSH_FXP_STATUS message with error code of SSH_FX_EOF.
-
- When the client no longer wishes to read more names from the
- directory, it SHOULD call SSH_FXP_CLOSE for the handle. The handle
- should be closed regardless of whether an error has occurred or not.
-
-6.8 Retrieving File Attributes
-
- Very often, file attributes are automatically returned by
- SSH_FXP_READDIR. However, sometimes there is need to specifically
- retrieve the attributes for a named file. This can be done using the
-
-
-
-Galbraith, et al. Expires June 18, 2003 [Page 22]
-
-Internet-Draft SSH File Transfer Protocol December 2002
-
-
- SSH_FXP_STAT, SSH_FXP_LSTAT and SSH_FXP_FSTAT requests.
-
- SSH_FXP_STAT and SSH_FXP_LSTAT only differ in that SSH_FXP_STAT
- follows symbolic links on the server, whereas SSH_FXP_LSTAT does not
- follow symbolic links. Both have the same format:
-
- uint32 id
- string path [UTF-8]
- uint32 flags
-
- where `id' is the request identifier, and `path' specifies the file
- system object for which status is to be returned. The server
- responds to this request with either SSH_FXP_ATTRS or SSH_FXP_STATUS.
-
- The flags field specify the attribute flags in which the client has
- particular interest. This is a hint to the server. For example,
- because retrieving owner / group and acl information can be an
- expensive operation under some operating systems, the server may
- choose not to retrieve this information unless the client expresses a
- specific interest in it.
-
- The client has no guarantee the server will provide all the fields
- that it has expressed an interest in.
-
- SSH_FXP_FSTAT differs from the others in that it returns status
- information for an open file (identified by the file handle). Its
- format is as follows:
-
- uint32 id
- string handle
- uint32 flags
-
- where `id' is the request identifier and `handle' is a file handle
- returned by SSH_FXP_OPEN. The server responds to this request with
- SSH_FXP_ATTRS or SSH_FXP_STATUS.
-
-6.9 Setting File Attributes
-
- File attributes may be modified using the SSH_FXP_SETSTAT and
- SSH_FXP_FSETSTAT requests. These requests are used for operations
- such as changing the ownership, permissions or access times, as well
- as for truncating a file.
-
- The SSH_FXP_SETSTAT request is of the following format:
-
-
-
-
-
-
-
-Galbraith, et al. Expires June 18, 2003 [Page 23]
-
-Internet-Draft SSH File Transfer Protocol December 2002
-
-
- uint32 id
- string path [UTF-8]
- ATTRS attrs
-
- where `id' is the request identifier, `path' specifies the file
- system object (e.g. file or directory) whose attributes are to be
- modified, and `attrs' specifies the modifications to be made to its
- attributes. Attributes are discussed in more detail in Section
- ``File Attributes''.
-
- An error will be returned if the specified file system object does
- not exist or the user does not have sufficient rights to modify the
- specified attributes. The server responds to this request with a
- SSH_FXP_STATUS message.
-
- The SSH_FXP_FSETSTAT request modifies the attributes of a file which
- is already open. It has the following format:
-
- uint32 id
- string handle
- ATTRS attrs
-
- where `id' is the request identifier, `handle' (MUST be returned by
- SSH_FXP_OPEN) identifies the file whose attributes are to be
- modified, and `attrs' specifies the modifications to be made to its
- attributes. Attributes are discussed in more detail in Section
- ``File Attributes''. The server will respond to this request with
- SSH_FXP_STATUS.
-
-6.10 Dealing with Symbolic links
-
- The SSH_FXP_READLINK request may be used to read the target of a
- symbolic link. It would have a data part as follows:
-
- uint32 id
- string path [UTF-8]
-
- where `id' is the request identifier and `path' specifies the path
- name of the symlink to be read.
-
- The server will respond with a SSH_FXP_NAME packet containing only
- one name and a dummy attributes value. The name in the returned
- packet contains the target of the link. If an error occurs, the
- server may respond with SSH_FXP_STATUS.
-
- The SSH_FXP_SYMLINK request will create a symbolic link on the
- server. It is of the following format
-
-
-
-
-Galbraith, et al. Expires June 18, 2003 [Page 24]
-
-Internet-Draft SSH File Transfer Protocol December 2002
-
-
- uint32 id
- string linkpath [UTF-8]
- string targetpath [UTF-8]
-
- where `id' is the request identifier, `linkpath' specifies the path
- name of the symlink to be created and `targetpath' specifies the
- target of the symlink. The server shall respond with a
- SSH_FXP_STATUS indicating either success (SSH_FX_OK) or an error
- condition.
-
-6.11 Canonicalizing the Server-Side Path Name
-
- The SSH_FXP_REALPATH request can be used to have the server
- canonicalize any given path name to an absolute path. This is useful
- for converting path names containing ".." components or relative
- pathnames without a leading slash into absolute paths. The format of
- the request is as follows:
-
- uint32 id
- string path [UTF-8]
-
- where `id' is the request identifier and `path' specifies the path
- name to be canonicalized. The server will respond with a
- SSH_FXP_NAME packet containing the name in canonical form and a dummy
- attributes value. If an error occurs, the server may also respond
- with SSH_FXP_STATUS.
-
-6.11.1 Best practice for dealing with paths
-
- The client SHOULD treat the results of SSH_FXP_REALPATH as a
- canonical absolute path, even if the path does not appear to be
- absolute. A client that use REALPATH(".") and treats the result as
- absolute, even if there is no leading slash, will continue to
- function correctly, even when talking to a Windows NT or VMS style
- system, where absolute paths may not begin with a slash.
-
- For example, if the client wishes to change directory up, and the
- server has returned "c:/x/y/z" from REALPATH, the client SHOULD use
- "c:/x/y/z/..".
-
- As a second example, if the client wishes to open the file "x.txt" in
- the current directory, and server has returned "dka100:/x/y/z" as the
- canonical path of the directory, the client SHOULD open "dka100:/x/y/
- z/x.txt"
-
-
-
-
-
-
-
-Galbraith, et al. Expires June 18, 2003 [Page 25]
-
-Internet-Draft SSH File Transfer Protocol December 2002
-
-
-7. Responses from the Server to the Client
-
- The server responds to the client using one of a few response
- packets. All requests can return a SSH_FXP_STATUS response upon
- failure. When the operation is successful, any of the responses may
- be returned (depending on the operation). If no data needs to be
- returned to the client, the SSH_FXP_STATUS response with SSH_FX_OK
- status is appropriate. Otherwise, the SSH_FXP_HANDLE message is used
- to return a file handle (for SSH_FXP_OPEN and SSH_FXP_OPENDIR
- requests), SSH_FXP_DATA is used to return data from SSH_FXP_READ,
- SSH_FXP_NAME is used to return one or more file names from a
- SSH_FXP_READDIR or SSH_FXP_REALPATH request, and SSH_FXP_ATTRS is
- used to return file attributes from SSH_FXP_STAT, SSH_FXP_LSTAT, and
- SSH_FXP_FSTAT requests.
-
- Exactly one response will be returned for each request. Each
- response packet contains a request identifier which can be used to
- match each response with the corresponding request. Note that it is
- legal to have several requests outstanding simultaneously, and the
- server is allowed to send responses to them in a different order from
- the order in which the requests were sent (the result of their
- execution, however, is guaranteed to be as if they had been processed
- one at a time in the order in which the requests were sent).
-
- Response packets are of the same general format as request packets.
- Each response packet begins with the request identifier.
-
- The format of the data portion of the SSH_FXP_STATUS response is as
- follows:
-
- uint32 id
- uint32 error/status code
- string error message (ISO-10646 UTF-8 [RFC-2279])
- string language tag (as defined in [RFC-1766])
-
- where `id' is the request identifier, and `error/status code'
- indicates the result of the requested operation. The value SSH_FX_OK
- indicates success, and all other values indicate failure.
-
- Currently, the following values are defined (other values may be
- defined by future versions of this protocol):
-
-
-
-
-
-
-
-
-
-
-Galbraith, et al. Expires June 18, 2003 [Page 26]
-
-Internet-Draft SSH File Transfer Protocol December 2002
-
-
- #define SSH_FX_OK 0
- #define SSH_FX_EOF 1
- #define SSH_FX_NO_SUCH_FILE 2
- #define SSH_FX_PERMISSION_DENIED 3
- #define SSH_FX_FAILURE 4
- #define SSH_FX_BAD_MESSAGE 5
- #define SSH_FX_NO_CONNECTION 6
- #define SSH_FX_CONNECTION_LOST 7
- #define SSH_FX_OP_UNSUPPORTED 8
- #define SSH_FX_INVALID_HANDLE 9
- #define SSH_FX_NO_SUCH_PATH 10
- #define SSH_FX_FILE_ALREADY_EXISTS 11
- #define SSH_FX_WRITE_PROTECT 12
- #define SSH_FX_NO_MEDIA 13
-
- SSH_FX_OK
- Indicates successful completion of the operation.
-
- SSH_FX_EOF
- indicates end-of-file condition; for SSH_FX_READ it means that no
- more data is available in the file, and for SSH_FX_READDIR it
- indicates that no more files are contained in the directory.
-
- SSH_FX_NO_SUCH_FILE
- is returned when a reference is made to a file which does not
- exist.
-
- SSH_FX_PERMISSION_DENIED
- is returned when the authenticated user does not have sufficient
- permissions to perform the operation.
-
- SSH_FX_FAILURE
- is a generic catch-all error message; it should be returned if an
- error occurs for which there is no more specific error code
- defined.
-
- SSH_FX_BAD_MESSAGE
- may be returned if a badly formatted packet or protocol
- incompatibility is detected.
-
- SSH_FX_NO_CONNECTION
- is a pseudo-error which indicates that the client has no
- connection to the server (it can only be generated locally by the
- client, and MUST NOT be returned by servers).
-
- SSH_FX_CONNECTION_LOST
- is a pseudo-error which indicates that the connection to the
- server has been lost (it can only be generated locally by the
-
-
-
-Galbraith, et al. Expires June 18, 2003 [Page 27]
-
-Internet-Draft SSH File Transfer Protocol December 2002
-
-
- client, and MUST NOT be returned by servers).
-
- SSH_FX_OP_UNSUPPORTED
- indicates that an attempt was made to perform an operation which
- is not supported for the server (it may be generated locally by
- the client if e.g. the version number exchange indicates that a
- required feature is not supported by the server, or it may be
- returned by the server if the server does not implement an
- operation).
-
- SSH_FX_INVALID_HANDLE
- The handle value was invalid.
-
- SSH_FX_NO_SUCH_PATH
- The file path does not exist or is invalid.
-
- SSH_FX_FILE_ALREADY_EXISTS
- The file already exists.
-
- SSH_FX_WRITE_PROTECT
- The file is on read only media, or the media is write protected.
-
- SSH_FX_NO_MEDIA
- The requested operation can not be completed because there is no
- media available in the drive.
-
- The SSH_FXP_HANDLE response has the following format:
-
- uint32 id
- string handle
-
- where `id' is the request identifier, and `handle' is an arbitrary
- string that identifies an open file or directory on the server. The
- handle is opaque to the client; the client MUST NOT attempt to
- interpret or modify it in any way. The length of the handle string
- MUST NOT exceed 256 data bytes.
-
- The SSH_FXP_DATA response has the following format:
-
- uint32 id
- string data
-
- where `id' is the request identifier, and `data' is an arbitrary byte
- string containing the requested data. The data string may be at most
- the number of bytes requested in a SSH_FXP_READ request, but may also
- be shorter if end of file is reached or if the read is from something
- other than a regular file.
-
-
-
-
-Galbraith, et al. Expires June 18, 2003 [Page 28]
-
-Internet-Draft SSH File Transfer Protocol December 2002
-
-
- The SSH_FXP_NAME response has the following format:
-
- uint32 id
- uint32 count
- repeats count times:
- string filename [UTF-8]
- ATTRS attrs
-
- where `id' is the request identifier, `count' is the number of names
- returned in this response, and the remaining fields repeat `count'
- times (so that all three fields are first included for the first
- file, then for the second file, etc). In the repeated part,
- `filename' is a file name being returned (for SSH_FXP_READDIR, it
- will be a relative name within the directory, without any path
- components; for SSH_FXP_REALPATH it will be an absolute path name),
- and `attrs' is the attributes of the file as described in Section
- ``File Attributes''.
-
- The SSH_FXP_ATTRS response has the following format:
-
- uint32 id
- ATTRS attrs
-
- where `id' is the request identifier, and `attrs' is the returned
- file attributes as described in Section ``File Attributes''.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Galbraith, et al. Expires June 18, 2003 [Page 29]
-
-Internet-Draft SSH File Transfer Protocol December 2002
-
-
-8. Vendor-Specific Extensions
-
- The SSH_FXP_EXTENDED request provides a generic extension mechanism
- for adding vendor-specific commands. The request has the following
- format:
-
- uint32 id
- string extended-request
- ... any request-specific data ...
-
- where `id' is the request identifier, and `extended-request' is a
- string of the format "name@domain", where domain is an internet
- domain name of the vendor defining the request. The rest of the
- request is completely vendor-specific, and servers should only
- attempt to interpret it if they recognize the `extended-request'
- name.
-
- The server may respond to such requests using any of the response
- packets defined in Section ``Responses from the Server to the
- Client''. Additionally, the server may also respond with a
- SSH_FXP_EXTENDED_REPLY packet, as defined below. If the server does
- not recognize the `extended-request' name, then the server MUST
- respond with SSH_FXP_STATUS with error/status set to
- SSH_FX_OP_UNSUPPORTED.
-
- The SSH_FXP_EXTENDED_REPLY packet can be used to carry arbitrary
- extension-specific data from the server to the client. It is of the
- following format:
-
- uint32 id
- ... any request-specific data ...
-
- There is a range of packet types reserved for use by extensions. In
- order to avoid collision, extensions that turn on the use of
- additional packet types should determine those numbers dynamically.
-
- The suggested way of doing this is have an extension request from the
- client to the server that enables the extension; the extension
- response from the server to the client would specify the actual type
- values to use, in additional to any other data.
-
- Extension authors should be mindful of the limited range of packet
- types available (there are only 45 values available) and avoid
- requiring a new packet type where possible.
-
-
-
-
-
-
-
-Galbraith, et al. Expires June 18, 2003 [Page 30]
-
-Internet-Draft SSH File Transfer Protocol December 2002
-
-
-9. Security Considerations
-
- This protocol assumes that it is run over a secure channel and that
- the endpoints of the channel have been authenticated. Thus, this
- protocol assumes that it is externally protected from network-level
- attacks.
-
- This protocol provides file system access to arbitrary files on the
- server (only constrained by the server implementation). It is the
- responsibility of the server implementation to enforce any access
- controls that may be required to limit the access allowed for any
- particular user (the user being authenticated externally to this
- protocol, typically using the SSH User Authentication Protocol [8].
-
- Care must be taken in the server implementation to check the validity
- of received file handle strings. The server should not rely on them
- directly; it MUST check the validity of each handle before relying on
- it.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Galbraith, et al. Expires June 18, 2003 [Page 31]
-
-Internet-Draft SSH File Transfer Protocol December 2002
-
-
-10. Changes from previous protocol versions
-
- The SSH File Transfer Protocol has changed over time, before it's
- standardization. The following is a description of the incompatible
- changes between different versions.
-
-10.1 Changes between versions 4 and 3
-
- Many of the changes between version 4 and version 3 are to the
- attribute structure to make it more flexible for non-unix platforms.
-
- o Clarify the use of stderr by the server.
-
- o Clarify handling of very large read requests by the server.
-
- o Make all filenames UTF-8.
-
- o Added 'newline' extension.
-
- o Made time fields 64 bit, and optionally have nanosecond resultion.
-
- o Made file attribute owner and group strings so they can actually
- be used on disparate systems.
-
- o Added createtime field, and added separate flags for atime,
- createtime, and mtime so they can be set separately.
-
- o Split the file type out of the permissions field and into it's own
- field (which is always present.)
-
- o Added acl attribute.
-
- o Added SSH_FXF_TEXT file open flag.
-
- o Added flags field to the get stat commands so that the client can
- specifically request information the server might not normally
- included for performance reasons.
-
- o Removed the long filename from the names structure-- it can now be
- built from information available in the attrs structure.
-
- o Added reserved range of packet numbers for extensions.
-
- o Added several additional error codes.
-
-
-
-
-
-
-
-Galbraith, et al. Expires June 18, 2003 [Page 32]
-
-Internet-Draft SSH File Transfer Protocol December 2002
-
-
-10.2 Changes between versions 3 and 2
-
- o The SSH_FXP_READLINK and SSH_FXP_SYMLINK messages were added.
-
- o The SSH_FXP_EXTENDED and SSH_FXP_EXTENDED_REPLY messages were
- added.
-
- o The SSH_FXP_STATUS message was changed to include fields `error
- message' and `language tag'.
-
-
-10.3 Changes between versions 2 and 1
-
- o The SSH_FXP_RENAME message was added.
-
-
-10.4 Changes between versions 1 and 0
-
- o Implementation changes, no actual protocol changes.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Galbraith, et al. Expires June 18, 2003 [Page 33]
-
-Internet-Draft SSH File Transfer Protocol December 2002
-
-
-11. Trademark Issues
-
- "ssh" is a registered trademark of SSH Communications Security Corp
- in the United States and/or other countries.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Galbraith, et al. Expires June 18, 2003 [Page 34]
-
-Internet-Draft SSH File Transfer Protocol December 2002
-
-
-References
-
- [1] Dierks, T., Allen, C., Treese, W., Karlton, P., Freier, A. and
- P. Kocher, "The TLS Protocol Version 1.0", RFC 2246, January
- 1999.
-
- [2] Alvestrand, H., "IETF Policy on Character Sets and Languages",
- BCP 18, RFC 2277, January 1998.
-
- [3] Shepler, S., Callaghan, B., Robinson, D., Thurlow, R., Beame,
- C., Eisler, M. and D. Noveck, "NFS version 4 Protocol", RFC
- 3010, December 2000.
-
- [4] Institute of Electrical and Electronics Engineers, "Information
- Technology - Portable Operating System Interface (POSIX) - Part
- 1: System Application Program Interface (API) [C Language]",
- IEEE Standard 1003.2, 1996.
-
- [5] Rinne, T., Ylonen, T., Kivinen, T., Saarinen, M. and S.
- Lehtinen, "SSH Protocol Architecture",
- draft-ietf-secsh-architecture-13 (work in progress), September
- 2002.
-
- [6] Rinne, T., Ylonen, T., Kivinen, T., Saarinen, M. and S.
- Lehtinen, "SSH Protocol Transport Protocol",
- draft-ietf-secsh-transport-15 (work in progress), September
- 2002.
-
- [7] Rinne, T., Ylonen, T., Kivinen, T., Saarinen, M. and S.
- Lehtinen, "SSH Connection Protocol", draft-ietf-secsh-connect-16
- (work in progress), September 2002.
-
- [8] Rinne, T., Ylonen, T., Kivinen, T., Saarinen, M. and S.
- Lehtinen, "SSH Authentication Protocol",
- draft-ietf-secsh-userauth-16 (work in progress), September 2002.
-
-
-Authors' Addresses
-
- Joseph Galbraith
- VanDyke Software
- 4848 Tramway Ridge Blvd
- Suite 101
- Albuquerque, NM 87111
- US
-
- Phone: +1 505 332 5700
- EMail: galb-list@vandyke.com
-
-
-
-Galbraith, et al. Expires June 18, 2003 [Page 35]
-
-Internet-Draft SSH File Transfer Protocol December 2002
-
-
- Tatu Ylonen
- SSH Communications Security Corp
- Fredrikinkatu 42
- HELSINKI FIN-00100
- Finland
-
- EMail: ylo@ssh.com
-
-
- Sami Lehtinen
- SSH Communications Security Corp
- Fredrikinkatu 42
- HELSINKI FIN-00100
- Finland
-
- EMail: sjl@ssh.com
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Galbraith, et al. Expires June 18, 2003 [Page 36]
-
-Internet-Draft SSH File Transfer Protocol December 2002
-
-
-Intellectual Property Statement
-
- The IETF takes no position regarding the validity or scope of any
- intellectual property or other rights that might be claimed to
- pertain to the implementation or use of the technology described in
- this document or the extent to which any license under such rights
- might or might not be available; neither does it represent that it
- has made any effort to identify any such rights. Information on the
- IETF's procedures with respect to rights in standards-track and
- standards-related documentation can be found in BCP-11. Copies of
- claims of rights made available for publication and any assurances of
- licenses to be made available, or the result of an attempt made to
- obtain a general license or permission for the use of such
- proprietary rights by implementors or users of this specification can
- be obtained from the IETF Secretariat.
-
- The IETF invites any interested party to bring to its attention any
- copyrights, patents or patent applications, or other proprietary
- rights which may cover technology that may be required to practice
- this standard. Please address the information to the IETF Executive
- Director.
-
-
-Full Copyright Statement
-
- Copyright (C) The Internet Society (2002). All Rights Reserved.
-
- This document and translations of it may be copied and furnished to
- others, and derivative works that comment on or otherwise explain it
- or assist in its implementation may be prepared, copied, published
- and distributed, in whole or in part, without restriction of any
- kind, provided that the above copyright notice and this paragraph are
- included on all such copies and derivative works. However, this
- document itself may not be modified in any way, such as by removing
- the copyright notice or references to the Internet Society or other
- Internet organizations, except as needed for the purpose of
- developing Internet standards in which case the procedures for
- copyrights defined in the Internet Standards process must be
- followed, or as required to translate it into languages other than
- English.
-
- The limited permissions granted above are perpetual and will not be
- revoked by the Internet Society or its successors or assignees.
-
- This document and the information contained herein is provided on an
- "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
- TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
- BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
-
-
-
-Galbraith, et al. Expires June 18, 2003 [Page 37]
-
-Internet-Draft SSH File Transfer Protocol December 2002
-
-
- HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
- MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
-
-
-Acknowledgement
-
- Funding for the RFC Editor function is currently provided by the
- Internet Society.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Galbraith, et al. Expires June 18, 2003 [Page 38]
-
[7/9] Remove third party documents from scm
Posted by gn...@apache.org.
http://git-wip-us.apache.org/repos/asf/mina-sshd/blob/46ea0930/sshd-core/src/docs/draft-ietf-secsh-filexfer-05.txt
----------------------------------------------------------------------
diff --git a/sshd-core/src/docs/draft-ietf-secsh-filexfer-05.txt b/sshd-core/src/docs/draft-ietf-secsh-filexfer-05.txt
deleted file mode 100644
index 1677a54..0000000
--- a/sshd-core/src/docs/draft-ietf-secsh-filexfer-05.txt
+++ /dev/null
@@ -1,2802 +0,0 @@
-
-
-
-
-Secure Shell Working Group J. Galbraith
-Internet-Draft VanDyke Software
-Expires: July 1, 2004 T. Ylonen
- S. Lehtinen
- SSH Communications Security Corp
- January 2004
-
-
- SSH File Transfer Protocol
- draft-ietf-secsh-filexfer-05.txt
-
-Status of this Memo
-
- This document is an Internet-Draft and is in full conformance with
- all provisions of Section 10 of RFC2026.
-
- Internet-Drafts are working documents of the Internet Engineering
- Task Force (IETF), its areas, and its working groups. Note that other
- groups may also distribute working documents as Internet-Drafts.
-
- Internet-Drafts are draft documents valid for a maximum of six months
- and may be updated, replaced, or obsoleted by other documents at any
- time. It is inappropriate to use Internet-Drafts as reference
- material or to cite them other than as "work in progress."
-
- The list of current Internet-Drafts can be accessed at http://
- www.ietf.org/ietf/1id-abstracts.txt.
-
- The list of Internet-Draft Shadow Directories can be accessed at
- http://www.ietf.org/shadow.html.
-
- This Internet-Draft will expire on July 1, 2004.
-
-Copyright Notice
-
- Copyright (C) The Internet Society (2004). All Rights Reserved.
-
-Abstract
-
- The SSH File Transfer Protocol provides secure file transfer
- functionality over any reliable data stream. It is the standard file
- transfer protocol for use with the SSH2 protocol. This document
- describes the file transfer protocol and its interface to the SSH2
- protocol suite.
-
-
-
-
-
-
-
-
-Galbraith, et al. Expires July 1, 2004 [Page 1]
-
-Internet-Draft SSH File Transfer Protocol January 2004
-
-
-Table of Contents
-
- 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . 4
- 2. Use with the SSH Connection Protocol . . . . . . . . . . . 5
- 2.1 The Use of 'stderr' in the server . . . . . . . . . . . . 5
- 3. General Packet Format . . . . . . . . . . . . . . . . . . 6
- 3.1 Packet Types . . . . . . . . . . . . . . . . . . . . . . . 6
- 4. Protocol Initialization . . . . . . . . . . . . . . . . . 8
- 4.1 Client Initialization . . . . . . . . . . . . . . . . . . 8
- 4.2 Server Initialization . . . . . . . . . . . . . . . . . . 8
- 4.3 Determining Server Newline Convention . . . . . . . . . . 9
- 4.4 Supported Features . . . . . . . . . . . . . . . . . . . . 9
- 5. File Attributes . . . . . . . . . . . . . . . . . . . . . 12
- 5.1 valid-attribute-flags . . . . . . . . . . . . . . . . . . 12
- 5.2 Type . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
- 5.3 Size . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
- 5.4 Owner and Group . . . . . . . . . . . . . . . . . . . . . 14
- 5.5 Permissions . . . . . . . . . . . . . . . . . . . . . . . 14
- 5.6 Times . . . . . . . . . . . . . . . . . . . . . . . . . . 15
- 5.7 ACL . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
- 5.8 attrib-bits . . . . . . . . . . . . . . . . . . . . . . . 17
- 5.9 Extended Attributes . . . . . . . . . . . . . . . . . . . 19
- 6. Requests From the Client to the Server . . . . . . . . . . 20
- 6.1 Request Synchronization and Reordering . . . . . . . . . . 20
- 6.2 File Names . . . . . . . . . . . . . . . . . . . . . . . . 20
- 6.3 Opening and Closing Files and Directories . . . . . . . . 21
- 6.3.1 Opening a File . . . . . . . . . . . . . . . . . . . . . . 21
- 6.3.2 Opening a Directory . . . . . . . . . . . . . . . . . . . 25
- 6.3.3 Closing Handles . . . . . . . . . . . . . . . . . . . . . 26
- 6.4 Reading and Writing . . . . . . . . . . . . . . . . . . . 26
- 6.4.1 Reading Files . . . . . . . . . . . . . . . . . . . . . . 26
- 6.4.2 Reading Directories . . . . . . . . . . . . . . . . . . . 27
- 6.4.3 Writing Files . . . . . . . . . . . . . . . . . . . . . . 27
- 6.5 Removing and Renaming Files . . . . . . . . . . . . . . . 28
- 6.6 Creating and Deleting Directories . . . . . . . . . . . . 29
- 6.7 Retrieving File Attributes . . . . . . . . . . . . . . . . 30
- 6.8 Setting File Attributes . . . . . . . . . . . . . . . . . 30
- 6.9 Dealing with Symbolic Links . . . . . . . . . . . . . . . 31
- 6.10 Canonicalizing the Server-Side Path Name . . . . . . . . . 32
- 6.10.1 Best Practice for Dealing with Paths . . . . . . . . . . . 32
- 7. Responses from the Server to the Client . . . . . . . . . 34
- 8. Extensions . . . . . . . . . . . . . . . . . . . . . . . . 39
- 8.1 Checking File Contents . . . . . . . . . . . . . . . . . . 40
- 9. Security Considerations . . . . . . . . . . . . . . . . . 42
- 10. Changes from Previous Protocol Versions . . . . . . . . . 43
- 10.1 Changes Between Versions 5 and 4 . . . . . . . . . . . . . 43
- 10.2 Changes Between Versions 4 and 3 . . . . . . . . . . . . . 44
- 10.3 Changes Between Versions 3 and 2 . . . . . . . . . . . . . 44
-
-
-
-Galbraith, et al. Expires July 1, 2004 [Page 2]
-
-Internet-Draft SSH File Transfer Protocol January 2004
-
-
- 10.4 Changes Between Versions 2 and 1 . . . . . . . . . . . . . 45
- 10.5 Changes Between Versions 1 and 0 . . . . . . . . . . . . . 45
- 11. Trademark Issues . . . . . . . . . . . . . . . . . . . . . 46
- Normative References . . . . . . . . . . . . . . . . . . . 47
- Informative References . . . . . . . . . . . . . . . . . . 48
- Authors' Addresses . . . . . . . . . . . . . . . . . . . . 48
- Intellectual Property and Copyright Statements . . . . . . 49
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Galbraith, et al. Expires July 1, 2004 [Page 3]
-
-Internet-Draft SSH File Transfer Protocol January 2004
-
-
-1. Introduction
-
- This protocol provides secure file transfer (and more generally file
- system access.) It is designed so that it could be used to implement
- a secure remote file system service, as well as a secure file
- transfer service.
-
- This protocol assumes that it runs over a secure channel, such as a
- channel in the SSH2 protocol [3]. and that the server has already
- authenticated the client, and that the identity of the client user is
- available to the protocol.
-
- In general, this protocol follows a simple request-response model.
- Each request and response contains a sequence number and multiple
- requests may be pending simultaneously. There are a relatively large
- number of different request messages, but a small number of possible
- response messages. Each request has one or more response messages
- that may be returned in result (e.g., a read either returns data or
- reports error status).
-
- The packet format descriptions in this specification follow the
- notation presented in the secsh architecture draft. [3]
-
- Even though this protocol is described in the context of the SSH2
- protocol, this protocol is general and independent of the rest of the
- SSH2 protocol suite. It could be used in a number of different
- applications, such as secure file transfer over TLS RFC 2246 [6] and
- transfer of management information in VPN applications.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Galbraith, et al. Expires July 1, 2004 [Page 4]
-
-Internet-Draft SSH File Transfer Protocol January 2004
-
-
-2. Use with the SSH Connection Protocol
-
- When used with the SSH2 Protocol suite, this protocol is intended to
- be used from the SSH Connection Protocol [5] as a subsystem, as
- described in section ''Starting a Shell or a Command''. The subsystem
- name used with this protocol is "sftp".
-
-2.1 The Use of 'stderr' in the server
-
- This protocol uses stdout and stdin to transmit binary protocol data.
- The "session" channel SSH Connection Protocol [5], which is used by
- the subsystem, also supports the use of stderr.
-
- Data sent on stderr by the server SHOULD be considered free format
- debug or supplemental error information, and MAY be displayed to the
- user.
-
- For example, during initialization, there is no client request
- active, so errors or warning information cannot be sent to the client
- as part of the SFTP protocol at this early stage. However, the
- errors or warnings MAY be sent as stderr text.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Galbraith, et al. Expires July 1, 2004 [Page 5]
-
-Internet-Draft SSH File Transfer Protocol January 2004
-
-
-3. General Packet Format
-
- All packets transmitted over the secure connection are of the
- following format:
-
- uint32 length
- byte type
- byte[length - 1] data payload
-
- That is, they are data preceded by 32-bit length and 8-bit type
- fields. The 'length' is the length of the data area, and does not
- include the 'length' field itself. The format and interpretation of
- the data area depends on the packet type.
-
- All packet descriptions specify the packet type and the data that
- goes into the data field. Thus, they should be prefixed by the
- 'length' fields.
-
- This document defines one data type in addition to those defined in
- secsh architecture draft. [3]
-
- int64
- Represents a 64-bit signed integer. Stored as eight bytes in the
- order of decreasing significance (network byte order).
-
- The maximum size of a packet is in practice determined by the client
- (the maximum size of read or write requests that it sends, plus a few
- bytes of packet overhead). All servers SHOULD support packets of at
- least 34000 bytes (where the packet size refers to the full length,
- including the header above). This should allow for reads and writes
- of at most 32768 bytes.
-
- There is no limit on the number of outstanding (non-acknowledged)
- requests that the client may send to the server. In practice this is
- limited by the buffering available on the data stream and the queuing
- performed by the server. If the server's queues are full, it should
- not read any more data from the stream, and flow control will prevent
- the client from sending more requests. Note, however, that while
- there is no restriction on the protocol level, the client's API may
- provide a limit in order to prevent infinite queuing of outgoing
- requests at the client.
-
-3.1 Packet Types
-
- The following values are defined for packet types.
-
-
-
-
-
-
-Galbraith, et al. Expires July 1, 2004 [Page 6]
-
-Internet-Draft SSH File Transfer Protocol January 2004
-
-
- #define SSH_FXP_INIT 1
- #define SSH_FXP_VERSION 2
- #define SSH_FXP_OPEN 3
- #define SSH_FXP_CLOSE 4
- #define SSH_FXP_READ 5
- #define SSH_FXP_WRITE 6
- #define SSH_FXP_LSTAT 7
- #define SSH_FXP_FSTAT 8
- #define SSH_FXP_SETSTAT 9
- #define SSH_FXP_FSETSTAT 10
- #define SSH_FXP_OPENDIR 11
- #define SSH_FXP_READDIR 12
- #define SSH_FXP_REMOVE 13
- #define SSH_FXP_MKDIR 14
- #define SSH_FXP_RMDIR 15
- #define SSH_FXP_REALPATH 16
- #define SSH_FXP_STAT 17
- #define SSH_FXP_RENAME 18
- #define SSH_FXP_READLINK 19
- #define SSH_FXP_SYMLINK 20
-
- #define SSH_FXP_STATUS 101
- #define SSH_FXP_HANDLE 102
- #define SSH_FXP_DATA 103
- #define SSH_FXP_NAME 104
- #define SSH_FXP_ATTRS 105
-
- #define SSH_FXP_EXTENDED 200
- #define SSH_FXP_EXTENDED_REPLY 201
-
- RESERVED_FOR_EXTENSIONS 210-255
-
- Additional packet types should only be defined if the protocol
- version number (see Section ''Protocol Initialization'') is
- incremented, and their use MUST be negotiated using the version
- number. However, the SSH_FXP_EXTENDED and SSH_FXP_EXTENDED_REPLY
- packets can be used to implement extensions, which can be vendor
- specific. See Section ''Extensions'' for more details.
-
-
-
-
-
-
-
-
-
-
-
-
-
-Galbraith, et al. Expires July 1, 2004 [Page 7]
-
-Internet-Draft SSH File Transfer Protocol January 2004
-
-
-4. Protocol Initialization
-
- When the file transfer protocol starts, the client first sends a
- SSH_FXP_INIT (including its version number) packet to the server. The
- server responds with a SSH_FXP_VERSION packet, supplying the lowest
- of its own and the client's version number. Both parties should from
- then on adhere to particular version of the protocol.
-
- The version number of the protocol specified in this document is 5.
- The version number should be incremented for each incompatible
- revision of this protocol.
-
-4.1 Client Initialization
-
- The SSH_FXP_INIT packet (from client to server) has the following
- data:
-
- uint32 version
-
- Version 3 of this protocol allowed clients to include extensions in
- the SSH_FXP_INIT packet; however, this can cause interoperability
- problems with version 1 and version 2 servers because the client must
- send this packet before knowing the servers version.
-
- In this version of the protocol, clients MUST use the
- SSH_FXP_EXTENDED packet to send extensions to the server after
- version exchange has completed. Clients MUST NOT include extensions
- in the version packet. This will prevent interoperability problems
- with older servers
-
-4.2 Server Initialization
-
- The SSH_FXP_VERSION packet (from server to client) has the following
- data:
-
- uint32 version
- <extension data>
-
- 'version' is the lower of the protocol version supported by the
- server and the version number received from the client.
-
- The extension data may be empty, or may be a sequence of
-
- string extension_name
- string extension_data
-
- pairs (both strings MUST always be present if one is, but the
- 'extension_data' string may be of zero length). If present, these
-
-
-
-Galbraith, et al. Expires July 1, 2004 [Page 8]
-
-Internet-Draft SSH File Transfer Protocol January 2004
-
-
- strings indicate extensions to the baseline protocol. The
- 'extension_name' field(s) identify the name of the extension. The
- name should be of the form "name@domain", where the domain is the DNS
- domain name of the organization defining the extension. Additional
- names that are not of this format may be defined later by the IETF.
- Implementations MUST silently ignore any extensions whose name they
- do not recognize.
-
-4.3 Determining Server Newline Convention
-
- In order to correctly process text files in a cross platform
- compatible way, newline sequences must be converted between client
- and server conventions.
-
- The SSH_FXF_TEXT file open flag (Section 6.3.1) makes it possible to
- request that the server translate a file to a 'canonical' wire
- format. This format uses \r\n as the line separator.
-
- Servers for systems using multiple newline characters (for example,
- Mac OS X or VMS) or systems using counted records, MUST translate to
- the canonical form.
-
- However, to ease the burden of implementation on servers that use a
- single, simple separator sequence, the following extension allows the
- canonical format to be changed.
-
- string "newline"
- string new-canonical-separator (usually "\r" or "\n" or "\r\n")
-
- All clients MUST support this extension.
-
- When processing text files, clients SHOULD NOT translate any
- character or sequence that is not an exact match of the server's
- newline separator.
-
- In particular, if the newline sequence being used is the canonical
- "\r\n" sequence, a lone "\r" or a lone "\n" SHOULD be written through
- without change.
-
-4.4 Supported Features
-
- The sftp protocol has grown to be very rich, and now supports a
- number of features that may not be available on all servers.
-
- When a server receives a request for a feature it cannot support, it
- MUST return a SSH_FX_OP_UNSUPPORTED status code, unless otherwise
- specified. In order to facilitate clients being able to use the
- maximum available feature set, and yet not be overly burdened by
-
-
-
-Galbraith, et al. Expires July 1, 2004 [Page 9]
-
-Internet-Draft SSH File Transfer Protocol January 2004
-
-
- dealing with SSH_FX_OP_UNSUPPORTED status codes, the following
- extension is introduced.
-
- string "supported"
- string supported-structure
- uint32 supported-attribute-mask
- uint32 supported-attribute-bits
- uint32 supported-open-flags
- uint32 supported-access-mask
- uint32 max-read-size
- string extension-names[0..n]
-
- supported-attribute-mask
- This mask MAY by applied to the 'File Attributes'
- valid-attribute-flags field (Section 5.1) to ensure that no
- unsupported attributes are present during a operation which writes
- attributes.
-
- supported-attribute-bits
- This mask MAY by applied to the 'File Attributes' attrib-bits
- field (Section 5.8) to ensure that no unsupported attrib-bits are
- present during a operation which writes attributes.
-
- supported-open-flags
- The supported-open-flags mask MAY be applied to the SSH_FXP_OPEN
- (Section 6.3.1) flags field.
-
- supported-access-mask
- The supported-access-mask mask MAY be applied to the SSH_FXP_OPEN
- (Section 6.3.1) desired-access field or the ace-mask field of an
- ACL.
-
- max-read-size
- This is the maximum read size that the server gaurantees to
- complete. For example, certain embedded server implementations
- only complete the first 4K of a read, even if there is additional
- data to be read from the file.
-
- If the server specifies a non-zero value, it MUST return at least
- the max-read-size number of bytes for any read requesting
- max-read-size bytes. Failure to return max-read-size bytes in
- such a case indicates either EOF or another error condition
- occurred.
-
- extension names
- The extension names may be empty (contains zero strings), or it
- may contain any named extensions that the server wishes to
- advertise.
-
-
-
-Galbraith, et al. Expires July 1, 2004 [Page 10]
-
-Internet-Draft SSH File Transfer Protocol January 2004
-
-
- The client must be able to differentiate between attribute
- extensions (Section 5.9) and extended requests (Section 8) by the
- extension name.
-
- Naturally, if a given attribute field, attribute mask bit, open flag,
- or extension is required for correct operation, the client MUST
- either not allow the bit to be masked off, or MUST fail the operation
- gracefully without sending the request to the server.
-
- The client MAY send requests that are not supported by the server;
- however, it is not normally expected to be productive to do so. The
- client SHOULD apply the mask even to attrib structures received from
- the server. The server MAY include attributes or attrib-bits that
- are not included in the mask. Such attributes or attrib-bits are
- effectively read-only.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Galbraith, et al. Expires July 1, 2004 [Page 11]
-
-Internet-Draft SSH File Transfer Protocol January 2004
-
-
-5. File Attributes
-
- A new compound data type is defined for encoding file attributes. The
- same encoding is used both when returning file attributes from the
- server and when sending file attributes to the server.
-
- uint32 valid-attribute-flags
- byte type always present
- uint64 size present only if flag SIZE
- string owner present only if flag OWNERGROUP
- string group present only if flag OWNERGROUP
- uint32 permissions present only if flag PERMISSIONS
- int64 atime present only if flag ACCESSTIME
- uint32 atime_nseconds present only if flag SUBSECOND_TIMES
- int64 createtime present only if flag CREATETIME
- uint32 createtime_nseconds present only if flag SUBSECOND_TIMES
- int64 mtime present only if flag MODIFYTIME
- uint32 mtime_nseconds present only if flag SUBSECOND_TIMES
- string acl present only if flag ACL
- uint32 attrib-bits present only if flag BITS
- uint32 extended_count present only if flag EXTENDED
- string extended_type
- string extended_data
- ... more extended data (extended_type - extended_data pairs),
- so that number of pairs equals extended_count
-
-
-5.1 valid-attribute-flags
-
- The 'valid-attribute-flags' specifies which of the fields are
- present. Those fields for which the corresponding flag is not set are
- not present (not included in the packet).
-
- The server generally includes all attributes it knows about; however,
- it may exclude attributes that are overly expensive to retrieve
- unless the client explicitly requests them.
-
- When writing attributes, the server SHOULD NOT modify attributes that
- are not present in the structure. However, if necessary, the server
- MAY use a default value for an absent attribute.
-
- New fields can only be added by incrementing the protocol version
- number (or by using the extension mechanism described below).
-
- The following values are defined:
-
-
-
-
-
-
-Galbraith, et al. Expires July 1, 2004 [Page 12]
-
-Internet-Draft SSH File Transfer Protocol January 2004
-
-
- #define SSH_FILEXFER_ATTR_SIZE 0x00000001
- #define SSH_FILEXFER_ATTR_PERMISSIONS 0x00000004
- #define SSH_FILEXFER_ATTR_ACCESSTIME 0x00000008
- #define SSH_FILEXFER_ATTR_CREATETIME 0x00000010
- #define SSH_FILEXFER_ATTR_MODIFYTIME 0x00000020
- #define SSH_FILEXFER_ATTR_ACL 0x00000040
- #define SSH_FILEXFER_ATTR_OWNERGROUP 0x00000080
- #define SSH_FILEXFER_ATTR_SUBSECOND_TIMES 0x00000100
- #define SSH_FILEXFER_ATTR_BITS 0x00000200
- #define SSH_FILEXFER_ATTR_EXTENDED 0x80000000
-
- 0x00000002 was used in a previous version of this protocol. It is
- now a reserved value and MUST NOT appear in the mask. Some future
- version of this protocol may reuse this value.
-
-5.2 Type
-
- The type field is always present. The following types are defined:
-
- #define SSH_FILEXFER_TYPE_REGULAR 1
- #define SSH_FILEXFER_TYPE_DIRECTORY 2
- #define SSH_FILEXFER_TYPE_SYMLINK 3
- #define SSH_FILEXFER_TYPE_SPECIAL 4
- #define SSH_FILEXFER_TYPE_UNKNOWN 5
- #define SSH_FILEXFER_TYPE_SOCKET 6
- #define SSH_FILEXFER_TYPE_CHAR_DEVICE 7
- #define SSH_FILEXFER_TYPE_BLOCK_DEVICE 8
- #define SSH_FILEXFER_TYPE_FIFO 9
-
- On a POSIX system, these values would be derived from the mode field
- of the stat structure. SPECIAL should be used for files that are of
- a known type which cannot be expressed in the protocol. UNKNOWN
- should be used if the type is not known.
-
-5.3 Size
-
- The 'size' field specifies the size of the file on disk, in bytes. If
- it is present during file creation, it SHOULD be considered a hint as
- to the file's eventual size.
-
- If this field is present during a setstat operation, the file MUST be
- extended or truncated to the specified size. Clients SHOULD
- therefore be careful specifying size during a setstat operation.
-
- Files opened with the SSH_FXF_TEXT flag may have a size that is
- greater or less than the value of the size field.
-
-
-
-
-
-Galbraith, et al. Expires July 1, 2004 [Page 13]
-
-Internet-Draft SSH File Transfer Protocol January 2004
-
-
-5.4 Owner and Group
-
- The 'owner' and 'group' fields are represented as UTF-8 strings; this
- is the form used by NFS v4. See NFS version 4 Protocol [1]. The
- following text is selected quotations from section 5.6.
-
- To avoid a representation that is tied to a particular underlying
- implementation at the client or server, the use of UTF-8 strings has
- been chosen. The string should be of the form user@dns_domain". This
- will allow for a client and server that do not use the same local
- representation the ability to translate to a common syntax that can
- be interpreted by both. In the case where there is no translation
- available to the client or server, the attribute value must be
- constructed without the "@". Therefore, the absence of the @ from
- the owner or owner_group attribute signifies that no translation was
- available and the receiver of the attribute should not place any
- special meaning with the attribute value. Even though the attribute
- value cannot be translated, it may still be useful. In the case of a
- client, the attribute string may be used for local display of
- ownership.
-
- user@localhost represents a user in the context of the server.
-
- If either the owner or group field is zero length, the field should
- be considered absent, and no change should be made to that specific
- field.
-
-5.5 Permissions
-
- The 'permissions' field contains a bit mask specifying file
- permissions. These permissions correspond to the st_mode field of
- the stat structure defined by POSIX [2].
-
- This protocol uses the following values for the symbols declared in
- the posix standard.
-
- #define S_IRUSR 0000400 (octal)
- #define S_IWUSR 0000200
- #define S_IXUSR 0000100
- #define S_IRGRP 0000040
- #define S_IWGRP 0000020
- #define S_IXGRP 0000010
- #define S_IROTH 0000004
- #define S_IWOTH 0000002
- #define S_IXOTH 0000001
- #define S_ISUID 0004000
- #define S_ISGID 0002000
- #define S_ISVTX 0001000
-
-
-
-Galbraith, et al. Expires July 1, 2004 [Page 14]
-
-Internet-Draft SSH File Transfer Protocol January 2004
-
-
- Implementations MUST NOT send bits that are not defined.
-
-5.6 Times
-
- The 'atime', 'createtime', and 'mtime' contain the accesses,
- creation, and modification times of the files, respectively. They
- are represented as seconds from Jan 1, 1970 in UTC.
-
- A negative value indicates number of seconds before Jan 1, 1970. In
- both cases, if the SSH_FILEXFER_ATTR_SUBSECOND_TIMES flag is set, the
- nseconds field is to be added to the seconds field for the final time
- representation. For example, if the time to be represented is
- one-half second before 0 hour January 1, 1970, the seconds field
- would have a value of negative one (-1) and the nseconds fields would
- have a value of one-half second (500000000). Values greater than
- 999,999,999 for nseconds are considered invalid.
-
-5.7 ACL
-
- The 'ACL' field contains an ACL similar to that defined in section
- 5.9 of NFS version 4 Protocol [1].
-
- uint32 ace-count
-
- repeated ace-count time:
- uint32 ace-type
- uint32 ace-flag
- uint32 ace-mask
- string who [UTF-8]
-
- ace-type is one of the following four values (taken from NFS Version
- 4 Protocol [1]:
-
- #define ACE4_ACCESS_ALLOWED_ACE_TYPE 0x00000000;
- #define ACE4_ACCESS_DENIED_ACE_TYPE 0x00000001;
- #define ACE4_SYSTEM_AUDIT_ACE_TYPE 0x00000002;
- #define ACE4_SYSTEM_ALARM_ACE_TYPE 0x00000003;
-
- ace-flag is a combination of the following flag values. See NFS
- Version 4 Protocol [1] section 5.9.2:
-
- #define ACE4_FILE_INHERIT_ACE 0x00000001;
- #define ACE4_DIRECTORY_INHERIT_ACE 0x00000002;
- #define ACE4_NO_PROPAGATE_INHERIT_ACE 0x00000004;
- #define ACE4_INHERIT_ONLY_ACE 0x00000008;
- #define ACE4_SUCCESSFUL_ACCESS_ACE_FLAG 0x00000010;
- #define ACE4_FAILED_ACCESS_ACE_FLAG 0x00000020;
- #define ACE4_IDENTIFIER_GROUP 0x00000040;
-
-
-
-Galbraith, et al. Expires July 1, 2004 [Page 15]
-
-Internet-Draft SSH File Transfer Protocol January 2004
-
-
- ace-mask is any combination of the following flags (taken from NFS
- Version 4 Protocol [1] section 5.9.3:
-
- #define ACE4_READ_DATA 0x00000001;
- #define ACE4_LIST_DIRECTORY 0x00000001;
- #define ACE4_WRITE_DATA 0x00000002;
- #define ACE4_ADD_FILE 0x00000002;
- #define ACE4_APPEND_DATA 0x00000004;
- #define ACE4_ADD_SUBDIRECTORY 0x00000004;
- #define ACE4_READ_NAMED_ATTRS 0x00000008;
- #define ACE4_WRITE_NAMED_ATTRS 0x00000010;
- #define ACE4_EXECUTE 0x00000020;
- #define ACE4_DELETE_CHILD 0x00000040;
- #define ACE4_READ_ATTRIBUTES 0x00000080;
- #define ACE4_WRITE_ATTRIBUTES 0x00000100;
- #define ACE4_DELETE 0x00010000;
- #define ACE4_READ_ACL 0x00020000;
- #define ACE4_WRITE_ACL 0x00040000;
- #define ACE4_WRITE_OWNER 0x00080000;
- #define ACE4_SYNCHRONIZE 0x00100000;
-
- who is a UTF-8 string of the form described in 'Owner and Group'
- (Section 5.4)
-
- Also, as per '5.9.4 ACE who' [1] there are several identifiers that
- need to be understood universally. Some of these identifiers cannot
- be understood when an client access the server, but have meaning when
- a local process accesses the file. The ability to display and modify
- these permissions is permitted over SFTP.
-
- OWNER The owner of the file.
-
- GROUP The group associated with the file.
-
- EVERYONE The world.
-
- INTERACTIVE Accessed from an interactive terminal.
-
- NETWORK Accessed via the network.
-
- DIALUP Accessed as a dialup user to the server.
-
- BATCH Accessed from a batch job.
-
- ANONYMOUS Accessed without any authentication.
-
- AUTHENTICATED Any authenticated user (opposite of ANONYMOUS).
-
-
-
-
-Galbraith, et al. Expires July 1, 2004 [Page 16]
-
-Internet-Draft SSH File Transfer Protocol January 2004
-
-
- SERVICE Access from a system service.
-
- To avoid conflict, these special identifiers are distinguish by an
- appended "@". For example: ANONYMOUS@.
-
-5.8 attrib-bits
-
- These bits reflect various attributes of the file or directory on the
- server.
-
- The following attrib-bits are defined:
-
- #define SSH_FILEXFER_ATTR_FLAGS_READONLY 0x00000001
- #define SSH_FILEXFER_ATTR_FLAGS_SYSTEM 0x00000002
- #define SSH_FILEXFER_ATTR_FLAGS_HIDDEN 0x00000004
- #define SSH_FILEXFER_ATTR_FLAGS_CASE_INSENSITIVE 0x00000008
- #define SSH_FILEXFER_ATTR_FLAGS_ARCHIVE 0x00000010
- #define SSH_FILEXFER_ATTR_FLAGS_ENCRYPTED 0x00000020
- #define SSH_FILEXFER_ATTR_FLAGS_COMPRESSED 0x00000040
- #define SSH_FILEXFER_ATTR_FLAGS_SPARSE 0x00000080
- #define SSH_FILEXFER_ATTR_FLAGS_APPEND_ONLY 0x00000100
- #define SSH_FILEXFER_ATTR_FLAGS_IMMUTABLE 0x00000200
- #define SSH_FILEXFER_ATTR_FLAGS_SYNC 0x00000400
-
- SSH_FILEXFER_ATTR_FLAGS_READONLY
- Advisory, read-only bit. This bit is not part of the access
- control information on the file, but is rather an advisory field
- indicating that the file should not be written.
-
- SSH_FILEXFER_ATTR_FLAGS_SYSTEM
- The file is part of operating system.
-
- SSH_FILEXFER_ATTR_FLAGS_HIDDEN
- File SHOULD NOT be shown to user unless specifically requested.
- For example, most UNIX systems SHOULD set this bit if the filename
- begins with a 'period'. This bit may be read-only (Section 4.4).
- Most UNIX systems will not allow this to be changed.
-
- SSH_FILEXFER_ATTR_FLAGS_CASE_INSENSITIVE
- This attribute can only apply to directories. This attribute is
- always read-only, and cannot be modified. This attribute means
- that files and directory names in this directory should be
- compared without regard to case.
-
- It is recommended that where possible, the server's filesystem be
- allowed to do comparisons. For example, if a client wished to
- prompt a user before overwriting a file, it should not compare the
- new name with the previously retrieved list of names in the
-
-
-
-Galbraith, et al. Expires July 1, 2004 [Page 17]
-
-Internet-Draft SSH File Transfer Protocol January 2004
-
-
- directory. Rather, it should first try to create the new file by
- specifying SSH_FXF_CREATE_NEW flag. Then, if this fails and
- returns SSH_FX_FILE_ALREADY_EXISTS, it should prompt the user and
- then retry the create specifying SSH_FXF_CREATE_TRUNCATE.
-
- Unless otherwise specified, filenames are assumed to be case
- sensitive.
-
- SSH_FILEXFER_ATTR_FLAGS_ARCHIVE
- The file should be included in backup / archive operations.
-
- SSH_FILEXFER_ATTR_FLAGS_ENCRYPTED
- The file is encrypted.
-
- SSH_FILEXFER_ATTR_FLAGS_COMPRESSED
- The file is compressed.
-
- SSH_FILEXFER_ATTR_FLAGS_SPARSE
- The file is a sparse file; this means that file blocks that have
- not been explicitly written are not stored on disk. For example,
- if a client writes a buffer at 10 M from the beginning of the
- file, the blocks between the previous EOF marker and the 10 M
- offset would not consume physical disk space.
-
- Some server may store all files as sparse files, in which case
- this bit will be unconditionally set. Other servers may not have
- a mechanism for determining if the file is sparse, and so the file
- MAY be stored sparse even if this flag is not set.
-
- SSH_FILEXFER_ATTR_FLAGS_APPEND_ONLY
- The file can only be opened for writing in append mode.
-
- SSH_FILEXFER_ATTR_FLAGS_IMMUTABLE
- The file cannot be deleted or renamed, no hard link can be created
- to this file and no data can be written to the file.
-
- This bit implies a stronger level of protection than
- SSH_FILEXFER_ATTR_FLAGS_READONLY, the file permission mask or
- ACLs. Typically even the superuser cannot write to immutable
- files, and only the superuser can set or remove the bit.
-
- SSH_FILEXFER_ATTR_FLAGS_SYNC
- When the file is modified, the changes are written synchronously
- to the disk.
-
-
-
-
-
-
-
-Galbraith, et al. Expires July 1, 2004 [Page 18]
-
-Internet-Draft SSH File Transfer Protocol January 2004
-
-
-5.9 Extended Attributes
-
- The SSH_FILEXFER_ATTR_EXTENDED flag provides a general extension
- mechanism for the attrib structure. If the flag is specified, then
- the 'extended_count' field is present. It specifies the number of
- extended_type-extended_data pairs that follow. Each of these pairs
- specifies an extended attribute. For each of the attributes, the
- extended_type field should be a string of the format "name@domain",
- where "domain" is a valid, registered domain name and "name"
- identifies the method. The IETF may later standardize certain names
- that deviate from this format (e.g., that do not contain the "@"
- sign). The interpretation of 'extended_data' depends on the type.
- Implementations SHOULD ignore extended data fields that they do not
- understand.
-
- Additional fields can be added to the attributes by either defining
- additional bits to the flags field to indicate their presence, or by
- defining extended attributes for them. The extended attributes
- mechanism is recommended for most purposes; additional flags bits
- should only be defined by an IETF standards action that also
- increments the protocol version number. The use of such new fields
- MUST be negotiated by the version number in the protocol exchange.
- It is a protocol error if a packet with unsupported protocol bits is
- received.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Galbraith, et al. Expires July 1, 2004 [Page 19]
-
-Internet-Draft SSH File Transfer Protocol January 2004
-
-
-6. Requests From the Client to the Server
-
- Requests from the client to the server represent the various file
- system operations. Each request begins with an 'request-id' field,
- which is a 32-bit identifier identifying the request (selected by the
- client). The same identifier will be returned in the response to the
- request. One possible implementation is a monotonically increasing
- request sequence number (modulo 2^32).
-
-6.1 Request Synchronization and Reordering
-
- The protocol and implementations MUST process requests relating to
- the same file in the order in which they are received. In other
- words, if an application submits multiple requests to the server, the
- results in the responses will be the same as if it had sent the
- requests one at a time and waited for the response in each case. For
- example, the server may process non-overlapping read/write requests
- to the same file in parallel, but overlapping reads and writes cannot
- be reordered or parallelized. However, there are no ordering
- restrictions on the server for processing requests from two different
- file transfer connections. The server may interleave and parallelize
- them at will.
-
- There are no restrictions on the order in which responses to
- outstanding requests are delivered to the client, except that the
- server must ensure fairness in the sense that processing of no
- request will be indefinitely delayed even if the client is sending
- other requests so that there are multiple outstanding requests all
- the time.
-
-6.2 File Names
-
- This protocol represents file names as strings. File names are
- assumed to use the slash ('/') character as a directory separator.
-
- File names starting with a slash are "absolute", and are relative to
- the root of the file system. Names starting with any other character
- are relative to the user's default directory (home directory). Note
- that identifying the user is assumed to take place outside of this
- protocol.
-
- Servers SHOULD interpret a path name component ".." as referring to
- the parent directory, and "." as referring to the current directory.
- If the server implementation limits access to certain parts of the
- file system, it must be extra careful in parsing file names when
- enforcing such restrictions. There have been numerous reported
- security bugs where a ".." in a path name has allowed access outside
- the intended area.
-
-
-
-Galbraith, et al. Expires July 1, 2004 [Page 20]
-
-Internet-Draft SSH File Transfer Protocol January 2004
-
-
- An empty path name is valid, and it refers to the user's default
- directory (usually the user's home directory).
-
- Otherwise, no syntax is defined for file names by this specification.
- Clients should not make any other assumptions; however, they can
- splice path name components returned by SSH_FXP_READDIR together
- using a slash ('/') as the separator, and that will work as expected.
-
- In order to comply with IETF Policy on Character Sets and Languages
- [7], all filenames MUST be encoded in UTF-8. The shortest valid UTF-8
- encoding of the UNICODE data MUST be used. The server is responsible
- for converting the UNICODE data to whatever canonical form it
- requires.
-
- For example, if the server requires that precomposed characters
- always be used, the server MUST NOT assume the filename as sent by
- the client has this attribute, but must do this normalization itself.
-
- It is understood that the lack of well-defined semantics for file
- names may cause interoperability problems between clients and servers
- using radically different operating systems. However, this approach
- is known to work acceptably with most systems, and alternative
- approaches that e.g. treat file names as sequences of structured
- components are quite complicated.
-
-6.3 Opening and Closing Files and Directories
-
- Many operations in the protocol operate on open files. The
- SSH_FXP_OPEN and SSH_FXP_OPENDIR requests return a handle (which is
- an opaque, variable-length string) which may be used to access the
- file or directory later. The client MUST NOT send requests the
- server with bogus or closed handles. However, the server MUST
- perform adequate checks on the handle in order to avoid security
- risks due to fabricated handles.
-
- This design allows either stateful and stateless server
- implementation, as well as an implementation which caches state
- between requests but may also flush it. The contents of the file
- handle string are entirely up to the server and its design. The
- client should not modify or attempt to interpret the file handle
- strings.
-
- The file handle strings MUST NOT be longer than 256 bytes.
-
-6.3.1 Opening a File
-
- Files are opened and created using the SSH_FXP_OPEN message:
-
-
-
-
-Galbraith, et al. Expires July 1, 2004 [Page 21]
-
-Internet-Draft SSH File Transfer Protocol January 2004
-
-
- byte SSH_FXP_OPEN
- uint32 request-id
- string filename [UTF-8]
- uint32 desired-access
- uint32 flags
- ATTRS attrs
-
- The response to this message will be either SSH_FXP_HANDLE (if the
- operation is successful) or SSH_FXP_STATUS (if the operation fails).
-
- The 'request-id' field is the request identifier as for all requests.
-
- The 'filename' field specifies the file name. See Section ''File
- Names'' for more information.
-
- The 'desired-access' field is a bitmask containing a combination of
- values from the ace-mask flags from section 5.7.
-
- The 'flags' field controls various aspects of the operation,
- including whether or not the file is created and the kind of locking
- desired.
-
- The following 'flags' are defined:
-
- SSH_FXF_ACCESS_DISPOSITION = 0x00000007
- SSH_FXF_CREATE_NEW = 0x00000000
- SSH_FXF_CREATE_TRUNCATE = 0x00000001
- SSH_FXF_OPEN_EXISTING = 0x00000002
- SSH_FXF_OPEN_OR_CREATE = 0x00000003
- SSH_FXF_TRUNCATE_EXISTING = 0x00000004
- SSH_FXF_ACCESS_APPEND_DATA = 0x00000008
- SSH_FXF_ACCESS_APPEND_DATA_ATOMIC = 0x00000010
- SSH_FXF_ACCESS_TEXT_MODE = 0x00000020
- SSH_FXF_ACCESS_READ_LOCK = 0x00000040
- SSH_FXF_ACCESS_WRITE_LOCK = 0x00000080
- SSH_FXF_ACCESS_DELETE_LOCK = 0x00000100
-
- SSH_FXF_ACCESS_DISPOSITION
- Disposition is a 3 bit field that controls how the file is opened.
- The server MUST support these bits. Any one of the following
- enumeration is allowed:
-
- SSH_FXF_CREATE_NEW
- A new file is created; if the file already exists, the server
- MUST return status SSH_FX_FILE_ALREADY_EXISTS.
-
-
-
-
-
-
-Galbraith, et al. Expires July 1, 2004 [Page 22]
-
-Internet-Draft SSH File Transfer Protocol January 2004
-
-
- SSH_FXF_CREATE_TRUNCATE
- A new file is create; if the file already exists, it is
- truncated.
-
- SSH_FXF_OPEN_EXISTING
- An existing file is opened. If the file does not exist, the
- server MUST return SSH_FX_NO_SUCH_FILE. If a directory in the
- path does not exist, the server SHOULD return
- SSH_FX_NO_SUCH_PATH. It is also acceptable if the server
- returns SSH_FX_NO_SUCH_FILE in this case.
-
- SSH_FXF_OPEN_OR_CREATE
- If the file exists, it is opened. If the file does not exist,
- it is created.
-
- SSH_FXF_TRUNCATE_EXISTING
- An existing file is opened and truncated. If the file does not
- exist, the server MUST return the same error codes as defined
- for SSH_FXF_OPEN_EXISTING.
-
- SSH_FXF_ACCESS_APPEND_DATA
- Data is always written at the end of the file. The offset field
- of the SSH_FXP_WRITE requests are ignored.
-
- Data is not required to be appended atomically. This means that
- if multiple writers attempt to append data simultaneously, data
- from the first may be lost. However, data MAY be appended
- atomically.
-
- SSH_FXF_ACCESS_APPEND_DATA_ATOMIC
- Data is always written at the end of the file. The offset field
- of the SSH_FXP_WRITE requests are ignored.
-
- Date MUST be written atomically so that there is no chance that
- multiple appenders can collide and result in data being lost.
-
- If both append flags are specified, the server SHOULD use atomic
- append if it is available, but SHOULD use non-atomic appends
- otherwise. The server SHOULD NOT fail the request in this case.
-
- SSH_FXF_TEXT
- Indicates that the server should treat the file as text and
- convert it to the canonical newline convention in use. (See
- Determining Server Newline Convention. (Section 4.3)
-
- When a file is opened with the FXF_TEXT flag, the offset field in
- both the read and write function are ignored.
-
-
-
-
-Galbraith, et al. Expires July 1, 2004 [Page 23]
-
-Internet-Draft SSH File Transfer Protocol January 2004
-
-
- Servers MUST correctly process multiple, parallel reads and writes
- correctly in this mode. Naturally, it is permissible for them to
- do this by serializing the requests.
-
- Clients SHOULD use the SSH_FXF_ACCESS_APPEND_DATA flag to append
- data to a text file rather then using write with a calculated
- offset.
-
- To support seeks on text files the following SSH_FXP_EXTENDED
- packet is defined.
-
- string "text-seek"
- string file-handle
- uint64 line-number
-
- line-number is the index of the line number to seek to, where byte
- 0 in the file is line number 0, and the byte directly following
- the first newline sequence in the file is line number 1 and so on.
-
- The response to a "text-seek" request is an SSH_FXP_STATUS
- message.
-
- An attempt to seek past the end-of-file should result in a
- SSH_FX_EOF status.
-
- Servers SHOULD support at least one "text-seek" in order to
- support resume. However, a client MUST be prepared to receive
- SSH_FX_OP_UNSUPPORTED when attempting a "text-seek" operation.
- The client can then try a fall-back strategy, if it has one.
-
- Clients MUST be prepared to handle SSH_FX_OP_UNSUPPORTED returned
- for read or write operations that are not sequential.
-
- SSH_FXF_ACCESS_READ_LOCK
- The file should be opened with a read lock. The server MUST
- gaurantee that the client will be the exclusive reader of the file
- until the client closes the handle. If there is a conflicting lock
- the server MUST return SSH_FX_LOCK_CONFlICT. If the server cannot
- make the locking gaurantee, it MUST return SSH_FX_OP_UNSUPPORTED.
-
- SSH_FXF_ACCESS_WRITE_LOCK
- The file should be opened with a write lock. The server MUST
- gaurantee that the client will be the exclusive writer of the file
- until the client closes the handle.
-
- SSH_FXF_ACCESS_DELETE_LOCK
- The file should be opened with a delete lock. The server MUST
- gaurantee that the file will not be deleted until the client
-
-
-
-Galbraith, et al. Expires July 1, 2004 [Page 24]
-
-Internet-Draft SSH File Transfer Protocol January 2004
-
-
- closes the handle.
-
- The 'attrs' field specifies the initial attributes for the file.
- Default values MUST be supplied by the server for those attributes
- that are not specified. See Section ''File Attributes'' for more
- information.
-
- The following table is provided to assist in mapping posix semantics
- to equivalent SFTP file open parameters:
-
- O_RDONLY
- desired-access = READ_DATA|READ_ATTRIBUTES
-
- O_WRONLY
- desired-access = WRITE_DATA|WRITE_ATTRIBUTES
-
- O_RDWR
- desired-access =
- READ_DATA|READ_ATTRIBUTES|WRITE_DATA|WRITE_ATTRIBUTES
-
- O_APPEND
- desired-access = WRITE_DATA|WRITE_ATTRIBUTES|APPEND_DATA
- flags = SSH_FXF_ACCESS_APPEND_DATA and or
- SSH_FXF_ACCESS_APPEND_DATA_ATOMIC
-
- O_CREAT
- flags = SSH_FXF_OPEN_OR_CREATE
-
- O_TRUNC
- flags = SSH_FXF_TRUNCATE_EXISTING
-
- O_TRUNC|O_CREATE
- flags = SSH_FXF_CREATE_TRUNCATE
-
-
-6.3.2 Opening a Directory
-
- To enumerate a directory, the client first obtains a handle and then
- issues directory read requests. When enumeration is complete, the
- handle MUST be closed.
-
- byte SSH_FXP_OPENDIR
- uint32 request-id
- string path [UTF-8]
-
- 'request-id' is the request identifier.
-
- 'path' is the path name of the directory to be listed (without any
-
-
-
-Galbraith, et al. Expires July 1, 2004 [Page 25]
-
-Internet-Draft SSH File Transfer Protocol January 2004
-
-
- trailing slash). See Section 'File Names' for more information on
- file names.
-
- The response to this message will be either SSH_FXP_HANDLE (if the
- operation is successful) or SSH_FXP_STATUS (if the operation fails).
-
-6.3.3 Closing Handles
-
- A handle is closed using the following request.
-
- byte SSH_FXP_CLOSE
- uint32 request-id
- string handle
-
- 'request-id' is the request identifier, and 'handle' is a handle
- previously returned in the response to SSH_FXP_OPEN or
- SSH_FXP_OPENDIR. The handle becomes invalid immediately after this
- request has been sent.
-
- The response to this request will be a SSH_FXP_STATUS message. Note
- that on some server platforms even a close can fail. For example, if
- the server operating system caches writes, and an error occurs while
- flushing cached writes, the close operation may fail.
-
-6.4 Reading and Writing
-
-6.4.1 Reading Files
-
- The following request can be used to read file data:
-
- byte SSH_FXP_READ
- uint32 request-id
- string handle
- uint64 offset
- uint32 length
-
- where 'request-id' is the request identifier, 'handle' is an open
- file handle returned by SSH_FXP_OPEN, 'offset' is the offset (in
- bytes) relative to the beginning of the file from where to start
- reading, and 'length' is the maximum number of bytes to read.
-
- In response to this request, the server will read as many bytes as it
- can from the file (up to 'length'), and return them in a SSH_FXP_DATA
- message. If an error occurs or EOF is encountered before reading any
- data, the server will respond with SSH_FXP_STATUS.
-
- For normal disk files, it is normally guaranteed that this will read
- the specified number of bytes, or up to end of file. However, if the
-
-
-
-Galbraith, et al. Expires July 1, 2004 [Page 26]
-
-Internet-Draft SSH File Transfer Protocol January 2004
-
-
- read length is very long, the server may truncate it if it doesn't
- support packets of that length. See General Packet Format (Section
- 3).
-
-6.4.2 Reading Directories
-
- In order to retrieve a directory listing, the client issues one or
- more SSH_FXP_READDIR requests. In order to obtain a complete
- directory listing, the client MUST issue repeated SSH_FXP_READDIR
- requests until the server responds with an SSH_FXP_STATUS message.
-
- byte SSH_FXP_READDIR
- uint32 request-id
- string handle
-
- where 'request-id' is the request identifier, and 'handle' is a
- handle returned by SSH_FXP_OPENDIR. (It is a protocol error to
- attempt to use an ordinary file handle returned by SSH_FXP_OPEN.)
-
- The server responds to this request with either a SSH_FXP_NAME or a
- SSH_FXP_STATUS message. One or more names may be returned at a time.
- Full status information is returned for each name in order to speed
- up typical directory listings.
-
- If there are no more names available to be read, the server MUST
- respond with a SSH_FXP_STATUS message with error code of SSH_FX_EOF.
-
-6.4.3 Writing Files
-
- Writing to a file is achieved using the following message:
-
- byte SSH_FXP_WRITE
- uint32 request-id
- string handle
- uint64 offset
- string data
-
- where 'request-id' is a request identifier, 'handle' is a file handle
- returned by SSH_FXP_OPEN, 'offset' is the offset (in bytes) from the
- beginning of the file where to start writing, and 'data' is the data
- to be written.
-
- The write will extend the file if writing beyond the end of the file.
- It is legal to write to an offset that extends beyond the end of the
- file; the semantics are to write zeroes from the end of the file to
- the specified offset and then the data. On most operating systems,
- such writes do not allocate disk space but instead create a sparse
- file.
-
-
-
-Galbraith, et al. Expires July 1, 2004 [Page 27]
-
-Internet-Draft SSH File Transfer Protocol January 2004
-
-
- The server responds to a write request with a SSH_FXP_STATUS message.
-
-6.5 Removing and Renaming Files
-
- The following request can be used to remove a file:
-
- byte SSH_FXP_REMOVE
- uint32 request-id
- string filename [UTF-8]
-
- where 'request-id' is the request identifier and 'filename' is the
- name of the file to be removed. See Section ''File Names'' for more
- information. This request cannot be used to remove directories.
-
- The server will respond to this request with a SSH_FXP_STATUS
- message.
-
- Files (and directories) can be renamed using the SSH_FXP_RENAME
- message.
-
- byte SSH_FXP_RENAME
- uint32 request-id
- string oldpath [UTF-8]
- string newpath [UTF-8]
- uint32 flags
-
- where 'request-id' is the request identifier, 'oldpath' is the name
- of an existing file or directory, and 'newpath' is the new name for
- the file or directory.
-
- 'flags' is 0 or a combination of:
-
- SSH_FXP_RENAME_OVERWRITE 0x00000001
- SSH_FXP_RENAME_ATOMIC 0x00000002
- SSH_FXP_RENAME_NATIVE 0x00000004
-
- If flags does not include SSH_FXP_RENAME_OVERWRITE, and there already
- exists a file with the name specified by newpath, the server MUST
- respond with SSH_FX_FILE_ALREADY_EXISTS.
-
- If flags includes SSH_FXP_RENAME_ATOMIC, and the destination file
- already exists, it is replaced in an atomic fashion. I.e., there is
- no observable instant in time where the name does not refer to either
- the old or the new file. SSH_FXP_RENAME_ATOMIC implies
- SSH_FXP_RENAME_OVERWRITE.
-
- If flags includes SSH_FXP_RENAME_ATOMIC and the server cannot replace
- the destination in an atomic fashion, then the server MUST respond
-
-
-
-Galbraith, et al. Expires July 1, 2004 [Page 28]
-
-Internet-Draft SSH File Transfer Protocol January 2004
-
-
- with SSH_FX_OP_UNSUPPORTED.
-
- Because some servers cannot provide atomic rename, clients should
- only specify atomic rename if correct operation requires it. If
- SSH_FXP_RENAME_OVERWRITE is specified, the server MAY perform an
- atomic rename even if it is not requested.
-
- If flags includes SSH_FXP_RENAME_NATIVE, the server is free to do the
- rename operation in whatever fashion it deems appropriate. Other
- flag values are considered hints as to desired behavior, but not
- requirements.
-
- The server will respond to this request with a SSH_FXP_STATUS
- message.
-
-6.6 Creating and Deleting Directories
-
- New directories can be created using the SSH_FXP_MKDIR request. It
- has the following format:
-
- byte SSH_FXP_MKDIR
- uint32 request-id
- string path [UTF-8]
- ATTRS attrs
-
- where 'request-id' is the request identifier.
-
- 'path' specifies the directory to be created. See Section ''File
- Names'' for more information on file names.
-
- 'attrs' specifies the attributes that should be applied to it upon
- creation. Attributes are discussed in more detail in Section ''File
- Attributes''.
-
- The server will respond to this request with a SSH_FXP_STATUS
- message. If a file or directory with the specified path already
- exists, an error will be returned.
-
- Directories can be removed using the SSH_FXP_RMDIR request, which has
- the following format:
-
- byte SSH_FXP_RMDIR
- uint32 request-id
- string path [UTF-8]
-
- where 'request-id' is the request identifier, and 'path' specifies
- the directory to be removed. See Section ''File Names'' for more
- information on file names.
-
-
-
-Galbraith, et al. Expires July 1, 2004 [Page 29]
-
-Internet-Draft SSH File Transfer Protocol January 2004
-
-
- The server responds to this request with a SSH_FXP_STATUS message.
-
-6.7 Retrieving File Attributes
-
- Very often, file attributes are automatically returned by
- SSH_FXP_READDIR. However, sometimes there is need to specifically
- retrieve the attributes for a named file. This can be done using the
- SSH_FXP_STAT, SSH_FXP_LSTAT and SSH_FXP_FSTAT requests.
-
- SSH_FXP_STAT and SSH_FXP_LSTAT only differ in that SSH_FXP_STAT
- follows symbolic links on the server, whereas SSH_FXP_LSTAT does not
- follow symbolic links. Both have the same format:
-
- byte SSH_FXP_STAT or SSH_FXP_LSTAT
- uint32 request-id
- string path [UTF-8]
- uint32 flags
-
- where 'request-id' is the request identifier, and 'path' specifies
- the file system object for which status is to be returned. The
- server responds to this request with either SSH_FXP_ATTRS or
- SSH_FXP_STATUS.
-
- The flags field specify the attribute flags in which the client has
- particular interest. This is a hint to the server. For example,
- because retrieving owner / group and acl information can be an
- expensive operation under some operating systems, the server may
- choose not to retrieve this information unless the client expresses a
- specific interest in it.
-
- The client has no guarantee the server will provide all the fields
- that it has expressed an interest in.
-
- SSH_FXP_FSTAT differs from the others in that it returns status
- information for an open file (identified by the file handle).
-
- byte SSH_FXP_FSTAT
- uint32 request-id
- string handle
- uint32 flags
-
- where 'request-id' is the request identifier and 'handle' is a file
- handle returned by SSH_FXP_OPEN. The server responds to this request
- with SSH_FXP_ATTRS or SSH_FXP_STATUS.
-
-6.8 Setting File Attributes
-
- File attributes may be modified using the SSH_FXP_SETSTAT and
-
-
-
-Galbraith, et al. Expires July 1, 2004 [Page 30]
-
-Internet-Draft SSH File Transfer Protocol January 2004
-
-
- SSH_FXP_FSETSTAT requests.
-
- byte SSH_FXP_SETSTAT
- uint32 request-id
- string path [UTF-8]
- ATTRS attrs
-
-
- byte SSH_FXP_FSETSTAT
- uint32 request-id
- string handle
- ATTRS attrs
-
- request-id
- The request identifier to be returned as part of the response.
-
- path
- The file system object (e.g. file or directory) whose attributes
- are to be modified. If this object does not exist, or the user
- does not have sufficient access to write the attributes, the
- request MUST fail.
-
- handle
- The handle is a handle previously returned from a SSH_FXP_OPEN
- request which identifies the file whose attributes are to be
- modified. If the handle was not opened with sufficient access to
- write the requested attributes, the request MUST fail.
-
- attrs
- Specifies the modified attributes to be applied. Attributes are
- discussed in more detail in Section ''File Attributes''.
-
- The server will respond with a SSH_FXP_STATUS message.
-
- Because some systems must use separate system calls to set various
- attributes, it is possible that a failure response will be returned,
- but yet some of the attributes may be have been successfully
- modified. If possible, servers SHOULD avoid this situation; however,
- client MUST be aware that this is possible.
-
-6.9 Dealing with Symbolic Links
-
- The SSH_FXP_READLINK request reads the target of a symbolic link.
-
- byte SSH_FXP_READLINK
- uint32 request-id
- string path [UTF-8]
-
-
-
-
-Galbraith, et al. Expires July 1, 2004 [Page 31]
-
-Internet-Draft SSH File Transfer Protocol January 2004
-
-
- where 'request-id' is the request identifier and 'path' specifies the
- path name of the symlink to be read.
-
- The server will respond with a SSH_FXP_NAME packet containing only
- one name and a dummy attributes value. The name in the returned
- packet contains the target of the link. If an error occurs, the
- server MAY respond with SSH_FXP_STATUS.
-
- The SSH_FXP_SYMLINK request creates a symbolic link on the server.
-
- byte SSH_FXP_SYMLINK
- uint32 request-id
- string linkpath [UTF-8]
- string targetpath [UTF-8]
-
- where 'request-id' is the request identifier, 'linkpath' specifies
- the path name of the symlink to be created and 'targetpath' specifies
- the target of the symlink. The server shall respond with a
- SSH_FXP_STATUS.
-
-6.10 Canonicalizing the Server-Side Path Name
-
- The SSH_FXP_REALPATH request can be used to have the server
- canonicalize any given path name to an absolute path. This is useful
- for converting path names containing ".." components or relative
- pathnames without a leading slash into absolute paths. The format of
- the request is as follows:
-
- byte SSH_FXP_REALPATH
- uint32 request-id
- string path [UTF-8]
-
- where 'request-id' is the request identifier and 'path' specifies the
- path name to be canonicalized. The server will respond with a
- SSH_FXP_NAME packet containing the name in canonical form and a dummy
- attributes value. If an error occurs, the server may also respond
- with SSH_FXP_STATUS.
-
- The server SHOULD fail the request if the path is not present on the
- server.
-
-6.10.1 Best Practice for Dealing with Paths
-
- The client SHOULD treat the results of SSH_FXP_REALPATH as a
- canonical absolute path, even if the path does not appear to be
- absolute. A client that use REALPATH(".") and treats the result as
- absolute, even if there is no leading slash, will continue to
- function correctly, even when talking to a Windows NT or VMS style
-
-
-
-Galbraith, et al. Expires July 1, 2004 [Page 32]
-
-Internet-Draft SSH File Transfer Protocol January 2004
-
-
- system, where absolute paths may not begin with a slash.
-
- For example, if the client wishes to change directory up, and the
- server has returned "c:/x/y/z" from REALPATH, the client SHOULD use
- "c:/x/y/z/..".
-
- As a second example, if the client wishes to open the file "x.txt" in
- the current directory, and server has returned "dka100:/x/y/z" as the
- canonical path of the directory, the client SHOULD open "dka100:/x/y/
- z/x.txt"
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Galbraith, et al. Expires July 1, 2004 [Page 33]
-
-Internet-Draft SSH File Transfer Protocol January 2004
-
-
-7. Responses from the Server to the Client
-
- The server responds to the client using one of a few response
- packets. All requests can return a SSH_FXP_STATUS response upon
- failure. When the operation is successful, and no data needs to be
- returned, the SSH_FXP_STATUS response with SSH_FX_OK status is
- appropriate.
-
- Exactly one response will be returned for each request. Each
- response packet contains a request identifier which can be used to
- match each response with the corresponding request. Note that it is
- legal to have several requests outstanding simultaneously, and the
- server is allowed to send responses to them in a different order from
- the order in which the requests were sent (the result of their
- execution, however, is guaranteed to be as if they had been processed
- one at a time in the order in which the requests were sent).
-
- Response packets are of the same general format as request packets.
- Each response packet begins with the request identifier.
-
- The format of the data portion of the SSH_FXP_STATUS response is as
- follows:
-
- byte SSH_FXP_STATUS
- uint32 request-id
- uint32 error/status code
- string error message (ISO-10646 UTF-8 [RFC-2279])
- string language tag (as defined in [RFC-1766])
- <error-specific data>
-
- request-id
- The 'request-id' specified by the client in the request the server
- is responding to.
-
- error/status code
- Machine readable status code indicating the result of the request.
- Error code values are defined below. The value SSH_FX_OK
- indicates success, and all other values indicate failure.
-
- error message
- Human readable description of the error. 'language tag' specifies
- the language the error is in.
-
- <error-specific data>
- The error-specific data may be empty, or may contain additional
- information about the error. For error codes that send
- error-specific data, the format of the data is defined below.
-
-
-
-
-Galbraith, et al. Expires July 1, 2004 [Page 34]
-
-Internet-Draft SSH File Transfer Protocol January 2004
-
-
- Error codes:
-
- #define SSH_FX_OK 0
- #define SSH_FX_EOF 1
- #define SSH_FX_NO_SUCH_FILE 2
- #define SSH_FX_PERMISSION_DENIED 3
- #define SSH_FX_FAILURE 4
- #define SSH_FX_BAD_MESSAGE 5
- #define SSH_FX_NO_CONNECTION 6
- #define SSH_FX_CONNECTION_LOST 7
- #define SSH_FX_OP_UNSUPPORTED 8
- #define SSH_FX_INVALID_HANDLE 9
- #define SSH_FX_NO_SUCH_PATH 10
- #define SSH_FX_FILE_ALREADY_EXISTS 11
- #define SSH_FX_WRITE_PROTECT 12
- #define SSH_FX_NO_MEDIA 13
- #define SSH_FX_NO_SPACE_ON_FILESYSTEM 14
- #define SSH_FX_QUOTA_EXCEEDED 15
- #define SSH_FX_UNKNOWN_PRINCIPLE 16
- #define SSH_FX_LOCK_CONFlICT 17
-
- SSH_FX_OK
- Indicates successful completion of the operation.
-
- SSH_FX_EOF
- An attempt to read past the end-of-file was made; or, there are no
- more directory entries to return.
-
- SSH_FX_NO_SUCH_FILE
- A reference was made to a file which does not exist.
-
- SSH_FX_PERMISSION_DENIED
- The user does not have sufficient permissions to perform the
- operation.
-
- SSH_FX_FAILURE
- An error occured, but no specific error code exists to describe
- the failure.
-
- This error message SHOULD always have meaningful text in the the
- 'error message' field.
-
- SSH_FX_BAD_MESSAGE
- A badly formatted packet or other SFTP protocol incompatibility
- was detected.
-
-
-
-
-
-
-Galbraith, et al. Expires July 1, 2004 [Page 35]
-
-Internet-Draft SSH File Transfer Protocol January 2004
-
-
- SSH_FX_NO_CONNECTION
- There is no connection to the server. This error can only be
- generated locally, and MUST NOT be return by a server.
-
- SSH_FX_CONNECTION_LOST
- The connection to the server was lost. This error can only be
- generated locally, and MUST NOT be return by a server.
-
- SSH_FX_OP_UNSUPPORTED
- An attempted operation could not be completed by the server
- because the server does not support the operation.
-
- This error MAY be generated locally by the client if e.g. the
- version number exchange indicates that a required feature is not
- supported by the server, or it may be returned by the server if
- the server does not implement an operation).
-
- SSH_FX_INVALID_HANDLE
- The handle value was invalid.
-
- SSH_FX_NO_SUCH_PATH
- The file path does not exist or is invalid.
-
- SSH_FX_FILE_ALREADY_EXISTS
- The file already exists.
-
- SSH_FX_WRITE_PROTECT
- The file is on read-only media, or the media is write protected.
-
- SSH_FX_NO_MEDIA
- The requested operation cannot be completed because there is no
- media available in the drive.
-
- SSH_FX_NO_SPACE_ON_FILESYSTEM
- The requested operation cannot be completed because there is no
- free space on the filesystem.
-
- SSH_FX_QUOTA_EXCEEDED
- The operation cannot be completed because the it would exceed the
- users storage quota.
-
- SSH_FX_UNKNOWN_PRINCIPLE
- A principle referenced by the request (either the 'owner',
- 'group', or 'who' field of an ACL), was unknown. The error
- specific data contains the problematic names. The format is one
- or more:
-
- string unknown-name
-
-
-
-Galbraith, et al. Expires July 1, 2004 [Page 36]
-
-Internet-Draft SSH File Transfer Protocol January 2004
-
-
- Each string contains the name of a principle that was unknown.
-
- SSH_FX_LOCK_CONFlICT
- The file could not be opened because it is locked by another
- process.
-
- The SSH_FXP_HANDLE response has the following format:
-
- byte SSH_FXP_HANDLE
- uint32 request-id
- string handle
-
- where 'request-id' is the request identifier, and 'handle' is an
- arbitrary string that identifies an open file or directory on the
- server. The handle is opaque to the client; the client MUST NOT
- attempt to interpret or modify it in any way. The length of the
- handle string MUST NOT exceed 256 data bytes.
-
- The SSH_FXP_DATA response has the following format:
-
- byte SSH_FXP_DATA
- uint32 request-id
- string data
-
- where 'request-id' is the request identifier, and 'data' is an
- arbitrary byte string containing the requested data. The data string
- may be at most the number of bytes requested in a SSH_FXP_READ
- request, but may also be shorter if end of file is reached or if the
- read is from something other than a regular file.
-
- The SSH_FXP_NAME response has the following format:
-
- byte SSH_FXP_NAME
- uint32 request-id
- uint32 count
- repeats count times:
- string filename [UTF-8]
- ATTRS attrs
-
- where 'request-id' is the request identifier, 'count' is the number
- of names returned in this response, and the remaining fields repeat
- 'count' times. In the repeated part, 'filename' is a file name being
- returned (for SSH_FXP_READDIR, it will be a relative name within the
- directory, without any path components; for SSH_FXP_REALPATH it will
- be an absolute path name), and 'attrs' is the attributes of the file
- as described in Section ''File Attributes''.
-
- The SSH_FXP_ATTRS response has the following format:
-
-
-
-Galbraith, et al. Expires July 1, 2004 [Page 37]
-
-Internet-Draft SSH File Transfer Protocol January 2004
-
-
- byte SSH_FXP_ATTRS
- uint32 request-id
- ATTRS attrs
-
- where 'request-id' is the request identifier, and 'attrs' is the
- returned file attributes as described in Section ''File Attributes''.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Galbraith, et al. Expires July 1, 2004 [Page 38]
-
-Internet-Draft SSH File Transfer Protocol January 2004
-
-
-8. Extensions
-
- The SSH_FXP_EXTENDED request provides a generic extension mechanism
- for adding additional commands.
-
- byte SSH_FXP_EXTENDED
- uint32 request-id
- string extended-request
- ... any request-specific data ...
-
- request-id
- Identifier to be returned from the server with the response.
-
- extended-request
- A string naming the extension. Vendor-specific extensions have
- use the "name@domain" syntax, where domain is an internet domain
- name of the vendor defining the request.
-
- The IETF may also define extensions to the protocol. These
- extension names will not have an '@' in them.
-
- request-specific data
- The rest of the request is defined by the extension, and servers
- should only attempt to interpret it if they recognize the
- 'extended-request' name.
-
- The server may respond to such requests using any of the response
- packets defined in Section ''Responses from the Server to the
- Client''. Additionally, the server may also respond with a
- SSH_FXP_EXTENDED_REPLY packet, as defined below. If the server does
- not recognize the 'extended-request' name, then the server MUST
- respond with SSH_FXP_STATUS with error/status set to
- SSH_FX_OP_UNSUPPORTED.
-
- The SSH_FXP_EXTENDED_REPLY packet can be used to carry arbitrary
- extension-specific data from the server to the client. It is of the
- following format:
-
- byte SSH_FXP_EXTENDED_REPLY
- uint32 request-id
- ... any request-specific data ...
-
- There is a range of packet types reserved for use by extensions. In
- order to avoid collision, extensions that that use additional packet
- types should determine those numbers dynamically.
-
- The suggested way of doing this is have an extension request from the
- client to the server that enables the extension; the extension
-
-
-
-Galbraith, et al. Expires July 1, 2004 [Page 39]
-
-Internet-Draft SSH File Transfer Protocol January 2004
-
-
- response from the server to the client would specify the actual type
- values to use, in additional to any other data.
-
- Extension authors should be mindful of the limited range of packet
- types available (there are only 45 values available) and avoid
- requiring a new packet type where possible.
-
-8.1 Checking File Contents
-
- This extension allows a client to easily check if a file (or portion
- thereof) that it already has matches what is on the server.
-
- byte SSH_FXP_EXTENDED
- uint32 request-id
- string "md5-hash" / "md5-hash-handle"
- string filename / file-handle
- uint64 start-offset
- uint64 length
- string quick-check-hash
-
- filename
- Used if "md5-hash" is specified; indicates the name of the file to
- use.
-
- file-handle
- Used if "md5-hash-handle" is specified; specifies a file handle to
- read the data from. The handle MUST be a file handle, and
- ACE4_READ_DATA MUST have been included in the desired-access when
- the fail was opened.
-
- start-offset
- The starting offset of the data to hash.
-
- length
- The length of data to include in the hash. If both start-offset
- and length are zero, the entire file should be included.
-
- quick-check-hash
- The hash over the first 2048 bytes of the data range as the client
- knows it, or the entire range, if it is less than 2048 bytes.
- This allows the server to quickly check if it is worth the
- resources to hash a big file.
-
- If this is a zero length string, the client does not have the
- data, and is requesting the hash for reasons other than comparing
- with a local file. The server MAY return SSH_FX_OP_UNSUPPORTED in
- this case.
-
-
-
-
-Galbraith, et al. Expires July 1, 2004 [Page 40]
-
-Internet-Draft SSH File Transfer Protocol January 2004
-
-
- The response is either a SSH_FXP_STATUS packet, indicating an error,
- or the following extended reply packet:
-
- byte SSH_FXP_EXTENDED_REPLY
- uint32 request-id
- string "md5-hash"
- string hash
-
- If 'hash' is zero length, then the 'quick-check-hash' did not match,
- and no hash operation was preformed. Otherwise, 'hash' contains the
- hash of the entire data range (including the first 2048 bytes that
- were included in the 'quick-check-hash'.)
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Galbraith, et al. Expires July 1, 2004 [Page 41]
-
-Internet-Draft SSH File Transfer Protocol January 2004
-
-
-9. Security Considerations
-
- It is assumed that both ends of the connection have been
- authenticated and that the connection has privacy and integrity
- features. Such security issues are left to the underlying transport
- protocol, except to note that if this is not the case, an attacker
- could manipulate files on the server at will and thus wholly
- compromise the server.
-
- This protocol provides file system access to arbitrary files on the
- server (only constrained by the server implementation). It is the
- responsibility of the server implementation to enforce any access
- controls that may be required to limit the access allowed for any
- particular user (the user being authenticated externally to this
- protocol, typically using the SSH User Authentication Protocol [8].
-
- Extreme care must be used when interpreting file handle strings. In
- particular, care must be taken that a file handle string is valid in
- the context of a given SFTP session. For example, the sftp server
- daemon may have files which it has opened for its own purposes, and
- the client must not be able to access these files by specifying an
- arbitrary file handle string.
-
- The permission field of the attrib structure (Section 5.5) may
- include the SUID, SGID, and SVTX (sticky) bits. Clients should use
- extreme caution when setting these bits on either remote or local
- files. (I.e., just because a file was SUID on the remote system does
- not necessarily imply that it should be SUID on the local system.)
-
- Filesystems often contain entries for objects that are not files at
- all, but are rather devices. For example, it may be possible to
- access serial ports, tape devices, or named pipes using this
- protocol. Servers should exercise caution when granting access to
- such resources. In addition to the dangers inherent in allowing
- access to such a device, some devices may be 'slow', and could cause
- denial of service by causing the server to block for a long period of
- time while I/O is performed to such a device.
-
- Servers should take care that file-system quotas are respected for
- users. In addition, implementations should be aware that attacks may
- be possible, or facilitated, by filling a filesystem. For example,
- filling the filesystem where event logging and auditing occurs may,
- at best, cause the system to crash, or at worst, allow the attacker
- to take untraceable actions in the future.
-
- Servers should take care that filenames are in their appropriate
- canonical form, and to insure that filenames not in canonical form
- cannot be used to bypass access checks or controls.
-
-
-
-Galbraith, et al. Expires July 1, 2004 [Page 42]
-
-Internet-Draft SSH File Transfer Protocol January 2004
-
-
-10. Changes from Previous Protocol Versions
-
- The SSH File Transfer Protocol has changed over time, before its
- standardization. The following is a description of the incompatible
- changes between different versions.
-
-10.1 Changes Between Versions 5 and 4
-
- Many of the changes between version 5 and version 4 are to better
- support the changes in version 4, and to better specify error
- conditions.
-
- o Add "supported" extension to communicate features supported.
-
- o Clarify error handling when client requests unsupported feature.
- (For example, attempts to write an unsupported attribute.)
-
- o Add attrib-bits field to the attribute structure, which specifies
- a number of boolean attributes related to files and directories,
- including advisory read-only and case-sensitivity bits.
-
- o Clarify the actual bit values to be used for the permissions field
- (since posix doesn't define values) and correct the value of
- ATTR_PERMISSIONS flag.
-
- o Some reordering of sections to attempt to get a better grouping of
- related functionality.
-
- o Open request explicitly specifies the access desired for the file.
-
- o Add support for explicitly requesting file locking.
-
- o Add support for better control of the rename operation.
-
- o Add SSH_FX_NO_SPACE_ON_FILESYSTEM, SSH_FX_QUOTA_EXCEEDED, and
- SSH_FX_UNKNOWN_PRINCIPLE error codes.
-
- o Add support for error specific data. This is used by a new
- SSH_FX_UNKNOWN_PRINCIPLE error to communicate which principles are
- unknown.
-
- o Add support for retrieving md5-hash of file contents.
-
- o Update security section.
-
-
-
-
-
-
-
-Galbraith, et al. Expires July 1, 2004 [Page 43]
-
-Internet-Draft SSH File Transfer Protocol January 2004
-
-
-10.2 Changes Between Versions 4 and 3
-
- Many of the changes between version 4 and version 3 are to the
- attribute structure to make it more flexible for non-unix platforms.
-
- o Clarify the use of stderr by the server.
-
- o Clarify handling of very large read requests by the server.
-
- o Make all filenames UTF-8.
-
- o Added 'newline' extension.
-
- o Made time fields 64 bit, and optionally have nanosecond
- resolution.
-
- o Made file attribute owner and group strings so they can actually
- be used on disparate systems.
-
- o Added createtime field, and added separate flags for atime,
- createtime, and mtime so they can be set separately.
-
- o Split the file type out of the permissions field and into its own
- field (which is always present.)
-
- o Added acl attribute.
-
- o Added SSH_FXF_TEXT file open flag.
-
- o Added flags field to the get stat commands so that the client can
- specifically request information the server might not normally
- included for performance reasons.
-
- o Removed the long filename from the names structure-- it can now be
- built from information available in the attrs structure.
-
- o Added reserved range of packet numbers for extensions.
-
- o Added several additional error codes.
-
-
-10.3 Changes Between Versions 3 and 2
-
- o The SSH_FXP_READLINK and SSH_FXP_SYMLINK messages were added.
-
- o The SSH_FXP_EXTENDED and SSH_FXP_EXTENDED_REPLY messages were
- added.
-
-
-
-
-Galbraith, et al. Expires July 1, 2004 [Page 44]
-
-Internet-Draft SSH File Transfer Protocol January 2004
-
-
- o The SSH_FXP_STATUS message was changed to include fields 'error
- message' and 'language tag'.
-
-
-10.4 Changes Between Versions 2 and 1
-
- o The SSH_FXP_RENAME message was added.
-
-
-10.5 Changes Between Versions 1 and 0
-
- o Implementation changes, no actual protocol changes.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Galbraith, et al. Expires July 1, 2004 [Page 45]
-
-Internet-Draft SSH File Transfer Protocol January 2004
-
-
-11. Trademark Issues
-
- "ssh" is a registered trademark of SSH Communications Security Corp
- in the United States and/or other countries.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Galbraith, et al. Expires July 1, 2004 [Page 46]
-
-Internet-Draft SSH File Transfer Protocol January 2004
-
-
-Normative References
-
- [1] Shepler, S., Callaghan, B., Robinson, D., Thurlow, R., Beame,
- C., Eisler, M. and D. Noveck, "NFS version 4 Protocol", RFC
- 3010, December 2000.
-
- [2] Institute of Electrical and Electronics Engineers, "Information
- Technology - Portable Operating System Interface (POSIX) - Part
- 1: System Application Program Interface (API) [C Language]",
- IEEE Standard 1003.2, 1996.
-
- [3] Rinne, T., Ylonen, T., Kivinen, T., Saarinen, M. and S.
- Lehtinen, "SSH Protocol Architecture",
- draft-ietf-secsh-architecture-13 (work in progress), September
- 2002.
-
- [4] Rinne, T., Ylonen, T., Kivinen, T., Saarinen, M. and S.
- Lehtinen, "SSH Protocol Transport Protocol",
- draft-ietf-secsh-transport-15 (work in progress), September
- 2002.
-
- [5] Rinne, T., Ylonen, T., Kivinen, T., Saarinen, M. and S.
- Lehtinen, "SSH Connection Protocol", draft-ietf-secsh-connect-16
- (work in progress), September 2002.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Galbraith, et al. Expires July 1, 2004 [Page 47]
-
-Internet-Draft SSH File Transfer Protocol January 2004
-
-
-Informative References
-
- [6] Dierks, T., Allen, C., Treese, W., Karlton, P., Freier, A. and
- P. Kocher, "The TLS Protocol Version 1.0", RFC 2246, January
- 1999.
-
- [7] Alvestrand, H., "IETF Policy on Character Sets and Languages",
- BCP 18, RFC 2277, January 1998.
-
- [8] Rinne, T., Ylonen, T., Kivinen, T., Saarinen, M. and S.
- Lehtinen, "SSH Authentication Protocol",
- draft-ietf-secsh-userauth-16 (work in progress), September 2002.
-
-
-Authors' Addresses
-
- Joseph Galbraith
- VanDyke Software
- 4848 Tramway Ridge Blvd
- Suite 101
- Albuquerque, NM 87111
- US
-
- Phone: +1 505 332 5700
- EMail: galb-list@vandyke.com
-
-
- Tatu Ylonen
- SSH Communications Security Corp
- Fredrikinkatu 42
- HELSINKI FIN-00100
- Finland
-
- EMail: ylo@ssh.com
-
-
- Sami Lehtinen
- SSH Communications Security Corp
- Fredrikinkatu 42
- HELSINKI FIN-00100
- Finland
-
- EMail: sjl@ssh.com
-
-
-
-
-
-
-
-
-Galbraith, et al. Expires July 1, 2004 [Page 48]
-
-Internet-Draft SSH File Transfer Protocol January 2004
-
-
-Intellectual Property Statement
-
- The IETF takes no position regarding the validity or scope of any
- intellectual property or
<TRUNCATED>