diff options
| author | Aris Adamantiadis <aris@0xbadc0de.be> | 2006-12-10 23:13:29 +0000 |
|---|---|---|
| committer | Aris Adamantiadis <aris@0xbadc0de.be> | 2006-12-10 23:13:29 +0000 |
| commit | f159b5d817a6643a179fa12745c8f95f8873c5f7 (patch) | |
| tree | 188ab3c44395a99e77d6c697a9fd446377d7fca6 /doc | |
| parent | 129881704634914c9c1bdc838d588ee854ea6cd4 (diff) | |
| download | libssh-f159b5d817a6643a179fa12745c8f95f8873c5f7.tar.gz libssh-f159b5d817a6643a179fa12745c8f95f8873c5f7.tar.xz libssh-f159b5d817a6643a179fa12745c8f95f8873c5f7.zip | |
moved ssh drafts elsewhere (for packaging reasons)
git-svn-id: svn+ssh://svn.berlios.de/svnroot/repos/libssh/trunk@95 7dcaeef0-15fb-0310-b436-a5af3365683c
Diffstat (limited to 'doc')
21 files changed, 0 insertions, 19590 deletions
diff --git a/doc/base64.txt b/doc/base64.txt deleted file mode 100644 index 48eafabe..00000000 --- a/doc/base64.txt +++ /dev/null @@ -1,107 +0,0 @@ - The Base64 Content-Transfer-Encoding is designed to represent - arbitrary sequences of octets in a form that need not be humanly - readable. The encoding and decoding algorithms are simple, but the - encoded data are consistently only about 33 percent larger than the - unencoded data. This encoding is virtually identical to the one used - in Privacy Enhanced Mail (PEM) applications, as defined in RFC 1421. - The base64 encoding is adapted from RFC 1421, with one change: base64 - eliminates the "*" mechanism for embedded clear text. - - A 65-character subset of US-ASCII is used, enabling 6 bits to be - represented per printable character. (The extra 65th character, "=", - is used to signify a special processing function.) - - NOTE: This subset has the important property that it is - represented identically in all versions of ISO 646, including US - ASCII, and all characters in the subset are also represented - identically in all versions of EBCDIC. Other popular encodings, - such as the encoding used by the uuencode utility and the base85 - encoding specified as part of Level 2 PostScript, do not share - these properties, and thus do not fulfill the portability - requirements a binary transport encoding for mail must meet. - - The encoding process represents 24-bit groups of input bits as output - strings of 4 encoded characters. Proceeding from left to right, a - 24-bit input group is formed by concatenating 3 8-bit input groups. - These 24 bits are then treated as 4 concatenated 6-bit groups, each - of which is translated into a single digit in the base64 alphabet. - When encoding a bit stream via the base64 encoding, the bit stream - must be presumed to be ordered with the most-significant-bit first. - - That is, the first bit in the stream will be the high-order bit in - the first byte, and the eighth bit will be the low-order bit in the - first byte, and so on. - - Each 6-bit group is used as an index into an array of 64 printable - characters. The character referenced by the index is placed in the - output string. These characters, identified in Table 1, below, are - selected so as to be universally representable, and the set excludes - characters with particular significance to SMTP (e.g., ".", CR, LF) - and to the encapsulation boundaries defined in this document (e.g., - "-"). - - Table 1: The Base64 Alphabet - - Value Encoding Value Encoding Value Encoding Value Encoding - 0 A 17 R 34 i 51 z - 1 B 18 S 35 j 52 0 - 2 C 19 T 36 k 53 1 - 3 D 20 U 37 l 54 2 - 4 E 21 V 38 m 55 3 - 5 F 22 W 39 n 56 4 - 6 G 23 X 40 o 57 5 - 7 H 24 Y 41 p 58 6 - 8 I 25 Z 42 q 59 7 - 9 J 26 a 43 r 60 8 - 10 K 27 b 44 s 61 9 - 11 L 28 c 45 t 62 + - 12 M 29 d 46 u 63 / - 13 N 30 e 47 v - 14 O 31 f 48 w (pad) = - 15 P 32 g 49 x - 16 Q 33 h 50 y - The output stream (encoded bytes) must be represented in lines of no - more than 76 characters each. All line breaks or other characters - not found in Table 1 must be ignored by decoding software. In base64 - data, characters other than those in Table 1, line breaks, and other - white space probably indicate a transmission error, about which a - warning message or even a message rejection might be appropriate - under some circumstances. - - Special processing is performed if fewer than 24 bits are available - at the end of the data being encoded. A full encoding quantum is - always completed at the end of a body. When fewer than 24 input bits - are available in an input group, zero bits are added (on the right) - to form an integral number of 6-bit groups. Padding at the end of - the data is performed using the '=' character. Since all base64 - input is an integral number of octets, only the following cases can -arise: (1) the final quantum of encoding input is an integral - multiple of 24 bits; here, the final unit of encoded output will be - an integral multiple of 4 characters with no "=" padding, (2) the - final quantum of encoding input is exactly 8 bits; here, the final - unit of encoded output will be two characters followed by two "=" - padding characters, or (3) the final quantum of encoding input is - exactly 16 bits; here, the final unit of encoded output will be three - characters followed by one "=" padding character. - - Because it is used only for padding at the end of the data, the - occurrence of any '=' characters may be taken as evidence that the - end of the data has been reached (without truncation in transit). No - such assurance is possible, however, when the number of octets - transmitted was a multiple of three. - - Any characters outside of the base64 alphabet are to be ignored in - base64-encoded data. The same applies to any illegal sequence of - characters in the base64 encoding, such as "=====" - - Care must be taken to use the proper octets for line breaks if base64 - encoding is applied directly to text material that has not been - converted to canonical form. In particular, text line breaks must be - converted into CRLF sequences prior to base64 encoding. The important - thing to note is that this may be done directly by the encoder rather - than in a prior canonicalization step in some implementations. - - NOTE: There is no need to worry about quoting apparent - encapsulation boundaries within base64-encoded parts of multipart - entities because no hyphen characters are used in the base64 - encoding. diff --git a/doc/draft-ietf-secsh-agent-01.txt b/doc/draft-ietf-secsh-agent-01.txt deleted file mode 100644 index 4c67b724..00000000 --- a/doc/draft-ietf-secsh-agent-01.txt +++ /dev/null @@ -1,647 +0,0 @@ -Network Working Group Tatu Ylonen -INTERNET-DRAFT Timo J. Rinne -draft-ietf-secsh-agent-01.txt Sami Lehtinen -Expires in six months SSH Communications Security - 20 November, 2002 - - - - 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 20 November, 2002 - -Table of Contents - -1. Authentication Agent Protocol . . . . . . . . . . . . . . . . . 2 - 1.1. Packet Format . . . . . . . . . . . . . . . . . . . . . . . 2 - 1.2. Forwarding Notices . . . . . . . . . . . . . . . . . . . . . 3 - 1.3. Requesting Version Number . . . . . . . . . . . . . . . . . 3 - 1.4. Adding Keys to the Agent . . . . . . . . . . . . . . . . . . 4 - 1.5. Deleting Keys from the Agent . . . . . . . . . . . . . . . . 5 - 1.6. Deleting specific key from the Agent . . . . . . . . . . . . 5 - 1.7. Listing the Keys that the Agent Can Use . . . . . . . . . . 6 -2. Performing Private Key Operations . . . . . . . . . . . . . . . 6 - 2.1. Signing . . . . . . . . . . . . . . . . . . . . . . . . . . 7 - 2.2. Decrypting . . . . . . . . . . . . . . . . . . . . . . . . . 7 - 2.3. Secure Shell Challenge-Response Authentication . . . . . . . 7 -3. Administrative Messages . . . . . . . . . . . . . . . . . . . . 7 - 3.1. Locking and unlocking the agent . . . . . . . . . . . . . . 8 - 3.2. Miscellaneous Agent Commands . . . . . . . . . . . . . . . . 8 -4. Agent Forwarding With Secure Shell . . . . . . . . . . . . . . . 9 - 4.1. Requesting Agent Forwarding . . . . . . . . . . . . . . . . 9 - 4.2. Agent Forwarding Channels . . . . . . . . . . . . . . . . . 9 -5. Security Considerations . . . . . . . . . . . . . . . . . . . . 9 -6. Intellectual Property . . . . . . . . . . . . . . . . . . . . . 10 -7. Additional Information . . . . . . . . . . . . . . . . . . . . . 10 -8. References . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 -9. Address of Authors . . . . . . . . . . . . . . . . . . . . . . . 10 - - - -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. - -1.1. Packet Format - -All messages passed to/from the authentication agent have the following -format: - - -Tatu Ylonen, Timo J. Rinne and Sami Lehtinen [page 2] - -INTERNET-DRAFT 20 November, 2002 - - 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 - - /* 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 - -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 - - -Tatu Ylonen, Timo J. Rinne and Sami Lehtinen [page 3] - -INTERNET-DRAFT 20 November, 2002 - - (optional) - -If the agent follows this protocol, it will respond with - - byte SSH_AGENT_VERSION_RESPONSE - uint32 version number, 2 for this protocol - -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. - -1.4. Adding Keys to the Agent - -The client can add a new private key to the agent with the following -message. - - byte SSH_AGENT_ADD_KEY - string private key blob with empty passphrase - string public key and/or certificates for it - string description of the key - ... 0, 1 or several constraints follow - -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 */ - #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 - - - -Tatu Ylonen, Timo J. Rinne and Sami Lehtinen [page 4] - -INTERNET-DRAFT 20 November, 2002 - - /* 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 - -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 - #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. - - - - -Tatu Ylonen, Timo J. Rinne and Sami Lehtinen [page 5] - -INTERNET-DRAFT 20 November, 2002 - -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 -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. - - -Tatu Ylonen, Timo J. Rinne and Sami Lehtinen [page 6] - -INTERNET-DRAFT 20 November, 2002 - -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 - -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. - - - - -Tatu Ylonen, Timo J. Rinne and Sami Lehtinen [page 7] - -INTERNET-DRAFT 20 November, 2002 - -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 - ... 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. - - - -Tatu Ylonen, Timo J. Rinne and Sami Lehtinen [page 8] - -INTERNET-DRAFT 20 November, 2002 - -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. - -5. 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. - - - -Tatu Ylonen, Timo J. Rinne and Sami Lehtinen [page 9] - -INTERNET-DRAFT 20 November, 2002 - -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. - -6. 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. - -7. Additional Information - -The current document editor is: Sami Lehtinen <sjl@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 - -8. References - -[SECSH-CONNECT] Ylonen, T., et al: "Secure Shell Connection Protocol", -Internet-Draft, draft-ietf-secsh-connect-16.txt - -9. 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 - - -Tatu Ylonen, Timo J. Rinne and Sami Lehtinen [page 10] - -INTERNET-DRAFT 20 November, 2002 - - 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 11] diff --git a/doc/draft-ietf-secsh-architecture-14.txt b/doc/draft-ietf-secsh-architecture-14.txt deleted file mode 100644 index 9a7c4082..00000000 --- a/doc/draft-ietf-secsh-architecture-14.txt +++ /dev/null @@ -1,1736 +0,0 @@ - - -Network Working Group T. Ylonen -Internet-Draft T. Kivinen -Expires: January 12, 2004 SSH Communications Security Corp - M. Saarinen - University of Jyvaskyla - T. Rinne - S. Lehtinen - SSH Communications Security Corp - July 14, 2003 - - - SSH Protocol Architecture - draft-ietf-secsh-architecture-14.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 January 12, 2004. - -Copyright Notice - - Copyright (C) The Internet Society (2003). All Rights Reserved. - -Abstract - - SSH 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 - - - -Ylonen, et. al. Expires January 12, 2004 [Page 1] - -Internet-Draft SSH Protocol Architecture July 2003 - - - 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. - -Table of Contents - - 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 - 2. Specification of Requirements . . . . . . . . . . . . . . . 4 - 3. Architecture . . . . . . . . . . . . . . . . . . . . . . . . 4 - 3.1 Host Keys . . . . . . . . . . . . . . . . . . . . . . . . . 4 - 3.2 Extensibility . . . . . . . . . . . . . . . . . . . . . . . 6 - 3.3 Policy Issues . . . . . . . . . . . . . . . . . . . . . . . 6 - 3.4 Security Properties . . . . . . . . . . . . . . . . . . . . 7 - 3.5 Packet Size and Overhead . . . . . . . . . . . . . . . . . . 7 - 3.6 Localization and Character Set Support . . . . . . . . . . . 8 - 4. Data Type Representations Used in the SSH Protocols . . . . 9 - 5. Algorithm Naming . . . . . . . . . . . . . . . . . . . . . . 11 - 6. Message Numbers . . . . . . . . . . . . . . . . . . . . . . 12 - 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . 12 - 8. Security Considerations . . . . . . . . . . . . . . . . . . 13 - 8.1 Pseudo-Random Number Generation . . . . . . . . . . . . . . 13 - 8.2 Transport . . . . . . . . . . . . . . . . . . . . . . . . . 14 - 8.2.1 Confidentiality . . . . . . . . . . . . . . . . . . . . . . 14 - 8.2.2 Data Integrity . . . . . . . . . . . . . . . . . . . . . . . 17 - 8.2.3 Replay . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 - 8.2.4 Man-in-the-middle . . . . . . . . . . . . . . . . . . . . . 18 - 8.2.5 Denial-of-service . . . . . . . . . . . . . . . . . . . . . 20 - 8.2.6 Covert Channels . . . . . . . . . . . . . . . . . . . . . . 21 - 8.2.7 Forward Secrecy . . . . . . . . . . . . . . . . . . . . . . 21 - 8.3 Authentication Protocol . . . . . . . . . . . . . . . . . . 21 - 8.3.1 Weak Transport . . . . . . . . . . . . . . . . . . . . . . . 22 - 8.3.2 Debug messages . . . . . . . . . . . . . . . . . . . . . . . 22 - 8.3.3 Local security policy . . . . . . . . . . . . . . . . . . . 23 - 8.3.4 Public key authentication . . . . . . . . . . . . . . . . . 23 - 8.3.5 Password authentication . . . . . . . . . . . . . . . . . . 24 - 8.3.6 Host based authentication . . . . . . . . . . . . . . . . . 24 - 8.4 Connection protocol . . . . . . . . . . . . . . . . . . . . 24 - 8.4.1 End point security . . . . . . . . . . . . . . . . . . . . . 24 - 8.4.2 Proxy forwarding . . . . . . . . . . . . . . . . . . . . . . 24 - 8.4.3 X11 forwarding . . . . . . . . . . . . . . . . . . . . . . . 25 - 9. Intellectual Property . . . . . . . . . . . . . . . . . . . 25 - 10. Additional Information . . . . . . . . . . . . . . . . . . . 26 - References . . . . . . . . . . . . . . . . . . . . . . . . . 26 - Authors' Addresses . . . . . . . . . . . . . . . . . . . . . 29 - - - -Ylonen, et. al. Expires January 12, 2004 [Page 2] - -Internet-Draft SSH Protocol Architecture July 2003 - - - Full Copyright Statement . . . . . . . . . . . . . . . . . . 31 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Ylonen, et. al. Expires January 12, 2004 [Page 3] - -Internet-Draft SSH Protocol Architecture July 2003 - - - 1. Introduction - - 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. Specification of Requirements - - 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. They are to be interpreted as described in [RFC- - 2119]. - - 3. Architecture - - 3.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 using each REQUIRED public key algorithm - (currently DSS [FIPS-186]). - - 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 - - - -Ylonen, et. al. Expires January 12, 2004 [Page 4] - -Internet-Draft SSH Protocol Architecture July 2003 - - - 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 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 some trusted - certification authority. 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 yet, 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 [RFC-854] and rlogin [RFC-1282]). - - 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 of the public key. Such fingerprints can - easily be verified by using telephone or other external - communication channels. - - All implementations SHOULD provide an option to not accept host - - - -Ylonen, et. al. Expires January 12, 2004 [Page 5] - -Internet-Draft SSH Protocol Architecture July 2003 - - - keys that cannot be verified. - - We 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 believed to improve the overall - security of the Internet, even though it reduces the security of - the protocol in configurations where it is allowed. - - 3.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 necessary 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 drafts. See Section Algorithm Naming - (Section 5) for more information. - - 3.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 - - - -Ylonen, et. al. Expires January 12, 2004 [Page 6] - -Internet-Draft SSH Protocol Architecture July 2003 - - - 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. - 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 where the user is trying to log in - from. - 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. - - 3.4 Security Properties - - The primary goal of the SSH protocol is improved 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 wide-spread 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. - - 3.5 Packet Size and Overhead - - Some readers will worry about the increase in packet size due to - new headers, padding, and MAC. The minimum packet size is in the - order of 28 bytes (depending on negotiated algorithms). The - - - -Ylonen, et. al. Expires January 12, 2004 [Page 7] - -Internet-Draft SSH Protocol Architecture July 2003 - - - 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). - o The minimum size of the data field of an Ethernet packet is 46 - bytes [RFC-894]. 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 [RFC-1134] 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. - - 3.6 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 the data MUST be explicitly specified. In most - places, ISO 10646 with UTF-8 encoding is used [RFC-2279]. When - applicable, a field is also provided for a language tag [RFC- - 1766]. - - 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 - - - -Ylonen, et. al. Expires January 12, 2004 [Page 8] - -Internet-Draft SSH Protocol Architecture July 2003 - - - 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. - - 4. Data Type Representations Used in the SSH Protocols - byte - - A byte represents an arbitrary 8-bit value (octet) [RFC-1700]. - Fixed length data is sometimes represented as an array of - bytes, written byte[n], where n is the number of bytes in the - array. - - 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). - - - - -Ylonen, et. al. Expires January 12, 2004 [Page 9] - -Internet-Draft SSH Protocol Architecture July 2003 - - - 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 UTF8 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. - - 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 - - - -Ylonen, et. al. Expires January 12, 2004 [Page 10] - -Internet-Draft SSH Protocol Architecture July 2003 - - - zero or more names. A name MUST be non-zero length, and it - MUST NOT contain a comma (','). Context may impose additional - restrictions on the names; for example, the names in a list may - have to be valid algorithm identifier (see Algorithm Naming - below), or [RFC-1766] language tags. The order of the names in - a list may or may not be significant, also depending on the - context where the list is is used. Terminating NUL characters - are not used, neither for the individual names, nor for the - list as a whole. - - Examples: - value representation (hex) - --------------------------------------- - (), the empty 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 - - - - - 5. Algorithm Naming - - The SSH protocols refer to particular hash, encryption, integrity, - compression, and key exchange algorithms or protocols by names. - There are some standard algorithms that all implementations MUST - support. There are also algorithms that are defined in the - protocol specification but are OPTIONAL. Furthermore, it is - expected that some organizations will want to use their own - algorithms. - - In this protocol, all algorithm identifiers MUST be printable US- - ASCII non-empty strings no longer than 64 characters. Names MUST - be case-sensitive. - - There are two formats for algorithm names: - o Names that do not contain an at-sign (@) are reserved to be - assigned by IETF consensus (RFCs). Examples include `3des- - cbc', `sha-1', `hmac-sha1', and `zlib' (the quotes are not part - of the name). Names of this format MUST NOT be used without - first registering them. Registered names MUST NOT contain an - at-sign (@) or a comma (,). - o Anyone can define additional algorithms by using names in the - format name@domainname, e.g. "ourcipher-cbc@ssh.com". The - format of the part preceding the at sign is not specified; it - MUST consist of US-ASCII characters except at-sign and comma. - The part following the at-sign MUST be a valid fully qualified - internet domain name [RFC-1034] controlled by the person or - organization defining the name. It is up to each domain how it - - - -Ylonen, et. al. Expires January 12, 2004 [Page 11] - -Internet-Draft SSH Protocol Architecture July 2003 - - - manages its local namespace. - - 6. 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) - - 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 - - - - 7. IANA Considerations - - Allocation of the following types of names in the SSH protocols is - assigned by IETF consensus: - o encryption algorithm names, - o MAC algorithm names, - o public key algorithm names (public key algorithm also implies - encoding and signature/encryption capability), - o key exchange method names, and - o protocol (service) names. - - - - -Ylonen, et. al. Expires January 12, 2004 [Page 12] - -Internet-Draft SSH Protocol Architecture July 2003 - - - These names MUST be printable US-ASCII strings, and MUST NOT - contain the characters at-sign ('@'), comma (','), or whitespace - or control characters (ASCII codes 32 or less). Names are case- - sensitive, and MUST NOT be longer than 64 characters. - - Names with the at-sign ('@') in them are allocated by the owner of - DNS name after the at-sign (hierarchical allocation in [RFC- - 2343]), otherwise the same restrictions as above. - - 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 Message Numbers (Section 6)) in the - range of 0..191 should be allocated via IETF consensus; message - numbers in the 192..255 range (the "Local extensions" set) are - reserved for private use. - - 8. 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 [1] 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 [2] provides a suite of mechanisms - which can be used to authenticate the client user to the server. - Individual mechanisms specified in the in 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 [3] 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. - - 8.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 - - - -Ylonen, et. al. Expires January 12, 2004 [Page 13] - -Internet-Draft SSH Protocol Architecture July 2003 - - - 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., 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. RFC 1750 [1750] offers - suggestions for sources of random numbers and entropy. - Implementors should note the importance of entropy and the well- - meant, anecdotal warning about the difficulty in properly - implementing pseudo-random number generating functions. - - 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. - - 8.2 Transport - - 8.2.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 which have been established and accepted within the - industry. At the time of this writing, ciphers commonly in use - include 3DES, ARCFOUR, twofish, serpent and blowfish. AES has - been accepted by The published as a US Federal Information - Processing Standards [FIPS-197] and the cryptographic community as - being acceptable for this purpose as well has accepted AES. As - always, implementors and users should check current literature to - ensure that no recent vulnerabilities have been found in ciphers - used within products. Implementors 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. It's cryptographic properties are - sufficiently described in RFC 2410, 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 - - - -Ylonen, et. al. Expires January 12, 2004 [Page 14] - -Internet-Draft SSH Protocol Architecture July 2003 - - - [KAUFMAN,PERLMAN,SPECINER]. 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 still deemed - difficult and not considered fully practicable especially if - relatively longer block sizes are used. - - 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,KOHNO,NAMPREMPRE]) to work, the attacker - would need to know the 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 implementor 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. Implementors - may wish to check to see if there are any unsent packets awaiting - transmission, but unfortunately it is not normally easy to obtain - this information from the kernel or buffers. If there are not, - 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 successfull. - - 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 - - - - -Ylonen, et. al. Expires January 12, 2004 [Page 15] - -Internet-Draft SSH Protocol Architecture July 2003 - - - 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, since it gets ACKed. - 3. Yet, the attack is possible because Record 1 has already been - seen. - - As this example indicates, it's totally unsafe to use the - existence of unflushed data in the TCP buffers proper as a guide - to whether you need an empty packet, since when you do the second - write(), the buffers will contain the un-ACKed Record 1. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Ylonen, et. al. Expires January 12, 2004 [Page 16] - -Internet-Draft SSH Protocol Architecture July 2003 - - - On the other hand, it's 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 second SSH Record is fixed after the data for - the Data packet is determined -i.e. you do: - read from user - encrypt null packet - encrypt data packet - - - 8.2.2 Data Integrity - - This protocol does allow the Data Integrity mechanism to be - disabled. Implementors 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 [1] 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. - - 8.2.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 replay of data from prior sessions. For example, the - authentication protocol 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 - - - -Ylonen, et. al. Expires January 12, 2004 [Page 17] - -Internet-Draft SSH Protocol Architecture July 2003 - - - other sessions. Note that the session ID can be made public - without harming the security of the protocol. - - If two session happen to 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 so 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 RFC - 2085 [2085], RFC 2246 [2246], RFC 2743 [2743], RFC 1964 [1964], - RFC 2025 [2025], and RFC 1510 [1510]. The underlying construct is - discussed in RFC 2104 [2104]. 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 as 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) - then the calculated MAC will not match the MAC received with the - packet. - - 8.2.4 Man-in-the-middle - - This protocol makes no assumptions nor 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 and users to understand the importance of verifying - this association before any session is initiated. - - - - -Ylonen, et. al. Expires January 12, 2004 [Page 18] - -Internet-Draft SSH Protocol Architecture July 2003 - - - 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 3.1 of [ARCH], 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 they 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 3.1 of [SSH- - ARCH] and may also include secured Web pages, physical pieces of - paper, etc. Implementors SHOULD provide recommendations on how - - - -Ylonen, et. al. Expires January 12, 2004 [Page 19] - -Internet-Draft SSH Protocol Architecture July 2003 - - - 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 over gssapi 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 the Replay part of this - section, a successful attack of this nature is very improbable. - As in the Replay section, 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 RFC 2104. 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 that, implementors 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. It may however be - necessary in non-security critical environments, and will still - provide protection against passive attacks. Implementors of - protocols and applications running on top of this protocol should - keep this possibility in mind. - - 8.2.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 - - - -Ylonen, et. al. Expires January 12, 2004 [Page 20] - -Internet-Draft SSH Protocol Architecture July 2003 - - - exchange without authenticating. Implementors SHOULD provide - features that make this more difficult. For example, only - allowing connections from a subset of IPs known to have valid - users. - - 8.2.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 to verify whether such - information is being sent. - - 8.2.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] SSHv2 sessions resulting from a key - exchange using diffie-hellman-group1-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, SSHv2 does have PFS. It is hoped that all other key exchange - mechanisms proposed and used in the future will also provide PFS. - This property is not commuted to any of the applications or - protocols using SSH as a transport however. 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. - - 8.3 Authentication Protocol - - The purpose of this protocol is to perform client user - authentication. It assumes that this run 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 - - - -Ylonen, et. al. Expires January 12, 2004 [Page 21] - -Internet-Draft SSH Protocol Architecture July 2003 - - - 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. - - 8.3.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 as stated above that the Authentication Protocol - only run 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-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. - - 8.3.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 messages 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 - - - -Ylonen, et. al. Expires January 12, 2004 [Page 22] - -Internet-Draft SSH Protocol Architecture July 2003 - - - 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. - - 8.3.3 Local security policy - - 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 or 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. - - Implementors are encouraged to provide a default local policy and - make its parameters known to administrators and users. At the - discretion of the implementors, 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 which case the administrators will have to - actively make changes to this policy 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. - - 8.3.4 Public key authentication - - The use of public-key authentication assumes that the client 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 section on password authentication - below.) - - - -Ylonen, et. al. Expires January 12, 2004 [Page 23] - -Internet-Draft SSH Protocol Architecture July 2003 - - - 8.3.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. - - 8.3.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. - - 8.4 Connection protocol - - 8.4.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 end point 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. Implementors 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 target in 'port-forwarding' operations, which users are - allowed to use interactive shell facilities, or which users are - allowed to use exposed subsystems. - - 8.4.2 Proxy forwarding - - The SSH connection protocol allows for proxy forwarding of other - protocols such as SNMP, 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 - - - -Ylonen, et. al. Expires January 12, 2004 [Page 24] - -Internet-Draft SSH Protocol Architecture July 2003 - - - through a firewall. Implementors 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. - - 8.4.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. Implementors, - administrators and users who wish to further explore the security - mechanisms of X11 are invited to read [SCHEIFLER] and analyze - previously reported 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 SSHv2 (or other, secure protocols), - combined with actual and pseudo-displays which accept connections - only over local IPC mechanisms authorized by permissions or 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 allowing display opens only over local IPC. It is - RECOMMENDED that SSHv2 server implementations that support X11 - forwarding default to allowing display opens only over local IPC. - On single-user systems it might be reasonable to default to - allowing local display opens over TCP/IP. - - Implementors 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. - - 9. 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 - - - -Ylonen, et. al. Expires January 12, 2004 [Page 25] - -Internet-Draft SSH Protocol Architecture July 2003 - - - 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. - - 10. Additional Information - - The current document editor is: Darren.Moffat@Sun.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 - -References - - [FIPS-186] Federal Information Processing - Standards Publication, ., "FIPS PUB - 186, Digital Signature Standard", May - 1994. - - [FIPS-197] National Institue of Standards and - Technology, ., "FIPS 197, - Specification for the Advanced - Encryption Standard", November 2001. - - [ANSI T1.523-2001] American National Standards Insitute, - Inc., "Telecom Glossary 2000", - February 2001. - - [SCHEIFLER] Scheifler, R., "X Window System : The - Complete Reference to Xlib, X - Protocol, Icccm, Xlfd, 3rd edition.", - Digital Press ISBN 1555580882, - Feburary 1992. - - [RFC0854] Postel, J. and J. Reynolds, "Telnet - Protocol Specification", STD 8, RFC - - - -Ylonen, et. al. Expires January 12, 2004 [Page 26] - -Internet-Draft SSH Protocol Architecture July 2003 - - - 854, May 1983. - - [RFC0894] Hornig, C., "Standard for the - transmission of IP datagrams over - Ethernet networks", STD 41, RFC 894, - Apr 1984. - - [RFC1034] Mockapetris, P., "Domain names - - concepts and facilities", STD 13, RFC - 1034, Nov 1987. - - [RFC1134] Perkins, D., "Point-to-Point Protocol: - A proposal for multi-protocol - transmission of datagrams over Point- - to-Point links", RFC 1134, Nov 1989. - - [RFC1282] Kantor, B., "BSD Rlogin", RFC 1282, - December 1991. - - [RFC1510] Kohl, J. and C. Neuman, "The Kerberos - Network Authentication Service (V5)", - RFC 1510, September 1993. - - [RFC1700] Reynolds, J. and J. Postel, "Assigned - Numbers", STD 2, RFC 1700, October - 1994. - - [RFC1750] Eastlake, D., Crocker, S. and J. - Schiller, "Randomness Recommendations - for Security", RFC 1750, December - 1994. - - [RFC1766] Alvestrand, H., "Tags for the - Identification of Languages", RFC - 1766, March 1995. - - [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. - - - -Ylonen, et. al. Expires January 12, 2004 [Page 27] - -Internet-Draft SSH Protocol Architecture July 2003 - - - 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. - - [RFC2246] Dierks, T. and C. Allen, "The TLS - Protocol Version 1.0", RFC 2246, - January 1999. - - [RFC2279] Yergeau, F., "UTF-8, a transformation - format of ISO 10646", RFC 2279, - January 1998. - - [RFC2410] Glenn, R. and S. Kent, "The NULL - Encryption Algorithm and Its Use With - IPsec", RFC 2410, November 1998. - - [RFC2434] Narten, T. and H. Alvestrand, - "Guidelines for Writing an IANA - Considerations Section in RFCs", BCP - 26, RFC 2434, October 1998. - - [RFC2743] Linn, J., "Generic Security Service - Application Program Interface Version - 2, Update 1", RFC 2743, January 2000. - - [SSH-ARCH] Ylonen, T., "SSH Protocol - Architecture", I-D draft-ietf- - architecture-14.txt, July 2003. - - [SSH-TRANS] Ylonen, T., "SSH Transport Layer - Protocol", I-D draft-ietf-transport- - 16.txt, July 2003. - - [SSH-USERAUTH] Ylonen, T., "SSH Authentication - Protocol", I-D draft-ietf-userauth- - 17.txt, July 2003. - - [SSH-CONNECT] Ylonen, T., "SSH Connection Protocol", - I-D draft-ietf-connect-17.txt, July - 2003. - - [SSH-NUMBERS] Lehtinen, S. and D. Moffat, "SSH - Protocol Assigned Numbers", I-D draft- - ietf-secsh-assignednumbers-03.txt, - - - -Ylonen, et. al. Expires January 12, 2004 [Page 28] - -Internet-Draft SSH Protocol Architecture July 2003 - - - July 2003. - - [SCHNEIER] Schneier, B., "Applied Cryptography - Second Edition: protocols algorithms - and source in code in C", 1996. - - [KAUFMAN,PERLMAN,SPECINER] Kaufman, C., Perlman, R. and M. - Speciner, "Network Security: PRIVATE - Communication in a PUBLIC World", - 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,KOHNO,NAMPREMPRE] Bellaire, M., Kohno, T. and C. - Namprempre, "Authenticated Encryption - in SSH: Fixing the SSH Binary Packet - Protocol", , Sept 2002. - - -Authors' Addresses - - Tatu Ylonen - SSH Communications Security Corp - Fredrikinkatu 42 - HELSINKI FIN-00100 - Finland - - EMail: ylo@ssh.com - - - - -Ylonen, et. al. Expires January 12, 2004 [Page 29] - -Internet-Draft SSH Protocol Architecture July 2003 - - - Tero Kivinen - SSH Communications Security Corp - Fredrikinkatu 42 - HELSINKI FIN-00100 - Finland - - EMail: kivinen@ssh.com - - - Markku-Juhani O. Saarinen - University of Jyvaskyla - - - Timo J. Rinne - SSH Communications Security Corp - Fredrikinkatu 42 - HELSINKI FIN-00100 - Finland - - EMail: tri@ssh.com - - - Sami Lehtinen - SSH Communications Security Corp - Fredrikinkatu 42 - HELSINKI FIN-00100 - Finland - - EMail: sjl@ssh.com - - - - - - - - - - - - - - - - - - - - - - -Ylonen, et. al. Expires January 12, 2004 [Page 30] - -Internet-Draft SSH Protocol Architecture July 2003 - - -Full Copyright Statement - - Copyright (C) The Internet Society (2003). 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, et. al. Expires January 12, 2004 [Page 31] - diff --git a/doc/draft-ietf-secsh-assignednumbers-04.txt b/doc/draft-ietf-secsh-assignednumbers-04.txt deleted file mode 100644 index f87ca0c7..00000000 --- a/doc/draft-ietf-secsh-assignednumbers-04.txt +++ /dev/null @@ -1,559 +0,0 @@ -Network Working Group S. Lehtinen -Internet-Draft SSH Communications Security Corp -Expires: February 13, 2004 D. Moffat - Sun Microsystems - August 15, 2003 - - - SSH Protocol Assigned Numbers - draft-ietf-secsh-assignednumbers-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 February 13, 2004. - -Copyright Notice - - Copyright (C) The Internet Society (2003). All Rights Reserved. - -Abstract - - This document defines the initial state of the IANA assigned numbers - for the SSH protocol as defined in [SSH-ARCH], [SSH-TRANS], [SSH- - CONNECT], [SSH-USERAUTH]. Except for one HISTORIC algorithm - generally regarded as obsolete, this document does not define any new - protocols or any number ranges not already defined in the above - referenced documents. It is intended only for initalization of the - IANA databases referenced in those documents. - - - - - - -Lehtinen & Moffat Expires February 13, 2004 [Page 1] - -Internet-Draft SSH Protocol Assigned Numbers August 2003 - - -Table of Contents - - 1. Message Numbers . . . . . . . . . . . . . . . . . . . . . . 3 - 1.1 Disconnect Codes . . . . . . . . . . . . . . . . . . . . . . 4 - 2. Service Names . . . . . . . . . . . . . . . . . . . . . . . 5 - 2.1 Authentication Method Names . . . . . . . . . . . . . . . . 5 - 2.2 Connection Protocol Assigned Names . . . . . . . . . . . . . 6 - 2.2.1 Connection Protocol Channel Types . . . . . . . . . . . . . 6 - 2.2.2 Connection Protocol Global Request Names . . . . . . . . . . 6 - 2.2.3 Connection Protocol Channel Request Names . . . . . . . . . 6 - 3. Key Exchange Method Names . . . . . . . . . . . . . . . . . 7 - 4. Assigned Algorithm Names . . . . . . . . . . . . . . . . . . 7 - 4.1 Encryption Algorithm Names . . . . . . . . . . . . . . . . . 7 - 4.2 MAC Algorithm Names . . . . . . . . . . . . . . . . . . . . 8 - 4.3 Public Key Algorithm Names . . . . . . . . . . . . . . . . . 8 - 4.4 Compression Algorithm Names . . . . . . . . . . . . . . . . 8 - References . . . . . . . . . . . . . . . . . . . . . . . . . 8 - Authors' Addresses . . . . . . . . . . . . . . . . . . . . . 9 - Full Copyright Statement . . . . . . . . . . . . . . . . . . 10 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Lehtinen & Moffat Expires February 13, 2004 [Page 2] - -Internet-Draft SSH Protocol Assigned Numbers August 2003 - - -1. Message Numbers - - The Message Number is an 8-bit value, which describes the payload of - a packet. - - Protocol packets have message numbers in the range 1 to 255. These - numbers have been allocated as follows in [SSH-ARCH]: - - 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) - - 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 - - - Requests for assignments of new message numbers must be accompanied - by an RFC which describes the new packet type. If the RFC is not on - the standards-track (i.e. it is an informational or experimental - RFC), it must be explicitly reviewed and approved by the IESG before - the RFC is published and the message number is assigned. - - Message ID Value Reference - ----------- ----- --------- - SSH_MSG_DISCONNECT 1 [SSH-TRANS] - SSH_MSG_IGNORE 2 [SSH-TRANS] - SSH_MSG_UNIMPLEMENTED 3 [SSH-TRANS] - SSH_MSG_DEBUG 4 [SSH-TRANS] - SSH_MSG_SERVICE_REQUEST 5 [SSH-TRANS] - - - -Lehtinen & Moffat Expires February 13, 2004 [Page 3] - -Internet-Draft SSH Protocol Assigned Numbers August 2003 - - - SSH_MSG_SERVICE_ACCEPT 6 [SSH-TRANS] - SSH_MSG_KEXINIT 20 [SSH-TRANS] - SSH_MSG_NEWKEYS 21 [SSH-TRANS] - SSH_MSG_KEXDH_INIT 30 [SSH-TRANS] - SSH_MSG_KEXDH_REPLY 31 [SSH-TRANS] - SSH_MSG_USERAUTH_REQUEST 50 [SSH-USERAUTH] - SSH_MSG_USERAUTH_FAILURE 51 [SSH-USERAUTH] - SSH_MSG_USERAUTH_SUCCESS 52 [SSH-USERAUTH] - SSH_MSG_USERAUTH_BANNER 53 [SSH-USERAUTH] - SSH_MSG_USERAUTH_PK_OK 60 [SSH-USERAUTH] - SSH_MSG_GLOBAL_REQUEST 80 [SSH-CONNECT] - SSH_MSG_REQUEST_SUCCESS 81 [SSH-CONNECT] - SSH_MSG_REQUEST_FAILURE 82 [SSH-CONNECT] - SSH_MSG_CHANNEL_OPEN 90 [SSH-CONNECT] - SSH_MSG_CHANNEL_OPEN_CONFIRMATION 91 [SSH-CONNECT] - SSH_MSG_CHANNEL_OPEN_FAILURE 92 [SSH-CONNECT] - SSH_MSG_CHANNEL_WINDOW_ADJUST 93 [SSH-CONNECT] - SSH_MSG_CHANNEL_DATA 94 [SSH-CONNECT] - SSH_MSG_CHANNEL_EXTENDED_DATA 95 [SSH-CONNECT] - SSH_MSG_CHANNEL_EOF 96 [SSH-CONNECT] - SSH_MSG_CHANNEL_CLOSE 97 [SSH-CONNECT] - SSH_MSG_CHANNEL_REQUEST 98 [SSH-CONNECT] - SSH_MSG_CHANNEL_SUCCESS 99 [SSH-CONNECT] - SSH_MSG_CHANNEL_FAILURE 100 [SSH-CONNECT] - - -1.1 Disconnect Codes - - The Disconnect code is an 8-bit value, which describes the disconnect - reason. Requests for assignments of new disconnect codes must be - accompanied by an RFC which describes the new disconnect reason code. - - - Disconnect code Value Reference - ---------------- ----- --------- - SSH_DISCONNECT_HOST_NOT_ALLOWED_TO_CONNECT 1 [SSH-TRANS] - SSH_DISCONNECT_PROTOCOL_ERROR 2 [SSH-TRANS] - SSH_DISCONNECT_KEY_EXCHANGE_FAILED 3 [SSH-TRANS] - SSH_DISCONNECT_RESERVED 4 [SSH-TRANS] - SSH_DISCONNECT_MAC_ERROR 5 [SSH-TRANS] - SSH_DISCONNECT_COMPRESSION_ERROR 6 [SSH-TRANS] - SSH_DISCONNECT_SERVICE_NOT_AVAILABLE 7 [SSH-TRANS] - SSH_DISCONNECT_PROTOCOL_VERSION_NOT_SUPPORTED 8 [SSH-TRANS] - SSH_DISCONNECT_HOST_KEY_NOT_VERIFIABLE 9 [SSH-TRANS] - SSH_DISCONNECT_CONNECTION_LOST 10 [SSH-TRANS] - SSH_DISCONNECT_BY_APPLICATION 11 [SSH-TRANS] - SSH_DISCONNECT_TOO_MANY_CONNECTIONS 12 [SSH-TRANS] - SSH_DISCONNECT_AUTH_CANCELLED_BY_USER 13 [SSH-TRANS] - - - -Lehtinen & Moffat Expires February 13, 2004 [Page 4] - -Internet-Draft SSH Protocol Assigned Numbers August 2003 - - - SSH_DISCONNECT_NO_MORE_AUTH_METHODS_AVAILABLE 14 [SSH-TRANS] - SSH_DISCONNECT_ILLEGAL_USER_NAME 15 [SSH-TRANS] - - -2. Service Names - - The Service Name is used to describe a protocol layer. These names - MUST be printable US-ASCII strings, and MUST NOT contain the - characters at-sign ('@'), comma (','), or whitespace or control - characters (ASCII codes 32 or less). Names are case-sensitive, and - MUST NOT be longer than 64 characters. - - Requests for assignments of new service names must be accompanied by - an RFC which describes the interpretation for the service name. If - the RFC is not on the standards-track (i.e. it is an informational - or experimental RFC), it must be explicitly reviewed and approved by - the IESG before the RFC is published and the service name is - assigned. - - Service name Reference - ------------- --------- - ssh-userauth [SSH-USERAUTH] - ssh-connection [SSH-CONNECT] - - -2.1 Authentication Method Names - - The Authentication Method Name is used to describe an authentication - method for the "ssh-userauth" service [SSH-USERAUTH]. These names - MUST be printable US-ASCII strings, and MUST NOT contain the - characters at-sign ('@'), comma (','), or whitespace or control - characters (ASCII codes 32 or less). Names are case-sensitive, and - MUST NOT be longer than 64 characters. - - Requests for assignments of new authentication method names must be - accompanied by an RFC which describes the interpretation for the - authentication method. - - Method name Reference - ------------ --------- - publickey [SSH-USERAUTH, Section 4] - password [SSH-USERAUTH, Section 5] - hostbased [SSH-USERAUTH, Section 6] - none [SSH-USERAUTH, Section 2.3] - - - - - - - -Lehtinen & Moffat Expires February 13, 2004 [Page 5] - -Internet-Draft SSH Protocol Assigned Numbers August 2003 - - -2.2 Connection Protocol Assigned Names - - The following request and type names MUST be printable US-ASCII - strings, and MUST NOT contain the characters at-sign ('@'), comma - (','), or whitespace or control characters (ASCII codes 32 or less). - Names are case-sensitive, and MUST NOT be longer than 64 characters. - - Requests for assignments of new assigned names must be accompanied by - an RFC which describes the interpretation for the type or request. - -2.2.1 Connection Protocol Channel Types - - Channel type Reference - ------------ --------- - session [SSH-CONNECT, Section 4.1] - x11 [SSH-CONNECT, Section 4.3.2] - forwarded-tcpip [SSH-CONNECT, Section 5.2] - direct-tcpip [SSH-CONNECT, Section 5.2] - - -2.2.2 Connection Protocol Global Request Names - - Request type Reference - ------------ --------- - tcpip-forward [SSH-CONNECT, Section 5.1] - cancel-tcpip-forward [SSH-CONNECT, Section 5.1] - - -2.2.3 Connection Protocol Channel Request Names - - Request type Reference - ------------ --------- - pty-req [SSH-CONNECT, Section 4.2] - x11-req [SSH-CONNECT, Section 4.3.1] - env [SSH-CONNECT, Section 4.4] - shell [SSH-CONNECT, Section 4.5] - exec [SSH-CONNECT, Section 4.5] - subsystem [SSH-CONNECT, Section 4.5] - window-change [SSH-CONNECT, Section 4.7] - xon-xoff [SSH-CONNECT, Section 4.8] - signal [SSH-CONNECT, Section 4.9] - exit-status [SSH-CONNECT, Section 4.10] - exit-signal [SSH-CONNECT, Section 4.10] - - - - - - - - -Lehtinen & Moffat Expires February 13, 2004 [Page 6] - -Internet-Draft SSH Protocol Assigned Numbers August 2003 - - -3. Key Exchange Method Names - - The Key Exchange Method Name describes a key-exchange method for the - protocol [SSH-TRANS]. The names MUST be printable US-ASCII strings, - and MUST NOT contain the characters at-sign ('@'), comma (','), or - whitespace or control characters (ASCII codes 32 or less). Names are - case-sensitive, and MUST NOT be longer than 64 characters. - - Requests for assignment of new key-exchange method names must be - accompanied by a reference to a standards-track or Informational RFC - which describes this method. - - Method name Reference - ------------ --------- - diffie-hellman-group1-sha1 [SSH-TRANS, Section 4.5] - - -4. Assigned Algorithm Names - - The following identifiers (names) MUST be printable US-ASCII strings, - and MUST NOT contain the characters at-sign ('@'), comma (','), or - whitespace or control characters (ASCII codes 32 or less). Names are - case-sensitive, and MUST NOT be longer than 64 characters. - - Requests for assignment of new algorithm names must be accompanied by - a reference to a standards-track or Informational RFC or a reference - to published cryptographic literature which describes the algorithm. - -4.1 Encryption Algorithm Names - - Cipher name Reference - ------------ --------- - 3des-cbc [SSH-TRANS, Section 4.3] - blowfish-cbc [SSH-TRANS, Section 4.3] - twofish256-cbc [SSH-TRANS, Section 4.3] - twofish-cbc [SSH-TRANS, Section 4.3] - twofish192-cbc [SSH-TRANS, Section 4.3] - twofish128-cbc [SSH-TRANS, Section 4.3] - aes256-cbc [SSH-TRANS, Section 4.3] - aes192-cbc [SSH-TRANS, Section 4.3] - aes128-cbc [SSH-TRANS, Section 4.3] - serpent256-cbc [SSH-TRANS, Section 4.3] - serpent192-cbc [SSH-TRANS, Section 4.3] - serpent128-cbc [SSH-TRANS, Section 4.3] - arcfour [SSH-TRANS, Section 4.3] - idea-cbc [SSH-TRANS, Section 4.3] - cast128-cbc [SSH-TRANS, Section 4.3] - none [SSH-TRANS, Section 4.3] - - - -Lehtinen & Moffat Expires February 13, 2004 [Page 7] - -Internet-Draft SSH Protocol Assigned Numbers August 2003 - - - des-cbc [FIPS-46-3] HISTORIC; See page 4 of [FIPS 46-3] - - -4.2 MAC Algorithm Names - - - - MAC name Reference - --------- --------- - hmac-sha1 [SSH-TRANS, Section 4.4] - hmac-sha1-96 [SSH-TRANS, Section 4.4] - hmac-md5 [SSH-TRANS, Section 4.4] - hmac-md5-96 [SSH-TRANS, Section 4.4] - none [SSH-TRANS, Section 4.4] - - -4.3 Public Key Algorithm Names - - Algorithm name Reference - --------------- --------- - ssh-dss [SSH-TRANS, Section 4.6] - ssh-rsa [SSH-TRANS, Section 4.6] - x509v3-sign-rsa [SSH-TRANS, Section 4.6] - x509v3-sign-dss [SSH-TRANS, Section 4.6] - spki-sign-rsa [SSH-TRANS, Section 4.6] - spki-sign-dss [SSH-TRANS, Section 4.6] - pgp-sign-rsa [SSH-TRANS, Section 4.6] - pgp-sign-dss [SSH-TRANS, Section 4.6] - - -4.4 Compression Algorithm Names - - Algorithm name Reference - --------------- --------- - none [SSH-TRANS, Section 4.2] - zlib [SSH-TRANS, Section 4.2] - -References - - [SSH-ARCH] Ylonen, T., "SSH Protocol Architecture", I-D draft- - ietf-architecture-14.txt, July 2003. - - [SSH-TRANS] Ylonen, T., "SSH Transport Layer Protocol", I-D - draft-ietf-transport-16.txt, July 2003. - - [SSH-USERAUTH] Ylonen, T., "SSH Authentication Protocol", I-D draft- - ietf-userauth-17.txt, July 2003. - - - - -Lehtinen & Moffat Expires February 13, 2004 [Page 8] - -Internet-Draft SSH Protocol Assigned Numbers August 2003 - - - [SSH-CONNECT] Ylonen, T., "SSH Connection Protocol", I-D draft- - ietf-connect-17.txt, July 2003. - - [SSH-NUMBERS] Lehtinen, S. and D. Moffat, "SSH Protocol Assigned - Numbers", I-D draft-ietf-secsh-assignednumbers- - 03.txt, July 2003. - - [FIPS-46-3] U.S. Dept. of Commerce, ., "FIPS PUB 46-3, Data - Encryption Standard (DES)", October 1999. - - -Authors' Addresses - - Sami Lehtinen - SSH Communications Security Corp - Fredrikinkatu 42 - HELSINKI FIN-00100 - Finland - - EMail: sjl@ssh.com - - - Darren J Moffat - Sun Microsystems - 901 San Antonio Road - Palo Alto 94303 - USA - - EMail: Darren.Moffat@Sun.COM - - - - - - - - - - - - - - - - - - - - - - -Lehtinen & Moffat Expires February 13, 2004 [Page 9] - -Internet-Draft SSH Protocol Assigned Numbers August 2003 - - -Full Copyright Statement - - Copyright (C) The Internet Society (2003). 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. - - - - - - - - - - - - - - - - - - - -Lehtinen & Moffat Expires February 13, 2004 [Page 10] - - diff --git a/doc/draft-ietf-secsh-auth-kbdinteract-05-cleaned.txt b/doc/draft-ietf-secsh-auth-kbdinteract-05-cleaned.txt deleted file mode 100644 index b22a6632..00000000 --- a/doc/draft-ietf-secsh-auth-kbdinteract-05-cleaned.txt +++ /dev/null @@ -1,366 +0,0 @@ - - Generic Message Exchange Authentication For SSH - <draft-ietf-secsh-auth-kbdinteract-05.txt> - -Abstract - - 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. 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 which 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 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". - -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. - - This authentication method is however limited to authentication - mechanisms which do not require any special code, such as hardware - drivers or password mangling, on the client. - -3. Protocol Exchanges - - The client initiates the authentication with a - SSH_MSG_USERAUTH_REQUEST message. The server then requests - authentication information from the client with a - SSH_MSG_USERAUTH_INFO_REQUEST message. The client obtains the - information from the user and then responds with a - 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-2279]) - 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. The - server SHOULD instead 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. The language to be - used if the server does not support the requested language 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 a comma-separated list of - authentication submethods (software or hardware) which 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 which the user and - the server needs to agree upon. - - Server interpretation of the submethods field is implementation- - dependent. - - 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 either a 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) which 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 just comparing the results when - authenticating as different users. - -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. - - 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 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 language tag SHOULD describe the language used in the textual - fields. If the server does not know the language used, or if - multiple languages are used, the language tag MUST be the empty - string. - - 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). - -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; it SHOULD instead 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 occured. - 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 or - not 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. - -3.4 Information Responses - - After obtaining the requested information from the user, the client - MUST respond with a 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. - - 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. - - 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 a - 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 - 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 to the client. - It is suspected that implementations are likely to make the time - delay a 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 - - The second example is of 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 - - [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 diff --git a/doc/draft-ietf-secsh-auth-kbdinteract-05.txt b/doc/draft-ietf-secsh-auth-kbdinteract-05.txt deleted file mode 100644 index 99504dbf..00000000 --- a/doc/draft-ietf-secsh-auth-kbdinteract-05.txt +++ /dev/null @@ -1,619 +0,0 @@ - - - -Network Working Group F. Cusack -INTERNET-DRAFT Google, Inc. -Expires November 1, 2003 M. Forssen - Appgate AB - May 1, 2003 - - - - - Generic Message Exchange Authentication For SSH - <draft-ietf-secsh-auth-kbdinteract-05.txt> - -Status of this Memo - - This document is an Internet-Draft and is subject to 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 November 1, 2003. - -Abstract - - 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. 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). - - - - - - - - - -F. Cusack, M. Forssen Expires November 1, 2003 [Page 1] - -Internet Draft SSH Generic Interactive Authentication May 1, 2003 - - -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 which 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 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 since 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. - - - - -F. Cusack, M. Forssen Expires November 1, 2003 [Page 2] - -Internet Draft SSH Generic Interactive Authentication May 1, 2003 - - - 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. - - This authentication method is however limited to authentication - mechanisms which do not require any special code, such as hardware - drivers or password mangling, on the client. - -3. Protocol Exchanges - - The client initiates the authentication with a - SSH_MSG_USERAUTH_REQUEST message. The server then requests - authentication information from the client with a - SSH_MSG_USERAUTH_INFO_REQUEST message. The client obtains the - information from the user and then responds with a - 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-2279]) - 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. The - server SHOULD instead 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. The language to be - used if the server does not support the requested language is - implementation-dependent. - - The submethods field is included so the user can give a hint of which - - - -F. Cusack, M. Forssen Expires November 1, 2003 [Page 3] - -Internet Draft SSH Generic Interactive Authentication May 1, 2003 - - - actual methods he wants to use. It is a a comma-separated list of - authentication submethods (software or hardware) which 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 which the user and - the server needs to agree upon. - - Server interpretation of the submethods field is implementation- - dependent. - - 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 either a 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) which 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 just comparing the results when - authenticating as different users. - -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. - - - - - -F. Cusack, M. Forssen Expires November 1, 2003 [Page 4] - -Internet Draft SSH Generic Interactive Authentication May 1, 2003 - - - 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 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 language tag SHOULD describe the language used in the textual - fields. If the server does not know the language used, or if - multiple languages are used, the language tag MUST be the empty - string. - - 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). - -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 - - - -F. Cusack, M. Forssen Expires November 1, 2003 [Page 5] - -Internet Draft SSH Generic Interactive Authentication May 1, 2003 - - - 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; it SHOULD instead 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 occured. - 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 or - not 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. - -3.4 Information Responses - - After obtaining the requested information from the user, the client - MUST respond with a 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) - - - - -F. Cusack, M. Forssen Expires November 1, 2003 [Page 6] - -Internet Draft SSH Generic Interactive Authentication May 1, 2003 - - - 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. - - 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. - - 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 a - 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 - 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 to the client. - It is suspected that implementations are likely to make the time - delay a 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 "" - - - - - -F. Cusack, M. Forssen Expires November 1, 2003 [Page 7] - -Internet Draft SSH Generic Interactive Authentication May 1, 2003 - - - 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 - - The second example is of 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" - - - - - - - - - - - - -F. Cusack, M. Forssen Expires November 1, 2003 [Page 8] - -Internet Draft SSH Generic Interactive Authentication May 1, 2003 - - - 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 - - [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, depends - 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. - - - - -F. Cusack, M. Forssen Expires November 1, 2003 [Page 9] - -Internet Draft SSH Generic Interactive Authentication May 1, 2003 - - - 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 frequency of 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 Level", BCP 14, RFC 2119, March 1997. - - - [RFC-2279] Yergeau, F., "UTF-8, a transformation format of - Unicode and ISO 10646", RFC 2279, October 1996. - - - [RFC-3066] Alvestrand, H., "Tags for the Identification of - Languages", BCP 47, RFC 3066, January 2001. - - - [SSH-ARCH] Ylonen, T., Kivinen, T, Saarinen, M., Rinne, T., and - Lehtinen, S., "SSH Protocol Architecture", work in - progress, draft-ietf-secsh-architecture-13.txt, - September, 2002. - - - [SSH-CONNECT] Ylonen, T., Kivinen, T, Saarinen, M., Rinne, T., and - Lehtinen, S., "SSH Connection Protocol", work in - progress, draft-ietf-secsh-connect-16.txt, September, - 2002. - - - [SSH-TRANS] Ylonen, T., Kivinen, T, Saarinen, M., Rinne, T., and - Lehtinen, S., "SSH Transport Layer Protocol", work in - progress, draft-ietf-secsh-transport-15.txt, - September, 2002. - - - [SSH-USERAUTH] Ylonen, T., Kivinen, T, Saarinen, M., Rinne, T., and - Lehtinen, S., "SSH Authentication Protocol", work in - progress, draft-ietf-secsh-userauth-16.txt, - September, 2002. - - - - - -F. Cusack, M. Forssen Expires November 1, 2003 [Page 10] - -Internet Draft SSH Generic Interactive Authentication May 1, 2003 - - -7.2 Informative References - - - [PAM] Samar, V., Schemers, R., "Unified Login With - Pluggable Authentication Modules (PAM)", OSF RFC - 86.0, October 1995 - -8. Author's Addresses - - Frank Cusack - Google, Inc. - 2400 Bayshore Parkway - Mountain View, CA 94043 - Email: frank@google.com - - Martin Forssen - Appgate AB - Stora Badhusgatan 18-20 - SE-411 21 Gothenburg - SWEDEN - Email: maf@appgate.com - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -F. Cusack, M. Forssen Expires November 1, 2003 [Page 11] -
\ No newline at end of file diff --git a/doc/draft-ietf-secsh-break-00.txt b/doc/draft-ietf-secsh-break-00.txt deleted file mode 100644 index f10763ba..00000000 --- a/doc/draft-ietf-secsh-break-00.txt +++ /dev/null @@ -1,394 +0,0 @@ - - - -Secure Shell Working Group J. Galbraith -Internet-Draft VanDyke Software -Expires: September 17, 2003 P. Remaker - Cisco Systems, Inc - March 19, 2003 - - - Session Channel Break Extension - draft-ietf-secsh-break-00.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 September 17, 2003. - -Copyright Notice - - Copyright (C) The Internet Society (2003). All Rights Reserved. - -Abstract - - The Break Extension provides a way to send a break signal during a - SSH terminal session. - - - - - - - - - - - - -Galbraith & Remaker Expires September 17, 2003 [Page 1] - -Internet-Draft Session Channel Break Extension March 2003 - - -Table of Contents - - 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . 3 - 2. The Break Request . . . . . . . . . . . . . . . . . . . . . . . 4 - References . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 - Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 5 - Intellectual Property and Copyright Statements . . . . . . . . . 6 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Galbraith & Remaker Expires September 17, 2003 [Page 2] - -Internet-Draft Session Channel Break Extension March 2003 - - -1. Introduction - - The SSH session channel provides a mechanism for the client-user to - interactively enter commands and receive output from a remote host - while taking advantage of the SSH transport's privacy and integrity - features. - - A common application of the telnet protocol is the "Console Server" - whereby a telnet NVT can be connected to a physical RS-232/V.24 - asynchronous port, allowing the telnet NVT to appear as a locally - attached terminal to that port, and allowing that port to appear as a - network addressable device. A number of major computer equipment - vendors provide high level administrative functions through an - asynchronous serial port and generally expect the attached terminal - to be capable of send a BREAK signal, which is defined as the TxD - signal being held in a SPACE state for a time greater than a whole - character time, typically interpreted as 250 to 500 ms. - - The telnet protocolprovides a means to send a "BREAK" signal, which - is defined as a "a signal outside the USASCII set which is currently - given local meaning within many systems." [1] Console Server vendors - interpret the TELNET break signal as a physical break signal, which - can then allow access to the full range of administartive functions - available on an asynchronous serial console port. - - The lack of a similar facility in the SSH session channel has forced - users to continue the use of telnet for the "Console Server" - function. - - - - - - - - - - - - - - - - - - - - - - - -Galbraith & Remaker Expires September 17, 2003 [Page 3] - -Internet-Draft Session Channel Break Extension March 2003 - - -2. The Break Request - - The following following channel specific request can be sent to - request that the remote host perform a break operation. - - byte SSH_MSG_CHANNEL_REQUEST - uint32 recipient channel - string "break" - boolean want_reply - uint32 break-length in milliseconds - - If the break length cannot be controlled by the application receiving - this request, the break length parameter SHOULD be ignored and the - default break signal length of the chipset or underlying chipset - driver SHOULD be sent. - - If the application can control the break-length, the following - suggestions are made reagarding break duration. If a break duration - request of greater than 3000ms is received, it SHOULD be processed as - a 3000ms break, in order to an unreasonably long break request - causing the port to become unavailable for as long as 47 days while - executing the break. Applications that require a longer break may - choose to ignore this requirement. If break duration request of - less than 500ms, is requested a break of 500ms SHOULD be sent since - most devices will recognize a break of that length. In the event - that an application needs a shorter break, this can be ignored. If - the break-length parameter is 0, the break SHOULD be sent as 500ms or - the default break signal length of the chipset or underlying chipset - driver . - - If the want_reply boolean is set, the server MUST reply using - SSH_MSG_CHANNEL_SUCCESS or SSH_MSG_CHANNEL_FAILURE [4] messages. If - a break of any kind was preformed, SSH_MSG_CHANNEL_SUCCESS MUST be - sent. If no break was preformed, SSH_MSG_CHANNEL_FAILURE MUST be - sent. - - This operation SHOULD be support by most general purpose SSH clients. - - - - - - - - - - - - - - -Galbraith & Remaker Expires September 17, 2003 [Page 4] - -Internet-Draft Session Channel Break Extension March 2003 - - -References - - [1] Postel, J. and J. Reynolds, "Telnet Protocol Specification", STD - 8, RFC 854, May 1983. - - [2] Rinne, T., Ylonen, T., Kivinen, T. and S. Lehtinen, "SSH - Protocol Architecture", draft-ietf-secsh-architecture-13 (work - in progress), September 2002. - - [3] Rinne, T., Ylonen, T., Kivinen, T., Saarinen, M. and S. - Lehtinen, "SSH Transport Layer Protocol", - draft-ietf-secsh-transport-15 (work in progress), September - 2002. - - [4] Rinne, T., Ylonen, T., Kivinen, T. and S. Lehtinen, "SSH - Connection Protocol", draft-ietf-secsh-connect-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 - - - Phillip Remaker - Cisco Systems, Inc - 170 West Tasman Drive - San Jose, CA 95120 - US - - EMail: remaker@cisco.com - - - - - - - - - - - - -Galbraith & Remaker Expires September 17, 2003 [Page 5] - -Internet-Draft Session Channel Break Extension March 2003 - - -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 (2003). 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 & Remaker Expires September 17, 2003 [Page 6] - -Internet-Draft Session Channel Break Extension March 2003 - - - 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 & Remaker Expires September 17, 2003 [Page 7] - - diff --git a/doc/draft-ietf-secsh-connect-17.txt b/doc/draft-ietf-secsh-connect-17.txt deleted file mode 100644 index 5a8a43e0..00000000 --- a/doc/draft-ietf-secsh-connect-17.txt +++ /dev/null @@ -1,1232 +0,0 @@ - - -Network Working Group T. Ylonen -Internet-Draft T. Kivinen -Expires: January 12, 2004 SSH Communications Security Corp - M. Saarinen - University of Jyvaskyla - T. Rinne - S. Lehtinen - SSH Communications Security Corp - July 14, 2003 - - - SSH Connection Protocol - draft-ietf-secsh-connect-17.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 January 12, 2004. - -Copyright Notice - - Copyright (C) The Internet Society (2003). All Rights Reserved. - -Abstract - - 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, - - - -Ylonen, et. al. Expires January 12, 2004 [Page 1] - -Internet-Draft SSH Connection Protocol July 2003 - - - 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. - -Table of Contents - - 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 - 2. Global Requests . . . . . . . . . . . . . . . . . . . . . . 3 - 3. Channel Mechanism . . . . . . . . . . . . . . . . . . . . . 3 - 3.1 Opening a Channel . . . . . . . . . . . . . . . . . . . . . 4 - 3.2 Data Transfer . . . . . . . . . . . . . . . . . . . . . . . 5 - 3.3 Closing a Channel . . . . . . . . . . . . . . . . . . . . . 6 - 3.4 Channel-Specific Requests . . . . . . . . . . . . . . . . . 7 - 4. Interactive Sessions . . . . . . . . . . . . . . . . . . . . 8 - 4.1 Opening a Session . . . . . . . . . . . . . . . . . . . . . 8 - 4.2 Requesting a Pseudo-Terminal . . . . . . . . . . . . . . . . 8 - 4.3 X11 Forwarding . . . . . . . . . . . . . . . . . . . . . . . 9 - 4.3.1 Requesting X11 Forwarding . . . . . . . . . . . . . . . . . 9 - 4.3.2 X11 Channels . . . . . . . . . . . . . . . . . . . . . . . . 9 - 4.4 Environment Variable Passing . . . . . . . . . . . . . . . . 10 - 4.5 Starting a Shell or a Command . . . . . . . . . . . . . . . 10 - 4.6 Session Data Transfer . . . . . . . . . . . . . . . . . . . 11 - 4.7 Window Dimension Change Message . . . . . . . . . . . . . . 11 - 4.8 Local Flow Control . . . . . . . . . . . . . . . . . . . . . 12 - 4.9 Signals . . . . . . . . . . . . . . . . . . . . . . . . . . 12 - 4.10 Returning Exit Status . . . . . . . . . . . . . . . . . . . 12 - 5. TCP/IP Port Forwarding . . . . . . . . . . . . . . . . . . . 14 - 5.1 Requesting Port Forwarding . . . . . . . . . . . . . . . . . 14 - 5.2 TCP/IP Forwarding Channels . . . . . . . . . . . . . . . . . 15 - 6. Encoding of Terminal Modes . . . . . . . . . . . . . . . . . 16 - 7. Summary of Message Numbers . . . . . . . . . . . . . . . . . 18 - 8. Security Considerations . . . . . . . . . . . . . . . . . . 18 - 9. Intellectual Property . . . . . . . . . . . . . . . . . . . 18 - 10. Additional Information . . . . . . . . . . . . . . . . . . . 19 - References . . . . . . . . . . . . . . . . . . . . . . . . . 19 - Authors' Addresses . . . . . . . . . . . . . . . . . . . . . 20 - Full Copyright Statement . . . . . . . . . . . . . . . . . . 22 - - - - - - - - - - - - -Ylonen, et. al. Expires January 12, 2004 [Page 2] - -Internet-Draft SSH Connection Protocol July 2003 - - - 1. Introduction - - The SSH Connection Protocol has been designed to run on top of the - SSH transport layer and user authentication protocols. It - provides interactive login sessions, remote execution of commands, - forwarded TCP/IP connections, and forwarded X11 connections. The - service name for this protocol (after user authentication) is - "ssh-connection". - - 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. 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. All - such requests use the following format. - - byte SSH_MSG_GLOBAL_REQUEST - string request name (restricted to US-ASCII) - boolean want reply - ... request-specific data follows - - Request names follow 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 - - - 3. Channel Mechanism - - All terminal sessions, forwarded connections, etc. are channels. - Either side may open a channel. Multiple channels are multiplexed - - - -Ylonen, et. al. Expires January 12, 2004 [Page 3] - -Internet-Draft SSH Connection Protocol July 2003 - - - 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. - - 3.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 (restricted to US-ASCII) - 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 the SSH architecture - document, with similar extension mechanisms. `sender channel' is - a local identifier for the channel used by the sender of this - message. `initial window size' specifies how many bytes of - channel data can be sent to the sender of this message without - adjusting the window. `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 - - 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 - - where `recipient channel' is the channel number given in the - - - -Ylonen, et. al. Expires January 12, 2004 [Page 4] - -Internet-Draft SSH Connection Protocol July 2003 - - - original open request, and `sender channel' is the channel number - allocated by the other side, or - - byte SSH_MSG_CHANNEL_OPEN_FAILURE - uint32 recipient channel - uint32 reason code - string additional textual information (ISO-10646 UTF-8 [RFC2279]) - string language tag (as defined in [RFC1766]) - - 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 additional - information to the user. If this is done, the client software - should take the precautions discussed in [SSH-ARCH]. - - The following reason codes are defined: - - #define SSH_OPEN_ADMINISTRATIVELY_PROHIBITED 1 - #define SSH_OPEN_CONNECT_FAILED 2 - #define SSH_OPEN_UNKNOWN_CHANNEL_TYPE 3 - #define SSH_OPEN_RESOURCE_SHORTAGE 4 - - - 3.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. - - 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 the current window size. - 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, et. al. Expires January 12, 2004 [Page 5] - -Internet-Draft SSH Connection Protocol July 2003 - - - 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 the data. The - available types and their interpretation depend on the type of the - 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. - - #define SSH_EXTENDED_DATA_STDERR 1 - - - 3.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 a 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 - - - -Ylonen, et. al. Expires January 12, 2004 [Page 6] - -Internet-Draft SSH Connection Protocol July 2003 - - - no window space is available. - - It is recommended that any data sent before this message is - delivered to the actual destination, if possible. - - 3.4 Channel-Specific Requests - - Many channel types 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 (restricted to US-ASCII) - boolean want reply - ... type-specific data - - If want reply is FALSE, no response will be sent to the request. - Otherwise, the recipient responds with either - SSH_MSG_CHANNEL_SUCCESS or 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. Request types 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] - - 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. - - - - - - -Ylonen, et. al. Expires January 12, 2004 [Page 7] - -Internet-Draft SSH Connection Protocol July 2003 - - - 4. 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. - - 4.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. - - 4.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 encoding of terminal modes is described in Section Encoding of - Terminal Modes (Section 6). 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. - - - - -Ylonen, et. al. Expires January 12, 2004 [Page 8] - -Internet-Draft SSH Connection Protocol July 2003 - - - 4.3 X11 Forwarding - - 4.3.1 Requesting X11 Forwarding - - X11 forwarding may be requested for a session by sending - - 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 authentication cookie that is sent be a - fake, random cookie, and that the cookie is 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. - - 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. - - X Protocol is documented in [SCHEIFLER]. - - 4.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 - - - - -Ylonen, et. al. Expires January 12, 2004 [Page 9] - -Internet-Draft SSH Connection Protocol July 2003 - - - 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. - - 4.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 - - - 4.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 the user's default shell (typically - defined in /etc/passwd in UNIX systems) to 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 the server to 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 - - - -Ylonen, et. al. Expires January 12, 2004 [Page 10] - -Internet-Draft SSH Connection Protocol July 2003 - - - 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 to request and check the reply for these - messages. The client SHOULD ignore these messages. - - Subsystem names follow the DNS extensibility naming convention - outlined in [SSH-ARCH]. - - 4.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. - - 4.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 - - - -Ylonen, et. al. Expires January 12, 2004 [Page 11] - -Internet-Draft SSH Connection Protocol July 2003 - - - uint32 terminal width, pixels - uint32 terminal height, pixels - - No response SHOULD be sent to this message. - - 4.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. - - 4.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 names will be encoded as discussed in the "exit-signal" - SSH_MSG_CHANNEL_REQUEST. - - 4.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 - - - -Ylonen, et. al. Expires January 12, 2004 [Page 12] - -Internet-Draft SSH Connection Protocol July 2003 - - - command. Returning the status is RECOMMENDED. No acknowledgment - 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 (ISO-10646 UTF-8) - string language tag (as defined in [RFC1766]) - - 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 names MAY be sent in the format "sig-name@xyz", - where `sig-name' and `xyz' may be anything a particular - implementor wants (except the `@' sign). However, it is suggested - that if a `configure' script is used, the non-standard signal - names it finds be encoded as "SIG@xyz.config.guess", where `SIG' - is the signal name without the "SIG" prefix, and `xyz' be the host - - - -Ylonen, et. al. Expires January 12, 2004 [Page 13] - -Internet-Draft SSH Connection Protocol July 2003 - - - type, as determined by `config.guess'. - - The `error message' contains an additional explanation of the - error message. The message may consist of multiple lines. 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]. - - 5. TCP/IP Port Forwarding - - 5.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 - - `Address to bind' and `port number to bind' specify the IP address - and port to which the socket to be listened is bound. The address - should be "0.0.0.0" if connections are allowed from anywhere. - (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 - 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_GLOBAL_REQUEST_SUCCESS - uint32 port that was bound on the server - - A port forwarding can be cancelled with the following message. - Note that channel open requests may be received until a reply to - - - -Ylonen, et. al. Expires January 12, 2004 [Page 14] - -Internet-Draft SSH Connection Protocol July 2003 - - - 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. - - 5.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 be sent also 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 - - `Host to connect' and `port to connect' specify the TCP/IP host - - - -Ylonen, et. al. Expires January 12, 2004 [Page 15] - -Internet-Draft SSH Connection Protocol July 2003 - - - and port where the recipient should connect the channel. `Host to - connect' may be either a domain name or a numeric IP address. - - `Originator IP address' is the numeric IP address of the machine - where the connection request comes from, and `originator port' is - the port on the originator host from where the connection came - from. - - 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. - - Client implementations SHOULD reject direct TCP/IP open requests - for security reasons. - - 6. Encoding of Terminal Modes - - 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 tty mode description is a stream of bytes. The stream - consists of opcode-argument pairs. It is terminated by opcode - TTY_OP_END (0). 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 client SHOULD put in the stream any modes it knows about, 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 following opcodes have been defined. The naming of opcodes - mostly follows the POSIX terminal mode flags. - - 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. - - - -Ylonen, et. al. Expires January 12, 2004 [Page 16] - -Internet-Draft SSH Connection Protocol July 2003 - - - 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. - 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 set, 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 - - - -Ylonen, et. al. Expires January 12, 2004 [Page 17] - -Internet-Draft SSH Connection Protocol July 2003 - - - (output). - 75 ONLRET Newline performs a carriage return (output). - 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. - - - 7. Summary of Message Numbers - - #define SSH_MSG_GLOBAL_REQUEST 80 - #define SSH_MSG_REQUEST_SUCCESS 81 - #define SSH_MSG_REQUEST_FAILURE 82 - #define SSH_MSG_CHANNEL_OPEN 90 - #define SSH_MSG_CHANNEL_OPEN_CONFIRMATION 91 - #define SSH_MSG_CHANNEL_OPEN_FAILURE 92 - #define SSH_MSG_CHANNEL_WINDOW_ADJUST 93 - #define SSH_MSG_CHANNEL_DATA 94 - #define SSH_MSG_CHANNEL_EXTENDED_DATA 95 - #define SSH_MSG_CHANNEL_EOF 96 - #define SSH_MSG_CHANNEL_CLOSE 97 - #define SSH_MSG_CHANNEL_REQUEST 98 - #define SSH_MSG_CHANNEL_SUCCESS 99 - #define SSH_MSG_CHANNEL_FAILURE 100 - - - 8. 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. - - 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. - - Full security considerations for this protocol are provided in - Section 8 of [SSH-ARCH] - - 9. 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 - - - -Ylonen, et. al. Expires January 12, 2004 [Page 18] - -Internet-Draft SSH Connection Protocol July 2003 - - - 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. - - 10. Additional Information - - The current document editor is: Darren.Moffat@Sun.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 - -References - - [RFC1766] Alvestrand, H., "Tags for the Identification of - Languages", RFC 1766, March 1995. - - [RFC1884] Hinden, R., Deering, S. and Editors, "IP Version 6 - Addressing Architecture", RFC 1884, December 1995. - - [RFC2279] Yergeau, F., "UTF-8, a transformation format of - ISO 10646", RFC 2279, January 1998. - - [SCHEIFLER] Scheifler, R., "X Window System : The Complete - Reference to Xlib, X Protocol, Icccm, Xlfd, 3rd - edition.", Digital Press ISBN 1555580882, Feburary - 1992. - - [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. - - [SSH-ARCH] Ylonen, T., "SSH Protocol Architecture", I-D - draft-ietf-architecture-14.txt, July 2003. - - - - -Ylonen, et. al. Expires January 12, 2004 [Page 19] - -Internet-Draft SSH Connection Protocol July 2003 - - - [SSH-TRANS] Ylonen, T., "SSH Transport Layer Protocol", I-D - draft-ietf-transport-16.txt, July 2003. - - [SSH-USERAUTH] Ylonen, T., "SSH Authentication Protocol", I-D - draft-ietf-userauth-17.txt, July 2003. - - [SSH-CONNECT] Ylonen, T., "SSH Connection Protocol", I-D draft- - ietf-connect-17.txt, July 2003. - - [SSH-NUMBERS] Lehtinen, S. and D. Moffat, "SSH Protocol Assigned - Numbers", I-D draft-ietf-secsh-assignednumbers- - 03.txt, July 2003. - - -Authors' Addresses - - Tatu Ylonen - SSH Communications Security Corp - Fredrikinkatu 42 - HELSINKI FIN-00100 - Finland - - EMail: ylo@ssh.com - - - Tero Kivinen - SSH Communications Security Corp - Fredrikinkatu 42 - HELSINKI FIN-00100 - Finland - - EMail: kivinen@ssh.com - - - Markku-Juhani O. Saarinen - University of Jyvaskyla - - - Timo J. Rinne - SSH Communications Security Corp - Fredrikinkatu 42 - HELSINKI FIN-00100 - Finland - - EMail: tri@ssh.com - - - - - - -Ylonen, et. al. Expires January 12, 2004 [Page 20] - -Internet-Draft SSH Connection Protocol July 2003 - - - Sami Lehtinen - SSH Communications Security Corp - Fredrikinkatu 42 - HELSINKI FIN-00100 - Finland - - EMail: sjl@ssh.com - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Ylonen, et. al. Expires January 12, 2004 [Page 21] - -Internet-Draft SSH Connection Protocol July 2003 - - -Full Copyright Statement - - Copyright (C) The Internet Society (2003). 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, et. al. Expires January 12, 2004 [Page 22] - diff --git a/doc/draft-ietf-secsh-dh-group-exchange-04.txt b/doc/draft-ietf-secsh-dh-group-exchange-04.txt deleted file mode 100644 index ee6b2fb8..00000000 --- a/doc/draft-ietf-secsh-dh-group-exchange-04.txt +++ /dev/null @@ -1,451 +0,0 @@ - - - - - - -Network Working Group Markus Friedl -INTERNET-DRAFT Niels Provos -Expires in six months William A. Simpson - July 2003 - - - Diffie-Hellman Group Exchange for the SSH Transport Layer Protocol - draft-ietf-secsh-dh-group-exchange-04.txt - - -1. 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 docu- - ments 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. - -2. Copyright Notice - - Copyright (C) 2000-2003 by Markus Friedl, Niels Provos and William - A. Simpson. - -3. Abstract - - This memo describes a new key exchange method for the SSH protocol. - It allows the SSH server to propose to the client new groups on - which to perform the Diffie-Hellman key exchange. The proposed - groups need not be fixed and can change with time. - -4. Overview and Rational - - SSH [4,5,6,7] is a a very common protocol for secure remote login - on the Internet. Currently, SSH performs the initial key exchange - - - -Friedl/Provos/Simpson expires in six months [Page 1] - -INTERNET DRAFT July 2003 - - - using the "diffie-hellman-group1-sha1" method. This method pre- - scribes a fixed group on which all operations are performed. - - The Diffie-Hellman key exchange provides a shared secret that can - not be determined by either party alone. 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 effi- - cient algorithms to compute the discrete logarithm over a fixed - group might pose a security threat to the SSH protocol. - - The ability to propose new groups will reduce the incentive to use - precomputation for more efficient calculation of the discrete loga- - rithm. The server can constantly compute new groups in the back- - ground. - -5. 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 gener- - ated subgroup does not factor into small primes, i.e., 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 dis- - tributed 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"). - - Implementation Notes: - - One useful technique is to select the generator, and then - limit the modulus selection sieve to primes with that genera- - tor: - - 2 when p (mod 24) = 11. - 5 when p (mod 10) = 3 or 7. - - 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. - - - - - -Friedl/Provos/Simpson expires in six months [Page 2] - -INTERNET DRAFT July 2003 - - - The client requests a modulus from the server indicating the pre- - ferred 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 genera- - tor 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 S's KEXINIT message - which have been exchanged before this part begins): - - 1. C sends "min || n || max" to S, indicating the minimal accept- - able group size, the preferred size of the group and the maxi- - mal 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 (1 < x < (p-1)/2). It computes e - = g^x mod p, and sends "e" to S. - - 4. S generates a random number y (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 opera- - tion may involve a second hashing operation. - - Implementation Notes: - - To increase the speed of the key exchange, both client - and server may reduce the size of their private expo- - nents. 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 - [1]. - - 5. 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 || min || n || max || p || g || e || - f || K), and verifies the signature s on H. - - Servers and clients SHOULD support groups with a modulus - - - -Friedl/Provos/Simpson expires in six months [Page 3] - -INTERNET DRAFT July 2003 - - - 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 algo- - rithm 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 should send - uint32 max, maximal size in bits of an acceptable group - - 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 - - - -Friedl/Provos/Simpson expires in six months [Page 4] - -INTERNET DRAFT July 2003 - - - uint32 min, minimal size in bits of an acceptable group - uint32 n, preferred size in bits of the group the server should 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 authenti- - cate the key exchange. - - -6. diffie-hellman-group-exchange-sha1 - - The "diffie-hellman-group-exchange-sha1" method specifies Diffie- - Hellman Group and Key Exchange with SHA-1 as HASH. - -7. Summary of Message numbers - - The following message numbers have been defined in this document. - - #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 backwards compatibility. - Instead of sending "min || n || max", the client only sends "n". - Additionally, 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. - -8. Security Considerations - - This protocol aims to be simple and uses only well understood prim- - itives. This encourages acceptance by the community and allows for - ease of implementation, which hopefully leads to a more secure sys- - tem. - - The use of multiple moduli inhibits a determined attacker from pre- - calculating moduli exchange values, and discourages dedication of - resources for analysis of any particular modulus. - - It is important to employ only safe primes as moduli. Van Oorshot - - - -Friedl/Provos/Simpson expires in six months [Page 5] - -INTERNET DRAFT July 2003 - - - and Wiener note that using short private exponents with a random - prime modulus p makes the computation of the discrete logarithm - easy [1]. 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 [2]. However, this is not a prob- - lem, 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) [3]. - -9. Acknowledgments - - The document is derived in part from "SSH Transport Layer Protocol" - 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, reduc- - ing the complexity of the implementation and the amount of data - that needs to be exchanged between client and server. - -10. Bibliography - - - 10.1. Informative References - - - [1] P. C. van Oorschot and M. J. Wiener, On Diffie-Hellman key - agreement with short exponents, In Advances in Cryptology - - EUROCRYPT'96, LNCS 1070, Springer-Verlag, 1996, pp.332-343. - - [2] Alfred J. Menezes, Paul C. van Oorschot, and Scott A. Van- - stone. Handbook of Applied Cryptography. CRC Press, 1996. - - [3] C. P. Waldvogel and J. L. Massey, The probability distribution - of the Diffie-Hellman key, in Proceedings of AUSCRYPT 92, LNCS - 718, Springer- Verlag, 1993, pp. 492-504. - - - - - - - - - - -Friedl/Provos/Simpson expires in six months [Page 6] - -INTERNET DRAFT July 2003 - - - 10.2. Normative References - - - [4] Ylonen, T., et al: "SSH Protocol Architecture", Internet- - Draft, draft-secsh-architecture-07.txt - - [5] Ylonen, T., et al: "SSH Transport Layer Protocol", Internet- - Draft, draft-ietf-secsh-transport-09.txt - - [6] Ylonen, T., et al: "SSH Authentication Protocol", Internet- - Draft, draft-ietf-secsh-userauth-09.txt - - [7] Ylonen, T., et al: "SSH Connection Protocol", Internet-Draft, - draft-ietf-secsh-connect-09.txt - - - -11. Appendix A: Generation of safe primes - - The Handbook of Applied Cryptography [2] lists the following algo- - rithm 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.1 Select a random (k-1)-bit prime q, so that q mod 12 = 5. - 1.2 Compute p := 2q + 1, and test whether p is prime, (using, e.g. - trial division and the Rabin-Miller test.) - 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 fol- - lows: - - 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. - - - - - - - - - - - - - -Friedl/Provos/Simpson expires in six months [Page 7] - -INTERNET DRAFT July 2003 - - -12. Author's Address - - Markus Friedl - Ganghoferstr. 7 - 80339 Munich - Germany - - Email: markus@openbsd.org - - Niels Provos - Center for Information Technology Integration - 535 W. William Street - Ann Arbor, MI, 48103 - - Phone: (734) 764-5207 - Email: provos@citi.umich.edu - - William Allen Simpson - DayDreamer - Computer Systems Consulting Services - 1384 Fontaine - Madion Heights, Michigan 48071 - - Email: wsimpson@greendragon.com - - - - - - - - - - - - - - - - - - - - - - - - - - - -Friedl/Provos/Simpson expires in six months [Page 8] - diff --git a/doc/draft-ietf-secsh-dns-04.txt b/doc/draft-ietf-secsh-dns-04.txt deleted file mode 100644 index 7667a5e8..00000000 --- a/doc/draft-ietf-secsh-dns-04.txt +++ /dev/null @@ -1,616 +0,0 @@ - - -Secure Shell Working Group J. Schlyter -Internet-Draft Carlstedt Research & -Expires: October 1, 2003 Technology - W. Griffin - Network Associates Laboratories - April 2, 2003 - - - Using DNS to securely publish SSH key fingerprints - draft-ietf-secsh-dns-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 October 1, 2003. - -Copyright Notice - - Copyright (C) The Internet Society (2003). All Rights Reserved. - -Abstract - - This document describes a method to verify SSH host keys using - DNSSEC. The document defines a new DNS resource record that contains - a standard SSH key fingerprint. - - - - - - - - - - -Schlyter & Griffin Expires October 1, 2003 [Page 1] - -Internet-Draft DNS and SSH fingerprints April 2003 - - -Table of Contents - - 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 - 2. SSH Host Key Verification . . . . . . . . . . . . . . . . . 3 - 2.1 Method . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 - 2.2 Implementation Notes . . . . . . . . . . . . . . . . . . . . 3 - 2.3 Fingerprint Matching . . . . . . . . . . . . . . . . . . . . 4 - 2.4 Authentication . . . . . . . . . . . . . . . . . . . . . . . 4 - 3. The SSHFP Resource Record . . . . . . . . . . . . . . . . . 4 - 3.1 The SSHFP RDATA Format . . . . . . . . . . . . . . . . . . . 4 - 3.1.1 Algorithm Number Specification . . . . . . . . . . . . . . . 5 - 3.1.2 Fingerprint Type Specification . . . . . . . . . . . . . . . 5 - 3.1.3 Fingerprint . . . . . . . . . . . . . . . . . . . . . . . . 5 - 3.2 Presentation Format of the SSHFP RR . . . . . . . . . . . . 6 - 4. Security Considerations . . . . . . . . . . . . . . . . . . 6 - 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . 7 - Normative References . . . . . . . . . . . . . . . . . . . . 8 - Informational References . . . . . . . . . . . . . . . . . . 8 - Authors' Addresses . . . . . . . . . . . . . . . . . . . . . 8 - A. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 9 - Intellectual Property and Copyright Statements . . . . . . . 10 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Schlyter & Griffin Expires October 1, 2003 [Page 2] - -Internet-Draft DNS and SSH fingerprints April 2003 - - -1. Introduction - - The SSH [5] 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. - - Server authentication is normally done by presenting the fingerprint - of an unknown public key to the user for verification. If the user - decides 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 - accepts 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 [4] to verify the lookup. - - In order to distribute the fingerprint using DNS, this document - defines a new DNS resource record to carry the fingerprint. - - Basic understanding of the DNS system [1][2] and the DNS security - extensions [4] 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 a 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 - matches 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 [5] 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 - configurable policy will allow administrators to determine which - - - -Schlyter & Griffin Expires October 1, 2003 [Page 3] - -Internet-Draft DNS and SSH fingerprints April 2003 - - - 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 - SSH FP fingerprint. - - -2.4 Authentication - - A public key verified using this method MUST only be trusted if the - SSHFP resource record (RR) used for verification was authenticated by - a trusted SIG RR. - - Clients that do not validate the DNSSEC signatures themselves MUST - use a secure transport, e.g. TSIG [8], SIG(0) [9] or IPsec [7], - 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 a - SSH public host key that is associated with a Domain Name System - (DNS) name. - - The RR type code for the SSHFP RR is TBA. - -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. - - - -Schlyter & Griffin Expires October 1, 2003 [Page 4] - -Internet-Draft DNS and SSH fingerprints April 2003 - - - 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. - -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. For interoperability - reasons, as few fingerprint types as possible should be reserved. - The only reason to reserve additional types is to increase security. - -3.1.3 Fingerprint - - The fingerprint is calculated over the public key blob as described - in [6]. - - The message-digest algorithm is presumed to produce an opaque octet - string output which is placed as-is in the RDATA fingerprint field. - - - - - -Schlyter & Griffin Expires October 1, 2003 [Page 5] - -Internet-Draft DNS and SSH fingerprints April 2003 - - -3.2 Presentation Format of the SSHFP RR - - 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 - - -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 approach suggested here shifts the burden of key checking from - each user of a machine to the key checking performed by the - administrator of the DNS recursive server used to resolve the host - information. Hopefully, by reducing the number of times that keys - need to be verified by hand, each verification is performed more - completely. Furthermore, by requiring an administrator do the - checking, the result may be more reliable than placing this task in - the hands of an application user. - - The overall security of using SSHFP for SSH host key verification is - dependent on detailed aspects of how verification is done in SSH - implementations. 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, - we can implement SSH host key revocation by removing the - corresponding SSHFP from DNS. - - 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 - - - -Schlyter & Griffin Expires October 1, 2003 [Page 6] - -Internet-Draft DNS and SSH fingerprints April 2003 - - - 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 [10] - 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 needs to allocate a RR type code for SSHFP from the standard RR - type space (type 44 requested). - - IANA needs to open a new registry for the SSHFP RR type for public - key algorithms. Defined types are: - - 0 is reserved - 1 is RSA - 2 is DSA - - Adding new reservations requires IETF consensus. - - IANA needs to open a new registry for the SSHFP RR type for - fingerprint types. Defined types are: - - 0 is reserved - 1 is SHA-1 - - Adding new reservations requires IETF consensus. - -Normative References - - - -Schlyter & Griffin Expires October 1, 2003 [Page 7] - -Internet-Draft DNS and SSH fingerprints April 2003 - - - [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] Eastlake, D., "Domain Name System Security Extensions", RFC - 2535, March 1999. - - [5] Rinne, T., Ylonen, T., Kivinen, T. 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 Transport Layer Protocol", - draft-ietf-secsh-transport-15 (work in progress), September - 2002. - -Informational References - - [7] Thayer, R., Doraswamy, N. and R. Glenn, "IP Security Document - Roadmap", RFC 2411, November 1998. - - [8] Vixie, P., Gudmundsson, O., Eastlake, D. and B. Wellington, - "Secret Key Transaction Authentication for DNS (TSIG)", RFC - 2845, May 2000. - - [9] Eastlake, D., "DNS Request and Transaction Signatures ( - SIG(0)s)", RFC 2931, September 2000. - - [10] Wellington, B., "Secure Domain Name System (DNS) Dynamic - Update", RFC 3007, November 2000. - - -Authors' Addresses - - Jakob Schlyter - Carlstedt Research & Technology - Stora Badhusgatan 18-20 - Goteborg SE-411 21 - Sweden - - EMail: jakob@crt.se - URI: http://www.crt.se/~jakob/ - - - - -Schlyter & Griffin Expires October 1, 2003 [Page 8] - -Internet-Draft DNS and SSH fingerprints April 2003 - - - Wesley Griffin - Network Associates Laboratories - 15204 Omega Drive Suite 300 - Rockville, MD 20850 - USA - - EMail: wgriffin@tislabs.com - URI: http://www.nailabs.com/ - -Appendix A. Acknowledgements - - The authors gratefully acknowledges, in no particular order, the - contributions of the following persons: - - Martin Fredriksson - - Olafur Gudmundsson - - Edward Lewis - - Bill Sommerfeld - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Schlyter & Griffin Expires October 1, 2003 [Page 9] - -Internet-Draft DNS and SSH fingerprints April 2003 - - -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 (2003). 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 - - - -Schlyter & Griffin Expires October 1, 2003 [Page 10] - -Internet-Draft DNS and SSH fingerprints April 2003 - - - 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. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Schlyter & Griffin Expires October 1, 2003 [Page 11] - diff --git a/doc/draft-ietf-secsh-filexfer-02.txt b/doc/draft-ietf-secsh-filexfer-02.txt deleted file mode 100644 index 45e979e8..00000000 --- a/doc/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] - - - diff --git a/doc/draft-ietf-secsh-filexfer-03.txt b/doc/draft-ietf-secsh-filexfer-03.txt deleted file mode 100644 index 83960ae9..00000000 --- a/doc/draft-ietf-secsh-filexfer-03.txt +++ /dev/null @@ -1,1962 +0,0 @@ - - - -Secure Shell Working Group J. Galbraith -Internet-Draft VanDyke Software -Expires: April 16, 2003 T. Ylonen - S. Lehtinen - SSH Communications Security Corp - October 16, 2002 - - - SSH File Transfer Protocol - draft-ietf-secsh-filexfer-03.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 16, 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 April 16, 2003 [Page 1] - -Internet-Draft SSH File Transfer Protocol October 2002 - - -Table of Contents - - 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . 3 - 2. Use with the SSH Connection Protocol . . . . . . . . . . . 4 - 3. General Packet Format . . . . . . . . . . . . . . . . . . 5 - 4. Protocol Initialization . . . . . . . . . . . . . . . . . 7 - 4.1 Client Initialization . . . . . . . . . . . . . . . . . . 7 - 4.2 Server Initialization . . . . . . . . . . . . . . . . . . 7 - 4.3 Determining Server Newline Convention . . . . . . . . . . 8 - 5. File Attributes . . . . . . . . . . . . . . . . . . . . . 9 - 5.1 Flags . . . . . . . . . . . . . . . . . . . . . . . . . . 9 - 5.2 Type . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 - 5.3 Size . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 - 5.4 Owner and Group . . . . . . . . . . . . . . . . . . . . . 10 - 5.5 Permissions . . . . . . . . . . . . . . . . . . . . . . . 11 - 5.6 Times . . . . . . . . . . . . . . . . . . . . . . . . . . 11 - 5.7 ACL . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 - 5.8 Extended attributes . . . . . . . . . . . . . . . . . . . 12 - 6. Requests From the Client to the Server . . . . . . . . . . 13 - 6.1 Request Synchronization and Reordering . . . . . . . . . . 13 - 6.2 File Names . . . . . . . . . . . . . . . . . . . . . . . . 14 - 6.3 Opening, Creating, and Closing Files . . . . . . . . . . . 14 - 6.4 Reading and Writing . . . . . . . . . . . . . . . . . . . 17 - 6.5 Removing and Renaming Files . . . . . . . . . . . . . . . 18 - 6.6 Creating and Deleting Directories . . . . . . . . . . . . 19 - 6.7 Scanning Directories . . . . . . . . . . . . . . . . . . . 19 - 6.8 Retrieving File Attributes . . . . . . . . . . . . . . . . 20 - 6.9 Setting File Attributes . . . . . . . . . . . . . . . . . 21 - 6.10 Dealing with Symbolic links . . . . . . . . . . . . . . . 22 - 6.11 Canonicalizing the Server-Side Path Name . . . . . . . . . 23 - 6.11.1 Best practice for dealing with paths . . . . . . . . . . . 23 - 7. Responses from the Server to the Client . . . . . . . . . 24 - 8. Vendor-Specific Extensions . . . . . . . . . . . . . . . . 28 - 9. Security Considerations . . . . . . . . . . . . . . . . . 29 - 10. Changes from previous protocol versions . . . . . . . . . 30 - 10.1 Changes between versions 4 and 3 . . . . . . . . . . . . . 30 - 10.2 Changes between versions 3 and 2 . . . . . . . . . . . . . 31 - 10.3 Changes between versions 2 and 1 . . . . . . . . . . . . . 31 - 10.4 Changes between versions 1 and 0 . . . . . . . . . . . . . 31 - 11. Trademark Issues . . . . . . . . . . . . . . . . . . . . . 32 - References . . . . . . . . . . . . . . . . . . . . . . . . 33 - Authors' Addresses . . . . . . . . . . . . . . . . . . . . 33 - Full Copyright Statement . . . . . . . . . . . . . . . . . 35 - - - - - - - - -Galbraith, et al. Expires April 16, 2003 [Page 2] - -Internet-Draft SSH File Transfer Protocol October 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 April 16, 2003 [Page 3] - -Internet-Draft SSH File Transfer Protocol October 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 April 16, 2003 [Page 4] - -Internet-Draft SSH File Transfer Protocol October 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 April 16, 2003 [Page 5] - -Internet-Draft SSH File Transfer Protocol October 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. - - - - - - - - - - - - - -Galbraith, et al. Expires April 16, 2003 [Page 6] - -Internet-Draft SSH File Transfer Protocol October 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 April 16, 2003 [Page 7] - -Internet-Draft SSH File Transfer Protocol October 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 April 16, 2003 [Page 8] - -Internet-Draft SSH File Transfer Protocol October 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 SSH_FILEXFER_ATTR_SIZE - string owner present only if flag SSH_FILEXFER_ATTR_OWNERGROUP - string group present only if flag SSH_FILEXFER_ATTR_OWNERGROUP - uint32 permissions present only if flag SSH_FILEXFER_ATTR_PERMISSIONS - uint32 atime present only if flag SSH_FILEXFER_ATTR_ACCESSTIME - uint32 createtime present only if flag SSH_FILEXFER_ATTR_CREATETIME - uint32 mtime present only if flag SSH_FILEXFER_ATTR_MODIFYTIME - string acl present only if flag SSH_FILEXFER_ATTR_ACL - 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 - - -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: - - #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_EXTENDED 0x80000000 - - - - -Galbraith, et al. Expires April 16, 2003 [Page 9] - -Internet-Draft SSH File Transfer Protocol October 2002 - - - 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 - 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. - - - -Galbraith, et al. Expires April 16, 2003 [Page 10] - -Internet-Draft SSH File Transfer Protocol October 2002 - - -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. - -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]: - - 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: - - - - - - -Galbraith, et al. Expires April 16, 2003 [Page 11] - -Internet-Draft SSH File Transfer Protocol October 2002 - - - 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) - -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 April 16, 2003 [Page 12] - -Internet-Draft SSH File Transfer Protocol October 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 April 16, 2003 [Page 13] - -Internet-Draft SSH File Transfer Protocol October 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 April 16, 2003 [Page 14] - -Internet-Draft SSH File Transfer Protocol October 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 April 16, 2003 [Page 15] - -Internet-Draft SSH File Transfer Protocol October 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 April 16, 2003 [Page 16] - -Internet-Draft SSH File Transfer Protocol October 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 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: - - - - - - - -Galbraith, et al. Expires April 16, 2003 [Page 17] - -Internet-Draft SSH File Transfer Protocol October 2002 - - - 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' - point to different file systems on the server. - - The server will respond to this request with a SSH_FXP_STATUS - - - -Galbraith, et al. Expires April 16, 2003 [Page 18] - -Internet-Draft SSH File Transfer Protocol October 2002 - - - 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 - 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 - - - -Galbraith, et al. Expires April 16, 2003 [Page 19] - -Internet-Draft SSH File Transfer Protocol October 2002 - - - 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 - 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 - - - -Galbraith, et al. Expires April 16, 2003 [Page 20] - -Internet-Draft SSH File Transfer Protocol October 2002 - - - 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: - - 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 - - - -Galbraith, et al. Expires April 16, 2003 [Page 21] - -Internet-Draft SSH File Transfer Protocol October 2002 - - - 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 - - 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 - - - -Galbraith, et al. Expires April 16, 2003 [Page 22] - -Internet-Draft SSH File Transfer Protocol October 2002 - - - 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 April 16, 2003 [Page 23] - -Internet-Draft SSH File Transfer Protocol October 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 April 16, 2003 [Page 24] - -Internet-Draft SSH File Transfer Protocol October 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 - - 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 - client, and MUST NOT be returned by servers). - - - -Galbraith, et al. Expires April 16, 2003 [Page 25] - -Internet-Draft SSH File Transfer Protocol October 2002 - - - 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. - - 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: - - - - - - - - -Galbraith, et al. Expires April 16, 2003 [Page 26] - -Internet-Draft SSH File Transfer Protocol October 2002 - - - 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 April 16, 2003 [Page 27] - -Internet-Draft SSH File Transfer Protocol October 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 April 16, 2003 [Page 28] - -Internet-Draft SSH File Transfer Protocol October 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 April 16, 2003 [Page 29] - -Internet-Draft SSH File Transfer Protocol October 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 Make all filenames UTF-8. - - o Added 'newline' extension. - - 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. - - o Change the way version negotiate works slightly. Previously, if - the client version were higher than the server version, the server - was supposed to 'echo back' the clients version. The server now - sends it's own version and the lower of the two is considered to - be the one in use. - - - - - - - -Galbraith, et al. Expires April 16, 2003 [Page 30] - -Internet-Draft SSH File Transfer Protocol October 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 April 16, 2003 [Page 31] - -Internet-Draft SSH File Transfer Protocol October 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 April 16, 2003 [Page 32] - -Internet-Draft SSH File Transfer Protocol October 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 April 16, 2003 [Page 33] - -Internet-Draft SSH File Transfer Protocol October 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 April 16, 2003 [Page 34] - -Internet-Draft SSH File Transfer Protocol October 2002 - - -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 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. - - - - - - - - - - - - - - - - - - - -Galbraith, et al. Expires April 16, 2003 [Page 35] - - diff --git a/doc/draft-ietf-secsh-filexfer-04.txt b/doc/draft-ietf-secsh-filexfer-04.txt deleted file mode 100644 index 9f51883c..00000000 --- a/doc/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] - - diff --git a/doc/draft-ietf-secsh-fingerprint-01.txt b/doc/draft-ietf-secsh-fingerprint-01.txt deleted file mode 100644 index 5edea39d..00000000 --- a/doc/draft-ietf-secsh-fingerprint-01.txt +++ /dev/null @@ -1,120 +0,0 @@ - - - - - - -INTERNET-DRAFT Markus Friedl -draft-ietf-secsh-fingerprint-01.txt The OpenBSD Project -Expires in six months September 2003 - - - SSH Fingerprint Format - - -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 docu- ments 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. - - Distribution of this memo is unlimited. - -Abstract - - This document formally documents the fingerprint format in use for - verifying public keys from SSH clients and servers. - -Introduction - - The security of the SSH protocols relies on the verification of - public host keys. Since public keys tend to be very large, it is - difficult for a human to verify an entire host key. Even with a PKI - in place, it is useful to have a standard for exchanging short - fingerprints of public keys. - - This document formally describes the simple key fingerprint format. - - - - - - -Friedl [Page 1] - - - - - -INTERNET-DRAFT March 2003 - - -Fingerprint Format - - The fingerprint of a public key consists of the output of the MD5 - message-digest algorithm [RFC-1321]. The input to the algorithm is - the public key blob as described in [SSH-TRANS]. The output of the - algorithm is presented to the user as a sequence of 16 octets printed - as hexadecimal with lowercase letters and separated by colons. - - For example: "c1:b1:30:29:d7:b8:de:6c:97:77:10:d7:46:41:63:87" - -References - - [SSH-TRANS] Ylonen, T., et al: "SSH Transport Layer Protocol", - Internet Draft, draft-secsh-transport-15.txt - - [RFC-1321] R. Rivest: "The MD5 Message-Digest Algorithm", April 1992. - - [RFC-2026] S. Bradner: "The Internet Standards Process -- Revision - 3", October 1996. - -Author's Address: - - Markus Friedl - markus@openbsd.org - Munich, Germany - - - - - - - - - - - - - - - - - - - - - - - - - - -Friedl [Page 2] - - diff --git a/doc/draft-ietf-secsh-gsskeyex-06.txt b/doc/draft-ietf-secsh-gsskeyex-06.txt deleted file mode 100644 index da442579..00000000 --- a/doc/draft-ietf-secsh-gsskeyex-06.txt +++ /dev/null @@ -1,1509 +0,0 @@ - - -Network Working Group J. Hutzelman -Internet-Draft CMU -Expires: August 31, 2003 J. Salowey - Cisco Systems - J. Galbraith - Van Dyke Technologies, Inc. - V. Welch - U Chicago / ANL - March 2, 2003 - - - GSSAPI Authentication and Key Exchange for the Secure Shell Protocol - draft-ietf-secsh-gsskeyex-06 - -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 August 31, 2003. - -Copyright Notice - - Copyright (C) The Internet Society (2003). All Rights Reserved. - -Abstract - - The Secure Shell protocol (SSH) is a protocol for secure remote - login and other secure network services over an insecure network. - - The Generic Security Service Application Program Interface (GSS-API) - [2] provides security services to callers in a mechanism-independent - fashion. - - - -Hutzelman, et. al. Expires August 31, 2003 [Page 1] - -Internet-Draft SSH GSSAPI Methods March 2003 - - - This memo describes methods for using the GSS-API for authentication - and key exchange in SSH. It defines an SSH user authentication - method which uses a specified GSSAPI mechanism to authenticate a - user, and a family of SSH key exchange methods which use GSSAPI to - authenticate the Diffie-Hellman exchange described in [8]. - - This memo also defines a new host public key algorithm which can be - used when no operations are needed using a host's public key, and a - new user authentication method which allows an authorization name to - be used in conjunction with any authentication which has already - occurred as a side-effect of key exchange. - - 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 [5]. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Hutzelman, et. al. Expires August 31, 2003 [Page 2] - -Internet-Draft SSH GSSAPI Methods March 2003 - - -1. Introduction - - This document describes the methods used to perform key exchange and - user authentication in the Secure Shell protocol using the GSSAPI. - To do this, it defines a family of key exchange methods, two user - authentication methods, and a new host key algorithm. These - definitions allow any GSSAPI mechanism to be used with the Secure - Shell protocol. - - This document should be read only after reading the documents - describing the SSH protocol architecture [6], transport layer - protocol [8], and user authentication protocol [9]. This document - freely uses terminology and notation from the architecture document - without reference or further explanation. - -1.1 SSH terminology - - The data types used in the packets are defined in the SSH - architecture document [6]. It is particularly important to note the - definition of string allows binary content. - - The SSH_MSG_USERAUTH_REQUEST packet refers to a service; this - service name is an SSH service name, and has no relationship to - GSSAPI service names. Currently, the only defined service name is - "ssh-connection", which refers to the SSH connection protocol [7]. - - - - - - - - - - - - - - - - - - - - - - - - - - -Hutzelman, et. al. Expires August 31, 2003 [Page 3] - -Internet-Draft SSH GSSAPI Methods March 2003 - - -2. GSSAPI Authenticated Diffie-Hellman Key Exchange - - This section defines a class of key exchange methods which combine - the Diffie-Hellman key exchange from section 6 of [8] with mutual - authentication using GSSAPI. - - Since the GSSAPI key exchange methods described in this section do - not require the use of public key signature or encryption - algorithms, they MAY be used with any host key algorithm, including - the "null" algorithm described in Section 5. - -2.1 Generic GSSAPI Key Exchange - - The following symbols are used in this description: - - o C is the client, and S is the server - - o p is a large safe prime, g is a generator for a subgroup of - GF(p), and q is the order of the subgroup - - o V_S is S's version string, and V_C is C's version string - - o I_C is C's KEXINIT message, and I_S is S's KEXINIT message - - 1. C generates a random number x (1 < x < q) and computes e = g^x - mod p. - - 2. C calls GSS_Init_sec_context, using the most recent reply token - received from S during this exchange, if any. For this call, - the client MUST set the mutual_req_flag to "true" to request - that mutual authentication be performed. It also MUST set the - integ_req_flag to "true" to request that per-message integrity - protection be supported for this context. In addition, the - deleg_req_flag MAY be set to "true" to request access - delegation, if requested by the user. Since the key exchange - process authenticates only the host, the setting of the - anon_req_flag is immaterial to this process. If the client does - not support the "external-keyx" user authentication method - described in Section 4, or does not intend to use that method, - then the anon_req_flag SHOULD be set to "true". Otherwise, this - flag MAY be set to true if the client wishes to hide its - identity. - - * If the resulting major_status code is GSS_S_COMPLETE and the - mutual_state flag is not true, then mutual authentication has - not been established, and the key exchange MUST fail. - - * If the resulting major_status code is GSS_S_COMPLETE and the - integ_avail flag is not true, then per-message integrity - - -Hutzelman, et. al. Expires August 31, 2003 [Page 4] - -Internet-Draft SSH GSSAPI Methods March 2003 - - - protection is not available, and the key exchange MUST fail. - - * If the resulting major_status code is GSS_S_COMPLETE and both - the mutual_state and integ_avail flags are true, the - resulting output token is sent to S. - - * If the resulting major_status code is GSS_S_CONTINUE_NEEDED, - the the output_token is sent to S, which will reply with a - new token to be provided to GSS_Init_sec_context. - - * The client MUST also include "e" with the first message it - sends to the server during this process; if the server - receives more than one "e" or none at all, the key exchange - fails. - - * It is an error if the call does not produce a token of - non-zero length to be sent to the server. In this case, the - key exchange MUST fail. - - 3. S calls GSS_Accept_sec_context, using the token received from C. - - * If the resulting major_status code is GSS_S_COMPLETE and the - mutual_state flag is not true, then mutual authentication has - not been established, and the key exchange MUST fail. - - * If the resulting major_status code is GSS_S_COMPLETE and the - integ_avail flag is not true, then per-message integrity - protection is not available, and the key exchange MUST fail. - - * If the resulting major_status code is GSS_S_COMPLETE and both - the mutual_state and integ_avail flags are true, then the - security context has been established, and processing - continues with step 4. - - * If the resulting major_status code is GSS_S_CONTINUE_NEEDED, - then the output token is sent to C, and processing continues - with step 2. - - * If the resulting major_status code is GSS_S_COMPLETE, but a - non-zero-length reply token is returned, then that token is - sent to the client. - - 4. S generates a random number y (0 < y < q) and computes f = g^y - mod p. It computes K = e ^ y mod p, and H = hash(V_C || V_S || - I_C || I_S || K_S || e || f || K). It then calls GSS_GetMIC to - obtain a GSSAPI message integrity code for H. S then sends f - and the MIC to C. - - 5. This step is performed only if the server's final call to - - -Hutzelman, et. al. Expires August 31, 2003 [Page 5] - -Internet-Draft SSH GSSAPI Methods March 2003 - - - GSS_Accept_sec_context produced a non-zero-length final reply - token to be sent to the client _and_ no previous call by the - client to GSS_Init_sec_context has resulted in a major_status of - GSS_S_COMPLETE. Under these conditions, the client makes an - additional call to GSS_Init_sec_context to process the final - reply token. This call is made exactly as described above. - However, if the resulting major_status is anything other than - GSS_S_COMPLETE, or a non-zero-length token is returned, it is an - error and the key exchange MUST fail. - - 6. C computes K = f^x mod p, and H = hash(V_C || V_S || I_C || I_S - || K_S || e || f || K). It then calls GSS_VerifyMIC to verify - that the MIC sent by S matches H. - - 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. - - If any call to GSS_Init_sec_context or GSS_Accept_sec_context - returns a major_status other than GSS_S_COMPLETE or - GSS_S_CONTINUE_NEEDED, or any other GSSAPI call returns a - major_status other than GSS_S_COMPLETE, the key exchange fails. In - this case, several mechanisms are available for communicating error - information to the peer before terminating the connection as - required by [8]: - - o If the key exchange fails due to any GSSAPI error on the server - (including errors returned by GSS_Accept_sec_context), the server - MAY send a message informing the client of the details of the - error. In this case, if an error token is also sent (see below), - then this message MUST be sent before the error token. - - o If the key exchange fails due to a GSSAPI error returned from the - server's call to GSS_Accept_sec_context, and an "error token" is - also returned, then the server SHOULD send the error token to the - client to allow completion of the GSS security exchange. - - o If the key exchange fails due to a GSSAPI error returned from the - client's call to GSS_Init_sec_context, and an "error token" is - also returned, then the client SHOULD send the error token to the - server to allow completion of the GSS security exchange. - - As noted in Section 9, it may be desirable under site security - policy to obscure information about the precise nature of the error; - thus, it is RECOMMENDED that implementations provide a method to - suppress these messages as a matter of policy. - - This is implemented with the following messages. The hash algorithm - for computing the exchange hash is defined by the method name, and - - -Hutzelman, et. al. Expires August 31, 2003 [Page 6] - -Internet-Draft SSH GSSAPI Methods March 2003 - - - is called HASH. The group used for Diffie-Hellman key exchange and - the underlying GSSAPI mechanism are also defined by the method name. - - After the client's first call to GSS_Init_sec_context, it sends the - following: - - byte SSH_MSG_KEXGSS_INIT - string output_token (from GSS_Init_sec_context) - mpint e - - Upon receiving the SSH_MSG_KEXGSS_INIT message, the server MAY send - the following message, prior to any other messages, to inform the - client of its host key. - - byte SSH_MSG_KEXGSS_HOSTKEY - string server public host key and certificates (K_S) - - Since this key exchange method does not require the host key to be - used for any encryption operations, this message is OPTIONAL. If - the "null" host key algorithm described in Section 5 is used, this - message MUST NOT be sent. If this message is sent, the server - public host key(s) and/or certificate(s) in this message are encoded - as a single string, in the format specified by the public key type - in use (see [8], section 4.6). - - Each time the server's call to GSS_Accept_sec_context returns a - major_status code of GSS_S_CONTINUE_NEEDED, it sends the following - reply to the client: - - byte SSH_MSG_KEXGSS_CONTINUE - string output_token (from GSS_Accept_sec_context) - - If the client receives this message after a call to - GSS_Init_sec_context has returned a major_status code of - GSS_S_COMPLETE, a protocol error has occurred and the key exchange - MUST fail. - - Each time the client receives the message described above, it makes - another call to GSS_Init_sec_context. It then sends the following: - - byte SSH_MSG_KEXGSS_CONTINUE - string output_token (from GSS_Init_sec_context) - - The server and client continue to trade these two messages as long - as the server's calls to GSS_Accept_sec_context result in - major_status codes of GSS_S_CONTINUE_NEEDED. When a call results in - a major_status code of GSS_S_COMPLETE, it sends one of two final - messages. - - - -Hutzelman, et. al. Expires August 31, 2003 [Page 7] - -Internet-Draft SSH GSSAPI Methods March 2003 - - - If the server's final call to GSS_Accept_sec_context (resulting in a - major_status code of GSS_S_COMPLETE) returns a non-zero-length token - to be sent to the client, it sends the following: - - byte SSH_MSG_KEXGSS_COMPLETE - mpint f - string per_msg_token (MIC of H) - boolean TRUE - string output_token (from GSS_Accept_sec_context) - - If the client receives this message after a call to - GSS_Init_sec_context has returned a major_status code of - GSS_S_COMPLETE, a protocol error has occurred and the key exchange - MUST fail. - - If the server's final call to GSS_Accept_sec_context (resulting in a - major_status code of GSS_S_COMPLETE) returns a zero-length token or - no token at all, it sends the following: - - byte SSH_MSG_KEXGSS_COMPLETE - mpint f - string per_msg_token (MIC of H) - boolean FALSE - - If the client receives this message when no call to - GSS_Init_sec_context has yet resulted in a major_status code of - GSS_S_COMPLETE, a protocol error has occurred and the key exchange - MUST fail. - - If either the client's call to GSS_Init_sec_context or the server's - call to GSS_Accept_sec_context returns an error status and produces - an output token (called an "error token"), then the following SHOULD - be sent to convey the error information to the peer: - - byte SSH_MSG_KEXGSS_CONTINUE - string error_token - - If a server sends both this message and an SSH_MSG_KEXGSS_ERROR - message, the SSH_MSG_KEXGSS_ERROR message MUST be sent first, to - allow clients to record and/or display the error information before - processing the error token. This is important because a client - processing an error token will likely disconnect without reading any - further messages. - - - - - - - - -Hutzelman, et. al. Expires August 31, 2003 [Page 8] - -Internet-Draft SSH GSSAPI Methods March 2003 - - - In the event of a GSSAPI error on the server, the server MAY send - the following message before terminating the connection: - - byte SSH_MSG_KEXGSS_ERROR - uint32 major_status - uint32 minor_status - string message - string language tag - - The message text MUST be encoded in the UTF-8 encoding described in - [10]. Language tags are those described in [11]. Note that the - message text may contain multiple lines separated by carriage - return-line feed (CRLF) sequences. Application developers should - take this into account when displaying these messages. - - 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 - 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. If no SSH_MSG_KEXGSS_HOSTKEY message has been sent by the - server or received by the client, then the empty string is used in - place of K_S when computing the exchange hash. - - The GSS_GetMIC call MUST be applied over H, not the original data. - -2.2 gss-group1-sha1-* - - Each of these methods specifies GSSAPI authenticated Diffie-Hellman - key exchange as described in Section 2.1 with SHA-1 as HASH, and the - group defined in section 6.1 of [8]. The method name for each - method is the concatenation of the string "gss-group1-sha1-" with - the Base64 encoding of the MD5 hash [3] of the ASN.1 DER encoding - [1] of the underlying GSSAPI mechanism's OID. Base64 encoding is - described in section 6.8 of [4]. - - Each and every such key exchange method is implicitly registered by - this specification. The IESG is considered to be the owner of all - such key exchange methods; this does NOT imply that the IESG is - considered to be the owner of the underlying GSSAPI mechanism. - - -Hutzelman, et. al. Expires August 31, 2003 [Page 9] - -Internet-Draft SSH GSSAPI Methods March 2003 - - -2.3 Other GSSAPI key exchange methods - - Key exchange method names starting with "gss-" are reserved for key - exchange methods which conform to this document; in particular, for - those methods which use the GSSAPI authenticated Diffie-Hellman key - exchange algorithm described in Section 2.1, including any future - methods which use different groups and/or hash functions. The - intent is that the names for any such future methods methods be - defined in a similar manner to that used in Section 2.2. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Hutzelman, et. al. Expires August 31, 2003 [Page 10] - -Internet-Draft SSH GSSAPI Methods March 2003 - - -3. GSSAPI User Authentication - - This section describes a general-purpose user authentication method - based on [2]. It is intended to be run over the SSH user - authentication protocol [9]. - - The authentication method name for this protocol is "gssapi". - -3.1 GSSAPI Authentication Overview - - GSSAPI authentication must maintain a context. Authentication - begins when the client sends a SSH_MSG_USERAUTH_REQUEST, which - specifies the mechanism OIDs the client supports. - - If the server supports any of the requested mechanism OIDs, the - server sends a SSH_MSG_USERAUTH_GSSAPI_RESPONSE message containing - the mechanism OID. - - After the client receives SSH_MSG_USERAUTH_GSSAPI_RESPONSE, the - client and server exchange SSH_MSG_USERAUTH_GSSAPI_TOKEN packets - until the authentication mechanism either succeeds or fails. - - If at any time during the exchange, the client sends a new - SSH_MSG_USERAUTH_REQUEST packet, the GSSAPI context is completely - discarded and destroyed, and any further GSSAPI authentication MUST - restart from the beginning. - -3.2 Initiating GSSAPI authentication - - The GSSAPI authentication method is initiated when the client sends - a SSH_MSG_USERAUTH_REQUEST: - - byte SSH_MSG_USERAUTH_REQUEST - string user name (in ISO-10646 UTF-8 encoding) - string service name (in US-ASCII) - string "gssapi" (US-ASCII method name) - uint32 n, the number of mechanism OIDs client supports - string[n] mechanism OIDs - - Mechanism OIDs are encoded according to the ASN.1 distinguished - encoding rules (DER), as described in [1] and in section 3.1 of [2]. - The mechanism OIDs MUST be listed in order of preference, and the - server must choose the first mechanism OID on the list that it - supports. - - The client SHOULD NOT send more then one gssapi mechanism OID unless - there are no non-GSSAPI authentication methods between the GSSAPI - mechanisms in the order of preference, otherwise, authentication - methods may be executed out of order. - - -Hutzelman, et. al. Expires August 31, 2003 [Page 11] - -Internet-Draft SSH GSSAPI Methods March 2003 - - - If the server does not support any of the specified OIDs, the server - MUST fail the request by sending a SSH_MSG_USERAUTH_FAILURE packet. - - The user name may be an empty string if it can be deduced from the - results of the gssapi authentication. If the user name is not - empty, and the requested user does not exist, the server MAY - disconnect, or MAY send a bogus list of acceptable authentications - but never accept any. This makes it possible for the server to - avoid disclosing information about which accounts exist. In any - case, if the user does not exist, the authentication request MUST - NOT be accepted. - - 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. - -3.3 Initial server response - - The server responds to the SSH_MSG_USERAUTH_REQUEST with either a - SSH_MSG_USERAUTH_FAILURE if none of the mechanisms are supported, or - with SSH_MSG_USERAUTH_GSSAPI_RESPONSE as follows: - - byte SSH_MSG_USERAUTH_GSSAPI_RESPONSE - string selected mechanism OID - - The mechanism OID must be one of the OIDs sent by the client in the - SSH_MSG_USERAUTH_REQUEST packet. - -3.4 GSSAPI session - - Once the mechanism OID has been selected, the client will then - initiate an exchange of one or more pairs of - SSH_MSG_USERAUTH_GSSAPI_TOKEN packets. These packets contain the - tokens produced from the 'GSS_Init_sec_context()' and - 'GSS_Accept_sec_context()' calls. The actual number of packets - exchanged is determined by the underlying GSSAPI mechanism. - - byte SSH_MSG_USERAUTH_GSSAPI_TOKEN - string data returned from either GSS_Init_sec_context() - or GSS_Accept_sec_context() - - If an error occurs during this exchange on server side, the server - can terminate the method by sending a SSH_MSG_USERAUTH_FAILURE - packet. If an error occurs on client side, the client can terminate - the method by sending a new SSH_MSG_USERAUTH_REQUEST packet. - - The client MAY use the deleg_req_flag in calls to - GSS_Init_sec_context() to request credential delegation. - - -Hutzelman, et. al. Expires August 31, 2003 [Page 12] - -Internet-Draft SSH GSSAPI Methods March 2003 - - - Additional SSH_MSG_USERAUTH_GSSAPI_TOKEN messages are sent if and - only if the calls to the GSSAPI routines produce send tokens of - non-zero length. - - Any major status code other than GSS_S_COMPLETE or - GSS_S_CONTINUE_NEEDED SHOULD be a failure. - -3.5 Client acknowledgement - - It is possible for the server to successfully complete the GSSAPI - method and the client to fail. If the server simply assumed success - on the part of the client and completed the authentication service, - it is possible that the client would fail to complete the - authentication method, but not be able to retry other methods - because the server had already moved on. - - Therefore, the client MUST send the following message when it has - successfully called GSS_Init_sec_context() and gotten GSS_S_COMPLETE: - - byte SSH_MSG_USERAUTH_GSSAPI_EXCHANGE_COMPLETE - - This message MUST be sent if and only if GSS_Init_sec_context() - returned GSS_S_COMPLETE. If a token is returned then the - SSH_MSG_USERAUTH_GSSAPI_TOKEN message MUST be sent before this one. - - If GSS_Init_sec_context() failed, the client MUST terminate the - method by sending a new SSH_MSG_USERAUTH_REQUEST. or by closing the - connection - -3.6 Completion - - As with all SSH authentication methods, successful completion is - indicated by a SSH_MSG_USERAUTH_SUCCESS if no other authentication - is required, or a SSH_MSG_USERAUTH_FAILURE with the partial success - flag set if the server requires further authentication. - - This packet should be sent immediately following receipt of the the - SSH_MSG_USERAUTH_GSSAPI_EXCHANGE_COMPLETE packet. - - - - - - - - - - - - - -Hutzelman, et. al. Expires August 31, 2003 [Page 13] - -Internet-Draft SSH GSSAPI Methods March 2003 - - -3.7 Error Status - - In the event a GSSAPI error occurs on the server during context - establishment, the server MAY send the following message to inform - the client of the details of the error before sending a - SSH_MSG_USERAUTH_FAILURE message: - - byte SSH_MSG_USERAUTH_GSSAPI_ERROR - uint32 major_status - uint32 minor_status - string message - string language tag - - The message text MUST be encoded in the UTF-8 encoding described in - [10]. Language tags are those described in [11]. Note that the - message text may contain multiple lines separated by carriage - return-line feed (CRLF) sequences. Application developers should - take this into account when displaying these messages. - - Clients receiving this message MAY log the error details and/or - report them to the user. Any server sending this message MUST - ignore any SSH_MSG_UNIMPLEMENTED sent by the client in response. - -3.8 Error Token - - In the event that, during context establishment, a client's call to - GSS_Init_sec_context or a server's call to GSS_Accept_sec_context - returns a token along with an error status, the resulting "error - token" SHOULD be sent to the peer using the following message: - - byte SSH_MSG_USERAUTH_GSSAPI_ERRTOK - string error token - - This message implies that the authentication is about to fail, and - is defined to allow the error token to be communicated without - losing synchronization. - - When a server sends this message, it MUST be followed by a - SSH_MSG_USERAUTH_FAILURE message, which is to be interpreted as - applying to the same authentication request. A client receiving - this message SHOULD wait for the following SSH_MSG_USERAUTH_FAILURE - message before beginning another authentication attempt. - - When a client sends this message, it MUST be followed by a new - authentication request or by terminating the connection. A server - receiving this message MUST NOT send a SSH_MSG_USERAUTH_FAILURE in - reply, since such a message might otherwise be interpreted by a - client as a response to the following authentication sequence. - - - -Hutzelman, et. al. Expires August 31, 2003 [Page 14] - -Internet-Draft SSH GSSAPI Methods March 2003 - - - Any server sending this message MUST ignore any - SSH_MSG_UNIMPLEMENTED sent by the client in response. If a server - sends both this message and an SSH_MSG_USERAUTH_GSSAPI_ERROR - message, the SSH_MSG_USERAUTH_GSSAPI_ERROR message MUST be sent - first, to allow the client to store and/or display the error status - before processing the error token. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Hutzelman, et. al. Expires August 31, 2003 [Page 15] - -Internet-Draft SSH GSSAPI Methods March 2003 - - -4. External Key Exchange User Authentication - - This section describes a user authentication method building on the - framework described in [9]. This method relies upon the key - exchange to authenticate both the client and the server. If the key - exchange did not successfully perform these functions then the - server MUST always respond to this request with - SSH_MSG_USERAUTH_FAILURE with partial success set to false. - - The new mechanism is defined as follows: - - byte SSH_MSG_USERAUTH_REQUEST - string user name (in ISO-10646 UTF-8 encoding) - string service name (in US-ASCII) - string "external-keyx" (US-ASCII method name) - - If the authentication performed as part of key exchange can be used - to authorize login as the requested user, this method is successful, - and the server responds with SSH_MSG_USERAUTH_SUCCESS if no more - authentications are needed, or with SSH_MSG_USERAUTH_FAILURE with - partial success set to true if more authentications are needed. - - If the authentication performed as part of key-exchange cannot be - used to authorize login as the requested user, then - SSH_MSG_USERAUTH_FAILURE is returned with partial success set to - false. - - If the user name is not empty, and the requested user does not - exist, the server MAY disconnect, or MAY send a bogus list of - acceptable authentications but never accept any. This makes it - possible for the server to avoid disclosing information about which - accounts exist. In any case, if the user does not exist, the - authentication request MUST NOT be accepted. - - Any implementation supporting at least one key exchange method which - conforms to section 1 of this document SHOULD also support the - "external-keyx" user authentication method, in order to allow user - authentication to be performed at the same time as key exchange, - thereby reducing the number of round trips needed for connection - setup. - - - - - - - - - - - -Hutzelman, et. al. Expires August 31, 2003 [Page 16] - -Internet-Draft SSH GSSAPI Methods March 2003 - - -5. Null Host Key Algorithm - - The "null" host key algorithm has no associated host key material, - and provides neither signature nor encryption algorithms. Thus, it - can be used only with key exchange methods that do not require any - public-key operations and do not require the use of host public key - material. The key exchange methods described in section 1 of this - document are examples of such methods. - - This algorithm is used when, as a matter of configuration, the host - does not have or does not wish to use a public key. For example, it - can be used when the administrator has decided as a matter of policy - to require that all key exchanges be authenticated using Kerberos - [12], and thus the only permitted key exchange method is the - GSSAPI-authenticated Diffie-Hellman exchange described above, with - Kerberos V5 as the underlying GSSAPI mechanism. In such a - configuration, the server implementation supports the "ssh-dss" key - algorithm (as required by [8]), but could be prohibited by - configuration from using it. In this situation, the server needs - some key exchange algorithm to advertise; the "null" algorithm fills - this purpose. - - Note that the use of the "null" algorithm in this way means that the - server will not be able to interoperate with clients which do not - support this algorithm. This is not a significant problem, since in - the configuration described, it will also be unable to interoperate - with implementations that do not support the GSSAPI-authenticated - key exchange and Kerberos. - - Any implementation supporting at least one key exchange method which - conforms to section 1 of this document MUST also support the "null" - host key algorithm. Servers MUST NOT advertise the "null" host key - algorithm unless it is the only algorithm advertised. - - - - - - - - - - - - - - - - - - -Hutzelman, et. al. Expires August 31, 2003 [Page 17] - -Internet-Draft SSH GSSAPI Methods March 2003 - - -6. Summary of Message Numbers - - The following message numbers have been defined for use with - GSSAPI-based key exchange methods: - - #define SSH_MSG_KEXGSS_INIT 30 - #define SSH_MSG_KEXGSS_CONTINUE 31 - #define SSH_MSG_KEXGSS_COMPLETE 32 - #define SSH_MSG_KEXGSS_HOSTKEY 33 - #define SSH_MSG_KEXGSS_ERROR 34 - - The numbers 30-49 are specific to key exchange and may be redefined - by other kex methods. - - The following message numbers have been defined for use with the - 'gssapi' user authentication method: - - #define SSH_MSG_USERAUTH_GSSAPI_RESPONSE 60 - #define SSH_MSG_USERAUTH_GSSAPI_TOKEN 61 - #define SSH_MSG_USERAUTH_GSSAPI_EXCHANGE_COMPLETE 63 - #define SSH_MSG_USERAUTH_GSSAPI_ERROR 64 - - The numbers 60-79 are specific to user authentication and may be - redefined by other user auth methods. Note that in the method - described in this document, message number 62 is unused. - - - - - - - - - - - - - - - - - - - - - - - - - - -Hutzelman, et. al. Expires August 31, 2003 [Page 18] - -Internet-Draft SSH GSSAPI Methods March 2003 - - -7. GSSAPI Considerations - -7.1 Naming Conventions - - In order to establish a GSSAPI security context, the SSH client - needs to determine the appropriate targ_name to use in identifying - the server when calling GSS_Init_sec_context. For this purpose, the - GSSAPI mechanism-independent name form for host-based services is - used, as described in section 4.1 of [2]. - - In particular, the targ_name to pass to GSS_Init_sec_context is - obtained by calling GSS_Import_name with an input_name_type of - GSS_C_NT_HOSTBASED_SERVICE, and an input_name_string consisting of - the string "host@" concatenated with the hostname of the SSH server. - -7.2 Channel Bindings - - This document recommends that channel bindings SHOULD NOT be - specified in the calls during context establishment. This document - does not specify any standard data to be used as channel bindings - and the use of network addresses as channel bindings may break SSH - in environments where it is most useful. - -7.3 SPNEGO - - The use of the Simple and Protected GSS-API Negotiation Mechanism - [14] in conjunction with the authentication and key exchange methods - described in this document is both unnecessary and undesirable. As - a result, mechanisms conforming to this document MUST NOT use SPNEGO - as the underlying GSSAPI mechanism. - - Since SSH performs its own negotiation of authentication and key - exchange methods, the negotiation capability of SPNEGO alone does - not provide any added benefit. In fact, as described below, it has - the potential to result in the use of a weaker method than desired. - - Normally, SPNEGO provides the added benefit of protecting the GSSAPI - mechanism negotiation. It does this by having the server compute a - MIC of the list of mechanisms proposed by the client, and then - checking that value at the client. In the case of key exchange, - this protection is not needed because the key exchange methods - described here already perform an equivalent operation; namely, they - generate a MIC of the SSH exchange hash, which is a hash of several - items including the lists of key exchange mechanisms supported by - both sides. In the case of user authentication, the protection is - not needed because the negotiation occurs over a secure channel, and - the host's identity has already been proved to the user. - - The use of SPNEGO combined with GSSAPI mechanisms used without - - -Hutzelman, et. al. Expires August 31, 2003 [Page 19] - -Internet-Draft SSH GSSAPI Methods March 2003 - - - SPNEGO can lead to interoperability problems. For example, a client - which supports key exchange using the Kerberos V5 GSSAPI mechanism - [13] only underneath SPNEGO will not interoperate with a server - which supports key exchange only using the Kerberos V5 GSSAPI - mechanism directly. As a result, allowing GSSAPI mechanisms to be - used both with and without SPNEGO is undesirable. - - If a client's policy is to first prefer GSSAPI-based key exchange - method X, then non-GSSAPI method Y, then GSSAPI-based method Z, and - if a server supports mechanisms Y and Z but not X, then an attempt - to use SPNEGO to negotiate a GSSAPI mechanism might result in the - use of method Z when method Y would have been preferable. As a - result, the use of SPNEGO could result in the subversion of the - negotiation algorithm for key exchange methods as described in - section 5.1 of [8] and/or the negotiation algorithm for user - authentication methods as described in [9]. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Hutzelman, et. al. Expires August 31, 2003 [Page 20] - -Internet-Draft SSH GSSAPI Methods March 2003 - - -8. IANA Considerations - - Consistent with section 7 of [6], the IANA is directed to make the - following registrations: - - The family of SSH key exchange method names beginning with - "gss-group1-sha1-" and not containing the at-sign ('@'), to name - the key exchange methods defined in Section 2.2. - - All other SSH key exchange method names beginning with "gss-" and - not containing the at-sign ('@'), to be reserved for future key - exchange methods defined in conformance with this document, as - noted in Section 2.3. - - The SSH host public key algorithm name "null", to name the NULL - host key algorithm defined in Section 5. - - The SSH user authentication method name "gssapi", to name the - GSSAPI user authentication method defined in Section 3. - - The SSH user authentication method name "external-keyx", to name - the "external key-exchange" user authentication method defined in - Section 4. - - This document creates no new registries. - - - - - - - - - - - - - - - - - - - - - - - - - - -Hutzelman, et. al. Expires August 31, 2003 [Page 21] - -Internet-Draft SSH GSSAPI Methods March 2003 - - -9. Security Considerations - - This document describes authentication and key-exchange protocols. - As such, security considerations are discussed throughout. - - This protocol depends on the SSH protocol itself, the GSSAPI, any - underlying GSSAPI mechanisms which are used, and any protocols on - which such mechanisms might depend. Each of these components plays - a part in the security of the resulting connection, and each will - have its own security considerations. - - The key exchange method described in section 1 of this document - depends on the underlying GSSAPI mechanism to provide both mutual - authentication and per-message integrity services. If either of - these features is not supported by a particular GSSAPI mechanism, or - by a particular implementation of a GSSAPI mechanism, then the key - exchange is not secure and MUST fail. - - In order for the "external-keyx" user authentication method to be - used, it MUST have access to user authentication information - obtained as a side-effect of the key exchange. If this information - is unavailable, the authentication MUST fail. - - Revealing information about the reason for an authentication failure - may be considered by some sites to be an unacceptable security risk - for a production environment. However, having that information - available can be invaluable for debugging purposes. Thus, it is - RECOMMENDED that implementations provide a means for controlling, as - a matter of policy, whether to send SSH_MSG_USERAUTH_GSSAPI_ERROR, - SSH_MSG_USERAUTH_GSSAPI_ERRTOK, and SSH_MSG_KEXGSS_ERROR messages, - and SSH_MSG_KEXGEE_CONTINUE messages containing a GSSAPI error token. - - - - - - - - - - - - - - - - - - - - -Hutzelman, et. al. Expires August 31, 2003 [Page 22] - -Internet-Draft SSH GSSAPI Methods March 2003 - - -10. Acknowledgements - - The authors would like to thank Sam Hartman, Simon Wilkinson, and - Nicolas Williams for their invaluable assistance with this document. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Hutzelman, et. al. Expires August 31, 2003 [Page 23] - -Internet-Draft SSH GSSAPI Methods March 2003 - - -11. Changes the last version - - This section lists important changes since the previous version of - this internet-draft. This section should be removed at the time of - publication of this document as an RFC. - - o Improved the description of error handling during key exchange. - - o Specified that SSH_MSG_GSSKEX_CONTINUE SHOULD be used to send - error tokens in the event of a failure of GSS_Init_sec_context or - GSS_Accept_sec_context during key exchange. - - o Made SSH_MSG_GSSKEX_ERROR be OPTIONAL instead of RECOMMENDED. - - o Specified a new SSH_MSG_USERAUTH_GSSAPI_ERRTOK message which - SHOULD be used to send error tokens in the event of a failure of - GSS_Init_sec_context or GSS_Accept_sec_context during user - authentication. - - o Made SSH_MSG_USERAUTH_GSSAPI_ERROR be OPTIONAL instead of - RECOMMENDED. - - o Added IANA considerations section. - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Hutzelman, et. al. Expires August 31, 2003 [Page 24] - -Internet-Draft SSH GSSAPI Methods March 2003 - - -Normative References - - [1] ISO/IEC, "ASN.1 Encoding Rules: Specification of Basic - Encoding Rules (BER), Canonical Encoding Rules (CER) and - Distinguished Encoding Rules (DER)", ITU-T Recommendation - X.690 (1997), ISO/IEC 8825-1:1998, November 1998. - - [2] Linn, J., "Generic Security Service Application Program - Interface Version 2, Update 1", RFC 2743, January 2000. - - [3] Rivest, R., "The MD5 Message-Digest Algorithm", RFC 1321, - April 1992. - - [4] Freed, N. and N. Borenstein, "Multipurpose Internet Mail - Extensions (MIME) Part One: Format of Internet Message - Bodies", RFC 2045, November 1996. - - [5] Bradner, S., "Key words for use in RFCs to Indicate - Requirement Levels", RFC 2119, BCP 14, March 1997. - - [6] Ylonen, T., Kivinen, T., Saarinen, M., Rinne, T. and S. - Lehtinen, "SSH Protocol Architecture", - draft-ietf-secsh-architecture-11.txt (work in progress), - November 2001. - - [7] Ylonen, T., Kivinen, T., Saarinen, M., Rinne, T. and S. - Lehtinen, "SSH Connection Protocol", - draft-ietf-secsh-connect-14.txt (work in progress), November - 2001. - - [8] Ylonen, T., Kivinen, T., Saarinen, M., Rinne, T. and S. - Lehtinen, "SSH Transport Layer Protocol", - draft-ietf-secsh-transport-11.txt (work in progress), November - 2001. - - [9] Ylonen, T., Kivinen, T., Saarinen, M., Rinne, T. and S. - Lehtinen, "SSH Authentication Protocol", - draft-ietf-secsh-userauth-13.txt (work in progress), November - 2001. - - [10] Yergeau, F., "UTF-8, a transformation format of ISO 10646", - RFC 2279, January 1998. - - [11] Alvestrand, H., "Tags for the Identification of Languages", - RFC 1766, March 1995. - - - -Hutzelman, et. al. Expires August 31, 2003 [Page 25] - -Internet-Draft SSH GSSAPI Methods March 2003 - - -Non-normative References - - [12] Kohl, J. and C. Neuman, "The Kerberos Network Authentication - Service (V5)", RFC 1510, September 1993. - - [13] Linn, J., "The Kerberos Version 5 GSS-API Mechanism", RFC - 1964, June 1996. - - [14] Baize, E. and D. Pinkas, "The Simple and Protected GSS-API - Negotiation Mechanism", RFC 2478, December 1998. - - -Authors' Addresses - - Jeffrey Hutzelman - Carnegie Mellon University - 5000 Forbes Ave - Pittsburgh, PA 15213 - US - - Phone: +1 412 268 7225 - EMail: jhutz+@cmu.edu - URI: http://www.cs.cmu.edu/~jhutz/ - - - Joseph Salowey - Cisco Systems - 2901 Third Avenue - Seattle, WA 98121 - US - - Phone: +1 206 256 3380 - EMail: jsalowey@cisco.com - - - Joseph Galbraith - Van Dyke Technologies, Inc. - 4848 Tramway Ridge Dr. NE - Suite 101 - Albuquerque, NM 87111 - US - - EMail: galb@vandyke.com - - - Von Welch - University of Chicago & Argonne National Laboratory - Distributed Systems Laboratory - 701 E. Washington - Urbana, IL 61801 - US - - EMail: welch@mcs.anl.gov - - - -Hutzelman, et. al. Expires August 31, 2003 [Page 26] - -Internet-Draft SSH GSSAPI Methods March 2003 - - -Full Copyright Statement - - Copyright (C) The Internet Society (2003). 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. - - - - - - - - - - - - - - -Hutzelman, et. al. Expires August 31, 2003 [Page 27] - diff --git a/doc/draft-ietf-secsh-newmodes-00.txt b/doc/draft-ietf-secsh-newmodes-00.txt deleted file mode 100644 index 1554ac35..00000000 --- a/doc/draft-ietf-secsh-newmodes-00.txt +++ /dev/null @@ -1,619 +0,0 @@ - - - - - - -Network Working Group M. Bellare -Internet-Draft T. Kohno -Expires: September 20, 2003 UC San Diego - C. Namprempre - Thammasat University - March 20, 2003 - - - SSH Transport Layer Encryption Modes - - draft-ietf-secsh-newmodes-00.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 September 20, 2003. - -Copyright Notice - - Copyright (C) The Internet Society (2003). All Rights Reserved. - -Abstract - - Researchers have recently discovered that the authenticated - encryption portion of the current SSH Transport Protocol is - vulnerable to several attacks. - - This document describes new symmetric encryption methods for the SSH - Transport Protocol and gives specific recommendations on how - - - -Bellare, Kohno, and Namprempre [Page 1] - -Internet Draft Month, Year - - - frequently SSH implementations should rekey. - - Bellare, Kohno, and Namprempre [ACM CCS 2002] prove that if an SSH - application implements the modifications described in this document, - then the symmetric cryptographic portion of that application will - provably resist chosen-plaintext, chosen-ciphertext, reaction-based - privacy and integrity/authenticity attacks. - -Table of Contents - - 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 2 - 2. Conventions Used in This Document . . . . . . . . . . . . . . 2 - 3. Rekeying . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 - 3.1 First Rekeying Recommendation . . . . . . . . . . . . . . . . 3 - 3.2 Second Rekeying Recommendation . . . . . . . . . . . . . . . . 3 - 4. Encryption Modes . . . . . . . . . . . . . . . . . . . . . . . 4 - 5. Security Considerations . . . . . . . . . . . . . . . . . . . 6 - 5.1 Rekeying Considerations . . . . . . . . . . . . . . . . . . . 7 - 5.2 Encryption Method Considerations . . . . . . . . . . . . . . . 8 - References . . . . . . . . . . . . . . . . . . . . . . . . . . 9 - Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . 10 - Full Copyright Statement . . . . . . . . . . . . . . . . . . . 10 - -1. Introduction - - The symmetric portion of the SSH Transport Protocol was designed to - provide both privacy and integrity of encapsulated data. Researchers - ([DAI,BKN]) have, however, recently identified several security - problems with the symmetric portion of the SSH Transport Protocol as - described in [SSH-TRANS]. For example, the encryption mode specified - in [SSH-TRANS] is vulnerable to a chosen-plaintext privacy attack. - Additionally, if not rekeyed frequently enough, the SSH Transport - Protocol may leak information about payload data. This latter - property is true regardless of what encryption mode is used. - - In [BKN] Bellare, Kohno, and Namprempre show how to modify the - symmetric portion of the SSH Transport Protocol so that it provably - preserves privacy and integrity against chosen-plaintext, chosen- - ciphertext, and reaction attacks. This document instantiates the - recommendations described in [BKN]. - -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]. - - The used data types and terminology are specified in the architecture - - - -Bellare, Kohno, and Namprempre [Page 2] - -Internet Draft Month, Year - - - document [SSH-ARCH]. - - The SSH Transport Protocol is specified in the transport document - [SSH-TRANS]. - -3. Rekeying - - Section 7 of [SSH-TRANS] suggests that SSH implementations rekey - after every gigabyte of transmitted data. [SSH-TRANS] does not, - however, discuss all the problems that could arise if an SSH - implementation does not rekey frequently enough. This section serves - to strengthen the suggestion in [SSH-TRANS] by giving firm upper - bounds on the tolerable number of encryptions between rekeying - operations. In Section 5 we discuss the motivation for these - rekeying recommendations in more detail. - - This section makes two recommendations. Informally, the first - recommendation is intended to protects against possible information - leakage through the MAC tag and the second recommendation is intended - to protect against possible information leakage through the block - cipher. Note that, depending on the block length of the underlying - block cipher and the length of the encrypted packets, the first - recommendation may supersede the second recommendation, or visa- - versa. - -3.1 First Rekeying Recommendation - - Because of possible information leakage through the MAC tag, SSH - implementations SHOULD rekey at least once every 2**32 outgoing - packets. More explicitly, after a key exchange an SSH implementation - SHOULD NOT send more than 2**32 packets before rekeying again. - - SSH implementations SHOULD also attempt to rekey before receiving - more than 2**32 packets since the last rekey operation. The - preferred way to do this is to rekey after receiving more than 2**31 - packets since the last rekey operation. - -3.2 Second Rekeying Recommendation - - Because of a birthday property of block ciphers and some modes of - operation, implementations must be careful not to encrypt too many - blocks with the same encryption key. - - Let L be the block length (in bits) of an SSH encryption method's - block cipher (eg, 128 for AES). If L is at least 128 then, after - rekeying, an SSH implementation SHOULD NOT encrypt more than 2**(L/4) - blocks before rekeying again. If L is at least 128, then SSH - implementations should also attempt to force a rekey before receiving - - - -Bellare, Kohno, and Namprempre [Page 3] - -Internet Draft Month, Year - - - more than 2**(L/4) blocks. If L is less than 128 (which is the case - for older ciphers such as 3DES, Blowfish, CAST-128, and IDEA), then, - although it may be too expensive to rekey every 2**(L/4) blocks, it - is still advisable for SSH implementations to follow the original - recommendation in [SSH-TRANS]: rekey at least once every gigabyte of - transmitted data. - - Note that if L is less than or equal to 128, then the recommendation - in this subsection supersedes the recommendation in Section 3.1. If - an SSH implementation uses a block cipher with a larger block size - (eg, Rijndael with 256-bit blocks), then the recommendations in the - above paragraph may supersede the recommendations in this paragraph - (depending on the lengths of the packets). - -4. Encryption Modes - - This document describes new encryption methods for use with the SSH - Transport Protocol. These encryption methods are in addition to the - encryption methods described in Section 4.3 of [SSH-TRANS]. - - Recall from [SSH-TRANS] that the encryption methods in each direction - of an SSH connection MUST run independently of each other and that, - when encryption is in effect, the packet length, padding length, - payload, and padding fields of each packet MUST be encrypted with the - chosen method. Further recall that the total length of the - concatenation of the packet length, padding length, payload, and - padding MUST be a multiple of the cipher's block size when the - cipher's block size is greater than or equal to 8 bytes (which is the - case for all of the following methods). - - This document describes the following new methods: - - aes128-ctr RECOMMENDED AES (Rijndael) in SDCTR mode, - with 128-bit key - aes192-ctr RECOMMENDED AES with 192-bit key - aes256-ctr RECOMMENDED AES with 256-bit key - 3des-ctr RECOMMENDED Three-key 3DES in SDCTR mode - blowfish-ctr RECOMMENDED Blowfish in SDCTR mode - twofish128-ctr RECOMMENDED Twofish in SDCTR mode, - with 128-bit key - twofish192-ctr OPTIONAL Twofish with 192-bit key - twofish256-ctr OPTIONAL Twofish with 256-bit key - serpent128-ctr RECOMMENDED Serpent in SDCTR mode, with - with 128-bit key - serpent192-ctr OPTIONAL Serpent with 192-bit key - serpent256-ctr OPTIONAL Serpent with 256-bit key - idea-ctr OPTIONAL IDEA in SDCTR mode - cast128-ctr OPTIONAL CAST-128 in SDCTR mode - - - -Bellare, Kohno, and Namprempre [Page 4] - -Internet Draft Month, Year - - - The label <cipher>-ctr means that the block cipher <cipher> is to be - used in "stateful-decryption counter" (SDCTR) mode. Let L be the - block length of <cipher> in bits. In stateful-decryption counter - mode both the sender and the receiver maintain an internal L-bit - counter X. The initial value of X should be the initial IV (as - computed in Section 5.2 of [SSH-TRANS]) interpreted as an L-bit - unsigned integer in network-byte-order. If X=(2**L)-1, then - "increment X" has the traditional semantics of "set X to 0." We use - the notation <X> to mean "convert X to an L-bit string in network- - byte-order." Naturally, implementations may differ in how the - internal value X is stored. For example, implementations may store X - as multiple unsigned 32-bit counters. - - To encrypt a packet P=P1||P2||...||Pn (where P1, P2, ..., Pn are each - blocks of length L), the encryptor first encrypts <X> with <cipher> - to obtain a block B1. The block B1 is then XORed with P1 to generate - the ciphertext block C1. The counter X is then incremented and the - process is repeated for each subsequent block in order to generate - the entire ciphertext C=C1||C2||...||Cn corresponding to the packet - P. Note that the counter X is not included in the ciphertext. Also - note that the keystream can be pre-computed and that encryption is - parallelizable. - - To decrypt a ciphertext C=C1||C2||...||Cn, the decryptor (who also - maintains its own copy of X), first encrypts its copy of <X> with - <cipher> to generate a block B1 and then XORs B1 to C1 to get P1. - The decryptor then increments its copy of the counter X and repeats - the above process for each block to obtain the plaintext packet - P=P1||P2||...||Pn. As before, the keystream can be pre-computed and - decryption is parallelizable. - - The "aes128-ctr" method uses AES (the Advanced Encryption Standard, - formerly Rijndael) with 128-bit keys [AES]. The block size is 16 - bytes. - - The "aes192-ctr" method uses AES with 192-bit keys. - - The "aes256-ctr" method uses AES with 256-bit keys. - - The "3des-ctr" method uses 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). The block size is 8 bytes. - This algorithm is defined in [SCHNEIER]. - - The "blowfish-ctr" method uses Blowfish with 256 bit keys [SCHNEIER]. - The block size is 8 bytes. - - - -Bellare, Kohno, and Namprempre [Page 5] - -Internet Draft Month, Year - - - The "twofish128-ctr" method uses Twofish with 128-bit keys [TWOFISH]. - The block size is 16 bytes. - - The "twofish192-ctr" method uses Twofish with 192-bit keys. - - The "twofish256-ctr" method uses Twofish with 256-bit keys. - - The "serpent128-ctr" method uses the Serpent block cipher [SERPENT] - with 128-bit keys. The block size is 16 bytes. - - The "serpent192-ctr" method uses Serpent with 192-bit keys. - - The "serpent256-ctr" method uses Serpent with 256-bit keys. - - The "idea-ctr" method uses the IDEA cipher [SCHNEIER]. IDEA is - patented by Ascom AG. The block size is 8 bytes. - - The "cast128-ctr" method uses the CAST-128 cipher [RFC2144]. The - block size is 8 bytes. - -5. Security Considerations - - This document describes additional encryption methods and - recommendations for the SSH Transport Protocol [SSH-TRANS]. [BKN] - prove that if an SSH application incorporates the methods and - recommendations described in this document, then the symmetric - cryptographic portion of that application will resist a large class - of privacy and integrity attacks. - - This section is designed to help implementors understand the - security-related motivations for, as well as possible consequences of - deviating from, the methods and recommendations described in this - document. Additional motivation and discussion, as well as proofs of - security, appear in the research paper [BKN]. - - Please note that the notion of "prove" in the context of [BKN] is - that of practice-oriented reductionist security: if an attacker is - able to break the symmetric portion of the SSH Transport Protocol - using a certain type of attack (eg, a chosen-ciphertext attack), then - the attacker will also be able to break one of the transport - protocol's underlying components (eg, the underlying block cipher or - MAC). If we make the reasonable assumption that the underlying - components (such as AES and HMAC-SHA1) are secure, then the attacker - against the symmetric portion of the SSH protocol cannot be very - successful (since otherwise there would be a contradiction). Please - see [BKN] for details. In particular, attacks are not impossible; - just extremely improbable (unless the building blocks, like AES, are - insecure). - - - -Bellare, Kohno, and Namprempre [Page 6] - -Internet Draft Month, Year - - - Note also that cryptography often plays only a small (but critical) - role in an application's overall security. In the case of the SSH - Transport Protocol, even though an application might implement the - symmetric portion of the SSH protocol exactly as described in this - document, the application may still be vulnerable to non-protocol- - based attacks (as an egregious example, an application might save - cryptographic keys in cleartext to an unprotected file). - Consequently, even though the methods described herein come with - proofs of security, developers must still execute caution when - developing applications that implement these methods. - -5.1 Rekeying Considerations - - Section 3 of this document makes two rekeying recommendations: (1) - rekey at least once every 2**32 packets and (2) rekey after a certain - number of encrypted blocks (eg, 2**(L/4) blocks if the block cipher's - block length L is at least 128 bits). The motivations for - recommendations (1) and (2) are different, and we consider each - recommendation in turn. Briefly, (1) is designed to protect against - information leakage through the SSH protocol's underlying MAC and (2) - is designed to protect against information leakage through the SSH - protocol's underlying encryption scheme. Please note that, depending - on the encryption method's block length L and the number of blocks - encrypted per packet, recommendation (1) may supersede recommendation - (2) or visa-versa. - - Recommendation (1) states that SSH implementations should rekey at - least once every 2**32 packets. As [BKN] show, if more than 2**32 - packets are encrypted and MACed by the SSH Transport Protocol between - rekeyings, then the SSH Transport Protocol's underlying MAC may begin - to leak information about the protocol's payload data. In more - detail, an adversary looks for a collision between the MACs - associated to two packets that were MACed with the same 32-bit - sequence number (see Section 4.4 of [SSH-TRANS]); if a collision is - found, then the payload data associated with those two ciphertexts is - probably identical. Note that this problem occurs regardless of how - secure the underlying encryption method is. Implementors who decide - not to rekey at least once every 2**32 packets should understand this - issue. - - Note that compressing payload data before encrypting and MACing will - not significantly reduce the risk of information leakage through the - underlying MAC. Similarly, the use of random (and unpredictable to - an adversary) padding will not prevent information leakage through - the underlying MAC [BKN]. - - One alternative to recommendation (1) would be to make the SSH - Transport Protocol's sequence number more than 32 bits long. This - - - -Bellare, Kohno, and Namprempre [Page 7] - -Internet Draft Month, Year - - - document does not suggest increasing the length of the sequence - number because doing so could hinder interoperability with older - version of the SSH protocol. Another alternative to recommendation - (1) would be to switch from HMAC to a privacy-preserving randomized - MAC. - - Recommendation (2) states that SSH implementations should rekey - before encrypting more than 2**(L/4) blocks with the same key - (assuming L is at least 128). This recommendation is designed to - minimize the risk of birthday attacks against the encryption method's - underlying block cipher. For example, there is a theoretical privacy - attack against stateful-decryption counter mode if an adversary is - allowed to encrypt approximately 2**(L/2) messages with the same key. - It is because of these birthday attacks that implementors are highly - encouraged to use secure block ciphers with large block lengths. - -5.2 Encryption Method Considerations - - Researchers have recently shown that the original CBC-based - encryption methods in [SSH-TRANS] are vulnerable to chosen-plaintext - privacy attacks [DAI,BKN]. The new stateful-decryption counter mode - encryption methods described in Section 4 of this document were - designed to be secure replacements to the original encryption methods - described in [SSH-TRANS]. - - Many people shy away from counter mode-based encryption schemes - because, when used incorrectly (such as when the keystream is allowed - to repeat), counter mode can be very insecure. Fortunately, the - common concerns with counter mode do not apply to SSH because of the - rekeying recommendations and because of the additional protection - provided by the transport protocol's MAC. This discussion is - formalized with proofs of security in [BKN]. - - As an additional note, when one of the stateful-decryption counter - mode encryption methods (Section 4) is used, then the padding - included in an SSH packet (Section 4 of [SSH-TRANS]) need not be (but - can still be) random. This eliminates the need to generate - cryptographically-secure pseudorandom bytes for each packet. - - One property of counter mode encryption is that it does not require - messages to be padded to a multiple of the block cipher's block - length. Although not padding messages can reduce the protocol's - network consumption, this document requires padding to be a multiple - of the block cipher's block length in order to (1) not alter the - packet description in [SSH-TRANS] and (2) not leak precise - information about the length of the packet's payload data. (Although - there may be some networks savings for padding to only 8-bytes even - if the block cipher uses 16-byte blocks, because of (1) we do not - - - -Bellare, Kohno, and Namprempre [Page 8] - -Internet Draft Month, Year - - - make that recommendation here.) - - In addition to stateful-decryption counter mode, [BKN] describe other - provably-secure encryption methods for use with the SSH Transport - Protocol. The stateful-decryption counter mode methods in Section 4 - are, however, the preferred alternatives to the insecure methods in - [SSH-TRANS] because stateful-decryption counter mode is the most - efficient (both in terms of network consumption and in terms of the - number of required cryptographic operations per packet). - -References - - [AES] Daemon, J. and Rijmen, V., "AES Proposal: Rijndael", - NIST AES Proposal, 1998. - - [BKN] Bellare, M., Kohno, T., and Namprempre, C., - "Authenticated Encryption in SSH: Provably Fixing the - SSH Binary Packet Protocol", Ninth ACM Conference on - Computer and Communications Security, 2002. - - [BN] Bellare, M. and Namprempre, C., "Authenticated - Encryption: Relations among notions and analysis of - the generic composition paradigm", Asiacrypt 2000. - - [DAI] Dai, W., "An Attack Against SSH2 Protocol", Email to - the ietf-ssh@netbsd.org email list, 2002. - - [KRAWCZYK] Krawczyk, H., "The Order of Encryption and - Authentication for Protecting Communications (Or: How - secure is SSL?)", Crypto 2001. - - [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. - - [SCHNEIER] Schneier, B., "Applied Cryptography Second Edition: - Protocols algorithms and source in code in C", Wiley, - 1996. - - [SERPENT] Anderson, R., Biham, E., and Knudsen, L. "Serpent: A - proposal for the Advanced Encryption Standard", NIST - AES Proposal, 1998. - - [SSH-ARCH] Ylonen, T., et. al., "SSH Protocol Architecture", - I-D draft-ietf-architecture-12.txt, January 2002. - - - - -Bellare, Kohno, and Namprempre [Page 9] - -Internet Draft Month, Year - - - [SSH-TRANS] Ylonen, T., et. al., "SSH Transport Layer Protocol", - I-D draft-ietf-transport-14.txt, March 2002. - - [TWOFISH] Schneier, B., et. al., "The Twofish Encryptions - Algorithm: A 128-bit block cipher, 1st Edition", - Wiley, 1999. - -Authors' Addresses: - - Mihir Bellare - Department of Computer Science and Engineering - University of California at San Diego - 9500 Gilman Drive, MC 0114 - La Jolla, CA 92093-0114 - - Phone: +1 858-822-2977 - EMail: mihir@cs.ucsd.edu - - Tadayoshi Kohno - Department of Computer Science and Engineering - University of California at San Diego - 9500 Gilman Drive, MC 0114 - La Jolla, CA 92093-0114 - - Phone: +1 858-822-2977 - EMail: tkohno@cs.ucsd.edu - - Chanathip Namprempre - Thammasat University - Faculty of Engineering - Electrical Engineering Department - Rangsit Campus, Klong Luang - Pathumthani, Thailand 12121 - - EMail: meaw@alum.mit.edu - -Full Copyright Statement - - Copyright (C) The Internet Society (2003). 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 - - - -Bellare, Kohno, and Namprempre [Page 10] - -Internet Draft Month, Year - - - 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. - -Acknowledgments - - Mihir Bellare and Chanathip Namprempre were supported by NSF Grant - CCR-0098123, NSF Grant ANR-0129617 and an IBM Faculty Partnership - Development Award. Tadayoshi Kohno was supported by a National - Defense Science and Engineering Fellowship. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Bellare, Kohno, and Namprempre [Page 11] -
\ No newline at end of file diff --git a/doc/draft-ietf-secsh-publickeyfile-03.txt b/doc/draft-ietf-secsh-publickeyfile-03.txt deleted file mode 100644 index 766f494e..00000000 --- a/doc/draft-ietf-secsh-publickeyfile-03.txt +++ /dev/null @@ -1,506 +0,0 @@ - - - -Secure Shell Working Group J. Galbraith -Internet-Draft VanDyke Software -Expires: April 16, 2003 R. Thayer - The Tillerman Group - October 16, 2002 - - - SSH Public Key File Format - draft-ietf-secsh-publickeyfile-03.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 16, 2003. - -Copyright Notice - - Copyright (C) The Internet Society (2002). All Rights Reserved. - -Abstract - - This document formally documents the existing public key file format - in use for exchanging public keys between different SSH - implementations. - - - - - - - - - - -Galbraith & Thayer Expires April 16, 2003 [Page 1] - -Internet-Draft SSH Public Key File Format October 2002 - - -Table of Contents - - 1. Conventions used in this document . . . . . . . . . . . . . 3 - 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 - 3. Key File Format . . . . . . . . . . . . . . . . . . . . . . 5 - 3.1 Line termination Characters . . . . . . . . . . . . . . . . 5 - 3.2 Begin and end markers . . . . . . . . . . . . . . . . . . . 5 - 3.3 Key File Header . . . . . . . . . . . . . . . . . . . . . . 5 - 3.3.1 Subject Header . . . . . . . . . . . . . . . . . . . . . . . 6 - 3.3.2 Comment Header . . . . . . . . . . . . . . . . . . . . . . . 6 - 3.4 Public Key File Body . . . . . . . . . . . . . . . . . . . . 6 - 3.5 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 7 - References . . . . . . . . . . . . . . . . . . . . . . . . . 8 - Authors' Addresses . . . . . . . . . . . . . . . . . . . . . 8 - Full Copyright Statement . . . . . . . . . . . . . . . . . . 9 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Galbraith & Thayer Expires April 16, 2003 [Page 2] - -Internet-Draft SSH Public Key File Format October 2002 - - -1. 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 [4]. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Galbraith & Thayer Expires April 16, 2003 [Page 3] - -Internet-Draft SSH Public Key File Format October 2002 - - -2. Introduction - - In order to use public key authentication, public keys must be - exchanged between client and server. This document formally - describes the existing public key file format, with few exceptions. - - Where this document departs from current practice, it also suggests a - mechanism for backwards compatibility. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Galbraith & Thayer Expires April 16, 2003 [Page 4] - -Internet-Draft SSH Public Key File Format October 2002 - - -3. Key File Format - - SSH implementations must share public key files between the client - and the server in order interoperate. - - A key file is a text file, containing a sequence of lines. Each line - in the file MUST NOT be longer than 72 bytes. - -3.1 Line termination Characters - - In order to achieve the goal of being able to exchange public key - files between servers, implementations are REQUIRED to read files - using any of the common line termination sequence, <CR>, <LF> or - <CR><LF>. - - Implementations may generate files using which ever line termination - convention is most convenient - -3.2 Begin and end markers - - The first line of a conforming key file MUST be a begin marker, which - is the literal text: - - ---- BEGIN SSH2 PUBLIC KEY ---- - - The last line of a conforming key file MUST be a end marker, which is - the literal text: - - ---- END SSH2 PUBLIC KEY ---- - -3.3 Key File Header - - The key file header section consists of multiple RFC822 - style - header fields. Each field is a line of the following format: - - Header-tag ':' ' ' Header-value - - The Header-tag MUST NOT be more than 64 bytes. The Header-value MUST - NOT be more than 1024 bytes. Each line in the header MUST NOT be - more than 72 bytes. - - A line is continued if the last character in the line is a '\'. If - the last character of a line is a '\', then the logical contents of - the line is formed by removing the '\' and appending the contents of - the next line. - - The Header-tag MUST be US-ASCII. The Header-value MUST be encoded in - UTF-8. [2] - - - -Galbraith & Thayer Expires April 16, 2003 [Page 5] - -Internet-Draft SSH Public Key File Format October 2002 - - - A line that is not a continuation line that has no ':' in it is - assumed to be the first line of the base 64 encoded body (Section 8) - - Compliant implementations MUST ignore unrecognized header fields. - Implementations SHOULD preserve unrecognized header fields when - manipulating the key file. - - Existing implementations may not correctly handle unrecognized - fields. During a transition period, implementations SHOULD generate - key file headers that contain only a Subject field followed by a - Comment field. - -3.3.1 Subject Header - - This field currently is used to store the login-name that the key was - generated under. For example: - - Subject: user - -3.3.2 Comment Header - - Contain a user specified comment which will be displayed when using - the key. - - It is suggested that this field default to user@hostname for the user - and machine used to generate the key. For example: - - Comment: user@mycompany.com - - Currently, common practice is to quote the Header-value of the - Comment, and some existing implementations fail if these quotes are - omitted. - - Compliant implementations MUST function correctly if the quotes are - omitted. - - During an interim period implementations MAY include the quotes. If - the first and last characters of the Header-value are matching - quotes, implementations SHOULD remove them before using the value. - -3.4 Public Key File Body - - The body of a public key file consists of the public key blob as - described in the SSH transport draft [1], section 4.6, "Public Key - Algorithms", encoded in base 64 as specified in RFC-2045, section - 6.8, "Base64 Content-Transfer-Encoding". [5] - - As with all other lines, each line in the body MUST NOT be longer - - - -Galbraith & Thayer Expires April 16, 2003 [Page 6] - -Internet-Draft SSH Public Key File Format October 2002 - - - than 72 characters. - -3.5 Examples - - The following are some example public key files that are compliant: - - ---- BEGIN SSH2 PUBLIC KEY ---- - Comment: "1024-bit RSA, converted from OpenSSH by galb@test1" - AAAAB3NzaC1yc2EAAAABIwAAAIEA1on8gxCGJJWSRT4uOrR13mUaUk0hRf4RzxSZ1zRbYY - Fw8pfGesIFoEuVth4HKyF8k1y4mRUnYHP1XNMNMJl1JcEArC2asV8sHf6zSPVffozZ5TT4 - SfsUu/iKy9lUcCfXzwre4WWZSXXcPff+EHtWshahu3WzBdnGxm5Xoi89zcE= - ---- END SSH2 PUBLIC KEY ---- - - - ---- BEGIN SSH2 PUBLIC KEY ---- - Comment: DSA Public Key for use with MyIsp - AAAAB3NzaC1kc3MAAACBAPY8ZOHY2yFSJA6XYC9HRwNHxaehvx5wOJ0rzZdzoSOXxbETW6 - ToHv8D1UJ/z+zHo9Fiko5XybZnDIaBDHtblQ+Yp7StxyltHnXF1YLfKD1G4T6JYrdHYI14 - Om1eg9e4NnCRleaqoZPF3UGfZia6bXrGTQf3gJq2e7Yisk/gF+1VAAAAFQDb8D5cvwHWTZ - DPfX0D2s9Rd7NBvQAAAIEAlN92+Bb7D4KLYk3IwRbXblwXdkPggA4pfdtW9vGfJ0/RHd+N - jB4eo1D+0dix6tXwYGN7PKS5R/FXPNwxHPapcj9uL1Jn2AWQ2dsknf+i/FAAvioUPkmdMc - 0zuWoSOEsSNhVDtX3WdvVcGcBq9cetzrtOKWOocJmJ80qadxTRHtUAAACBAN7CY+KKv1gH - pRzFwdQm7HK9bb1LAo2KwaoXnadFgeptNBQeSXG1vO+JsvphVMBJc9HSn24VYtYtsMu74q - XviYjziVucWKjjKEb11juqnF0GDlB3VVmxHLmxnAz643WK42Z7dLM5sY29ouezv4Xz2PuM - ch5VGPP+CDqzCM4loWgV - ---- END SSH2 PUBLIC KEY ---- - - - ---- BEGIN SSH2 PUBLIC KEY ---- - Subject: galb - Comment: 1024-bit rsa, created by galb@shimi Mon Jan 15 08:31:24 2001 - AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt459 - 6k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4soW6 - NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0= - ---- END SSH2 PUBLIC KEY ---- - - - - - - - - - - - - - - - - -Galbraith & Thayer Expires April 16, 2003 [Page 7] - -Internet-Draft SSH Public Key File Format October 2002 - - -References - - [1] Rinne, T., Ylonen, T., Kivinen, T., Saarinen, M. and S. - Lehtinen, "SSH Protocol Transport Protocol", September 2002. - - [2] Yergeau, F., "UTF-8, a Transformation Format of Unicode and ISO - 10646", October 1996. - - [3] Bradner, S., "The Internet Standards Process -- Revision 3", - October 1996. - - [4] Bradner, S., "Key words for use in RFCs to Indicate Requirement - Levels", March 1997. - - [5] Freed and Borenstein, "Multipurpose Internet Mail Extensions - (MIME) Part One: Format of Internet Message Bodies", November - 1996. - - -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 - - - Rodney Thayer - The Tillerman Group - 370 Altair Way, PMB 321 - Sunnyvale, CA 94086 - - Phone: +1 408 757 9693 - EMail: rodney@tillerman.to - - - - - - - - - - - - -Galbraith & Thayer Expires April 16, 2003 [Page 8] - -Internet-Draft SSH Public Key File Format October 2002 - - -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 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. - - - - - - - - - - - - - - - - - - - -Galbraith & Thayer Expires April 16, 2003 [Page 9] - - diff --git a/doc/draft-ietf-secsh-scp-sftp-ssh-uri-00.txt b/doc/draft-ietf-secsh-scp-sftp-ssh-uri-00.txt deleted file mode 100644 index f582a49b..00000000 --- a/doc/draft-ietf-secsh-scp-sftp-ssh-uri-00.txt +++ /dev/null @@ -1,426 +0,0 @@ -Network Working Group S. Suehring -Internet-Draft Sentry Insurance -Expires February 8, 2004 J. Salowey - Cisco Systems - August 8, 2003 - - - SCP/SFTP/SSH URI Format - draft-ietf-secsh-scp-sftp-ssh-uri-00.txt - -Status of this Memo - - This document is an Internet-Draft and is subject to 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/1id-abstracts.html - - The list of Internet-Draft Shadow Directories can be accessed at - http://www.ietf.org/shadow.html - - This Internet Draft will expire on February 8, 2004. - - -Copyright Notice - - Copyright (C) The Internet Society (2003). All Rights Reserved. - - -Abstract - - This document describes the Uniform Resource Identifiers used to - locate resources for the SCP, SFTP, and SSH protocols. The document - describes the generic syntax involved in URI definitions as well as - specific definitions for each protocol. These specific definitions - may include user credentials such as username and password and also - may include other parameters such as fingerprint. In addition, - security considerations and examples are also provided within this - document. - - -General Syntax - - The URI for each protocol shall consist of the scheme and the scheme - specific portion separated by a colon ":", as discussed in RFC 2396 - [1]. This specification shall adopt the definitions "port", "host", - "scheme", "userinfo", and "authority" from RFC 2396. - - -Suehring & Salowey Expires February 8, 2004 [Page 1] - -Internet Draft SCP/SFTP/SSH URI Format August 8, 2003 - -SSH URI - - The SSH scheme shall consist of the protocol acronym followed by a - colon ":" and a double slash "//" in accordance with RFC 2718 [2]. - - The first component of the scheme specific portion MAY include - credentials (userinfo) consisting of a username and optionally also - including a password. Including the password in the URL is NOT - RECOMMENDED. The username and password components are separated by - a single colon ":". - - Following the userinfo, if present, the at-sign "@" shall - precede the authority section of the URI. Optionally, the - authority section MAY also include the port preceded by a colon ":". - If the port is not included, port 22 is assumed. Following the port - additional parameters may be specified. These parameters are - defined in the connection parameters section. - - ssh_URI = "ssh://" [ userinfo "@" ] host [ ":" port ] - [;conn-parameter=value] - -SCP and SFTP URI - - For SCP and SFTP, the scheme portion (scp: or sftp:) is followed by - a double slash "//". - - Both SCP and SFTP URLs are terminated by a single slash "/" followed - by the path information to the requested resource. - - The first component of the scheme specific portion MAY include - credentials (userinfo) consisting of a username and optionally also - including a password. Including the password in the URL is NOT - RECOMMENDED. The username and password components are separated by - a single colon ":". - - Following the userinfo, if present, the at-sign "@" shall precede - the authority section of the URL. Optionally, the authority section - MAY also include the port preceded by a colon ":". If the port is - not included, port 22 is assumed. Following the port additional - parameters may be specified. These parameters are defined in the - connection parameters section. - - scp_URI = "scp://" [ userinfo "@" ] host [ ":" port ] - [ ; parameter = value ] [ abs_path ] - - Following the port additional parameters may be specified. These - parameters are defined in the connection parameters section. - Following the path additional sftp specific parameters may be - specified. - - sftp_URI = "sftp://" [ userinfo "@" ] host [ ":" port ] - [;conn-parameter=value] [ abs_path ] [;sftp-parameter=value] - - - -Suehring & Salowey Expires February 8, 2004 [Page 2] - -Internet Draft SCP/SFTP/SSH URI Format August 8, 2003 - - -Parameters - -SSH connection parameters - - The following parameters are associated with an SSH connection and - are applicable to SSH, SFTP and SCP. All parameters are optional - and MUST NOT overwrite configured defaults. Individual parameters - are separated by a comma (","). - -fingerprint - - The fingerprint parameter contains the fingerprint of the host key - for the host specified in the URL. The fingerprint is encoded as - in [3]. This parameter MUST NOT overwrite a key that is already - configured for the host. They fingerprint MAY be used to validate - the authenticity of the host key if the URL was obtained from an - authenticated source with its integrity protected. If this - parameter is not included then the validity of the host key is - validated using another method. See Security Considerations section - for additional considerations. There MUST be only one fingerprint - parameter for a given URL. - -cipher - - The cipher parameter indicates an acceptable encryption mechanism to - use in making the connection. The value is the string specifying the - SSH cipher type. This parameter MUST NOT add a mechanism to a - configured list of default configured acceptable encryption types. - If this parameter is not specified then the default configured cipher - list is used. There may be more than one cipher parameter. - -integrity - - The integrity parameter indicates an acceptable data integrity - mechanism to use in making the connection. The value is the string - specifying the SSH data integrity type. This parameter MUST NOT add - a mechanism to a configured list of default configured acceptable - data integrity types. If this parameter is not specified then the - default configured data integrity list is used. There may be more - than one integrity parameter. - -key-xchg - - The key-xchg parameter indicates an acceptable key exchange mechanism - to use when making the connection. The value is the string - specifying the SSH key exchange type. This parameter MUST NOT add a - mechanism to a configured list of default configured acceptable key - exchange types. If this parameter is not specified then the default - configured key exchange list is used. There may be more than one - key-xchg parameter. - - - - - -Suehring & Salowey Expires February 8, 2004 [Page 3] - -Internet Draft SCP/SFTP/SSH URI Format August 8, 2003 - -host-key-alg - - The host-key-alg parameter indicates an host key to use when making - the connection. The value is the string specifying the SSH host key - type. This parameter MUST NOT add a mechanism to a configured list - of default configured acceptable host key types. If this parameter - is not specified then the default configured host key type list is - used. There may be more than one host-key-alg parameter. - -user-auth - - The user-auth parameter indicates a user authentication mechanism to - use when making the connection. The value is the string specifying - the SSH user authentication mechanism type. This parameter MUST NOT - add a mechanism to a configured list of default configured - acceptable user authentication mechanism types. If this parameter - is not specified then the default configured user authentication - mechanism type list is used. There may be more than one user-auth - parameter. - -SFTP Parameters - - The SFTP parameters determine how to handle the file transfer - character translation. - -newline - - The newline parameter determines how the server translates new line - indicators. The possible choices are usually "\r" or "\n" or "\r\n". - The default is "\r\n". - -typecode - - The typecode identifies the type of file which determines how it - will be treated. Possible values are "i" for binary files, "a" for - text files, and "d" for directory listings. - - -Examples - - The following section shows basic examples of URLs for each - protocol. This section should not be considered to include all - possible combinations of URLs for each protocol. - - ssh://user@host - - ssh://user@host:2222 - - ssh://joeuser@example.com;fingerprint=c1:b1:30:29:d7:b8:de:6c - :97:77:10:d7:46:41:63:87,cipher=aes-cbc - - scp://user:password@host/file.txt - - sftp://user@host/dir/path/file.txt - - -Suehring & Salowey Expires February 8, 2004 [Page 4] - -Internet Draft SCP/SFTP/SSH URI Format August 8, 2003 - - sftp://joeuser@example.com:2222;fingerprint=c1:b1:30:29:d7:b8 - :de:6c:97:77:10:d7:46:41:63:87,cipher= - aes-cbc/pub/docs/test.txt;typecode=a - - -Security Considerations - - In general, URIs themselves have no security considerations. - However, since the password for each scheme can optionally be - included within the URL it should be noted that doing so poses a - security risk. Since URLs are usually sent in the clear with no - encryption or other security, any password or other credentials - (userinfo) included could be seen by a potential attacker. - - The fingerprint should only be used to validate the host key only if - the URL can be determined to be authentic from a trusted entity. - For example, the URL may be received through secure email or HTTPS - from a trusted and verifiable source. It is possible that the SSH - implementation may not be able to determine if the URL is authentic - in which case it SHOULD prompt the user to either allow or disallow - the connection based on the information provided. The SSH - implementation MUST NOT overwrite a currently configured public key - based on the URL alone. - - The other connection parameters MUST NOT add any mechanism to the - list of configured acceptable mechanisms defined in the SSH client. - -Normative References - - [1] Berners-Lee, T., Fielding, R., Masinter, L., "Uniform Resource - Identifiers (URI): Generic Syntax", RFC 2396, August 1998. - - [2] Masinter, L., et. al., "Guidelines for new URL Schemes", RFC - 2718, November 1999. - - [3] Markus Friedl, "SSH Fingerprint Format", - http://www.ietf.org/internet-drafts/ - draft-ietf-secsh-fingerprint-01.txt, - work in progress - -Non-Normative References - - Mealling, M., Denenberg, R., "Report from the Joint W3C/IETF URI - Planning Interest Group: Uniform Resource Identifiers (URIs), URLs, - and Uniform Resource Names (URNs): Clarifications and - Recommendations", RFC 3305, August 2002. - - -Author Information - - Steve Suehring - Sentry Insurance - 1800 North Point Dr, G2/61-17 - Stevens Point, WI 54481 - suehring@braingia.com - - Joseph Salowey - Cisco Systems - 2901 Third Avenue - Seattle, WA 98121 - E-mail: jsalowey@cisco.com - - -Suehring & Salowey Expires February 8, 2004 [Page 5] - -Internet Draft SCP/SFTP/SSH URI Format August 8, 2003 - -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 (2003). 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 - HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF - MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. - - - - - - -Suehring & Salowey Expires February 8, 2004 [Page 6] - -Internet Draft SCP/SFTP/SSH URI Format August 8, 2003 - -Acknowledgement - - Funding for the RFC Editor function is currently provided by the - Internet Society. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Suehring & Salowey Expires February 8, 2004 [Page 7] diff --git a/doc/draft-ietf-secsh-transport-16.txt b/doc/draft-ietf-secsh-transport-16.txt deleted file mode 100644 index b4564f17..00000000 --- a/doc/draft-ietf-secsh-transport-16.txt +++ /dev/null @@ -1,1624 +0,0 @@ - - -Network Working Group T. Ylonen -Internet-Draft T. Kivinen -Expires: January 12, 2004 SSH Communications Security Corp - M. Saarinen - University of Jyvaskyla - T. Rinne - S. Lehtinen - SSH Communications Security Corp - July 14, 2003 - - - SSH Transport Layer Protocol - draft-ietf-secsh-transport-16.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 January 12, 2004. - -Copyright Notice - - Copyright (C) The Internet Society (2003). All Rights Reserved. - -Abstract - - 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 - - - -Ylonen, et. al. Expires January 12, 2004 [Page 1] - -Internet-Draft SSH Transport Layer Protocol July 2003 - - - 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. - -Table of Contents - - 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 - 2. Conventions Used in This Document . . . . . . . . . . . . . . 4 - 3. Connection Setup . . . . . . . . . . . . . . . . . . . . . . . 4 - 3.1 Use over TCP/IP . . . . . . . . . . . . . . . . . . . . . . . 4 - 3.2 Protocol Version Exchange . . . . . . . . . . . . . . . . . . 4 - 3.3 Compatibility With Old SSH Versions . . . . . . . . . . . . . 5 - 3.4 Old Client, New Server . . . . . . . . . . . . . . . . . . . . 5 - 3.5 New Client, Old Server . . . . . . . . . . . . . . . . . . . . 6 - 4. Binary Packet Protocol . . . . . . . . . . . . . . . . . . . . 6 - 4.1 Maximum Packet Length . . . . . . . . . . . . . . . . . . . . 7 - 4.2 Compression . . . . . . . . . . . . . . . . . . . . . . . . . 7 - 4.3 Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . 8 - 4.4 Data Integrity . . . . . . . . . . . . . . . . . . . . . . . . 10 - 4.5 Key Exchange Methods . . . . . . . . . . . . . . . . . . . . . 11 - 4.6 Public Key Algorithms . . . . . . . . . . . . . . . . . . . . 11 - 5. Key Exchange . . . . . . . . . . . . . . . . . . . . . . . . . 14 - 5.1 Algorithm Negotiation . . . . . . . . . . . . . . . . . . . . 14 - 5.2 Output from Key Exchange . . . . . . . . . . . . . . . . . . . 17 - 5.3 Taking Keys Into Use . . . . . . . . . . . . . . . . . . . . . 18 - 6. Diffie-Hellman Key Exchange . . . . . . . . . . . . . . . . . 19 - 6.1 diffie-hellman-group1-sha1 . . . . . . . . . . . . . . . . . . 20 - 7. Key Re-Exchange . . . . . . . . . . . . . . . . . . . . . . . 21 - 8. Service Request . . . . . . . . . . . . . . . . . . . . . . . 22 - 9. Additional Messages . . . . . . . . . . . . . . . . . . . . . 22 - 9.1 Disconnection Message . . . . . . . . . . . . . . . . . . . . 23 - 9.2 Ignored Data Message . . . . . . . . . . . . . . . . . . . . . 23 - 9.3 Debug Message . . . . . . . . . . . . . . . . . . . . . . . . 24 - 9.4 Reserved Messages . . . . . . . . . . . . . . . . . . . . . . 24 - 10. Summary of Message Numbers . . . . . . . . . . . . . . . . . . 24 - 11. Security Considerations . . . . . . . . . . . . . . . . . . . 25 - 12. Intellectual Property . . . . . . . . . . . . . . . . . . . . 25 - 13. Additional Information . . . . . . . . . . . . . . . . . . . . 25 - References . . . . . . . . . . . . . . . . . . . . . . . . . . 26 - Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . 27 - - - -Ylonen, et. al. Expires January 12, 2004 [Page 2] - -Internet-Draft SSH Transport Layer Protocol July 2003 - - - Full Copyright Statement . . . . . . . . . . . . . . . . . . . 29 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Ylonen, et. al. Expires January 12, 2004 [Page 3] - -Internet-Draft SSH Transport Layer Protocol July 2003 - - - 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, flexible, to allow - parameter negotiation, and to minimize the number of round-trips. - 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. Conventions Used in This Document - - The keywords "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD - NOT", and "MAY" that appear in this document are to be interpreted - as described in [RFC2119] - - The used data types and terminology are specified in the - architecture document [SSH-ARCH] - - The architecture document also discusses the algorithm naming - conventions that MUST be used with the SSH protocols. - - 3. 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. - - 3.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. - - 3.2 Protocol Version Exchange - - When the connection has been established, both sides MUST send an - - - -Ylonen, et. al. Expires January 12, 2004 [Page 4] - -Internet-Draft SSH Transport Layer Protocol July 2003 - - - identification string of the form "SSH-protoversion- - softwareversion comments", followed by carriage return and newline - characters (ASCII 13 and 10, respectively). Both sides MUST be - able to process identification strings without carriage return - character. No null character is sent. The maximum length of the - string is 255 characters, including the carriage return and - newline. - - The part of the identification string preceding carriage return - and newline is used in the Diffie-Hellman key exchange (see - Section Section 6). - - The server MAY send other lines of data before sending the version - string. Each line SHOULD be terminated by a carriage return and - newline. Such lines MUST NOT begin with "SSH-", and SHOULD be - encoded in ISO-10646 UTF-8 [RFC2279] (language is not specified). - Clients MUST be able to process such lines; they MAY be silently - ignored, or MAY be displayed to the client user; if they are - displayed, control character filtering 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. - - Version strings MUST consist of printable US-ASCII characters, not - including whitespaces or a minus sign (-). The version string is - primarily used to trigger compatibility extensions and to indicate - the capabilities of an implementation. The comment string should - contain additional information that might be useful in solving - user problems. - - The protocol version described in this document is 2.0. - - Key exchange will begin immediately after sending this identifier. - All packets following the identification string SHALL use the - binary packet protocol, to be described below. - - 3.3 Compatibility With Old SSH Versions - - During the transition period, it is important to be able to work - in a way that is compatible with the installed SSH clients and - servers that use an older version of the protocol. Information in - this section is only relevant for implementations supporting - compatibility with SSH versions 1.x. - - 3.4 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 protocol version as "1.99". - - - -Ylonen, et. al. Expires January 12, 2004 [Page 5] - -Internet-Draft SSH Transport Layer Protocol July 2003 - - - 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 version - identification string. - - In the compatibility mode the server SHOULD NOT send any further - data after its initialization 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 version - string. - - When compatibility with old clients is not needed, the server MAY - send its initial key exchange data immediately after the - identification string. - - 3.5 New Client, Old Server - - Since the new client MAY immediately send additional data after - its identification string (before receiving server's - identification), the old protocol may already have been corrupted - 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. - - 4. 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); m = mac_length - - packet_length - The length of the packet (bytes), not including MAC or the - packet_length field itself. - - padding_length - Length of padding (bytes). - - payload - The useful contents of the packet. If compression has been - negotiated, this field is compressed. Initially, - compression MUST be "none". - - - - -Ylonen, et. al. Expires January 12, 2004 [Page 6] - -Internet-Draft SSH Transport Layer Protocol July 2003 - - - random padding - Arbitrary-length padding, such that the total length of - (packet_length || padding_length || payload || padding) is a - multiple of the cipher block size or 8, whichever is 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 length of the concatenation of packet length, padding - length, payload, and 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. - - 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. - - 4.1 Maximum Packet Length - - All implementations MUST be able to process packets with - uncompressed payload length of 32768 bytes or less and total - packet size of 35000 bytes or less (including length, padding - length, payload, padding, and MAC.). The maximum of 35000 bytes - is an arbitrary chosen value larger than uncompressed size. - Implementations SHOULD support longer packets, where they might be - needed, e.g. if an implementation wants to send a very large - number of certificates. Such packets MAY be sent if the version - string indicates that the other party is able to process them. - However, implementations SHOULD check that the packet length is - reasonable for the implementation to avoid denial-of-service - and/or buffer overflow attacks. - - 4.2 Compression - - If compression has been negotiated, the payload field (and only - it) will be compressed using the negotiated algorithm. The length - field and MAC will be computed from the compressed payload. - Encryption will be done after compression. - - - - -Ylonen, et. al. Expires January 12, 2004 [Page 7] - -Internet-Draft SSH Transport Layer Protocol July 2003 - - - Compression MAY be stateful, depending on the method. Compression - MUST be independent for each direction, and implementations MUST - allow independently choosing the algorithm for each direction. - - 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]. - - 4.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, and implementations MUST allow independently choosing the - algorithm for each direction (if multiple algorithms are allowed - by local policy). - - The following ciphers are currently defined: - - 3des-cbc REQUIRED three-key 3DES in CBC mode - blowfish-cbc RECOMMENDED Blowfish in CBC mode - twofish256-cbc OPTIONAL Twofish in CBC mode, - with 256-bit key - twofish-cbc OPTIONAL alias for "twofish256-cbc" (this - is being retained for - historical reasons) - - - -Ylonen, et. al. Expires January 12, 2004 [Page 8] - -Internet-Draft SSH Transport Layer Protocol July 2003 - - - twofish192-cbc OPTIONAL Twofish with 192-bit key - twofish128-cbc RECOMMENDED Twofish with 128-bit key - aes256-cbc OPTIONAL AES (Rijndael) in CBC mode, - with 256-bit key - aes192-cbc OPTIONAL AES with 192-bit key - aes128-cbc RECOMMENDED AES with 128-bit key - serpent256-cbc OPTIONAL Serpent in CBC mode, with - 256-bit key - serpent192-cbc OPTIONAL Serpent with 192-bit key - serpent128-cbc OPTIONAL Serpent with 128-bit key - arcfour OPTIONAL the ARCFOUR stream cipher - 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 [SCHNEIER] - - The "blowfish-cbc" cipher is Blowfish in CBC mode, with 128 bit - keys [SCHNEIER]. This is a block cipher with 8 byte blocks. - - 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. Same as above but with 192-bit key. - - The "twofish128-cbc" cipher. Same as above but with 128-bit key. - - The "aes256-cbc" cipher is AES (Advanced Encryption Standard), - formerly Rijndael, in CBC mode. This version uses 256-bit key. - - The "aes192-cbc" cipher. Same as above but with 192-bit key. - - The "aes128-cbc" cipher. Same as above but with 128-bit key. - - The "serpent256-cbc" cipher in CBC mode, with 256-bit key as - described in the Serpent AES submission. - - The "serpent192-cbc" cipher. Same as above but with 192-bit key. - - The "serpent128-cbc" cipher. Same as above but with 128-bit key. - - - -Ylonen, et. al. Expires January 12, 2004 [Page 9] - -Internet-Draft SSH Transport Layer Protocol July 2003 - - - The "arcfour" is the Arcfour stream cipher with 128 bit keys. The - Arcfour cipher is believed to be compatible with the RC4 cipher - [SCHNEIER]. RC4 is a registered trademark of RSA Data Security - Inc. 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]. - IDEA is patented by Ascom AG. - - The "cast128-cbc" cipher is the CAST-128 cipher in CBC mode - [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]. - - 4.4 Data Integrity - - Data integrity is protected by including with each packet a - message authentication code (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 selected MAC 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 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. - - The MAC bytes resulting from the MAC algorithm MUST be transmitted - - - -Ylonen, et. al. Expires January 12, 2004 [Page 10] - -Internet-Draft SSH Transport Layer Protocol July 2003 - - - 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. - - The hash algorithms are described in [SCHNEIER]. - - Additional methods may be defined as specified in [SSH-ARCH]. - - 4.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. - - Only one REQUIRED key exchange method has been defined: - - diffie-hellman-group1-sha1 REQUIRED - - This method is described later in this document. - - Additional methods may be defined as specified in [SSH-ARCH]. - - 4.6 Public Key Algorithms - - This protocol has been designed to be able 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 - - - -Ylonen, et. al. Expires January 12, 2004 [Page 11] - -Internet-Draft SSH Transport Layer Protocol July 2003 - - - restricted by policy statements in e.g. 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. - - The following public key and/or certificate formats are currently defined: - - ssh-dss REQUIRED sign Simple DSS - ssh-rsa RECOMMENDED sign Simple RSA - x509v3-sign-rsa OPTIONAL sign X.509 certificates (RSA key) - x509v3-sign-dss OPTIONAL sign X.509 certificates (DSS key) - spki-sign-rsa OPTIONAL sign SPKI certificates (RSA key) - spki-sign-dss OPTIONAL sign SPKI certificates (DSS 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]. - - 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 have 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 / certifcate 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 / cert 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 - - - -Ylonen, et. al. Expires January 12, 2004 [Page 12] - -Internet-Draft SSH Transport Layer Protocol July 2003 - - - mpint g - mpint y - - Here the p, q, g, and y parameters form the signature key blob. - - Signing and verifying using this key format is done according to - the Digital Signature Standard [FIPS-186] using the SHA-1 hash. A - description can also be found in [SCHNEIER]. - - The resulting signature is encoded as follows: - - string "ssh-dss" - string dss_signature_blob - - dss_signature_blob is encoded as a string containing r followed by - s (which are 160 bits long 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 done according to - [SCHNEIER] and [PKCS1] using the SHA-1 hash. - - The resulting signature is encoded as follows: - - string "ssh-rsa" - string rsa_signature_blob - - 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 "spki-sign-rsa" method indicates that the certificate blob - contains a sequence of SPKI certificates. The format of SPKI - certificates is described in [RFC2693]. This method indicates - that the key (or one of the keys in the certificate) is an RSA- - key. - - The "spki-sign-dss". As above, but indicates that the key (or one - of the keys in the certificate) is a DSS-key. - - The "pgp-sign-rsa" method indicates the certificates, the public - - - -Ylonen, et. al. Expires January 12, 2004 [Page 13] - -Internet-Draft SSH Transport Layer Protocol July 2003 - - - 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". As above, but indicates that the key is a - DSS-key. - - 5. Key Exchange - - Key exchange begins by each side sending 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 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. - - 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 Section 5.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. - - Server authentication in the key exchange MAY be implicit. After - a key exchange with implicit server authentication, the client - MUST wait for response to its service request message before - sending any further data. - - 5.1 Algorithm Negotiation - - Key exchange begins by each side sending the following packet: - - byte SSH_MSG_KEXINIT - byte[16] cookie (random bytes) - string kex_algorithms - string server_host_key_algorithms - string encryption_algorithms_client_to_server - string encryption_algorithms_server_to_client - - - -Ylonen, et. al. Expires January 12, 2004 [Page 14] - -Internet-Draft SSH Transport Layer Protocol July 2003 - - - string mac_algorithms_client_to_server - string mac_algorithms_server_to_client - string compression_algorithms_client_to_server - string compression_algorithms_server_to_client - string languages_client_to_server - string languages_server_to_client - boolean first_kex_packet_follows - uint32 0 (reserved for future extension) - - Each of the algorithm strings MUST be a comma-separated list of - algorithm names (see ''Algorithm Naming'' in [SSH-ARCH]). Each - supported (allowed) algorithm MUST be listed in order of - preference. - - The first algorithm in each list MUST be the preferred (guessed) - algorithm. Each string 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 - + 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 - 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 - - - -Ylonen, et. al. Expires January 12, 2004 [Page 15] - -Internet-Draft SSH Transport Layer Protocol July 2003 - - - 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 encryption - capable host key. It MUST be possible to determine this - from the public key algorithm name. The first algorithm on - the client's 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 - Lists the acceptable symmetric encryption algorithms in - order of preference. The chosen encryption algorithm to - each direction MUST be the first algorithm on the client's - list that is also on the server's 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 Section 4.3. - - mac_algorithms - Lists the acceptable MAC algorithms in order of preference. - The chosen MAC algorithm MUST be the first algorithm on the - client's list that is also on the server's 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 - Figure 1. - - compression_algorithms - Lists the acceptable compression algorithms in order of - preference. The chosen compression algorithm MUST be the - first algorithm on the client's list that is also on the - server's 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 Section 4.2. - - - - -Ylonen, et. al. Expires January 12, 2004 [Page 16] - -Internet-Draft SSH Transport Layer Protocol July 2003 - - - languages - This is a comma-separated list of language tags in order of - preference [RFC1766]. Both parties MAY ignore this list. - If there are no language preferences, this list SHOULD be - empty. - - 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 KEXINIT packet exchange, the key exchange algorithm is - run. It may involve several packet exchanges, as specified by the - key exchange method. - - 5.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) - - - -Ylonen, et. al. Expires January 12, 2004 [Page 17] - -Internet-Draft SSH Transport Layer Protocol July 2003 - - - 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. 128 - bits (16 bytes) SHOULD be used for algorithms with variable-length - keys. For other algorithms, as many bytes as are needed are taken - from the beginning of the hash value. If the key length in 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: - - 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. - - 5.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 - taken into use for receiving. - - - This message is the only valid message after key exchange, in - addition to SSH_MSG_DEBUG, SSH_MSG_DISCONNECT and SSH_MSG_IGNORE - messages. The purpose of this message is to ensure that a party - is able to respond with a disconnect message that the other party - can understand if something goes wrong with the key exchange. - Implementations MUST NOT accept any other messages after key - exchange before receiving SSH_MSG_NEWKEYS. - - byte SSH_MSG_NEWKEYS - - - -Ylonen, et. al. Expires January 12, 2004 [Page 18] - -Internet-Draft SSH Transport Layer Protocol July 2003 - - - 6. Diffie-Hellman Key Exchange - - The Diffie-Hellman key exchange provides a shared secret that can - not be determined by either party alone. The key exchange is - combined with a signature with the host key to provide host - authentication. - - - In the following description (C is the client, S is the server; p - is a large safe prime, g is a generator for a subgroup of GF(p), - and q is the order of the subgroup; 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 S's KEXINIT message which 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. - - 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. - - 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. - - - 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 the following: - - - - -Ylonen, et. al. Expires January 12, 2004 [Page 19] - -Internet-Draft SSH Transport Layer Protocol July 2003 - - - byte SSH_MSG_KEXDH_INIT - mpint e - - - The server responds with the following: - - byte SSH_MSG_KEXDH_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 - 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. For example, "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. - - 6.1 diffie-hellman-group1-sha1 - - The "diffie-hellman-group1-sha1" method specifies Diffie-Hellman - key exchange with SHA-1 as HASH, and the following group: - - The prime p is equal to 2^1024 - 2^960 - 1 + 2^64 * floor( 2^894 - Pi + 129093 ). Its hexadecimal value is: - - FFFFFFFF FFFFFFFF C90FDAA2 2168C234 C4C6628B 80DC1CD1 - 29024E08 8A67CC74 020BBEA6 3B139B22 514A0879 8E3404DD - EF9519B3 CD3A431B 302B0A6D F25F1437 4FE1356D 6D51C245 - E485B576 625E7EC6 F44C42E9 A637ED6B 0BFF5CB6 F406B7ED - EE386BFB 5A899FA5 AE9F2411 7C4B1FE6 49286651 ECE65381 - FFFFFFFF FFFFFFFF. - - - -Ylonen, et. al. Expires January 12, 2004 [Page 20] - -Internet-Draft SSH Transport Layer Protocol July 2003 - - - In decimal, this value is: - - 179769313486231590770839156793787453197860296048756011706444 - 423684197180216158519368947833795864925541502180565485980503 - 646440548199239100050792877003355816639229553136239076508735 - 759914822574862575007425302077447712589550957937778424442426 - 617334727629299387668709205606050270810842907692932019128194 - 467627007. - - The generator used with this prime is g = 2. The group order q is - (p - 1) / 2. - - This group was taken from the ISAKMP/Oakley specification, and was - originally generated by Richard Schroeppel at the University of - Arizona. Properties of this prime are described in [Orm96]. - - 7. 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 - Section 5.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). - - - 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 are 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 - - - -Ylonen, et. al. Expires January 12, 2004 [Page 21] - -Internet-Draft SSH Transport Layer Protocol July 2003 - - - above the SSH transport layer. - - 8. 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]. - - - 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 - "servicename@domain" syntax. - - 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. - - - 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 Section 6 in [SSH-ARCH]). 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 response to its service - request message before sending any further data. - - 9. Additional Messages - - Either party may send any of the following messages at any time. - - - - -Ylonen, et. al. Expires January 12, 2004 [Page 22] - -Internet-Draft SSH Transport Layer Protocol July 2003 - - - 9.1 Disconnection Message - - byte SSH_MSG_DISCONNECT - uint32 reason code - string description [RFC2279] - string language tag [RFC1766] - - 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 description field gives a more specific explanation - in a human-readable form. The error code gives the reason in a - more machine-readable format (suitable for localization), and can - have the following values: - - #define SSH_DISCONNECT_HOST_NOT_ALLOWED_TO_CONNECT 1 - #define SSH_DISCONNECT_PROTOCOL_ERROR 2 - #define SSH_DISCONNECT_KEY_EXCHANGE_FAILED 3 - #define SSH_DISCONNECT_RESERVED 4 - #define SSH_DISCONNECT_MAC_ERROR 5 - #define SSH_DISCONNECT_COMPRESSION_ERROR 6 - #define SSH_DISCONNECT_SERVICE_NOT_AVAILABLE 7 - #define SSH_DISCONNECT_PROTOCOL_VERSION_NOT_SUPPORTED 8 - #define SSH_DISCONNECT_HOST_KEY_NOT_VERIFIABLE 9 - #define SSH_DISCONNECT_CONNECTION_LOST 10 - #define SSH_DISCONNECT_BY_APPLICATION 11 - #define SSH_DISCONNECT_TOO_MANY_CONNECTIONS 12 - #define SSH_DISCONNECT_AUTH_CANCELLED_BY_USER 13 - #define SSH_DISCONNECT_NO_MORE_AUTH_METHODS_AVAILABLE 14 - #define SSH_DISCONNECT_ILLEGAL_USER_NAME 15 - - If the description string is displayed, control character - filtering discussed in [SSH-ARCH] should be used to avoid attacks - by sending terminal control characters. - - 9.2 Ignored Data Message - - byte SSH_MSG_IGNORE - string data - - All implementations MUST understand (and ignore) this message at - any time (after receiving the protocol version). No - implementation is required to send them. This message can be used - as an additional protection measure against advanced traffic - analysis techniques. - - - -Ylonen, et. al. Expires January 12, 2004 [Page 23] - -Internet-Draft SSH Transport Layer Protocol July 2003 - - - 9.3 Debug Message - - byte SSH_MSG_DEBUG - boolean always_display - string message [RFC2279] - string language tag [RFC1766] - - All implementations MUST understand this message, but they are - allowed to ignore it. This message is used to pass the other side - 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, terminal control character - filtering discussed in [SSH-ARCH] should be used to avoid attacks - by sending terminal control characters. - - 9.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 - - - 10. Summary of Message Numbers - - The following message numbers have been defined in this protocol: - - #define SSH_MSG_DISCONNECT 1 - #define SSH_MSG_IGNORE 2 - #define SSH_MSG_UNIMPLEMENTED 3 - #define SSH_MSG_DEBUG 4 - #define SSH_MSG_SERVICE_REQUEST 5 - #define SSH_MSG_SERVICE_ACCEPT 6 - - #define SSH_MSG_KEXINIT 20 - - - -Ylonen, et. al. Expires January 12, 2004 [Page 24] - -Internet-Draft SSH Transport Layer Protocol July 2003 - - - #define SSH_MSG_NEWKEYS 21 - - /* Numbers 30-49 used for kex packets. - Different kex methods may reuse message numbers in - this range. */ - - #define SSH_MSG_KEXDH_INIT 30 - #define SSH_MSG_KEXDH_REPLY 31 - - - 11. 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 - Section 8 of [SSH-ARCH] - - 12. 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. - - 13. Additional Information - - The current document editor is: Darren.Moffat@Sun.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 - - - -Ylonen, et. al. Expires January 12, 2004 [Page 25] - -Internet-Draft SSH Transport Layer Protocol July 2003 - - -References - - [FIPS-186] Federal Information Processing Standards - Publication, ., "FIPS PUB 186, Digital Signature - Standard", May 1994. - - [Orm96] Orman, H., "The Okaley Key Determination Protcol - version1, TR97-92", 1996. - - [RFC2459] Housley, R., Ford, W., Polk, W. and D. Solo, - "Internet X.509 Public Key Infrastructure - Certificate and CRL Profile", RFC 2459, January - 1999. - - [RFC1034] Mockapetris, P., "Domain names - concepts and - facilities", STD 13, RFC 1034, Nov 1987. - - [RFC1766] Alvestrand, H., "Tags for the Identification of - Languages", RFC 1766, March 1995. - - [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. - - [RFC2279] Yergeau, F., "UTF-8, a transformation format of - ISO 10646", RFC 2279, January 1998. - - [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. - - [RFC2440] Callas, J., Donnerhacke, L., Finney, H. and R. - Thayer, "OpenPGP Message Format", RFC 2440, - November 1998. - - [RFC2693] Ellison, C., Frantz, B., Lampson, B., Rivest, R., - Thomas, B. and T. Ylonen, "SPKI Certificate - Theory", RFC 2693, September 1999. - - - -Ylonen, et. al. Expires January 12, 2004 [Page 26] - -Internet-Draft SSH Transport Layer Protocol July 2003 - - - [SCHNEIER] Schneier, B., "Applied Cryptography Second - Edition: protocols algorithms and source in code - in C", 1996. - - [TWOFISH] Schneier, B., "The Twofish Encryptions Algorithm: - A 128-Bit Block Cipher, 1st Edition", March 1999. - - [SSH-ARCH] Ylonen, T., "SSH Protocol Architecture", I-D - draft-ietf-architecture-14.txt, July 2003. - - [SSH-TRANS] Ylonen, T., "SSH Transport Layer Protocol", I-D - draft-ietf-transport-16.txt, July 2003. - - [SSH-USERAUTH] Ylonen, T., "SSH Authentication Protocol", I-D - draft-ietf-userauth-17.txt, July 2003. - - [SSH-CONNECT] Ylonen, T., "SSH Connection Protocol", I-D draft- - ietf-connect-17.txt, July 2003. - - [SSH-NUMBERS] Lehtinen, S. and D. Moffat, "SSH Protocol Assigned - Numbers", I-D draft-ietf-secsh-assignednumbers- - 03.txt, July 2003. - - -Authors' Addresses - - Tatu Ylonen - SSH Communications Security Corp - Fredrikinkatu 42 - HELSINKI FIN-00100 - Finland - - EMail: ylo@ssh.com - - - Tero Kivinen - SSH Communications Security Corp - Fredrikinkatu 42 - HELSINKI FIN-00100 - Finland - - EMail: kivinen@ssh.com - - - Markku-Juhani O. Saarinen - University of Jyvaskyla - - - - - -Ylonen, et. al. Expires January 12, 2004 [Page 27] - -Internet-Draft SSH Transport Layer Protocol July 2003 - - - Timo J. Rinne - SSH Communications Security Corp - Fredrikinkatu 42 - HELSINKI FIN-00100 - Finland - - EMail: tri@ssh.com - - - Sami Lehtinen - SSH Communications Security Corp - Fredrikinkatu 42 - HELSINKI FIN-00100 - Finland - - EMail: sjl@ssh.com - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Ylonen, et. al. Expires January 12, 2004 [Page 28] - -Internet-Draft SSH Transport Layer Protocol July 2003 - - -Full Copyright Statement - - Copyright (C) The Internet Society (2003). 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, et. al. Expires January 12, 2004 [Page 29] - diff --git a/doc/draft-ietf-secsh-userauth-17.txt b/doc/draft-ietf-secsh-userauth-17.txt deleted file mode 100644 index 6624665e..00000000 --- a/doc/draft-ietf-secsh-userauth-17.txt +++ /dev/null @@ -1,840 +0,0 @@ - - -Network Working Group T. Ylonen -Internet-Draft T. Kivinen -Expires: March 2, 2003 SSH Communications Security Corp - M. Saarinen - University of Jyvaskyla - T. Rinne - S. Lehtinen - SSH Communications Security Corp - September 2002 - - - SSH Authentication Protocol - draft-ietf-secsh-userauth-17.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 March 2, 2003. - -Copyright Notice - - Copyright (C) The Internet Society (2002). All Rights Reserved. - -Abstract - - 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 - - - -Ylonen, et. al. Expires March 2, 2003 [Page 1] - -Internet-Draft SSH Authentication Protocol September 2002 - - - SSH authentication protocol runs on top of the SSH transport layer - protocol and provides a single authenticated tunnel for the SSH - connection protocol. - -Table of Contents - - 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 - 2. The Authentication Protocol Framework . . . . . . . . . . . . 3 - 2.1 Authentication Requests . . . . . . . . . . . . . . . . . . . 4 - 2.2 Responses to Authentication Requests . . . . . . . . . . . . . 5 - 2.3 The "none" Authentication Request . . . . . . . . . . . . . . 6 - 2.4 Completion of User Authentication . . . . . . . . . . . . . . 6 - 2.5 Banner Message . . . . . . . . . . . . . . . . . . . . . . . . 6 - 3. Authentication Protocol Message Numbers . . . . . . . . . . . 7 - 4. Public Key Authentication Method: publickey . . . . . . . . . 7 - 5. Password Authentication Method: password . . . . . . . . . . . 9 - 6. Host-Based Authentication: hostbased . . . . . . . . . . . . . 11 - 7. Security Considerations . . . . . . . . . . . . . . . . . . . 12 - 8. Intellectual Property . . . . . . . . . . . . . . . . . . . . 12 - 9. Additional Information . . . . . . . . . . . . . . . . . . . . 13 - References . . . . . . . . . . . . . . . . . . . . . . . . . . 13 - Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . 14 - Full Copyright Statement . . . . . . . . . . . . . . . . . . . 15 - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Ylonen, et. al. Expires March 2, 2003 [Page 2] - -Internet-Draft SSH Authentication Protocol September 2002 - - - 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. - - 2. 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 - allowed in 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 - - - -Ylonen, et. al. Expires March 2, 2003 [Page 3] - -Internet-Draft SSH Authentication Protocol September 2002 - - - exceeded, the server SHOULD disconnect. - - 2.1 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 [RFC2279]) - string service name (in US-ASCII) - string method name (US-ASCII) - The rest of the packet is method-specific. - - The user name and service 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 flush - some authentication state, it MUST disconnect if the user or - service name changes. - - The service name specifies the service to start after - authentication. There may be several different authenticated - services provided. If the requested service is not available, the - server MAY disconnect immediately or at any later time. Sending a - proper disconnect message is RECOMMENDED. In any case, if the - service does not exist, authentication MUST NOT be accepted. - - If the requested user does not exist, the server MAY disconnect, - or MAY send a bogus list of acceptable authentication methods, 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 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 - 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. - - - - - -Ylonen, et. al. Expires March 2, 2003 [Page 4] - -Internet-Draft SSH Authentication Protocol September 2002 - - - 2.2 Responses to Authentication Requests - - If the server rejects the authentication request, it MUST respond - with the following: - - byte SSH_MSG_USERAUTH_FAILURE - string authentications that can continue - boolean partial success - - "Authentications that can continue" is a comma-separated list of - authentication method names that may productively continue the - authentication dialog. - - It is RECOMMENDED that servers only include those methods in the - list that are actually useful. However, it is not illegal to - include methods that cannot be used to authenticate the user. - - Already successfully completed authentications SHOULD NOT be - included in the list, unless they really should be performed again - for some reason. - - "Partial success" MUST be TRUE if the authentication request to - which 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 results in further exchange of messages will be - aborted by a second request. It is not possible to send a second - request without waiting for a response from the server, if the - first request will result in further exchange of messages. No - SSH_MSG_USERAUTH_FAILURE message will be sent for the aborted - method. - - SSH_MSG_USERAUTH_SUCCESS MUST be sent only once. When - - - -Ylonen, et. al. Expires March 2, 2003 [Page 5] - -Internet-Draft SSH Authentication Protocol September 2002 - - - 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 - Message Numbers (Section 3)). - - 2.3 The "none" Authentication Request - - A client may request a list of authentication methods that may - continue by using the "none" authentication method. - - If no authentication at all 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 - authentication methods that can continue. - - This method MUST NOT be listed as supported by the server. - - 2.4 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. - - 2.5 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', or use "tcp wrappers" or similar software to display - a banner before issuing a login prompt. - - The SSH server may send a SSH_MSG_USERAUTH_BANNER message at any - time 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 (ISO-10646 UTF-8) - string language tag (as defined in [RFC1766]) - - The client SHOULD by default display the message on the screen. - - - -Ylonen, et. al. Expires March 2, 2003 [Page 6] - -Internet-Draft SSH Authentication Protocol September 2002 - - - 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. - - If the message string is displayed, control character filtering - discussed in [SSH-ARCH] SHOULD be used to avoid attacks by sending - terminal control characters. - - 3. 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 first to ease troubleshooting). - - After successful authentication, such messages are passed to the - higher-level service. - - These are the general authentication message codes: - - #define SSH_MSG_USERAUTH_REQUEST 50 - #define SSH_MSG_USERAUTH_FAILURE 51 - #define SSH_MSG_USERAUTH_SUCCESS 52 - #define SSH_MSG_USERAUTH_BANNER 53 - - In addition to the above, there is a range of message numbers - (60..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. - - 4. Public Key Authentication Method: publickey - - The only REQUIRED authentication method is public key - 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 - - - -Ylonen, et. al. Expires March 2, 2003 [Page 7] - -Internet-Draft SSH Authentication Protocol September 2002 - - - 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.) - - 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 key would be - acceptable. - - byte SSH_MSG_USERAUTH_REQUEST - string user name - string service - 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 - string "publickey" - - - -Ylonen, et. al. Expires March 2, 2003 [Page 8] - -Internet-Draft SSH Authentication Protocol September 2002 - - - boolean TRUE - string public key algorithm name - string public key to be used for authentication - string signature - - 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 - 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. - - /* Key-based */ - #define SSH_MSG_USERAUTH_PK_OK 60 - - - 5. Password Authentication Method: password - - Password authentication uses the following packets. Note that a - server MAY request the user to change the password. All - implementations SHOULD support password authentication. - - byte SSH_MSG_USERAUTH_REQUEST - string user name - string service - string "password" - boolean FALSE - string plaintext password (ISO-10646 UTF-8) - - Note that the password is encoded in ISO-10646 UTF-8. It is up to - - - -Ylonen, et. al. Expires March 2, 2003 [Page 9] - -Internet-Draft SSH Authentication Protocol September 2002 - - - |