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 . 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 - - -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 - - -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 - . - - The list of Internet-Draft Shadow Directories can be accessed at - . - - 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 - - - The SSH_FXP_VERSION packet (from server to client) has the following - data: - - uint32 version - - - 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 - - - '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 - - - '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 -ctr means that the block cipher is to be - used in "stateful-decryption counter" (SDCTR) mode. Let L be the - block length of 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 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 with - 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 with - 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, , or - . - - 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 - - - the server how it interprets the password and validates it against - the password database. However, if the client reads the password - in some other encoding (e.g., ISO 8859-1 (ISO Latin1)), it MUST - convert the password to ISO-10646 UTF-8 before transmitting, and - the server MUST convert the password to the encoding used on that - system for passwords. - - Note that even though the cleartext password is transmitted in the - packet, the entire packet is encrypted by the transport layer. - Both the server and the client should check whether the underlying - transport layer provides confidentiality (i.e., if encryption is - being used). If no confidentiality is provided (none cipher), - password authentication SHOULD be disabled. If there is no - confidentiality or no MAC, password change SHOULD be disabled. - - Normally, the server responds to this message with success or - failure. However, if the password has expired the server SHOULD - indicate this by responding with - SSH_MSG_USERAUTH_PASSWD_CHANGEREQ. In anycase the server MUST NOT - allow an expired password to be used for authentication. - - byte SSH_MSG_USERAUTH_PASSWD_CHANGEREQ - string prompt (ISO-10646 UTF-8) - string language tag (as defined in [RFC1766]) - - In this case, the client MAY continue with a different - authentication method, or request a new password from the user and - retry password authentication using the following message. The - client MAY also send this message instead of the normal password - authentication request without the server asking for it. - - byte SSH_MSG_USERAUTH_REQUEST - string user name - string service - string "password" - boolean TRUE - string plaintext old password (ISO-10646 UTF-8) - string plaintext new password (ISO-10646 UTF-8) - - The server must reply to request message with - SSH_MSG_USERAUTH_SUCCESS, SSH_MSG_USERAUTH_FAILURE, or another - SSH_MSG_USERAUTH_PASSWD_CHANGEREQ. The meaning of these is as - follows: - - SSH_MSG_USERAUTH_SUCCESS The password has been changed, and - authentication has been successfully completed. - - SSH_MSG_USERAUTH_FAILURE with partial success The password has - - - -Ylonen, et. al. Expires March 2, 2003 [Page 10] - -Internet-Draft SSH Authentication Protocol September 2002 - - - been changed, but more authentications are needed. - - SSH_MSG_USERAUTH_FAILURE without partial success The password - has not been changed. Either password changing was not - supported, or the old password was bad. Note that if the - server has already sent SSH_MSG_USERAUTH_PASSWD_CHANGEREQ, we - know that it supports changing the password. - - SSH_MSG_USERAUTH_CHANGEREQ The password was not changed because - the new password was not acceptable (e.g. too easy to guess). - - The following method-specific message numbers are used by the - password authentication method. - - #define SSH_MSG_USERAUTH_PASSWD_CHANGEREQ 60 - - - 6. Host-Based Authentication: hostbased - - Some sites wish to allow authentication based on the host where - the user is coming from, and the user name on the remote host. - While this form of authentication is not suitable for high- - security sites, it can be very convenient in many environments. - This form of authentication is OPTIONAL. When used, special care - SHOULD be taken to prevent a regular user from obtaining the - private host key. - - The client requests this form of authentication by sending the - following message. It is similar to the UNIX "rhosts" and - "hosts.equiv" styles of authentication, except that the identity - of the client host is checked more rigorously. - - This method works by having the client send a signature created - with the private key of the client host, which the server checks - with that host's public key. Once the client host's identity is - established, authorization (but no further authentication) is - performed based on the user names on the server and the client, - and the client host name. - - byte SSH_MSG_USERAUTH_REQUEST - string user name - string service - string "hostbased" - string public key algorithm for host key - string public host key and certificates for client host - string client host name (FQDN; US-ASCII) - string user name on the client host (ISO-10646 UTF-8) - string signature - - - -Ylonen, et. al. Expires March 2, 2003 [Page 11] - -Internet-Draft SSH Authentication Protocol September 2002 - - - Public key algorithm names for use in "public key algorithm for - host key" are defined in the transport layer specification. The - "public host key for client host" may include certificates. - - Signature is a signature with the private host key of the - following data, in this order: - - string session identifier - byte SSH_MSG_USERAUTH_REQUEST - string user name - string service - string "hostbased" - string public key algorithm for host key - string public host key and certificates for client host - string client host name (FQDN; US-ASCII) - string user name on the client host(ISO-10646 UTF-8) - - The server MUST verify that the host key actually belongs to the - client host named in the message, that the given user on that host - is allowed to log in, and that the signature is a valid signature - on the appropriate value by the given host key. The server MAY - ignore the client user name, if it wants to authenticate only the - client host. - - It is RECOMMENDED that whenever possible, the server perform - additional checks to verify that the network address obtained from - the (untrusted) network matches the given client host name. This - makes exploiting compromised host keys more difficult. Note that - this may require special handling for connections coming through a - firewall. - - 7. Security Considerations - - The purpose of this protocol is to perform client user - authentication. It assumed that this runs over a secure transport - layer protocol, which has already authenticated the server - machine, established an encrypted communications channel, and - computed a unique session identifier for this session. The - transport layer provides forward secrecy for password - authentication and other methods that rely on secret data. - - Full security considerations for this protocol are provided in - Section 8 of [SSH-ARCH] - - 8. Intellectual Property - - The IETF takes no position regarding the validity or scope of any - intellectual property or other rights that might be claimed to - - - -Ylonen, et. al. Expires March 2, 2003 [Page 12] - -Internet-Draft SSH Authentication Protocol September 2002 - - - 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. - - 9. 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. - - [RFC2279] Yergeau, F., "UTF-8, a transformation format of - ISO 10646", RFC 2279, January 1998. - - [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. - - - -Ylonen, et. al. Expires March 2, 2003 [Page 13] - -Internet-Draft SSH Authentication Protocol September 2002 - - -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 - - - Sami Lehtinen - SSH Communications Security Corp - Fredrikinkatu 42 - HELSINKI FIN-00100 - Finland - - EMail: sjl@ssh.com - - - - - - - - - - - -Ylonen, et. al. Expires March 2, 2003 [Page 14] - -Internet-Draft SSH Authentication Protocol September 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. - - - - - - - - - - - - - - - - - - - -Ylonen, et. al. Expires March 2, 2003 [Page 15] - diff --git a/doc/protocol-1.5.txt b/doc/protocol-1.5.txt deleted file mode 100644 index 9d49f6a9..00000000 --- a/doc/protocol-1.5.txt +++ /dev/null @@ -1,1501 +0,0 @@ -Network Working Group T. Ylonen -Internet-Draft Helsinki University of Technology -draft-ylonen-ssh-protocol-00.txt 15 November 1995 -Expires: 15 May 1996 - - - The SSH (Secure Shell) Remote Login Protocol - -Status of This Memo - - This document is an Internet-Draft. 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.'' - - To learn the current status of any Internet-Draft, please check the "1id-abstracts.txt'' listing contained in the Internet- Drafts Shadow Directories on ftp.is.co.za (Africa), nic.nordu.net (Europe), munnari.oz.au (Pacific Rim), ds.internic.net (US East Coast), or ftp.isi.edu (US West Coast). - - The distribution of this memo is unlimited. - -Introduction - - SSH (Secure Shell) is a program to log into another computer over a network, to execute commands in a remote machine, and to move files from one machine to another. It provides strong authentication and secure communications over insecure networks. Its features include - the following: - - o Closes several security holes (e.g., IP, routing, and DNS spoofing). New authentication methods: .rhosts together with RSA [RSA] based host authentication, and pure RSA authentication. - - o All communications are automatically and transparently encrypted. Encryption is also used to protect integrity. - - o X11 connection forwarding provides secure X11 sessions. - - o Arbitrary TCP/IP ports can be redirected over the encrypted channel in both directions. - - o Client RSA-authenticates the server machine in the beginning of every connection to prevent trojan horses (by routing or DNS spoofing) and man-in-the-middle attacks, and the server RSA-authenticates the client machine before accepting .rhosts or /etc/hosts.equiv authentication (to prevent DNS, routing, or IP spoofing). - - o An authentication agent, running in the user's local workstation or laptop, can be used to hold the user's RSA authentication keys. - - The goal has been to make the software as easy to use as possible for ordinary users. The protocol has been designed to be as secure as possible while making it possible to create implementations that are easy to use and install. The sample implementation has a number of convenient features that are not described in this document as they are not relevant for the protocol. - - -Overview of the Protocol - - The software consists of a server program running on a server machine, and a client program running on a client machine (plus a few auxiliary programs). The machines are connected by an insecure IP [RFC0791] network (that can be monitored, tampered with, and spoofed by hostile parties). - - A connection is always initiated by the client side. The server listens on a specific port waiting for connections. Many clients may connect to the same server machine. - - The client and the server are connected via a TCP/IP [RFC0793] socket that is used for bidirectional communication. Other types of transport can be used but are currently not defined. - - When the client connects the server, the server accepts the connection and responds by sending back its version identification string. - The client parses the server's identification, and sends its own identification. The purpose of the identification strings is to validate that the connection was to the correct port, declare the protocol version number used, and to declare the software version used on each side (for debugging purposes). The identification strings are human-readable. If either side fails to understand or support the other side's version, it closes the connection. - - After the protocol identification phase, both sides switch to a packet based binary protocol. The server starts by sending its host key (every host has an RSA key used to authenticate the host), server key (an RSA key regenerated every hour), and other information to the client. The client then generates a 256 bit session key, encrypts it using both RSA keys (see below for details), and sends the encrypted session key and selected cipher type to the server. Both sides then turn on encryption using the selected algorithm and key. The server sends an encrypted confirmation message to the client. - - The client then authenticates itself using any of a number of authentication methods. The currently supported authentication methods are .rhosts or /etc/hosts.equiv authentication (disabled by default), the same with RSA-based host authentication, RSA authentication, and password authentication. - - After successful authentication, the client makes a number of requests to prepare for the session. Typical requests include allocating a pseudo tty, starting X11 [X11] or TCP/IP port forwarding, - starting authentication agent forwarding, and executing the shell or a command. - - When a shell or command is executed, the connection enters interactive session mode. In this mode, data is passed in both directions, new forwarded connections may be opened, etc. The interactive session normally terminates when the server sends the exit status of the program to the client. - - - The protocol makes several reservations for future extensibility. First of all, the initial protocol identification messages include the protocol version number. Second, the first packet by both sides includes a protocol flags field, which can be used to agree on extensions in a compatible manner. Third, the authentication and session preparation phases work so that the client sends requests to the server, and the server responds with success or failure. If the client sends a request that the server does not support, the server simply returns failure for it. This permits compatible addition of new authentication methods and preparation operations. The interactive session phase, on the other hand, works asynchronously and does not permit the use of any extensions (because there is no easy and reliable way to signal rejection to the other side and problems would be hard to debug). Any compatible extensions to this phase must be agreed upon during any of the earlier phases. - -The Binary Packet Protocol - - After the protocol identification strings, both sides only send specially formatted packets. The packet layout is as follows: - - o Packet length: 32 bit unsigned integer, coded as four 8-bit bytes, msb first. Gives the length of the packet, not including the length field and padding. The maximum length of a packet (not including the length field and padding) is 262144 bytes. - - o Padding: 1-8 bytes of random data (or zeroes if not encrypting). The amount of padding is (8 - (length % 8)) bytes (where % stands for the modulo operator). The rationale for always having some random padding at the beginning of each packet is to make known plaintext attacks more difficult. - - o Packet type: 8-bit unsigned byte. The value 255 is reserved for future extension. - - o Data: binary data bytes, depending on the packet type. The number of data bytes is the "length" field minus 5. - - o Check bytes: 32-bit crc, four 8-bit bytes, msb first. The crc is the Cyclic Redundancy Check, with the polynomial 0xedb88320, of the Padding, Packet type, and Data fields. The crc is computed before any encryption. - - The packet, except for the length field, may be encrypted using any of a number of algorithms. The length of the encrypted part (Padding + Type + Data + Check) is always a multiple of 8 bytes. Typically the cipher is used in a chained mode, with all packets chained together as if it was a single data stream (the length field is never included in the encryption process). Details of encryption are described below. - - When the session starts, encryption is turned off. Encryption is enabled after the client has sent the session key. The encryption algorithm to use is selected by the client. - - -Packet Compression - - If compression is supported (it is an optional feature, see SSH_CMSG_REQUEST_COMPRESSION below), the packet type and data fields of the packet are compressed using the gzip deflate algorithm [GZIP]. - If compression is in effect, the packet length field indicates the length of the compressed data, plus 4 for the crc. The amount of padding is computed from the compressed data, so that the amount of data to be encrypted becomes a multiple of 8 bytes. - - When compressing, the packets (type + data portions) in each direction are compressed as if they formed a continuous data stream, with only the current compression block flushed between packets. This corresponds to the GNU ZLIB library Z_PARTIAL_FLUSH option. The compression dictionary is not flushed between packets. The two directions are compressed independently of each other. - - -Packet Encryption - - The protocol supports several encryption methods. During session initialization, the server sends a bitmask of all encryption methods that it supports, and the client selects one of these methods. The client also generates a 256-bit random session key (32 8-bit bytes) and sends it to the server. - - The encryption methods supported by the current implementation, and their codes are: - - SSH_CIPHER_NONE 0 No encryption - SSH_CIPHER_IDEA 1 IDEA in CFB mode - SSH_CIPHER_DES 2 DES in CBC mode - SSH_CIPHER_3DES 3 Triple-DES in CBC mode - SSH_CIPHER_RC4 5 RC4 - - All implementations are required to support SSH_CIPHER_3DES. Supporting SSH_CIPHER_IDEA, SSH_CIPHER_RC4, and SSH_CIPHER_NONE is recommended. Other ciphers may be added at a later time; support for them is optional. - - For encryption, the encrypted portion of the packet is considered a linear byte stream. The length of the stream is always a multiple of 8. The encrypted portions of consecutive packets (in the same direction) are encrypted as if they were a continuous buffer (that is, any initialization vectors are passed from the previous packet to the next packet). Data in each direction is encrypted independently. - - SSH_CIPHER_DES - The key is taken from the first 8 bytes of the session key. The least significant bit of each byte is ignored. This results in 56 bits of key data. DES [DES] is used in CBC mode. The iv (initialization vector) is initialized to all zeroes. - - SSH_CIPHER_3DES - The variant of triple-DES used here works as follows: there are three independent DES-CBC ciphers, with independent initialization vectors. The data (the whole encrypted data stream) is first encrypted with the first cipher, then decrypted with the second cipher, and finally encrypted with the third cipher. All these operations are performed in CBC mode. - - The key for the first cipher is taken from the first 8 bytes of the session key; the key for the next cipher from the next 8 bytes, and the key for the third cipher from the following 8 bytes. All three initialization vectors are initialized to zero. - - (Note: the variant of 3DES used here differs from some other descriptions.) - - SSH_CIPHER_IDEA - The key is taken from the first 16 bytes of the session key. IDEA [IDEA] is used in CFB mode. The initialization vector is initialized to all zeroes. - - SSH_CIPHER_RC4 - The first 16 bytes of the session key are used as the key for the server to client direction. The remaining 16 bytes are used as the key for the client to server direction. This gives independent 128-bit keys for each direction. - - This algorithm is the alleged RC4 cipher posted to the Usenet in 1995. It is widely believed to be equivalent with the original RSADSI RC4 cipher. This is a very fast algorithm. - - -Data Type Encodings - - The Data field of each packet contains data encoded as described in this section. There may be several data items; each item is coded as described here, and their representations are concatenated together (without any alignment or padding). - - Each data type is stored as follows: - - 8-bit byte - The byte is stored directly as a single byte. - - 32-bit unsigned integer - Stored in 4 bytes, msb first. - - Arbitrary length binary string - First 4 bytes are the length of the string, msb first (not including the length itself). The following "length" bytes are the string value. There are no terminating null characters. - - Multiple-precision integer - First 2 bytes are the number of bits in the integer, msb first (for example, the value 0x00012345 would have 17 bits). The value zero has zero bits. It is permissible that the number of bits be larger than the real number of bits. - - The number of bits is followed by (bits + 7) / 8 bytes of binary data, msb first, giving the value of the integer. - - -TCP/IP Port Number and Other Options - - The server listens for connections on TCP/IP port 22. - - The client may connect the server from any port. However, if the client wishes to use any form of .rhosts or /etc/hosts.equiv authentication, it must connect from a privileged port (less than 1024). - - For the IP Type of Service field [RFC0791], it is recommended that interactive sessions (those having a user terminal or forwarding X11 connections) use the IPTOS_LOWDELAY, and non-interactive connections use IPTOS_THROUGHPUT. - - It is recommended that keepalives are used, because otherwise programs on the server may never notice if the other end of the connection is rebooted. - - -Protocol Version Identification - - After the socket is opened, the server sends an identification string, which is of the form "SSH-.-\n", where and are integers and specify the protocol version number (not software distribution version). is server side software version string (max 40 characters); it is not interpreted by the remote side but may be useful for debugging. - - The client parses the server's string, and sends a corresponding string with its own information in response. If the server has lower version number, and the client contains special code to emulate it, - the client responds with the lower number; otherwise it responds with its own number. The server then compares the version number the client sent with its own, and determines whether they can work together. The server either disconnects, or sends the first packet using the binary packet protocol and both sides start working according to the lower of the protocol versions. - - By convention, changes which keep the protocol compatible with previous versions keep the same major protocol version; changes that are not compatible increment the major version (which will hopefully never happen). The version described in this document is 1.5. - -Key Exchange and Server Host Authentication - - The first message sent by the server using the packet protocol is SSH_SMSG_PUBLIC_KEY. It declares the server's host key, server public key, supported ciphers, supported authentication methods, and flags for protocol extensions. It also contains a 64-bit random number (cookie) that must be returned in the client's reply (to make IP spoofing more difficult). No encryption is used for this message. - - Both sides compute a session id as follows. The modulus of the host key is interpreted as a byte string (without explicit length field, with minimum length able to hold the whole value), most significant byte first. This string is concatenated with the server key interpreted the same way. Additionally, the cookie is concatenated with this. Both sides compute MD5 of the resulting string. The resulting 16 bytes (128 bits) are stored by both parties and are called the session id. - - In other words, session_id = MD5(hostkey->n || servkey->n || cookie) - - The client responds with a SSH_CMSG_SESSION_KEY message, which contains the selected cipher type, a copy of the 64-bit cookie sent by the server, client's protocol flags, and a session key encrypted with both the server's host key and server key. No encryption is used for this message. -The session key is 32 8-bit bytes (a total of 256 random bits generated by the client). The client first xors the 16 bytes of the session id with the first 16 bytes of the session key. The resulting string is then encrypted using the smaller key (one with smaller modulus), and the result is then encrypted using the other key. The number of bits in the public modulus of the two keys must differ by at least 128 bits. - - At each encryption step, a multiple-precision integer is constructed from the data to be encrypted as follows (the integer is here interpreted as a sequence of bytes, msb first; the number of bytes is the number of bytes needed to represent the modulus). - - The most significant byte (which is only partial as the value must be less than the public modulus, which is never a power of two) is zero. - - The next byte contains the value 2 (which stands for public-key encrypted data in the PKCS standard [PKCS#1]). Then, there are nonzero random bytes to fill any unused space, a zero byte, and the data to be encrypted in the least significant bytes, the last byte of the data in the least significant byte. - - This algorithm is used twice. First, it is used to encrypt the 32 random bytes generated by the client to be used as the session key (xored by the session id). This value is converted to an integer as described above, and encrypted with RSA using the key with the smaller modulus. The resulting integer is converted to a byte stream, msb first. This byte stream is padded and encrypted identically using the key with the larger modulus. - - After the client has sent the session key, it starts to use the selected algorithm and key for decrypting any received packets, and for encrypting any sent packets. Separate ciphers are used for different directions (that is, both directions have separate initialization vectors or other state for the ciphers). - - When the server has received the session key message, and has turned on encryption, it sends a SSH_SMSG_SUCCESS message to the client. - The recommended size of the host key is 1024 bits, and 768 bits for the server key. The minimum size is 512 bits for the smaller key. - -Declaring the User Name - - The client then sends a SSH_CMSG_USER message to the server. This message specifies the user name to log in as. - - The server validates that such a user exists, checks whether authentication is needed, and responds with either SSH_SMSG_SUCCESS or SSH_SMSG_FAILURE. SSH_SMSG_SUCCESS indicates that no authentication is needed for this user (no password), and authentication phase has now been completed. SSH_SMSG_FAILURE indicates that authentication is needed (or the user does not exist). - - If the user does not exist, it is recommended that this returns failure, but the server keeps reading messages from the client, and responds to any messages (except SSH_MSG_DISCONNECT, SSH_MSG_IGNORE, and SSH_MSG_DEBUG) with SSH_SMSG_FAILURE. This way the client cannot be certain whether the user exists. - - -Authentication Phase - - Provided the server didn't immediately accept the login, an authentication exchange begins. The client sends messages to the server requesting different types of authentication in arbitrary order as many times as desired (however, the server may close the connection after a timeout). The server always responds with SSH_SMSG_SUCCESS if it has accepted the authentication, and with SSH_SMSG_FAILURE if it has denied authentication with the requested method or it does not recognize the message. Some authentication methods cause an exchange of further messages before the final result is sent. The authentication phase ends when the server responds with success. - - The recommended value for the authentication timeout (timeout before disconnecting if no successful authentication has been made) is 5 minutes. - - The following authentication methods are currently supported: - - SSH_AUTH_RHOSTS 1 .rhosts or /etc/hosts.equiv - SSH_AUTH_RSA 2 pure RSA authentication - SSH_AUTH_PASSWORD 3 password authentication - SSH_AUTH_RHOSTS_RSA 4 .rhosts with RSA host authentication - - - SSH_AUTH_RHOSTS - - This is the authentication method used by rlogin and rsh [RFC1282]. - - The client sends SSH_CMSG_AUTH_RHOSTS with the client-side user name as an argument. - - The server checks whether to permit authentication. On UNIX systems, this is usually done by checking /etc/hosts.equiv, and .rhosts in the user's home directory. The connection must come from a privileged port. - - It is recommended that the server checks that there are no IP options (such as source routing) specified for the socket before accepting this type of authentication. The client host name should be reverse-mapped and then forward mapped to ensure that it has the proper IP-address. - - This authentication method trusts the remote host (root on the remote host can pretend to be any other user on that host), the name services, and partially the network: anyone who can see packets coming out from the server machine can do IP-spoofing and pretend to be any machine; however, the protocol prevents blind IP-spoofing (which used to be possible with rlogin). - - Many sites probably want to disable this authentication method because of the fundamental insecurity of conventional .rhosts or /etc/hosts.equiv authentication when faced with spoofing. It is recommended that this method not be supported by the server by default. - - SSH_AUTH_RHOSTS_RSA - - In addition to conventional .rhosts and hosts.equiv authentication, this method additionally requires that the client host be authenticated using RSA. - - The client sends SSH_CMSG_AUTH_RHOSTS_RSA specifying the client-side user name, and the public host key of the client host. - - The server first checks if normal .rhosts or /etc/hosts.equiv authentication would be accepted, and if not, responds with SSH_SMSG_FAILURE. Otherwise, it checks whether it knows the host key for the client machine (using the same name for the host that was used for checking the .rhosts and /etc/hosts.equiv files). If it does not know the RSA key for the client, access is denied and SSH_SMSG_FAILURE is sent. - - If the server knows the host key of the client machine, it verifies that the given host key matches that known for the client. - If not, access is denied and SSH_SMSG_FAILURE is sent. - - The server then sends a SSH_SMSG_AUTH_RSA_CHALLENGE message containing an encrypted challenge for the client. The challenge is 32 8-bit random bytes (256 bits). When encrypted, the highest (partial) byte is left as zero, the next byte contains the value 2, the following are non-zero random bytes, followed by a zero byte, and the challenge put in the remaining bytes. This is then encrypted using RSA with the client host's public key. - (The padding and encryption algorithm is the same as that used for the session key.) - - The client decrypts the challenge using its private host key, concatenates this with the session id, and computes an MD5 checksum of the resulting 48 bytes. The MD5 output is returned as 16 bytes in a SSH_CMSG_AUTH_RSA_RESPONSE message. (MD5 is used to deter chosen plaintext attacks against RSA; the session id binds it to a specific session). - - The server verifies that the MD5 of the decrypted challenge returned by the client matches that of the original value, and sends SSH_SMSG_SUCCESS if so. Otherwise it sends SSH_SMSG_FAILURE and refuses the authentication attempt. - - This authentication method trusts the client side machine in that root on that machine can pretend to be any user on that machine. Additionally, it trusts the client host key. The name and/or IP address of the client host is only used to select the public host key. The same host name is used when scanning .rhosts or /etc/hosts.equiv and when selecting the host key. It would in principle be possible to eliminate the host name entirely and substitute it directly by the host key. IP and/or DNS [RFC1034] spoofing can only be used to pretend to be a host for which the attacker has the private host key. - - SSH_AUTH_RSA - - The idea behind RSA authentication is that the server recognizes the public key offered by the client, generates a random challenge, and encrypts the challenge with the public key. The client must then prove that it has the corresponding private key by decrypting the challenge. - - The client sends SSH_CMSG_AUTH_RSA with public key modulus (n) as an argument. - - The server may respond immediately with SSH_SMSG_FAILURE if it does not permit authentication with this key. Otherwise it generates a challenge, encrypts it using the user's public key (stored on the server and identified using the modulus), and sends SSH_SMSG_AUTH_RSA_CHALLENGE with the challenge (mp-int) as an argument. - - The challenge is 32 8-bit random bytes (256 bits). When encrypted, the highest (partial) byte is left as zero, the next byte contains the value 2, the following are non-zero random bytes, followed by a zero byte, and the challenge put in the remaining bytes. This is then encrypted with the public key. (The padding and encryption algorithm is the same as that used for the session key.) - - The client decrypts the challenge using its private key, concatenates it with the session id, and computes an MD5 checksum of the resulting 48 bytes. The MD5 output is returned as 16 bytes in a SSH_CMSG_AUTH_RSA_RESPONSE message. (Note that the MD5 is necessary to avoid chosen plaintext attacks against RSA; the session id binds it to a specific session.) - - The server verifies that the MD5 of the decrypted challenge returned by the client matches that of the original value, and sends SSH_SMSG_SUCCESS if so. Otherwise it sends SSH_SMSG_FAILURE and refuses the authentication attempt. - - This authentication method does not trust the remote host, the network, name services, or anything else. Authentication is based solely on the possession of the private identification keys. Anyone in possession of the private keys can log in, but nobody else. - - The server may have additional requirements for a successful authentiation. For example, to limit damage due to a compromised RSA key, a server might restrict access to a limited set of hosts. - - SSH_AUTH_PASSWORD - - The client sends a SSH_CMSG_AUTH_PASSWORD message with the plain text password. (Note that even though the password is plain text inside the message, it is normally encrypted by the packet mechanism.) - - The server verifies the password, and sends SSH_SMSG_SUCCESS if authentication was accepted and SSH_SMSG_FAILURE otherwise. - Note that the password is read from the user by the client; the user never interacts with a login program. - - This authentication method does not trust the remote host, the network, name services or anything else. Authentication is based solely on the possession of the password. Anyone in possession of the password can log in, but nobody else. - -Preparatory Operations - - After successful authentication, the server waits for a request from the client, processes the request, and responds with SSH_SMSG_SUCCESS whenever a request has been successfully processed. If it receives a message that it does not recognize or it fails to honor a request, it returns SSH_SMSG_FAILURE. It is expected that new message types might be added to this phase in future. - - The following messages are currently defined for this phase. - - SSH_CMSG_REQUEST_COMPRESSION - Requests that compression be enabled for this session. A gzipcompatible compression level (1-9) is passed as an argument. - - SSH_CMSG_REQUEST_PTY - Requests that a pseudo terminal device be allocated for this session. The user terminal type and terminal modes are supplied as arguments. - - SSH_CMSG_X11_REQUEST_FORWARDING - Requests forwarding of X11 connections from the remote machine to the local machine over the secure channel. Causes an internet-domain socket to be allocated and the DISPLAY variable to be set on the server. X11 authentication data is automatically passed to the server, and the client may implement spoofing of authentication data for added security. The authentication data is passed as arguments. - - SSH_CMSG_PORT_FORWARD_REQUEST - Requests forwarding of a TCP/IP port on the server host over the secure channel. What happens is that whenever a connection is made to the port on the server, a connection will be made from the client end to the specified host/port. Any user can forward unprivileged ports; only the root can forward privileged ports (as determined by authentication done earlier). - - SSH_CMSG_AGENT_REQUEST_FORWARDING - Requests forwarding of the connection to the authentication agent. - - SSH_CMSG_EXEC_SHELL - Starts a shell (command interpreter) for the user, and moves into interactive session mode. - - SSH_CMSG_EXEC_CMD - Executes the given command (actually " -c " or equivalent) for the user, and moves into interactive session mode. - - -Interactive Session and Exchange of Data - - During the interactive session, any data written by the shell or command running on the server machine is forwarded to stdin or stderr on the client machine, and any input available from stdin on the client machine is forwarded to the program on the server machine. - - All exchange is asynchronous; either side can send at any time, and there are no acknowledgements (TCP/IP already provides reliable transport, and the packet protocol protects against tampering or IP spoofing). - - When the client receives EOF from its standard input, it will send SSH_CMSG_EOF; however, this in no way terminates the exchange. The exchange terminates and interactive mode is left when the server sends SSH_SMSG_EXITSTATUS to indicate that the client program has terminated. Alternatively, either side may disconnect at any time by sending SSH_MSG_DISCONNECT or closing the connection. - - The server may send any of the following messages: - - SSH_SMSG_STDOUT_DATA - Data written to stdout by the program running on the server. - The data is passed as a string argument. The client writes this data to stdout. - - SSH_SMSG_STDERR_DATA - Data written to stderr by the program running on the server. - The data is passed as a string argument. The client writes this data to stderr. (Note that if the program is running on a tty, it is not possible to separate stdout and stderr data, and all data will be sent as stdout data.) - - SSH_SMSG_EXITSTATUS - Indicates that the shell or command has exited. Exit status is passed as an integer argument. This message causes termination of the interactive session. - - SSH_SMSG_AGENT_OPEN - Indicates that someone on the server side is requesting a connection to the authentication agent. The server-side channel number is passed as an argument. The client must respond with either SSH_CHANNEL_OPEN_CONFIRMATION or SSH_CHANNEL_OPEN_FAILURE. - - SSH_SMSG_X11_OPEN - Indicates that a connection has been made to the X11 socket on the server side and should be forwarded to the real X server. An integer argument indicates the channel number allocated for this connection on the server side. The client should send back either SSH_MSG_CHANNEL_OPEN_CONFIRMATION or SSH_MSG_CHANNEL_OPEN_FAILURE with the same server side channel number. - - SSH_MSG_PORT_OPEN - Indicates that a connection has been made to a port on the server side for which forwarding has been requested. Arguments are server side channel number, host name to connect to, and port to connect to. The client should send back either SSH_MSG_CHANNEL_OPEN_CONFIRMATION or SSH_MSG_CHANNEL_OPEN_FAILURE with the same server side channel number. - - SSH_MSG_CHANNEL_OPEN_CONFIRMATION - This is sent by the server to indicate that it has opened a connection as requested in a previous message. The first argument indicates the client side channel number, and the second argument is the channel number that the server has allocated for this connection. - - SSH_MSG_CHANNEL_OPEN_FAILURE - This is sent by the server to indicate that it failed to open a connection as requested in a previous message. The client-side channel number is passed as an argument. The client will close the descriptor associated with the channel and free the channel. - - SSH_MSG_CHANNEL_DATA - This packet contains data for a channel from the server. The - first argument is the client-side channel number, and the second - argument (a string) is the data. - - SSH_MSG_CHANNEL_CLOSE - This is sent by the server to indicate that whoever was in the - other end of the channel has closed it. The argument is the - client side channel number. The client will let all buffered - data in the channel to drain, and when ready, will close the - socket, free the channel, and send the server a - SSH_MSG_CHANNEL_CLOSE_CONFIRMATION message for the channel. - - SSH_MSG_CHANNEL_CLOSE_CONFIRMATION - This is send by the server to indicate that a channel previously - closed by the client has now been closed on the server side as - well. The argument indicates the client channel number. The - client frees the channel. - - The client may send any of the following messages: - - SSH_CMSG_STDIN_DATA - This is data to be sent as input to the program running on the - server. The data is passed as a string. - - SSH_CMSG_EOF - Indicates that the client has encountered EOF while reading - standard input. The server will allow any buffered input data - to drain, and will then close the input to the program. - - SSH_CMSG_WINDOW_SIZE - Indicates that window size on the client has been changed. The - server updates the window size of the tty and causes SIGWINCH to - be sent to the program. The new window size is passed as four - integer arguments: row, col, xpixel, ypixel. - - SSH_MSG_PORT_OPEN - Indicates that a connection has been made to a port on the - client side for which forwarding has been requested. Arguments - are client side channel number, host name to connect to, and - port to connect to. The server should send back either - SSH_MSG_CHANNEL_OPEN_CONFIRMATION or - SSH_MSG_CHANNEL_OPEN_FAILURE with the same client side channel - number. - - SSH_MSG_CHANNEL_OPEN_CONFIRMATION - This is sent by the client to indicate that it has opened a con- - nection as requested in a previous message. The first argument - indicates the server side channel number, and the second argu- - ment is the channel number that the client has allocated for - this connection. - - SSH_MSG_CHANNEL_OPEN_FAILURE - This is sent by the client to indicate that it failed to open a - connection as requested in a previous message. The server side - channel number is passed as an argument. The server will close - the descriptor associated with the channel and free the channel. - - SSH_MSG_CHANNEL_DATA - This packet contains data for a channel from the client. The - first argument is the server side channel number, and the second - argument (a string) is the data. - - SSH_MSG_CHANNEL_CLOSE - This is sent by the client to indicate that whoever was in the - other end of the channel has closed it. The argument is the - server channel number. The server will allow buffered data to - drain, and when ready, will close the socket, free the channel, - and send the client a SSH_MSG_CHANNEL_CLOSE_CONFIRMATION message - for the channel. - - SSH_MSG_CHANNEL_CLOSE_CONFIRMATION - This is send by the client to indicate that a channel previously - closed by the server has now been closed on the client side as - well. The argument indicates the server channel number. The - server frees the channel. - - Any unsupported messages during interactive mode cause the connection - to be terminated with SSH_MSG_DISCONNECT and an error message. Com- - patible protocol upgrades should agree about any extensions during - the preparation phase or earlier. - - -Termination of the Connection - - Normal termination of the connection is always initiated by the - server by sending SSH_SMSG_EXITSTATUS after the program has exited. - The client responds to this message by sending - SSH_CMSG_EXIT_CONFIRMATION and closes the socket; the server then - closes the socket. There are two purposes for the confirmation: some - systems may lose previously sent data when the socket is closed, and - closing the client side first causes any TCP/IP TIME_WAIT [RFC0793] - waits to occur on the client side, not consuming server resources. - - If the program terminates due to a signal, the server will send - SSH_MSG_DISCONNECT with an appropriate message. If the connection is - closed, all file descriptors to the program will be closed and the - server will exit. If the program runs on a tty, the kernel sends it - the SIGHUP signal when the pty master side is closed. - -Protocol Flags - - Both the server and the client pass 32 bits of protocol flags to the - other side. The flags are intended for compatible protocol exten- - sion; the server first announces which added capabilities it sup- - ports, and the client then sends the capabilities that it supports. - - The following flags are currently defined (the values are bit masks): - - 1 SSH_PROTOFLAG_SCREEN_NUMBER - This flag can only be sent by the client. It indicates that the - X11 forwarding requests it sends will include the screen number. - - 2 SSH_PROTOFLAG_HOST_IN_FWD_OPEN - If both sides specify this flag, SSH_SMSG_X11_OPEN and - SSH_MSG_PORT_OPEN messages will contain an additional field con- - taining a description of the host at the other end of the con- - nection. - -Detailed Description of Packet Types and Formats - - The supported packet types and the corresponding message numbers are - given in the following table. Messages with _MSG_ in their name may - be sent by either side. Messages with _CMSG_ are only sent by the - client, and messages with _SMSG_ only by the server. - - A packet may contain additional data after the arguments specified - below. Any such data should be ignored by the receiver. However, it - is recommended that no such data be stored without good reason. - (This helps build compatible extensions.) - - 0 SSH_MSG_NONE - This code is reserved. This message type is never sent. - - 1 SSH_MSG_DISCONNECT - - string Cause of disconnection - - This message may be sent by either party at any time. It causes - the immediate disconnection of the connection. The message is - intended to be displayed to a human, and describes the reason - for disconnection. - - 2 SSH_SMSG_PUBLIC_KEY - - 8 bytes anti_spoofing_cookie - 32-bit int server_key_bits - mp-int server_key_public_exponent - mp-int server_key_public_modulus - 32-bit int host_key_bits - mp-int host_key_public_exponent - mp-int host_key_public_modulus - 32-bit int protocol_flags - 32-bit int supported_ciphers_mask - 32-bit int supported_authentications_mask - - Sent as the first message by the server. This message gives the - server's host key, server key, protocol flags (intended for com- - patible protocol extension), supported_ciphers_mask (which is - the bitwise or of (1 << cipher_number), where << is the left - shift operator, for all supported ciphers), and - supported_authentications_mask (which is the bitwise or of (1 << - authentication_type) for all supported authentication types). - The anti_spoofing_cookie is 64 random bits, and must be sent - back verbatim by the client in its reply. It is used to make - IP-spoofing more difficult (encryption and host keys are the - real defense against spoofing). - - 3 SSH_CMSG_SESSION_KEY - - 1 byte cipher_type (must be one of the supported values) - 8 bytes anti_spoofing_cookie (must match data sent by the server) - mp-int double-encrypted session key - 32-bit int protocol_flags - - Sent by the client as the first message in the session. Selects - the cipher to use, and sends the encrypted session key to the - server. The anti_spoofing_cookie must be the same bytes that - were sent by the server. Protocol_flags is intended for nego- - tiating compatible protocol extensions. - - 4 SSH_CMSG_USER - - string user login name on server - - Sent by the client to begin authentication. Specifies the user - name on the server to log in as. The server responds with - SSH_SMSG_SUCCESS if no authentication is needed for this user, - or SSH_SMSG_FAILURE if authentication is needed (or the user - does not exist). [Note to the implementator: the user name is - of arbitrary size. The implementation must be careful not to - overflow internal buffers.] - - 5 SSH_CMSG_AUTH_RHOSTS - - string client-side user name - - Requests authentication using /etc/hosts.equiv and .rhosts (or - equivalent mechanisms). This authentication method is normally - disabled in the server because it is not secure (but this is the - method used by rsh and rlogin). The server responds with - SSH_SMSG_SUCCESS if authentication was successful, and - SSH_SMSG_FAILURE if access was not granted. The server should - check that the client side port number is less than 1024 (a - privileged port), and immediately reject authentication if it is - not. Supporting this authentication method is optional. This - method should normally not be enabled in the server because it - is not safe. (However, not enabling this only helps if rlogind - and rshd are disabled.) - - 6 SSH_CMSG_AUTH_RSA - - mp-int identity_public_modulus - - Requests authentication using pure RSA authentication. The - server checks if the given key is permitted to log in, and if - so, responds with SSH_SMSG_AUTH_RSA_CHALLENGE. Otherwise, it - responds with SSH_SMSG_FAILURE. The client often tries several - different keys in sequence until one supported by the server is - found. Authentication is accepted if the client gives the - correct response to the challenge. The server is free to add - other criteria for authentication, such as a requirement that - the connection must come from a certain host. Such additions - are not visible at the protocol level. Supporting this authen- - tication method is optional but recommended. - - 7 SSH_SMSG_AUTH_RSA_CHALLENGE - - mp-int encrypted challenge - - Presents an RSA authentication challenge to the client. The - challenge is a 256-bit random value encrypted as described else- - where in this document. The client must decrypt the challenge - using the RSA private key, compute MD5 of the challenge plus - session id, and send back the resulting 16 bytes using - SSH_CMSG_AUTH_RSA_RESPONSE. - - 8 SSH_CMSG_AUTH_RSA_RESPONSE - - 16 bytes MD5 of decrypted challenge - - This message is sent by the client in response to an RSA chal- - lenge. The MD5 checksum is returned instead of the decrypted - challenge to deter known-plaintext attacks against the RSA key. - The server responds to this message with either SSH_SMSG_SUCCESS - or SSH_SMSG_FAILURE. - - 9 SSH_CMSG_AUTH_PASSWORD - - string plain text password - - Requests password authentication using the given password. Note - that even though the password is plain text inside the packet, - the whole packet is normally encrypted by the packet layer. It - would not be possible for the client to perform password - encryption/hashing, because it cannot know which kind of - encryption/hashing, if any, the server uses. The server - responds to this message with SSH_SMSG_SUCCESS or - SSH_SMSG_FAILURE. - - 10 SSH_CMSG_REQUEST_PTY - - string TERM environment variable value (e.g. vt100) - 32-bit int terminal height, rows (e.g., 24) - 32-bit int terminal width, columns (e.g., 80) - 32-bit int terminal width, pixels (0 if no graphics) (e.g., 480) - 32-bit int terminal height, pixels (0 if no graphics) (e.g., 640) - n bytes tty modes encoded in binary - - Requests a pseudo-terminal to be allocated for this command. - This message can be used regardless of whether the session will - later execute the shell or a command. If a pty has been - requested with this message, the shell or command will run on a - pty. Otherwise it will communicate with the server using pipes, - sockets or some other similar mechanism. - - The terminal type gives the type of the user's terminal. In the - UNIX environment it is passed to the shell or command in the - TERM environment variable. - - The width and height values give the initial size of the user's - terminal or window. All values can be zero if not supported by - the operating system. The server will pass these values to the - kernel if supported. - - Terminal modes are encoded into a byte stream in a portable for- - mat. The exact format is described later in this document. - - The server responds to the request with either SSH_SMSG_SUCCESS - or SSH_SMSG_FAILURE. If the server does not have the concept of - pseudo terminals, it should return success if it is possible to - execute a shell or a command so that it looks to the client as - if it was running on a pseudo terminal. - - 11 SSH_CMSG_WINDOW_SIZE - - 32-bit int terminal height, rows - 32-bit int terminal width, columns - 32-bit int terminal width, pixels - 32-bit int terminal height, pixels - - This message can only be sent by the client during the interac- - tive session. This indicates that the size of the user's window - has changed, and provides the new size. The server will update - the kernel's notion of the window size, and a SIGWINCH signal or - equivalent will be sent to the shell or command (if supported by - the operating system). - - 12 SSH_CMSG_EXEC_SHELL - - (no arguments) - - Starts a shell (command interpreter), and enters interactive - session mode. - - 13 SSH_CMSG_EXEC_CMD - - string command to execute - - Starts executing the given command, and enters interactive ses- - sion mode. On UNIX, the command is run as " -c ", where is the user's login shell. - - 14 SSH_SMSG_SUCCESS - - (no arguments) - - This message is sent by the server in response to the session - key, a successful authentication request, and a successfully - completed preparatory operation. - - 15 SSH_SMSG_FAILURE - - (no arguments) - - This message is sent by the server in response to a failed - authentication operation to indicate that the user has not yet - been successfully authenticated, and in response to a failed - preparatory operation. This is also sent in response to an - authentication or preparatory operation request that is not - recognized or supported. - - 16 SSH_CMSG_STDIN_DATA - - string data - - Delivers data from the client to be supplied as input to the - shell or program running on the server side. This message can - only be used in the interactive session mode. No acknowledge- - ment is sent for this message. - - 17 SSH_SMSG_STDOUT_DATA - - string data - - Delivers data from the server that was read from the standard - output of the shell or program running on the server side. This - message can only be used in the interactive session mode. No - acknowledgement is sent for this message. - - 18 SSH_SMSG_STDERR_DATA - - string data - - Delivers data from the server that was read from the standard - error of the shell or program running on the server side. This - message can only be used in the interactive session mode. No - acknowledgement is sent for this message. - - 19 SSH_CMSG_EOF - - (no arguments) - - This message is sent by the client to indicate that EOF has been - reached on the input. Upon receiving this message, and after - all buffered input data has been sent to the shell or program, - the server will close the input file descriptor to the program. - This message can only be used in the interactive session mode. - No acknowledgement is sent for this message. - - 20 SSH_SMSG_EXITSTATUS - - 32-bit int exit status of the command - - Returns the exit status of the shell or program after it has - exited. The client should respond with - SSH_CMSG_EXIT_CONFIRMATION when it has received this message. - This will be the last message sent by the server. If the pro- - gram being executed dies with a signal instead of exiting nor- - mally, the server should terminate the session with - SSH_MSG_DISCONNECT (which can be used to pass a human-readable - string indicating that the program died due to a signal) instead - of using this message. - - 21 SSH_MSG_CHANNEL_OPEN_CONFIRMATION - - 32-bit int remote_channel - 32-bit int local_channel - - This is sent in response to any channel open request if the - channel has been successfully opened. Remote_channel is the - channel number received in the initial open request; - local_channel is the channel number the side sending this mes- - sage has allocated for the channel. Data can be transmitted on - the channel after this message. - - 22 SSH_MSG_CHANNEL_OPEN_FAILURE - - 32-bit int remote_channel - - This message indicates that an earlier channel open request by - the other side has failed or has been denied. Remote_channel is - the channel number given in the original request. - - 23 SSH_MSG_CHANNEL_DATA - - 32-bit int remote_channel - string data - - Data is transmitted in a channel in these messages. A channel - is bidirectional, and both sides can send these messages. There - is no acknowledgement for these messages. It is possible that - either side receives these messages after it has sent - SSH_MSG_CHANNEL_CLOSE for the channel. These messages cannot be - received after the party has sent or received - SSH_MSG_CHANNEL_CLOSE_CONFIRMATION. - - 24 SSH_MSG_CHANNEL_CLOSE - - 32-bit int remote_channel - - When a channel is closed at one end of the connection, that side - sends this message. Upon receiving this message, the channel - should be closed. When this message is received, if the channel - is already closed (the receiving side has sent this message for - the same channel earlier), the channel is freed and no further - action is taken; otherwise the channel is freed and - SSH_MSG_CHANNEL_CLOSE_CONFIRMATION is sent in response. (It is - possible that the channel is closed simultaneously at both - ends.) - - 25 SSH_MSG_CHANNEL_CLOSE_CONFIRMATION - - 32-bit int remote_channel - - This message is sent in response to SSH_MSG_CHANNEL_CLOSE unless - the channel was already closed. When this message is sent or - received, the channel is freed. - - 26 (OBSOLETED; was unix-domain X11 forwarding) - - 27 SSH_SMSG_X11_OPEN - - 32-bit int local_channel - string originator_string (see below) - - This message can be sent by the server during the interactive - session mode to indicate that a client has connected the fake X - server. Local_channel is the channel number that the server has - allocated for the connection. The client should try to open a - connection to the real X server, and respond with - SSH_MSG_CHANNEL_OPEN_CONFIRMATION or - SSH_MSG_CHANNEL_OPEN_FAILURE. - - The field originator_string is present if both sides specified - SSH_PROTOFLAG_HOST_IN_FWD_OPEN in the protocol flags. It con- - tains a description of the host originating the connection. - - 28 SSH_CMSG_PORT_FORWARD_REQUEST - - 32-bit int server_port - string host_to_connect - 32-bit int port_to_connect - - Sent by the client in the preparatory phase, this message - requests that server_port on the server machine be forwarded - over the secure channel to the client machine, and from there to - the specified host and port. The server should start listening - on the port, and send SSH_MSG_PORT_OPEN whenever a connection is - made to it. Supporting this message is optional, and the server - is free to reject any forward request. For example, it is - highly recommended that unless the user has been authenticated - as root, forwarding any privileged port numbers (below 1024) is - denied. - - 29 SSH_MSG_PORT_OPEN - - 32-bit int local_channel - string host_name - 32-bit int port - string originator_string (see below) - - Sent by either party in interactive session mode, this message - indicates that a connection has been opened to a forwarded - TCP/IP port. Local_channel is the channel number that the send- - ing party has allocated for the connection. Host_name is the - host the connection should be be forwarded to, and the port is - the port on that host to connect. The receiving party should - open the connection, and respond with - SSH_MSG_CHANNEL_OPEN_CONFIRMATION or - SSH_MSG_CHANNEL_OPEN_FAILURE. It is recommended that the - receiving side check the host_name and port for validity to - avoid compromising local security by compromised remote side - software. Particularly, it is recommended that the client per- - mit connections only to those ports for which it has requested - forwarding with SSH_CMSG_PORT_FORWARD_REQUEST. - - The field originator_string is present if both sides specified - SSH_PROTOFLAG_HOST_IN_FWD_OPEN in the protocol flags. It con- - tains a description of the host originating the connection. - - 30 SSH_CMSG_AGENT_REQUEST_FORWARDING - - (no arguments) - - Requests that the connection to the authentication agent be for- - warded over the secure channel. The method used by clients to - contact the authentication agent within each machine is imple- - mentation and machine dependent. If the server accepts this - request, it should arrange that any clients run from this ses- - sion will actually contact the server program when they try to - contact the authentication agent. The server should then send a - SSH_SMSG_AGENT_OPEN to open a channel to the agent, and the - client should forward the connection to the real authentication - agent. Supporting this message is optional. - - 31 SSH_SMSG_AGENT_OPEN - - 32-bit int local_channel - - Sent by the server in interactive session mode, this message - requests opening a channel to the authentication agent. The - client should open a channel, and respond with either - SSH_MSG_CHANNEL_OPEN_CONFIRMATION or - SSH_MSG_CHANNEL_OPEN_FAILURE. - - 32 SSH_MSG_IGNORE - - string data - - Either party may send this message at any time. This message, - and the argument string, is silently ignored. This message - might be used in some implementations to make traffic analysis - more difficult. This message is not currently sent by the - implementation, but all implementations are required to recog- - nize and ignore it. - - 33 SSH_CMSG_EXIT_CONFIRMATION - - (no arguments) - - Sent by the client in response to SSH_SMSG_EXITSTATUS. This is - the last message sent by the client. - - 34 SSH_CMSG_X11_REQUEST_FORWARDING - - string x11_authentication_protocol - string x11_authentication_data - 32-bit int screen number (if SSH_PROTOFLAG_SCREEN_NUMBER) - - Sent by the client during the preparatory phase, this message - requests that the server create a fake X11 display and set the - DISPLAY environment variable accordingly. An internet-domain - display is preferable. The given authentication protocol and - the associated data should be recorded by the server so that it - is used as authentication on connections (e.g., in .Xauthority). - The authentication protocol must be one of the supported X11 - authentication protocols, e.g., "MIT-MAGIC-COOKIE-1". Authenti- - cation data must be a lowercase hex string of even length. Its - interpretation is protocol dependent. The data is in a format - that can be used with e.g. the xauth program. Supporting this - message is optional. - - The client is permitted (and recommended) to generate fake - authentication information and send fake information to the - server. This way, a corrupt server will not have access to the - user's terminal after the connection has terminated. The - correct authorization codes will also not be left hanging around - in files on the server (many users keep the same X session for - months, thus protecting the authorization data becomes impor- - tant). - - X11 authentication spoofing works by initially sending fake - (random) authentication data to the server, and interpreting the - first packet sent by the X11 client after the connection has - been opened. The first packet contains the client's authentica- - tion. If the packet contains the correct fake data, it is - replaced by the client by the correct authentication data, and - then sent to the X server. - - 35 SSH_CMSG_AUTH_RHOSTS_RSA - - string clint-side user name - 32-bit int client_host_key_bits - mp-int client_host_key_public_exponent - mp-int client_host_key_public_modulus - - Requests authentication using /etc/hosts.equiv and .rhosts (or - equivalent) together with RSA host authentication. The server - should check that the client side port number is less than 1024 - (a privileged port), and immediately reject authentication if it - is not. The server responds with SSH_SMSG_FAILURE or - SSH_SMSG_AUTH_RSA_CHALLENGE. The client must respond to the - challenge with the proper SSH_CMSG_AUTH_RSA_RESPONSE. The - server then responds with success if access was granted, or - failure if the client gave a wrong response. Supporting this - authentication method is optional but recommended in most - environments. - - 36 SSH_MSG_DEBUG - - string debugging message sent to the other side - - This message may be sent by either party at any time. It is - used to send debugging messages that may be informative to the - user in solving various problems. For example, if authentica- - tion fails because of some configuration error (e.g., incorrect - permissions for some file), it can be very helpful for the user - to make the cause of failure available. On the other hand, one - should not make too much information available for security rea- - sons. It is recommended that the client provides an option to - display the debugging information sent by the sender (the user - probably does not want to see it by default). The server can - log debugging data sent by the client (if any). Either party is - free to ignore any received debugging data. Every implementa- - tion must be able to receive this message, but no implementation - is required to send these. - - 37 SSH_CMSG_REQUEST_COMPRESSION - - 32-bit int gzip compression level (1-9) - - This message can be sent by the client in the preparatory opera- - tions phase. The server responds with SSH_SMSG_FAILURE if it - does not support compression or does not want to compress; it - responds with SSH_SMSG_SUCCESS if it accepted the compression - request. In the latter case the response to this packet will - still be uncompressed, but all further packets in either direc- - tion will be compressed by gzip. - - 38 SSH_CMSG_MAX_PACKET_SIZE - - 32-bit int maximum packet size, bytes (4096-1024k) - - This message can be sent by the client in the preparatory opera- - tions phase. The server responds with SSH_SMSG_FAILURE if it - does not support limiting packet size, or with SSH_SMSG_SUCCESS - if it has limited the maximum packet size (as determined by the - value in the size field) to the specified value. - - 39 SSH_CMSG_AUTH_TIS - - (no arguments) - - This message starts TIS authentication. The server responds with - SSH_SMSG_FAILURE or SSH_SMSG_AUTH_TIS_CHALLENGE. - - 40 SSH_SMSG_AUTH_TIS_CHALLENGE - - string tis challenge - - Server sends TIS challenge to user and client should show it to - user and ask for response, which is sent back using - SSH_CMSG_AUTH_TIS_RESPONSE message. - - 41 SSH_CMSG_AUTH_TIS_RESPONSE - - string user response to tis challenge - - When client receives SSH_SMSG_AUTH_TIS_CHALLENGE and ask users - response to challenge it sends it back this message. The server - answers with SSH_SMSG_FAILURE or SSH_SMSG_SUCCESS. - - 42 SSH_CMSG_AUTH_KERBEROS - - string authentication info - - Client sends authentication info to server, which replies with - SSH_SMSG_AUTH_KERBEROS_RESPONSE message having correct response - data encrypted with the session key. - - 43 SSH_SMSG_AUTH_KERBEROS_RESPONSE - - string response data - - Server replies to SSH_CMSG_AUTH_KERBEROS message with this mes- - sage so that the response data is encrypted with session key. - - 44 SSH_CMSG_HAVE_KERBEROS_TGT - - string kerberos credentials - - Client sends kerberos credentials to server and the server - replies with SSH_SMSG_SUCCESS or SSH_SMSG_FAILURE. - - -Encoding of Terminal Modes - - Terminal modes (as passed in SSH_CMSG_REQUEST_PTY) 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-127 have one-byte arguments. Opcodes 128-159 have 32-bit - integer arguments (stored msb first). Opcodes 160-255 are not yet - defined, and cause parsing to stop (they should only be used after - any other data). - - The client puts in the stream any modes it knows about, and the - server ignores any modes it does not know about. This allows some - degree of machine-independence, at least between systems that use a - POSIX-like [POSIX] 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 char- - acters. Not all of these characters are supported on all sys- - tems. - - 2 VQUIT - The quit character (sends SIGQUIT signal on UNIX systems). - - 3 VERASE - Erase the character to left of the cursor. - - 4 VKILL - Kill the current input line. - - 5 VEOF - End-of-file character (sends EOF from the terminal). - - 6 VEOL - End-of-line character in addition to carriage return and/or - linefeed. - - 7 VEOL2 - Additional end-of-line character. - - 8 VSTART - Continues paused output (normally ^Q). - - 9 VSTOP - Pauses output (^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 - More special input characters; these are probably not supported - on most systems. - - 15 VFLUSH - - 16 VSWTCH - - 17 VSTATUS - - 18 VDISCARD - - - 30 IGNPAR - The ignore parity flag. The next byte should be 0 if this flag - is not set, and 1 if it is set. - - 31 PARMRK - More flags. The exact definitions can be found in the POSIX - standard. - - 32 INPCK - - 33 ISTRIP - - 34 INLCR - - 35 IGNCR - - 36 ICRNL - - 37 IUCLC - - 38 IXON - - 39 IXANY - - 40 IXOFF - - 41 IMAXBEL - - - 50 ISIG - - 51 ICANON - - 52 XCASE - - 53 ECHO - - 54 ECHOE - - 55 ECHOK - - 56 ECHONL - - 57 NOFLSH - - 58 TOSTOP - - 59 IEXTEN - - 60 ECHOCTL - - 61 ECHOKE - - 62 PENDIN - - - 70 OPOST - - 71 OLCUC - - 72 ONLCR - - 73 OCRNL - - 74 ONOCR - - 75 ONLRET - - - 90 CS7 - - 91 CS8 - - 92 PARENB - - 93 PARODD - - - 192 TTY_OP_ISPEED - Specifies the input baud rate in bits per second (as a 32-bit - int, msb first). - - 193 TTY_OP_OSPEED - Specifies the output baud rate in bits per second (as a 32-bt - int, msb first). - - -The Authentication Agent Protocol - - The authentication agent is a program that can be used to hold RSA - authentication keys for the user (in future, it might hold data for - other authentication types as well). An authorized program can send - requests to the agent to generate a proper response to an RSA chal- - lenge. How the connection is made to the agent (or its representa- - tive) inside a host and how access control is done inside a host is - implementation-dependent; however, how it is forwarded and how one - interacts with it is specified in this protocol. The connection to - the agent is normally automatically forwarded over the secure chan- - nel. - - A program that wishes to use the agent first opens a connection to - its local representative (typically, the agent itself or an SSH - server). It then writes a request to the connection, and waits for - response. It is recommended that at least five minutes of timeout - are provided waiting for the agent to respond to an authentication - challenge (this gives sufficient time for the user to cut-and-paste - the challenge to a separate machine, perform the computation there, - and cut-and-paste the result back if so desired). - - Messages sent to and by the agent are in the following format: - - 4 bytes Length, msb first. Does not include length itself. - 1 byte Packet type. The value 255 is reserved for future extensions. - data Any data, depending on packet type. Encoding as in the ssh packet - protocol. - - - The following message types are currently defined: - - 1 SSH_AGENTC_REQUEST_RSA_IDENTITIES - - (no arguments) - - Requests the agent to send a list of all RSA keys for which it - can answer a challenge. - - 2 SSH_AGENT_RSA_IDENTITIES_ANSWER - - 32-bit int howmany - howmany times: - 32-bit int bits - mp-int public exponent - mp-int public modulus - string comment - - The agent sends this message in response to the to - SSH_AGENTC_REQUEST_RSA_IDENTITIES. The answer lists all RSA - keys for which the agent can answer a challenge. The comment - field is intended to help identify each key; it may be printed - by an application to indicate which key is being used. If the - agent is not holding any keys, howmany will be zero. - - 3 SSH_AGENTC_RSA_CHALLENGE - - 32-bit int bits - mp-int public exponent - mp-int public modulus - mp-int challenge - 16 bytes session_id - 32-bit int response_type - - Requests RSA decryption of random challenge to authenticate the - other side. The challenge will be decrypted with the RSA - private key corresponding to the given public key. - - The decrypted challenge must contain a zero in the highest (par- - tial) byte, 2 in the next byte, followed by non-zero random - bytes, a zero byte, and then the real challenge value in the - lowermost bytes. The real challenge must be 32 8-bit bytes (256 - bits). - - Response_type indicates the format of the response to be - returned. Currently the only supported value is 1, which means - to compute MD5 of the real challenge plus session id, and return - the resulting 16 bytes in a SSH_AGENT_RSA_RESPONSE message. - - 4 SSH_AGENT_RSA_RESPONSE - - 16 bytes MD5 of decrypted challenge - - Answers an RSA authentication challenge. The response is 16 - bytes: the MD5 checksum of the 32-byte challenge. - - 5 SSH_AGENT_FAILURE - - (no arguments) - - This message is sent whenever the agent fails to answer a - request properly. For example, if the agent cannot answer a - challenge (e.g., no longer has the proper key), it can respond - with this. The agent also responds with this message if it - receives a message it does not recognize. - - 6 SSH_AGENT_SUCCESS - - (no arguments) - - This message is sent by the agent as a response to certain - requests that do not otherwise cause a message be sent. - Currently, this is only sent in response to - SSH_AGENTC_ADD_RSA_IDENTITY and SSH_AGENTC_REMOVE_RSA_IDENTITY. - - 7 SSH_AGENTC_ADD_RSA_IDENTITY - - 32-bit int bits - mp-int public modulus - mp-int public exponent - mp-int private exponent - mp-int multiplicative inverse of p mod q - mp-int p - mp-int q - string comment - - Registers an RSA key with the agent. After this request, the - agent can use this RSA key to answer requests. The agent - responds with SSH_AGENT_SUCCESS or SSH_AGENT_FAILURE. - - 8 SSH_AGENT_REMOVE_RSA_IDENTITY - - 32-bit int bits - mp-int public exponent - mp-int public modulus - - Removes an RSA key from the agent. The agent will no longer - accept challenges for this key and will not list it as a sup- - ported identity. The agent responds with SSH_AGENT_SUCCESS or - SSH_AGENT_FAILURE. - - If the agent receives a message that it does not understand, it - responds with SSH_AGENT_FAILURE. This permits compatible future - extensions. - - It is possible that several clients have a connection open to the - authentication agent simultaneously. Each client will use a separate - connection (thus, any SSH connection can have multiple agent connec- - tions active simultaneously). - - -References - - - [DES] FIPS PUB 46-1: Data Encryption Standard. National Bureau of - Standards, January 1988. FIPS PUB 81: DES Modes of Operation. - National Bureau of Standards, December 1980. Bruce Schneier: - Applied Cryptography. John Wiley & Sons, 1994. J. Seberry and - J. Pieprzyk: Cryptography: An Introduction to Computer Secu- - rity. Prentice-Hall, 1989. - - [GZIP] - The GNU GZIP program; available for anonymous ftp at - prep.ai.mit.edu. Please let me know if you know a paper - describing the algorithm. - - [IDEA] - Xuejia Lai: On the Design and Security of Block Ciphers, ETH - Series in Information Processing, vol. 1, Hartung-Gorre Verlag, - Konstanz, Switzerland, 1992. Bruce Schneier: Applied Cryptogra- - phy, John Wiley & Sons, 1994. See also the following patents: - PCT/CH91/00117, EP 0 482 154 B1, US Pat. 5,214,703. - - [PKCS#1] - PKCS #1: RSA Encryption Standard. Version 1.5, RSA Labora- - tories, November 1993. Available for anonymous ftp at - ftp.rsa.com. - - [POSIX] - Portable Operating System Interface (POSIX) - Part 1: Applica- - tion Program Interface (API) [C language], ISO/IEC 9945-1, IEEE - Std 1003.1, 1990. - - [RFC0791] - J. Postel: Internet Protocol, RFC 791, USC/ISI, September 1981. - - [RFC0793] - J. Postel: Transmission Control Protocol, RFC 793, USC/ISI, Sep- - tember 1981. - - [RFC1034] - P. Mockapetris: Domain Names - Concepts and Facilities, RFC - 1034, USC/ISI, November 1987. - - [RFC1282] - B. Kantor: BSD Rlogin, RFC 1258, UCSD, December 1991. - - [RSA] Bruce Schneier: Applied Cryptography. John Wiley & Sons, 1994. - See also R. Rivest, A. Shamir, and L. M. Adleman: Cryptographic - Communications System and Method. US Patent 4,405,829, 1983. - - [X11] R. Scheifler: X Window System Protocol, X Consortium Standard, - Version 11, Release 6. Massachusetts Institute of Technology, - Laboratory of Computer Science, 1994. - - -Security Considerations - - This protocol deals with the very issue of user authentication and - security. - - First of all, as an implementation issue, the server program will - have to run as root (or equivalent) on the server machine. This is - because the server program will need be able to change to an arbi- - trary user id. The server must also be able to create a privileged - TCP/IP port. - - The client program will need to run as root if any variant of .rhosts - authentication is to be used. This is because the client program - will need to create a privileged port. The client host key is also - usually stored in a file which is readable by root only. The client - needs the host key in .rhosts authentication only. Root privileges - can be dropped as soon as the privileged port has been created and - the host key has been read. - - The SSH protocol offers major security advantages over existing tel- - net and rlogin protocols. - - o IP spoofing is restricted to closing a connection (by - encryption, host keys, and the special random cookie). If - encryption is not used, IP spoofing is possible for those who - can hear packets going out from the server. - - o DNS spoofing is made ineffective (by host keys). - - o Routing spoofing is made ineffective (by host keys). - - o All data is encrypted with strong algorithms to make eavesdrop- - ping as difficult as possible. This includes encrypting any - authentication information such as passwords. The information - for decrypting session keys is destroyed every hour. - - o Strong authentication methods: .rhosts combined with RSA host - authentication, and pure RSA authentication. - - o X11 connections and arbitrary TCP/IP ports can be forwarded - securely. - - o Man-in-the-middle attacks are deterred by using the server host - key to encrypt the session key. - - o Trojan horses to catch a password by routing manipulation are - deterred by checking that the host key of the server machine - matches that stored on the client host. - - The security of SSH against man-in-the-middle attacks and the secu- - rity of the new form of .rhosts authentication, as well as server - host validation, depends on the integrity of the host key and the - files containing known host keys. - - The host key is normally stored in a root-readable file. If the host - key is compromised, it permits attackers to use IP, DNS and routing - spoofing as with current rlogin and rsh. It should never be any - worse than the current situation. - - The files containing known host keys are not sensitive. However, if - an attacker gets to modify the known host key files, it has the same - consequences as a compromised host key, because the attacker can then - change the recorded host key. - - The security improvements obtained by this protocol for X11 are of - particular significance. Previously, there has been no way to pro- - tect data communicated between an X server and a client running on a - remote machine. By creating a fake display on the server, and for- - warding all X11 requests over the secure channel, SSH can be used to - run any X11 applications securely without any cooperation with the - vendors of the X server or the application. - - Finally, the security of this program relies on the strength of the - underlying cryptographic algorithms. The RSA algorithm is used for - authentication key exchange. It is widely believed to be secure. Of - the algorithms used to encrypt the session, DES has a rather small - key these days, probably permitting governments and organized crimi- - nals to break it in very short time with specialized hardware. 3DES - is probably safe (but slower). IDEA is widely believed to be secure. - People have varying degrees of confidence in the other algorithms. - This program is not secure if used with no encryption at all. - - -Additional Information - - Additional information (especially on the implementation and mailing - lists) is available via WWW at http://www.cs.hut.fi/ssh. - - Comments should be sent to Tatu Ylonen or the SSH - Mailing List . - -Author's Address - - - Tatu Ylonen - Helsinki University of Technology - Otakaari 1 - FIN-02150 Espoo, Finland - - Phone: +358-9-4354-3205 - Fax: +358-9-4354-3206 - EMail: ylo@cs.hut.fi -