aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorAris Adamantiadis <aris@0xbadc0de.be>2005-07-05 01:21:44 +0000
committerAris Adamantiadis <aris@0xbadc0de.be>2005-07-05 01:21:44 +0000
commitc65f56aefa50a2e2a78a0e45564526ecc921d74f (patch)
tree11bd53cf92869ccbab30f29253ce30f7078a4a26 /doc
downloadlibssh-c65f56aefa50a2e2a78a0e45564526ecc921d74f.tar.gz
libssh-c65f56aefa50a2e2a78a0e45564526ecc921d74f.tar.xz
libssh-c65f56aefa50a2e2a78a0e45564526ecc921d74f.zip
first import
git-svn-id: svn+ssh://svn.berlios.de/svnroot/repos/libssh/trunk@1 7dcaeef0-15fb-0310-b436-a5af3365683c
Diffstat (limited to 'doc')
-rw-r--r--doc/API.html886
-rw-r--r--doc/base64.txt107
-rw-r--r--doc/draft-ietf-secsh-agent-01.txt647
-rw-r--r--doc/draft-ietf-secsh-architecture-14.txt1736
-rw-r--r--doc/draft-ietf-secsh-assignednumbers-04.txt559
-rw-r--r--doc/draft-ietf-secsh-auth-kbdinteract-05-cleaned.txt366
-rw-r--r--doc/draft-ietf-secsh-auth-kbdinteract-05.txt619
-rw-r--r--doc/draft-ietf-secsh-break-00.txt394
-rw-r--r--doc/draft-ietf-secsh-connect-17.txt1232
-rw-r--r--doc/draft-ietf-secsh-dh-group-exchange-04.txt451
-rw-r--r--doc/draft-ietf-secsh-dns-04.txt616
-rw-r--r--doc/draft-ietf-secsh-filexfer-02.txt1626
-rw-r--r--doc/draft-ietf-secsh-filexfer-03.txt1962
-rw-r--r--doc/draft-ietf-secsh-filexfer-04.txt2130
-rw-r--r--doc/draft-ietf-secsh-fingerprint-01.txt120
-rw-r--r--doc/draft-ietf-secsh-gsskeyex-06.txt1509
-rw-r--r--doc/draft-ietf-secsh-newmodes-00.txt619
-rw-r--r--doc/draft-ietf-secsh-publickeyfile-03.txt506
-rw-r--r--doc/draft-ietf-secsh-scp-sftp-ssh-uri-00.txt426
-rw-r--r--doc/draft-ietf-secsh-transport-16.txt1624
-rw-r--r--doc/draft-ietf-secsh-userauth-17.txt840
-rw-r--r--doc/libssh-0.2-api-1.txt370
-rw-r--r--doc/protocol-1.5.txt1501
-rw-r--r--doc/style.css184
24 files changed, 21030 insertions, 0 deletions
diff --git a/doc/API.html b/doc/API.html
new file mode 100644
index 00000000..033843e3
--- /dev/null
+++ b/doc/API.html
@@ -0,0 +1,886 @@
+ <!DOCTYPE HTML SYSTEM>
+<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1">
+<head>
+<title>
+Libssh's Documentation
+</title>
+<link href="style.css" rel="stylesheet" type="text/css">
+</head>
+
+<div id="titre">
+<div align="center">
+LIBSSH API GUIDE <br>
+Or everything you ever wanted to know about a simple and fast ssh library.
+
+</div>
+</div>
+
+<h2> 0 Introduction</h2>
+
+<div class="tout">
+Before inserting ssh hooks into your programs, you must know some basics about
+the ssh protocol, and understand why the ssh library must implement them. <br>
+Lot of the protocols specifications are hidden by the ssh library API (of
+course !) but some still needs an attention from the end-user programmer.<br>
+Note that libssh is still an alpha product, and the API may vary from one
+version to another. The only guess I can make is that the API won't radically
+change. <br>
+The SSH protocol was designed for some goals which I resume here : <br>
+-Privacy of data<br>
+-Security<br>
+-Authentication of the server<br>
+-Authentication of the client.<br>
+The client MUST be sure who's speaking to before entering into any
+authentication way. That's where the end programmer must ensure the given
+fingerprints *are* from the legitimate server. A ssh connection must follow
+the following steps:<br>
+<br>
+1- Before connecting the socket, you can set up if you wish one or other
+ server public key authentication ie. DSA or RSA.
+ You can choose cryptographic algorithms you trust and compression algorithms
+ if any.<br>
+2- The connection is made. A secure handshake is made, and resulting from it,
+ a public key from the server is gained.
+ You MUST verify that the public key is legitimate.<br>
+3- The client must authenticate : the two implemented ways are password, and
+ public keys (from dsa and rsa key-pairs generated by openssh). It is
+ harmless to authenticate to a fake server with these keys because the
+ protocol ensures the data you sign can't be used twice. It just avoids
+ man-in-the-middle attacks.<br>
+4- Now that the user has been authenticated, you must open one or several
+ channels. channels are different subways for information into a single ssh
+ connection. Each channel has a standard stream (stdout) and an error
+ stream (stderr). You can theoretically open an infinity of channel.<br>
+5- With the channel you opened, you can do several things :<br>
+ -Open a shell. You may want to request a pseudo virtual terminal before <br>
+ -Execute a command. The virtual terminal is usable, too<br>
+ -Invoke the sftp subsystem. (look at chapter 6)<br>
+ -invoke your own subsystem. This is out the scope of this
+ document but it is easy to do.<br>
+6- When everything is finished, just close the channels, and then the
+ connection.<br>
+<br>
+At every place, a function which returns an error code (typically -1 for int
+values, NULL for pointers) also sets an error message and an error code.
+I high-lined the main steps, now that's you to follow them :)
+<br>
+</div>
+<h2> 1- Setting the options </h2>
+<div class="tout">
+The options mechanism will change during updates of the library, but the
+functions which exists now will certainly be kept.
+<br><br>
+The ssh system needs to know the preferences of the user, the trust into one
+or another algorithm and such. More important informations have to be given
+before connecting : the host name of the server, the port (if non default),
+the binding address, the default username, ... <br>
+The options structure is given to a ssh_connect function, then this option
+structure is used again and again by the ssh implementation. you shall not
+free it manually, and you shall not share it with multiple sessions.<br>
+Two ways are given for setting the options : the easy one (of course !) and
+the long-but-accurate one.<br><br>
+</div>
+<h3>a) the easy way</h3><br>
+<div class="tout">
+Lot of ssh options in fact come from the command line of the program... <br>
+you could parse them and then use the long way for every argument, but libssh
+has a mechanism to do that for you, automatically.<br>
+<br>
+<div class="prot">
+SSH_OPTIONS *ssh_getopt(int *argcptr, char **argv);
+</div>
+this function will return you a new options pointer based on the arguments
+you give in parameters. <br> better, they clean the argv array from used parameters
+so you can use them after in your own program<br>
+<div class="ex">
+int main(int argc, char **argv){<br>
+ SSH_OPTIONS *opt;<br>
+ opt=ssh_getopt(&argc, argv);<br>
+ if(!opt){<br>
+ ...<br>
+ }<br>
+</div>
+the function will return NULL if some problem is appearing.<br>
+As a matter of portability for you own programs, the hostname isn't always<br>
+the first argument from the command line, so the single arguments (not
+preceded by a -something) won't be parsed.<br>
+<div class="ex">
+example: <br>
+user@host:~$ myssh -u aris localhost <br>
+-u aris will be caught, localhost will not.<br>
+</div>
+
+cfr the options_set_user() function in the next part for more informations
+about it.<br>
+</div>
+<h3>b) the long way</h3>
+<div class="tout">
+<div class="prot">
+SSH_OPTIONS *options_new();
+</div>
+This function returns an empty but initialized option structure pointer.<br>
+The structure is freed by ssh_disconnect described later, so don't use the
+existing function options_free() (it's an internal function).<br>
+So : use it only for <b>one</b> ssh_connect(), <b>never</b> free it.<br>
+<br>
+<div class="prot">
+SSH_OPTIONS *options_copy(SSH_OPTIONS *opt);
+</div>
+If you need to replicate an option object before using it, use this function.
+<br><br>
+
+The following functions are all of the following form : <br>
+<div class="prot">
+int options_set_something(SSH_OPTIONS *opt, something);
+</div>
+the something parameters are always internaly copied, so you don't have to
+strdup them.<br>
+some return eather 0 or -1, in which case an error message appears in the
+error functions, others never fail (return void)<br>
+the error codes and descriptions for these functions are recoverable throught <i>ssh_get_error(NULL);</i>
+<br>
+<div class="prot">
+int options_set_wanted_method(SSH_OPTIONS *opt,int method, char *list);
+</div>
+Passing an option structure, a ssh macro for the method, and a list of allowed
+parameters indicates libssh you want to use these.<br>
+The macros are :<br>
+KEX_ALGO<br>
+KEX_HOSTKEY Server public key type expected<br>
+KEX_CRYPT_C_S 2 Cryptographic algorithm client->server<br>
+KEX_CRYPT_S_C 3 Cryptographic algorithm server->client<br>
+KEX_MAC_C_S 4<br>
+KEX_MAC_S_C 5<br>
+KEX_COMP_C_S 6 Compression method for the stream ("zlib" or "none"), client to server<br>
+KEX_COMP_S_C 7 Compression method for the stream ("zlib" or "none"), server to client<br>
+KEX_LANG_C_S 8<br>
+KEX_LANG_S_C 9<br>
+<br>
+Currently, only KEX_HOSTKEY and ,KEX_CRYPT_C_S,S_C, KEX_COMP_C_S and S_C work
+as expected. the list is a comma separated string of prefered
+algorithms/methods, in order of preference.<br>
+<br>
+<div class="ex">
+example : this sets the ssh stream to be compressed in client->server mode only
+<br>
+
+ret = option_set_wanted_method(options,KEX_COMP_C_S,"zlib");
+</div>
+<div class="ex">
+example: this will set the cryptographic algorithms wanted from server to
+client to aes128-cbc and then aes192-cbc if the first one isn't supported by
+server:<br>
+ret = option_set_wanted_method(options,KEX_CRYPT_S_C,"aes128-cbc,aes192-cbc");
+</div>
+<div class="ex">
+if you prefer getting the Dss key from a server instead of rsa, but you still
+accept rsa if dss isn't available :<br>
+options_set_wanted_method(options,KEX_HOSTKEY,"ssh-dss,ssh-rsa");
+</div>
+return value: <br>0 if the option is valid, -1 else.<br> An error is set in that case.
+<br><br>
+<div class="prot">
+void options_set_port(SSH_OPTIONS *opt, unsigned int port);
+</div>
+this function sets the server port.
+<div class="prot">
+void options_set_host(SSH_OPTIONS *opt, const char *hostname);
+</div>
+this function sets the hostname of the server. It also supports
+"user@hostname" syntax in which case the user options is set too.
+<div class="prot">
+void options_set_fd(SSH_OPTIONS *opt, int fd);
+</div>
+permits you to specify an opened file descriptor you've opened yourself.
+<br>
+It's a good way of bypassing the internal FD opening in libssh, but there are things you should take care of : <br>
+-The file descriptor should be returned to libssh without nonblocking settings<br>
+-If you wish to use <i>is_server_known()</i> You should also set <i>options_set_host</i>... Otherwise libssh won't have any mean of certifying the server is known or not.<br><br>
+<div class="prot">
+void options_set_bindaddr(SSH_OPTIONS *opt, char *bindaddr);
+</div>
+this function allows you to set the binding address, in case your computer has
+multiple IP or interfaces. it supports both hostnames and IP's
+<br><br>
+<div class="prot">
+void options_set_username(SSH_OPTIONS *opt,char *username);
+</div>
+sets username for authenticating in this session.
+<br><br>
+
+<div class="prot">
+void option_set_timeout(SSH_OPTIONS *opt,long seconds, long usec);
+</div>
+sets the timeout for connecting to the socket. It does not include a timeout for the name resolving or handshake.
+<br>
+<br>
+<div class="prot">
+void options_set_ssh_dir(SSH_OPTIONS *opt, char *dir);
+</div>
+this function sets the .ssh/ directory used by libssh. You may use a %s
+which will be replaced by the home directory of the user.
+NEVER accept parameters others than the user's one, they may contain
+format strings which are a security hole if a malicious agent gives it.
+<br><br>
+<div class="prot">
+void options_set_known_hosts_file(SSH_OPTIONS *opt, char *dir);
+</div>
+same than <i>options_set_ssh_dir()</i> for known_hosts file.
+<br><br>
+<div class="prot">
+void options_set_identity(SSH_OPTIONS *opt, char *identity);
+</div>
+same than upper for the identity file (they come by pair, the one asked is the file without the .pub suffix)
+<br><br>
+<div class="prot">
+void options_set_status_callback(SSH_OPTIONS *opt, void (*callback)(void *arg, float status), void *arg);
+</div>
+Because more and more developpers use libssh with GUI, I've added this function to make the ssh_connect function more
+interactive. This permits to set a callback of the form
+<div class="prot">void function(void *userarg, float status);</div> with status going from 0 to 1 during ssh_connect. The callback won't ever be called after the connection is made.
+<br><br>
+</div>
+<h2>
+2- Connecting the ssh server
+</H2>
+<div class="tout">
+The API provides an abstract data type, SSH_SESSION, which describes the
+connection to one particular server. You can make several connections to
+different servers under the same process because of this structure.
+<br>
+<br>
+<div class="prot">
+SSH_SESSION *ssh_connect(SSH_OPTIONS *options);
+</div>
+This function returns a handle on the newly connection. This function expects
+to have a pre-set options structure.
+<br>
+It returns NULL in case of error, in which case you can look at error messages
+for more informations.
+<br><br>
+<div class="prot">
+void ssh_disconnect(SSH_SESSION *session);
+</div>
+This function sends a polite disconnect message, and does clean the session.<br>
+This is the proper way of finishing a ssh connection.<br>
+<br>
+<div class="prot">
+int ssh_get_pubkey_hash(SSH_SESSION *session, char hash[MD5_DIGEST_LEN]);
+</div>
+This function places the MD5 hash of the server public key into the hash array.<br>
+It's IMPORTANT to verify it matches the previous known value. One server always
+have the same hash. No other server/attacker can emulate it (or it'd be caught
+by the public key verification procedure automatically made by libssh).
+<br>
+You can skip this step if you correctly handle <i>is_server_known()</i>
+<br><br>
+<div class="prot">
+int ssh_is_server_known(SSH_SESSION *session);
+</div>
+
+Checks the user's known host file to look for a previous connection to the specified server. Return values:<br>
+SSH_SERVER_KNOWN_OK : the host is known and the key has not changed<br>
+SSH_SERVER_KNOWN_CHANGED : The host's key has changed. Either you are under
+an active attack or the key changed. The API doesn't give any way to modify the key in known hosts yet. I Urge end developers to WARN the user about the possibility of an attack.<br>
+SSH_SERVER_FOUND_OTHER: The host gave us a public key of one type, which does
+not exist yet in our known host file, but there is an other type of key which is know.<br>
+IE server sent a DSA key and we had a RSA key.<br>
+Be carreful it's a possible attack (coder should use option_set_wanted_method() to specify
+which key to use).<br>
+SSH_SERVER_NOT_KNOWN: the server is unknown in known hosts. Possible reasons :
+case not matching, alias, ... In any case the user MUST confirm the Md5 hash is correct.<br>
+SSH_SERVER_ERROR : Some error happened while opening known host file.<br>
+<br>
+<div class="prot">
+int ssh_write_knownhost(SSH_SESSION *session);
+</div>
+write the current connected host as known in the known host file. returns a negative value if something went wrong. You generaly use it when ssh_is_server_known returned SSH_SERVER_NOT_KNOWN.
+<br><br>
+<div class="prot">
+int pubkey_get_hash(SSH_SESSION *session,char hash[MD5_DIGEST_LEN]);
+</div>
+deprecated but left for binary compatibility (will be removed in newer versions).
+</div>
+
+<h2>3- Authenticating to server</h2>
+<div class="tout">
+The ssh library supports the two most used authentication methods from SSH.
+In every function, there is a "username" argument. If null is given instead,
+the server will use the default username (which is guessed from what you gave
+to options_set_user or options_set_hostname or even the local user running the code).
+<br>
+
+Authentication methods :<br>
+<h3>A) Public keys</h3><br>
+ The public key is the only method which does not compromise your key if the
+ remote host has been compromised (the server can't do anything more than
+ getting your public key). This is not the case of a password authentication
+ (the server can get your plaintext password).<br>
+ Libssh is obviously fully compatible with the openssh public and private keys.<br>
+ The things go this way : you scan a list of files which contain public keys.<br>
+ For each key, you send it to ssh server until the server acknowledges a key
+ (a key it knows). Then, you get the private key for this key and send a
+ message proving you own that private key.<br>
+ Here again, two ways for the public key authentication... the easy and the
+ complicated one.<br>
+<br>
+<h4> easy way:</h4>
+<div class="prot">
+int ssh_userauth_autopubkey(SSH_SESSION *session);
+</div>
+This function will try the most common places for finding the public and
+ private keys (your home directory) or eventualy the identity files asked by
+ the <i>options_set_identity()</i> function.<br>
+ The return values are :<br>
+ SSH_AUTH_ERROR : some serious error happened during authentication<br>
+ SSH_AUTH_DENIED : no key matched<br>
+ SSH_AUTH_SUCCESS : you are now authenticated<br>
+ SSH_AUTH_PARTIAL : some key matched but you still have to give an other mean
+ of authentication (like password).<br>
+<br>
+<h4> peanful way:</h4>
+ there are three steps : you get a public key, you ask the server if the key
+ matches a known one, if true, you get the private key and authenticate with
+ it.<br>
+ <div class="prot">
+ STRING *publickey_from_file(char *filename,int *_type);
+</div>
+will return an handle on a public key. if you give a pointer to an int,
+ a symbolic value will be placed there. Do it because you need it in next
+ step.<br><br>
+<div class="prot">
+ int ssh_userauth_offer_pubkey(SSH_SESSION *session, char *username,
+ int type, STRING *publickey);
+ </div>
+ this function will offer a public key to the server. SSH_AUTH_SUCCESS is
+ returned if the key is accepted (in which case you'll want to get the
+ private key), SSH_AUTH_DENIED otherwise.<br>
+ Still watch for SSH_AUTH_ERROR as connection problems might happen.
+<br>
+ in case of SSH_AUTH_SUCCESS,
+ <br>
+ <div class="prot">
+ PRIVATE_KEY *privatekey_from_file(SSH_SESSION *session,char *filename,
+ int type,char *passphrase);
+ </div>
+ will get the privatekey from the filename previously set by
+ publickey_from_next_file(). You can call it with a passphrase for
+ unlocking the key. If passphrase==NULL, the default prompt will be used.<br>
+ The function returns NULL if the private key wasn't opened
+ (ie bad passphrase or missing file).<br>
+<br>
+<div class="prot">
+ int ssh_userauth_pubkey(SSH_SESSION *session, char *username,
+ STRING *publickey, PRIVATE_KEY *privatekey);
+</div>
+ Will try to authenticate using the public and private key. It shall return
+ SSH_AUTH_SUCCESS if you are authenticated, SSH_AUTH_ERROR, SSH_AUTH_DENIED or
+ SSH_AUTH_PARTIAL depending of return condition.<br>
+
+ each public key (of type STRING) must be freed with the libc "free" function.<br>
+ The private key must be freed with private_key_free(PRIVATE_KEY *) which
+ will clean the memory before (don't worry about passphrase leaking).<br>
+ <br>
+
+<h3> B) Password</h3><br>
+ <div class="prot">
+ int ssh_userauth_password(SSH_SESSION *session,char *username,char *password);
+ </div>
+ Will return SSH_AUTH_SUCCESS if the password matched, one of other constants
+ otherwise. It's your work to ask the password and to free it in a secure
+ manner.<br><br>
+
+<h3> C) Keyboard-interactive</h3><br>
+ <div class="prot">
+ int ssh_userauth_kbdint(SSH_SESSION *session, char *user, char *submethods);
+ </div>
+ This is the main keyboard-interactive function. It will return SSH_AUTH_SUCCESS,SSH_AUTH_DENIED, SSH_AUTH_PARTIAL, SSH_AUTH_ERROR depending on the result of the request.<br>
+ The keyboard-interactive authentication method of SSH2 is a feature which permits the server to ask a certain number of questions in an interactive manner to the client, until it decides to accept or deny the login.<br>
+ To begin, you call this function (you can omit user if it was set previously and omit submethods - instead you know what you do - just put them to NULL) and store the answer.
+ If the answer is SSH_AUTH_INFO, it means the server has sent a few questions to ask your user, which you can retrieve with the following functions. Then, set the answers and call back ssh_userauth_kbdint with same arguments. It may again ask a few other questions etc. until you get an other SSH_AUTH code than SSH_AUTH_INFO.<br>
+ Few remarks :<br>
+ -Even the first call can return SSH_AUTH_DENIED or SSH_AUTH_SUCCESS.<br>
+ -The server can send an empty question set (this is the default behavior on my system) after you have sent the answers to the first questions.
+ you must still parse the answer, it might contain some message from the server saying hello or such things. Just call ssh_userauth_kbdint() once more<br>
+<br>
+ <div class="prot">
+int ssh_userauth_kbdint_getnprompts(SSH_SESSION *session);
+ </div>
+After you called ssh_userauth_kbdint and got SSH_AUTH_INFO, the session contains a few questions (or prompts) from the server. This function returns the number of prompts and answers.<br>
+It could be zero, in which case you must act as said previously.<br>
+
+<div class="prot">
+ char *ssh_userauth_kbdint_getname(SSH_SESSION *session);
+</div>
+ this functions returns the "name" of the message block. The meaning is explained later.<br>
+ This function returns a pointer that stays valid until the next ssh_userauth_kbdint() call and must not be freed.<br>
+
+<div class="prot">
+ char *ssh_userauth_kbdint_getinstruction(SSH_SESSION *session);
+</div>
+ this functions returns the "instruction" of the message block. The meaning is explained later.<br>
+This function returns a pointer that stays valid until the next ssh_userauth_kbdint() call and must not be freed.<br>
+
+<div class="prot">
+ char *ssh_userauth_kbdint_getprompt(SSH_SESSION *session,int i, char *echo);
+</div>
+This functions returns a pointer to the nth prompt. The character pointed by echo, if different from null, will contain a boolean value after the call, which means that the user prompt must be echoed or not.<br>
+zero means that the echo is Off (like for a password prompt).<br>
+any other value means the echo is on.<br>
+This function returns a pointer that stays valid until the next ssh_userauth_kbdint() call and must not be freed.<br>
+
+<div class="prot">
+void ssh_userauth_kbdint_setanswer(SSH_SESSION *session, unsigned int i, char *a
+nswer);
+</div>
+This function sets the ith answer. The string you give will be duplicated, and this copy will be discarded once it is no longer necessary.<br>
+care must be taken so you discard the content of the original string after this function call.<br>
+
+<h3> A little note about how to use the informations from keyboard-interactive authentication</h3>
+<br>
+The words from the original drafts explain everything
+<div class="prot">
+3.3 User Interface
+
+Upon receiving a request message, the client SHOULD prompt the user
+as follows:<br>
+ 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.<br>
+<br>
+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.<br>
+<br>
+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.<br>
+The instruction field SHOULD NOT be truncated.<br>
+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.<br>
+<br>
+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.<br>
+
+</div>
+<br>
+<h3> D) "none"</h3><br>
+ In fact this mode only serve to get the list of supported authentications.<br>
+ however, it also serves to get the banner message from the server, if any.<br>
+ You should firstly try this method, at least for getting the banner, then to enter if there is no password at all.<br>
+ <div class="prot">
+ int ssh_userauth_none(SSH_SESSION *session, char *username);
+ </div>
+ if the account has no password (and the server is configured to let you
+ pass), the function might answer SSH_AUTH_SUCCESS. That's why
+ ssh_auth_autopubkey already calls it for you.
+<br><br>
+<div class="prot">
+ char *ssh_get_issue_banner(SSH_SESSION *session);
+</div>
+if during authentication, the server has given a banner, you can get it
+ this way. the function returns NULL if no banner exists, and you have to
+ free the returned pointer.<br><br>
+</div>
+
+<h2>4- Opening a channel</h2>
+<div class="tout">
+Maybe you want to use the sftp subsystem : all this is done for you, you
+better read at the end of the paper how to use the sftp functions.<br>
+You probably want to open one or more shells, or call one or more programs.<br>
+
+So you need a channel.<br>
+<div class="prot">
+ CHANNEL *channel;
+</div>
+This is an handler to a channel object. it describes your channel.
+<br>
+<div class="prot">
+CHANNEL *channel_open_session(SSH_SESSION *session);
+</div>
+This will open a channel for use into a session (which can be used for executing
+a command or a shell. Not for tcp forwarding).<br>
+The function returns NULL if for a reason or another the channel can't be
+opened.<br>
+<i>
+CHANNEL *open_session_channel(...)</i> is deprecated and should not be used in future
+applications.<br><br>
+<div class="prot">
+CHANNEL *channel_open_forward(SSH_SESSION *session, char *remotehost,
+ int remoteport, char *sourcehost, int localport);
+</div>
+Ask the server to tunnel a TCP connection. The server will connect to
+ remotehost:remoteport and libssh will return an handle to the channel if it is allowed.<br>
+ Otherwise, NULL will be returned. sourcehost and localport are generaly
+ used in message debugging purpose and have no effect on the result.<br>
+ <br>
+When you've finished with your channel, you may send an EOF message and
+then close it :<br>
+<div class="prot">
+void channel_send_eof(CHANNEL *channel);
+</div>
+sends an end of file into channel. It doesn't close the channel and you can still read it.<br><br>
+
+<div class="prot">
+void channel_free(CHANNEL *channel);
+</div>
+closes and destroy the channel.
+<br>
+<div class="prot">
+void channel_close(CHANNEL *channel);
+</div>
+sends an EOF and close the channel. (if you don't know what to do, use channel_free). It doesn't free the channel.
+
+</div>
+<h2>5- The shell</h2>
+<div class="tout">
+<div class="prot">
+int channel_request_env(CHANNEL *channel, char *name, char *value);
+</div>
+Ask the server to set the "name" environment variable to "value". For security
+ reasons, some variables won't be accepted by the server. It returns 0 otherwise.<br><br>
+<div class="prot">
+int channel_request_pty(CHANNEL *channel);
+</div>
+ ask the server to allocate a pseudo terminal for the current channel.<br>
+ the function returns 0 on success.<br><br>
+
+<div class="prot">
+int channel_request_pty_size(CHANNEL *channel, char *terminal, int cols, int rows);
+</div>
+ask the server to allocate a pty. The terminal parameter is the type of pty
+(vt100,xterm,...), cols and rows are the size of the new terminal (80x24 by example).<br><br>
+<div class="prot">
+int channel_change_pty_size(CHANNEL *channel, int cols,int rows);
+</div>
+changes the window size (terminal) of the current session;<br><br>
+<div class="prot">
+int channel_request_shell(CHANNEL *channel);
+</div>
+This function requests a shell. After its success, a shell is running at the other side of the channel.<br><br>
+<div class="prot">
+int channel_request_exec(CHANNEL *channel, char *cmd);
+</div>
+run a shell command without an interactive shell, ie $SHELL -c "command".<br>
+ returns 0 on success.<br><br>
+
+You might ask the server to open a subsystem for you. this is done this way :
+<div class="prot">
+int channel_request_subsystem(CHANNEL *channel, char *subsystem);
+</div>
+There are some functions used to manipulate the channels :
+<br><br>
+<div class="prot">
+int channel_write(CHANNEL *channel,void *data,int len);
+</div>
+writes len bytes of data into the channel. It returns the number of bytes written. The current implementation is a blocking write
+of the complete data buffer, but it may vary.<br><br>
+<div class="prot">
+int channel_read(CHANNEL *channel, BUFFER *buffer,int bytes,int is_stderr);
+</div>
+It makes a blocking read on the channel, of "bytes" bytes and returns the
+ result into an allocated buffer you passed in. (with <i>buffer_new()</i>).<br>
+ it will read on stderr, if is_stderr is set.<br>
+ The function might read less bytes than "bytes" variable if an End of File
+ happened. Otherwise, the function will always block reading until "bytes"
+ bytes are read.<br>
+ with "bytes"=0, <i>channel_read()</i> will read the current state of the read buffer, but will read at least one byte (and block if nothing is available, except EOF case).<br>
+
+ You don't need to free and allocate a new buffer each time you call this function, just pass the same object each time.<br>
+ look at the <i>buffer_</i> functions further for the correct way of retrieving the data.<br><br>
+
+<div class="prot">
+int channel_read_nonblocking (CHANNEL *channel, char *dest, int len, int is_stderr);
+</div>
+Non-blocking read on channel, at most len bytes of data are read. Returns 0 if EOF or if no data available.
+<br><br>
+<div class="prot">
+int channel_is_open(CHANNEL *channel);
+</div>
+ returns 0 if the channel has been closed by remote host, something else otherwise.<br><br>
+<div class="prot">
+int channel_poll(CHANNEL *channel, int is_stderr);
+</div>
+ This nonblocking function returns the number of bytes immediatly available for
+ reading on the channel and stdin/stderr.<br><br>
+
+More interesting, if you are going to do channel multiplexing, this function
+is for you :<br><br>
+<div class="prot">
+int ssh_select(CHANNEL **channels,CHANNEL **outchannels, int maxfd,
+ fd_set *readfds, struct timeval *timeout);
+</div>
+channels is an array of channel pointers, finished by a NULL pointer.<br>
+ It can be used ever and ever, as it is never written.<br>
+ outchannels is an array of size at least greater or equal to "channels".<br>
+ It hasn't to be initialized.<br>
+ maxfd is the maximum file descriptor from your own filedescriptors.<br>
+ readfds is a pointer to a fd_set structure, like in the original
+ select implementation (man select).<br>
+ the struct timeval *timeout has the same meaning than in
+ select(2) (man select).<br>
+
+ There is no support for writing or special events as in <i>select(2)</i> yet.<br>
+The function returns -1 if an error occured, or SSH_EINTR if select was interrupted by a syscall. This is not an error, you may restart the function.<br>
+<b>note about signals:</b> libssh is not threadsafe, and most functions are not
+reetrant when using the same data structures : it means you *cannot* do anything
+with a channel from a ssh session passed to <i>ssh_select</i> during a signal.
+<br>take a look at sample.c on how to bypass that limitation.<br>
+the function works this way : it returns in the readfds the filedescriptors which have data ready for reading (the given filedescriptors have a greatest priority).<br>
+Then, if no file descriptor can be read, the function looks for every
+channel from the array to get a channel with data bufferized. If nothing is
+available, it waits for activity on any channel/file descriptor and returns
+immediatly, or waits until timeout.<br>
+You will find the channels that can be read in the outchannels array (finished by NULL) and the filedescriptors in your fd_set (man FD_ISSET).<br>
+this is the "heart" of your main loop.<br>
+<br>
+<h3>The BUFFER object.</h3>
+Reading is done through the BUFFER object. here is the public interface :
+<br>
+<div class="prot">
+BUFFER *buffer_new();
+</div>
+creates a buffer object.
+<br><br>
+<div class="prot">
+void *buffer_get(BUFFER *buffer);
+</div>
+returns a pointer to the begining of buffer.
+<br><br>
+<div class="prot">
+int buffer_get_len(BUFFER *buffer);
+</div>
+returns buffer's data size.
+<br><br>
+<div class="prot">
+void buffer_free(BUFFER *buffer);
+</div>
+destoys the buffer.
+<br>
+<br>
+How to use the buffer system when you've read something:<br>
+I've seen people doing such code:<br>
+<div class="prot">
+char buffer[256];<br>
+channel_read(channel,buf,1234,0);<br>
+strcpy(buffer,buf.data);<br>
+</div>
+The correct way of doing this:
+<div class="prot">
+char buffer[256];<br>
+int i;<br>
+i=channel_read(channel,buf,1234,0);<br>
+if(i<=0)<br>
+&nbsp;&nbsp;&nbsp;&nbsp;go_out()...<br>
+if(i>=256)<br>
+&nbsp;&nbsp;&nbsp;&nbsp;i=255;<br>
+memcpy(buffer,buffer_get(buf),i);<br>
+buffer[i]=0;
+</div>
+Do not expect the buffer to be null-terminated. Don't access the internal structure of buffer. Check the sizes before copying.<br>
+</div>
+<h2>6- The SFTP subsystem</h2>
+<div class="tout">
+SFTP is a secure implementation of a file transfer protocol. The current
+implemented version is 3. All functions aren't implemented yet but the most
+important are.<br>
+<br>
+<h3>A) Opening the session</h3>
+<div class="prot">
+ SFTP_SESSION *sftp_new(SSH_SESSION *session);
+ int sftp_init(SFTP_SESSION *sftp);
+</div>
+ The former returns a SFTP_SESSION handle. It returns NULL if things didn't
+ work as expected.<br>
+ sftp_init makes some initialisation work. It returns 0 if things went right.
+ Both of them must be called.<br>
+<h3>B) Opening and reading a directory</h3>
+<div class="prot">
+ SFTP_DIR *sftp_opendir(SFTP_SESSION *session, char *path);
+</div>
+ opens a directory for file listing. Returns NULL in error case.
+ <br><br>
+<div class="prot">
+ SFTP_ATTRIBUTES *sftp_readdir(SFTP_SESSION *session, SFTP_DIR *dir);
+</div>
+This function reads one file attribute from an opened directory. It
+ returns NULL if the directory is EOF, or if something wrong happened.
+<br><br>
+<div class="prot">
+ int sftp_dir_eof(SFTP_DIR *dir);
+</div>
+ When a <i>sftp_readdir()</i> returned NULL, you can use this function to
+ tell if an EOF occured. the function returns 0 if no EOF occured.
+ <br><br>
+ <div class="prot">
+ void sftp_attributes_free(SFTP_ATTRIBUTES *file);
+</div>
+You have to free any SFTP_ATTRIBUTE structure given by an other function
+ with it.<br><br>
+<div class="prot">
+ int sftp_dir_close(SFTP_DIR *dir);
+</div>
+closes an opened directory. returns 0 when no error occured.
+<br><br>
+<h3>C) Opening, reading, writing files</h3>
+<div class="prot">
+ SFTP_FILE *sftp_open(SFTP_SESSION *session, char *file, int access,
+ SFTP_ATTRIBUTES *attr);
+</div>
+Opens a file. The access flags are the same than the stdio flags.<br>
+see open(2) for more details.<br>
+attr are the wanted attributes for the new file. If you supply NULL,
+ default values will be used.<br>
+rem: more work is going on parsing/making the attributes structure
+<br><br>
+<div class="prot">
+ int sftp_read(SFTP_FILE *file, void *dest, int len);
+</div>
+read on a file. Works as the fread() function. It is blocking by default but you can change the default behaviour with <i>sftp_file_set_nonblocking()</i>.
+ <br><br>
+<div class="prot">
+ void sftp_file_set_nonblocking(SFTP_FILE *file);
+</div>
+sets the file non blocking. reads on this file won't ever block. You can't detect end of files this way.<br>
+*** TODO more work going there for EOF ****
+<br><br>
+<div class="prot">
+ void sftp_file_set_blocking(SFTP_FILE *file);
+</div>
+restore the default setting of sftp_read.
+<br><br>
+<div class="prot">
+ int sftp_write(SFTP_FILE *file, void *source, int len);
+</div>
+works as fwrite() function. It is a blocking write.<br>
+<br>
+<div class="prot">
+ void sftp_seek(SFTP_FILE *file, int new_offset);
+</div>
+seek into the file for reading/writing at an other place.
+<br><br>
+<div class="prot">
+ unsigned long sftp_tell(SFTP_FILE *file);
+</div>
+returns the current offset (both writing and reading) into the opened file.
+<br><br>
+<div class="prot">
+ void sftp_rewind(SFTP_FILE *file);
+</div>
+ same as sftp_seek(file,0);
+<br><br>
+<div class="prot">
+ int sftp_file_close(SFTP_FILE *file);
+</div>
+ closes a file handle. returns 0 in no error case.
+<br><br>
+<div class="prot">
+ int sftp_rm(SFTP_SESSION *sftp, char *file);
+</div>
+deletes a file.
+<br><br>
+<div class="prot">
+ int sftp_rmdir(SFTP_SESSION *sftp, char *directory);
+</div>
+<br>
+deletes a directory.
+<br><br>
+<div class="prot">
+ int sftp_mkdir(SFTP_SESSION *sftp, char *directory, SFTP_ATTRIBUTES *attr);
+</div>
+makes a directory, with the given attributes. You can't pass NULL for attr and hope it works.
+ <br><br>
+<div class="prot">
+ int sftp_rename(SFTP_SESSION *sftp, char *original, char *newname);
+</div>
+changes the name of a file or directory.
+<br><br>
+<div class="prot">
+ int sftp_setstat(SFTP_SESSION *sftp, char *file, SFTP_ATTRIBUTES *attr);
+</div>
+changes the attributes of a file or directory.
+<br><br>
+<div class="prot">
+ char *sftp_canonicalize_path(SFTP_SESSION *sftp, char *path);
+</div>
+ gives the canonicalized form of some path. You have to
+ free the pointer given in return.<br>
+ (returns NULL if error).
+<br><br>
+
+ (a function to make proper SFTP_ATTRIBUTES structures is on the way )
+
+<h3>D) Closing the session</h3>
+<div class="prot">
+ void sftp_free(SFTP_SESSION *sftp);
+</div>
+it closes the sftp channel and subsystem.
+</div>
+
+<h2>7- Handling the errors</h2>
+<div class="tout">
+When some function returns an error code, it's allways possible to get an
+english message describing the problem. the function ssh_get_error()
+returns a pointer to the static error buffer.<br>
+ssh_error_code() returns the error code number. it's declared as an enum:<br>
+SSH_NO_ERROR, SSH_REQUEST_DENIED, SSH_INVALID_REQUEST, SSH_CONNECTION_LOST,
+SSH_FATAL, SSH_INVALID_DATA.<br><br>
+SSH_REQUEST_DENIED means the ssh server refused your request but the situation is
+recoverable. the others mean something happened to the connection (some
+encryption problems, server problems, library bug, ...).<br>
+SSH_INVALID_REQUEST means the library got some garbage from server. (But might be
+recoverable).<br>
+SSH_FATAL means the connection has an important problem and isn't probably
+recoverable.<br>
+<br>
+Most of time, the error returned are SSH_FATAL, but some functions (generaly the
+<i>ssh_request_*</i> ones) may fail because of server denying request. In these cases, SSH_REQUEST_DENIED is returned.<br><br>
+
+You'll see in the prototype SSH_SESSION *session. That's because for thread
+safety, error messages that can be attached to a session aren't static
+anymore. So, any error that could happen during ssh_getopt(), options_* or
+ssh_connect() will be retreavable giving NULL as argument.<br>
+<br>
+<div class="prot">
+char *ssh_get_error(SSH_SESSION *session);
+</div>
+returns a pointer to a static message error from the given session. No
+message freeing is needed.<br><br>
+<div class="prot">
+enum ssh_error ssh_get_error_code(SSH_SESSION *session);
+</div>
+returns the error code that last happened along with the message.
+<br><br>
+</div>
+
+<h2>8- Final word</h2>
+<div class="tout">
+I made this library because nothing in the Open source or free software community was existing yet. This project is a very personnal one as it's the first "useful" thing I ever wrote.
+I hope it fits your needs, but remember the experimental state of libssh : if
+something doesn't work, please mail me. If something lacks, please ask for it.
+If something stinks, please write a patch and send it !
+</div>
+
+</body>
+</html>
diff --git a/doc/base64.txt b/doc/base64.txt
new file mode 100644
index 00000000..48eafabe
--- /dev/null
+++ b/doc/base64.txt
@@ -0,0 +1,107 @@
+ 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
new file mode 100644
index 00000000..4c67b724
--- /dev/null
+++ b/doc/draft-ietf-secsh-agent-01.txt
@@ -0,0 +1,647 @@
+Network Working Group Tatu Ylonen
+INTERNET-DRAFT Timo J. Rinne
+draft-ietf-secsh-agent-01.txt Sami Lehtinen
+Expires in six months SSH Communications Security
+ 20 November, 2002
+
+
+
+ Secure Shell Authentication Agent Protocol
+
+Status of This Memo
+
+This document is an Internet-Draft and is in full conformance
+with all provisions of Section 10 of RFC2026.
+
+Internet-Drafts are working documents of the Internet Engineering
+Task Force (IETF), its areas, and its working groups. Note that
+other groups may also distribute working documents as
+Internet-Drafts.
+
+Internet-Drafts are draft documents valid for a maximum of six
+months and may be updated, replaced, or obsoleted by other
+documents at any time. It is inappropriate to use Internet-
+Drafts as reference material or to cite them other than as
+"work in progress."
+
+The list of current Internet-Drafts can be accessed at
+http://www.ietf.org/ietf/1id-abstracts.txt
+
+The list of Internet-Draft Shadow Directories can be accessed at
+http://www.ietf.org/shadow.html.
+
+Abstract
+
+This document describes the Secure Shell authentication agent protocol
+(i.e., the protocol used between a client requesting authentication and
+the authentication agent). This protocol usually runs in a machine-spe-
+cific local channel or over a forwarded authentication channel. It is
+assumed that the channel is trusted, so no protection for the communica-
+tions channel is provided by this protocol.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Tatu Ylonen, Timo J. Rinne and Sami Lehtinen [page 1]
+
+INTERNET-DRAFT 20 November, 2002
+
+Table of Contents
+
+1. Authentication Agent Protocol . . . . . . . . . . . . . . . . . 2
+ 1.1. Packet Format . . . . . . . . . . . . . . . . . . . . . . . 2
+ 1.2. Forwarding Notices . . . . . . . . . . . . . . . . . . . . . 3
+ 1.3. Requesting Version Number . . . . . . . . . . . . . . . . . 3
+ 1.4. Adding Keys to the Agent . . . . . . . . . . . . . . . . . . 4
+ 1.5. Deleting Keys from the Agent . . . . . . . . . . . . . . . . 5
+ 1.6. Deleting specific key from the Agent . . . . . . . . . . . . 5
+ 1.7. Listing the Keys that the Agent Can Use . . . . . . . . . . 6
+2. Performing Private Key Operations . . . . . . . . . . . . . . . 6
+ 2.1. Signing . . . . . . . . . . . . . . . . . . . . . . . . . . 7
+ 2.2. Decrypting . . . . . . . . . . . . . . . . . . . . . . . . . 7
+ 2.3. Secure Shell Challenge-Response Authentication . . . . . . . 7
+3. Administrative Messages . . . . . . . . . . . . . . . . . . . . 7
+ 3.1. Locking and unlocking the agent . . . . . . . . . . . . . . 8
+ 3.2. Miscellaneous Agent Commands . . . . . . . . . . . . . . . . 8
+4. Agent Forwarding With Secure Shell . . . . . . . . . . . . . . . 9
+ 4.1. Requesting Agent Forwarding . . . . . . . . . . . . . . . . 9
+ 4.2. Agent Forwarding Channels . . . . . . . . . . . . . . . . . 9
+5. Security Considerations . . . . . . . . . . . . . . . . . . . . 9
+6. Intellectual Property . . . . . . . . . . . . . . . . . . . . . 10
+7. Additional Information . . . . . . . . . . . . . . . . . . . . . 10
+8. References . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
+9. Address of Authors . . . . . . . . . . . . . . . . . . . . . . . 10
+
+
+
+1. Authentication Agent Protocol
+
+The authentication agent is a piece of software that runs in a user's
+local workstation, laptop, or other trusted device. It is used to
+implement single sign-on. It holds the user's private keys in its own
+storage, and can perform requested operations using the private key. It
+allows the keys to be kept on a smartcard or other special hardware that
+can perform cryptographic operations.
+
+The authentication agent protocol is used to communicate between the
+authentication agent and clients wanting to authenticate something or
+wanting to perform private key operations.
+
+The actual communication between the client and the agent happens using
+a machine-dependent trusted communications channel. This channel would
+typically be a local socket, named pipe, or some kind of secure
+messaging system that works inside the local machine.
+
+The protocol works by the client sending requests to the agent, and the
+agent responding to these requests.
+
+1.1. Packet Format
+
+All messages passed to/from the authentication agent have the following
+format:
+
+
+Tatu Ylonen, Timo J. Rinne and Sami Lehtinen [page 2]
+
+INTERNET-DRAFT 20 November, 2002
+
+ uint32 length
+ byte type
+ data[length -1] data payload
+
+The following packet types are currently defined:
+
+ /* Messages sent by the client. */
+ #define SSH_AGENT_REQUEST_VERSION 1
+ #define SSH_AGENT_ADD_KEY 202
+ #define SSH_AGENT_DELETE_ALL_KEYS 203
+ #define SSH_AGENT_LIST_KEYS 204
+ #define SSH_AGENT_PRIVATE_KEY_OP 205
+ #define SSH_AGENT_FORWARDING_NOTICE 206
+ #define SSH_AGENT_DELETE_KEY 207
+ #define SSH_AGENT_LOCK 208
+ #define SSH_AGENT_UNLOCK 209
+ #define SSH_AGENT_PING 212
+ #define SSH_AGENT_RANDOM 213
+
+ /* Messages sent by the agent. */
+ #define SSH_AGENT_SUCCESS 101
+ #define SSH_AGENT_FAILURE 102
+ #define SSH_AGENT_VERSION_RESPONSE 103
+ #define SSH_AGENT_KEY_LIST 104
+ #define SSH_AGENT_OPERATION_COMPLETE 105
+ #define SSH_AGENT_RANDOM_DATA 106
+ #define SSH_AGENT_ALIVE 150
+
+1.2. Forwarding Notices
+
+If the agent connection is forwarded through intermediate hosts (using
+the SSH Connection Protocol agent forwarding feature (described in
+Section ``Agent Forwarding With Secure Shell'' of this document), or
+some other means), each intermediate node (Secure Shell client) should
+insert the following message into the agent channel before forwarding
+any other messages. The real agent will then receive these messages in
+sequence the nearest node first, and can determine whether the
+connection is from a local machine and if not, can log the path where
+the connection came from. These messages must be wrapped in the
+appropriate header.
+
+ byte SSH_AGENT_FORWARDING_NOTICE
+ string remote host name (as typed by the user, preferably)
+ string remote host ip
+ uint32 remote host port
+
+1.3. Requesting Version Number
+
+When the client opens a connection, it must send the following message
+to the server. This must be the first message sent. The real agent
+will receive this after zero or more forwarding notice messages.
+ byte SSH_AGENT_REQUEST_VERSION
+ string version string of the application sending the request
+
+
+Tatu Ylonen, Timo J. Rinne and Sami Lehtinen [page 3]
+
+INTERNET-DRAFT 20 November, 2002
+
+ (optional)
+
+If the agent follows this protocol, it will respond with
+
+ byte SSH_AGENT_VERSION_RESPONSE
+ uint32 version number, 2 for this protocol
+
+If the version number request is ever sent to the Secure Shell 1.x
+agent, it will interpret it as a request to list identities. It will
+then respond with a message whose first byte is 2. This can be used to
+determine the version of the agent if compatibility with Secure Shell
+1.x is desired.
+
+If the version string query arrives without trailing string identifying
+the client software version, it can be translated list identities
+request sent by Secure Shell 1.x and handled accordingly. If agent
+software does not support the agent protocol of Secure Shell 1.x, it MAY
+also interpret this query as valid SSH_AGENT_REQUEST_VERSION packet.
+
+1.4. Adding Keys to the Agent
+
+The client can add a new private key to the agent with the following
+message.
+
+ byte SSH_AGENT_ADD_KEY
+ string private key blob with empty passphrase
+ string public key and/or certificates for it
+ string description of the key
+ ... 0, 1 or several constraints follow
+
+All constraints are pairs of following format:
+
+ byte SSH_AGENT_CONSTRAINT_*
+ variable argument for the constraint
+
+The type of the argument is dependent on the constraint type. Following
+constraint types are currently defined:
+
+ /* Constraints 50-99 have a uint32 argument */
+
+ /* Argument is uint32 defining key expiration time-out in
+ seconds. After this timeout expires, the key can't be used.
+ 0 == no timeout */
+ #define SSH_AGENT_CONSTRAINT_TIMEOUT 50
+
+ /* Argument is uint32 defining the number of operations that can
+ be performed with this key. 0xffffffff == no limit */
+ #define SSH_AGENT_CONSTRAINT_USE_LIMIT 51
+
+ /* Argument is uint32 defining the number of forwarding steps that
+ this key can be forwarded. 0xffffffff == no limit */
+ #define SSH_AGENT_CONSTRAINT_FORWARDING_STEPS 52
+
+
+
+Tatu Ylonen, Timo J. Rinne and Sami Lehtinen [page 4]
+
+INTERNET-DRAFT 20 November, 2002
+
+ /* Constraints 100-149 have a string argument */
+
+ /* Argument is string defining the allowed forwarding steps for
+ this key. XXX define this. */
+ #define SSH_AGENT_CONSTRAINT_FORWARDING_PATH 100
+
+ /* Constraints 150-199 have a boolean argument */
+
+ /* Argument is a boolean telling whether the key can be used
+ in Secure Shell 1.x compatibility operations. */
+
+ #define SSH_AGENT_CONSTRAINT_SSH1_COMPAT 150
+
+ /* Argument is a boolean telling whether operations performed
+ with this key should be confirmed interactively by the user
+ or not. */
+ #define SSH_AGENT_CONSTRAINT_NEED_USER_VERIFICATION 151
+
+Message can contain zero, one or multiple constraints.
+
+If the operation is successful, the agent will respond with the
+following message.
+
+ byte SSH_AGENT_SUCCESS
+
+If the operation fails for some reason, the following message will be
+returned instead.
+
+ byte SSH_AGENT_FAILURE
+ uint32 error code
+
+The error code is one of the following:
+
+ #define SSH_AGENT_ERROR_TIMEOUT 1
+ #define SSH_AGENT_ERROR_KEY_NOT_FOUND 2
+ #define SSH_AGENT_ERROR_DECRYPT_FAILED 3
+ #define SSH_AGENT_ERROR_SIZE_ERROR 4
+ #define SSH_AGENT_ERROR_KEY_NOT_SUITABLE 5
+ #define SSH_AGENT_ERROR_DENIED 6
+ #define SSH_AGENT_ERROR_FAILURE 7
+ #define SSH_AGENT_ERROR_UNSUPPORTED_OP 8
+
+1.5. Deleting Keys from the Agent
+
+All keys that are in possession of the agent can be deleted with the
+following message. (The client is allowed to ignore this for some keys
+if desired.)
+
+ byte SSH_AGENT_DELETE_ALL_KEYS
+
+The agent responds with either SSH_AGENT_SUCCESS or SSH_AGENT_FAILURE.
+
+
+
+
+Tatu Ylonen, Timo J. Rinne and Sami Lehtinen [page 5]
+
+INTERNET-DRAFT 20 November, 2002
+
+1.6. Deleting specific key from the Agent
+
+The client can delete a specific key with given public key with
+following message.
+
+ byte SSH_AGENT_DELETE_KEY
+ string public key and/or certificates for it
+ string description of the key
+
+The agent responds with either SSH_AGENT_SUCCESS or SSH_AGENT_FAILURE.
+
+1.7. Listing the Keys that the Agent Can Use
+
+The following message requests a list of all keys that the agent can
+use.
+
+ byte SSH_AGENT_LIST_KEYS
+
+The agent will respond with the following message.
+
+ byte SSH_AGENT_KEY_LIST
+ uint32 number_of_keys
+ repeats number_of_keys times:
+ string public key blob or certificates
+ string description
+
+2. Performing Private Key Operations
+
+The real purpose of the agent is to perform private key operations.
+Such operations are performed with the following message.
+
+ byte SSH_AGENT_PRIVATE_KEY_OP
+ string operation name
+ string key or certificates, as returned in SSH_AGENT_KEY_LIST
+ ... operation-specific data follows
+
+The operation to be performed is identified by a name (string). Custom
+operations can be added by suffixing the operation name by the fully
+qualified domain name of the person/organization adding the new
+operation.
+
+When the operation is complete, the agent will respond with either
+SSH_AGENT_FAILURE or with the following message if the operation is
+successful:
+
+ byte SSH_AGENT_OPERATION_COMPLETE
+ string resulting data
+
+If an operation is attempted that is not supported by the agent, the
+agent will respond with SSH_AGENT_FAILURE with error code set to
+SSH_AGENT_ERROR_UNSUPPORTED_OP.
+
+The standard operations are defined below.
+
+
+Tatu Ylonen, Timo J. Rinne and Sami Lehtinen [page 6]
+
+INTERNET-DRAFT 20 November, 2002
+
+2.1. Signing
+
+The agent can be used to create a digital signature using a key held by
+the agent. The operation name is "sign", and data in is a hash
+(suitable for the key) that is to be signed. This normally performs the
+raw private key operation, without hashing data first. The resulting
+data will be a binary representation of the output of the private key
+operation. The exact details of the operations to be performed depend
+on the key being used.
+
+The operation-specific data has the following format:
+
+ string data to be signed
+
+Alternatively, it is possible to give the actual data to be signed to
+the agent. This is done using the operation "hash-and-sign". This is
+otherwise equal, but performs key-dependent hashing before signing.
+
+If the requested operation is not legal for the key, SSH_AGENT_FAILURE
+will be returned with error code set to
+SSH_AGENT_ERROR_KEY_NOT_SUITABLE.
+
+2.2. Decrypting
+
+The agent can be used to decrypt a public key encrypted message with the
+operation "decrypt". This takes in raw public-key encrypted data, and
+returns the resulting decrypted data.
+
+This may also fail. If the requested operation is not legal for the
+key, error code is set to SSH_AGENT_ERROR_KEY_NOT_SUITABLE.
+
+The operation-specific data has the following format:
+
+ string data to be decrypted
+
+2.3. Secure Shell Challenge-Response Authentication
+
+Performs Secure Shell challenge-response authentication. This operation
+has the name "ssh1-challenge-response".
+
+This operation works by first decrypting the challenge, then computing
+MD5 of the concatenation of the decrypted challenge and the session id
+(in this order), and returns the resulting 16 byte hash. The operation-
+specific data is in the following format:
+
+ string challenge encrypted using the public key
+ string session id
+
+Normally, the length of the challenge before encryption will be 32 bytes
+and the length of the session id 16 bytes. The length of the encrypted
+challenge depends on the key and algorithm used.
+
+
+
+
+Tatu Ylonen, Timo J. Rinne and Sami Lehtinen [page 7]
+
+INTERNET-DRAFT 20 November, 2002
+
+3. Administrative Messages
+
+There are also a number of messages that are only used to administer the
+agent. These might e.g. be used by a user interface for the agent. The
+agent should only allow these messages from local connection (i.e., if
+no forwarding notice messages were received before the version number
+request).
+
+3.1. Locking and unlocking the agent
+
+The agent can be temporarily locked by message:
+
+ byte SSH_AGENT_LOCK
+ string locking password
+
+The agent responds with either SSH_AGENT_SUCCESS or SSH_AGENT_FAILURE.
+Particularily SSH_AGENT_FAILURE is sent, if agent is already locked.
+After this message, agent responds to all commands with
+SSH_AGENT_FAILURE until it receives a following command.
+
+ byte SSH_AGENT_UNLOCK
+ string locking password
+
+The agent responds with either SSH_AGENT_SUCCESS or SSH_AGENT_FAILURE.
+Particularily SSH_AGENT_FAILURE is sent, if agent is not locked or if
+the submitted password does not match with one given with SSH_AGENT_LOCK
+message.
+
+3.2. Miscellaneous Agent Commands
+
+ byte SSH_AGENT_PING
+ ... arbitrary padding data
+
+Any agent or client receiving this message, should respond with
+
+ byte SSH_AGENT_ALIVE
+ ... padding data from the SSH_AGENT_PING request
+
+where the padding data is identical to the data sent with
+SSH_AGENT_PING.
+
+ byte SSH_AGENT_RANDOM
+ uint32 the length of the requested random buffer
+
+Client can request random data from the agent by this message. Agent
+responds either with SSH_AGENT_RANDOM_DATA or SSH_AGENT_FAILURE message.
+
+ byte SSH_AGENT_RANDOM_DATA
+ string random data
+
+This message is a successful response to SSH_AGENT_RANDOM message.
+Message contains the random string of requested length.
+
+
+
+Tatu Ylonen, Timo J. Rinne and Sami Lehtinen [page 8]
+
+INTERNET-DRAFT 20 November, 2002
+
+4. Agent Forwarding With Secure Shell
+
+The agent connection is typically forwarded over a Secure Shell
+connection. This requires small additions to the SSH Connection Protocol
+[SSH-CONN].
+
+4.1. Requesting Agent Forwarding
+
+Agent forwarding may be requested for a session by sending
+
+ byte SSH_MSG_CHANNEL_REQUEST
+ uint32 recipient channel
+ string "auth-agent-req"
+ boolean want reply
+
+This will, on success, create an agent listener to the remote end.
+
+4.2. Agent Forwarding Channels
+
+When a connection comes to the forwarded agent listener, a channel is
+opened to forward the connection to the other side.
+
+ byte SSH_MSG_CHANNEL_OPEN
+ string "auth-agent"
+ uint32 sender channel
+ uint32 initial window size
+ uint32 maximum packet size
+
+Implementations MUST reject these messages unless they have previously
+requested agent forwarding.
+
+Forwarded agent channels are independent of any sessions, and closing a
+session channel does not in any way imply that forwarded connections
+should be closed.
+
+5. Security Considerations
+
+The authentication agent is used to control security-sensitive
+operations, and is used to implement single sign-on.
+
+Anyone with access to the authentication agent can perform private key
+operations with the agent. This is a power equivalent to possession of
+the private key as long as the connection to the key is maintained. It
+is not possible to retrieve the key from the agent.
+
+It is recommended that agent implementations allow and perform some form
+of logging and access control. This access control may utilize
+information about the path through which the connection was received (as
+collected with SSH_AGENT_FORWARDING_NOTICE messages; however, the path
+is reliable only up to and including the first unreliable machine.).
+Implementations should also allow restricting the operations that can be
+performed with keys - e.g., limiting them to challenge-response only.
+
+
+
+Tatu Ylonen, Timo J. Rinne and Sami Lehtinen [page 9]
+
+INTERNET-DRAFT 20 November, 2002
+
+One should note that a local superuser will be able to obtain access to
+agents running on the local machine. This cannot be prevented; in most
+operating systems, a user with sufficient privileges will be able to
+read the keys from the physical memory.
+
+The authentication agent should not be run or forwarded to machine whose
+integrity is not trusted, as security on such machines might be
+compromised and might allow an attacker to obtain unauthorized access to
+the agent.
+
+6. Intellectual Property
+
+The IETF takes no position regarding the validity or scope of any
+intellectual property or other rights that might be claimed to pertain
+to the implementation or use of the technology described in this
+document or the extent to which any license under such rights might or
+might not be available; neither does it represent that it has made any
+effort to identify any such rights. Information on the IETF's
+procedures with respect to rights in standards-track and standards-
+related documentation can be found in BCP-11. Copies of claims of
+rights made available for publication and any assurances of licenses to
+be made available, or the result of an attempt made to obtain a general
+license or permission for the use of such proprietary rights by
+implementers or users of this specification can be obtained from the
+IETF Secretariat.
+
+The IETF has been notified of intellectual property rights claimed in
+regard to some or all of the specification contained in this document.
+For more information consult the online list of claimed rights.
+
+7. Additional Information
+
+The current document editor is: Sami Lehtinen <sjl@ssh.com>. Comments
+on this Internet-Draft should be sent to the IETF SECSH working group,
+details at: http://ietf.org/html.charters/secsh-charter.html
+
+8. References
+
+[SECSH-CONNECT] Ylonen, T., et al: "Secure Shell Connection Protocol",
+Internet-Draft, draft-ietf-secsh-connect-16.txt
+
+9. Address of Authors
+
+ Tatu Ylonen
+ SSH Communications Security Corp
+ Fredrikinkatu 42
+ FIN-00100 HELSINKI
+ Finland
+ E-mail: ylo@ssh.com
+
+ Timo J. Rinne
+ SSH Communications Security Corp
+ Fredrikinkatu 42
+
+
+Tatu Ylonen, Timo J. Rinne and Sami Lehtinen [page 10]
+
+INTERNET-DRAFT 20 November, 2002
+
+ FIN-00100 HELSINKI
+ Finland
+ E-mail: tri@ssh.com
+
+ Sami Lehtinen
+ SSH Communications Security Corp
+ Fredrikinkatu 42
+ FIN-00100 HELSINKI
+ Finland
+ E-mail: sjl@ssh.com
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Tatu Ylonen, Timo J. Rinne and Sami Lehtinen [page 11]
diff --git a/doc/draft-ietf-secsh-architecture-14.txt b/doc/draft-ietf-secsh-architecture-14.txt
new file mode 100644
index 00000000..9a7c4082
--- /dev/null
+++ b/doc/draft-ietf-secsh-architecture-14.txt
@@ -0,0 +1,1736 @@
+
+
+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
new file mode 100644
index 00000000..f87ca0c7
--- /dev/null
+++ b/doc/draft-ietf-secsh-assignednumbers-04.txt
@@ -0,0 +1,559 @@
+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
new file mode 100644
index 00000000..b22a6632
--- /dev/null
+++ b/doc/draft-ietf-secsh-auth-kbdinteract-05-cleaned.txt
@@ -0,0 +1,366 @@
+
+ Generic Message Exchange Authentication For SSH
+ <draft-ietf-secsh-auth-kbdinteract-05.txt>
+
+Abstract
+
+ SSH is a protocol for secure remote login and other secure network
+ services over an insecure network. This document describes a general
+ purpose authentication method for the SSH protocol, suitable for
+ interactive authentications where the authentication data should be
+ entered via a keyboard. The major goal of this method is to allow
+ the SSH client to support a whole class of authentication
+ mechanism(s) without knowing the specifics of the actual
+ authentication mechanism(s).
+
+1. Introduction
+
+ The SSH authentication protocol [SSH-USERAUTH] is a general-purpose
+ user authentication protocol. It is intended to be run over the SSH
+ transport layer protocol [SSH-TRANS]. The authentication protocol
+ assumes that the underlying protocols provide integrity and
+ confidentiality protection.
+
+ This document describes a general purpose authentication method for
+ the SSH authentication protocol. This method is suitable for
+ interactive authentication methods which do not need any special
+ software support on the client side. Instead all authentication data
+ should be entered via the keyboard. The major goal of this method is
+ to allow the SSH client to have little or no knowledge of the
+ specifics of the underlying authentication mechanism(s) used by the
+ SSH server. This will allow the server to arbitrarily select or
+ change the underlying authentication mechanism(s) without having to
+ update client code.
+
+ The name for this authentication method is "keyboard-interactive".
+
+2. Rationale
+
+ Currently defined authentication methods for SSH are tightly coupled
+ with the underlying authentication mechanism. This makes it
+ difficult to add new mechanisms for authentication as all clients
+ must be updated to support the new mechanism. With the generic
+ method defined here, clients will not require code changes to support
+ new authentication mechanisms, and if a separate authentication layer
+ is used, such as [PAM], then the server may not need any code changes
+ either.
+
+ This presents a significant advantage to other methods, such as the
+ "password" method (defined in [SSH-USERAUTH]), as new (presumably
+ stronger) methods may be added "at will" and system security can be
+ transparently enhanced.
+
+ Challenge-response and One Time Password mechanisms are also easily
+ supported with this authentication method.
+
+ This authentication method is however limited to authentication
+ mechanisms which do not require any special code, such as hardware
+ drivers or password mangling, on the client.
+
+3. Protocol Exchanges
+
+ The client initiates the authentication with a
+ SSH_MSG_USERAUTH_REQUEST message. The server then requests
+ authentication information from the client with a
+ SSH_MSG_USERAUTH_INFO_REQUEST message. The client obtains the
+ information from the user and then responds with a
+ SSM_MSG_USERAUTH_INFO_RESPONSE message. The server MUST NOT send
+ another SSH_MSG_USERAUTH_INFO_REQUEST before it has received the
+ answer from the client.
+
+3.1 Initial Exchange
+
+ The authentication starts with the client sending the following
+ packet:
+
+ byte SSH_MSG_USERAUTH_REQUEST
+ string user name (ISO-10646 UTF-8, as defined in [RFC-2279])
+ string service name (US-ASCII)
+ string "keyboard-interactive" (US-ASCII)
+ string language tag (as defined in [RFC-3066])
+ string submethods (ISO-10646 UTF-8)
+
+ The language tag is deprecated and SHOULD be the empty string. It
+ may be removed in a future revision of this specification. The
+ server SHOULD instead select the language used based on the tags
+ communicated during key exchange [SSH-TRANS].
+
+ If the language tag is not the empty string, the server SHOULD use
+ the specified language for any messages sent to the client as part of
+ this protocol. The language tag SHOULD NOT be used for language
+ selection for messages outside of this protocol. The language to be
+ used if the server does not support the requested language is
+ implementation-dependent.
+
+ The submethods field is included so the user can give a hint of which
+ actual methods he wants to use. It is a a comma-separated list of
+ authentication submethods (software or hardware) which the user
+ prefers. If the client has knowledge of the submethods preferred by
+ the user, presumably through a configuration setting, it MAY use the
+ submethods field to pass this information to the server. Otherwise
+ it MUST send the empty string.
+
+ The actual names of the submethods is something which the user and
+ the server needs to agree upon.
+
+ Server interpretation of the submethods field is implementation-
+ dependent.
+
+ One possible implementation strategy of the submethods field on the
+ server is that, unless the user may use multiple different
+ submethods, the server ignores this field. If the user may
+ authenticate using one of several different submethods the server
+ should treat the submethods field as a hint on which submethod the
+ user wants to use this time.
+
+ Note that when this message is sent to the server, the client has not
+ yet prompted the user for a password, and so that information is NOT
+ included with this initial message (unlike the "password" method).
+
+ The server MUST reply with either a SSH_MSG_USERAUTH_SUCCESS,
+ SSH_MSG_USERAUTH_FAILURE, or SSH_MSG_USERAUTH_INFO_REQUEST message.
+
+ The server SHOULD NOT reply with the SSH_MSG_USERAUTH_FAILURE message
+ if the failure is based on the user name or service name; instead it
+ SHOULD send SSH_MSG_USERAUTH_INFO_REQUEST message(s) which look just
+ like the one(s) which would have been sent in cases where
+ authentication should proceed, and then send the failure message
+ (after a suitable delay, as described below). The goal is to make it
+ impossible to find valid usernames by just comparing the results when
+ authenticating as different users.
+
+3.2 Information Requests
+
+ Requests are generated from the server using the
+ SSH_MSG_USERAUTH_INFO_REQUEST message.
+
+ The server may send as many requests as are necessary to authenticate
+ the client; the client MUST be prepared to handle multiple exchanges.
+ However the server MUST NOT ever have more than one
+ SSH_MSG_USERAUTH_INFO_REQUEST message outstanding. That is, it may
+ not send another request before the client has answered.
+
+ The SSH_MSG_USERAUTH_INFO_REQUEST message is defined as follows:
+
+ byte SSH_MSG_USERAUTH_INFO_REQUEST
+ string name (ISO-10646 UTF-8)
+ string instruction (ISO-10646 UTF-8)
+ string language tag (as defined in [RFC-3066])
+ int num-prompts
+ string prompt[1] (ISO-10646 UTF-8)
+ boolean echo[1]
+ ...
+ string prompt[num-prompts] (ISO-10646 UTF-8)
+ boolean echo[num-prompts]
+
+ The server SHOULD take into consideration that some clients may not
+ be able to properly display a long name or prompt field (see next
+ section), and limit the lengths of those fields if possible. For
+ example, instead of an instruction field of "Enter Password" and a
+ prompt field of "Password for user23@host.domain: ", a better choice
+ might be an instruction field of
+ "Password authentication for user23@host.domain" and a prompt field
+ of "Password: ". It is expected that this authentication method
+ would typically be backended by [PAM] and so such choices would not
+ be possible.
+
+ The name and instruction fields MAY be empty strings, the client MUST
+ be prepared to handle this correctly. The prompt field(s) MUST NOT
+ be empty strings.
+
+ The language tag SHOULD describe the language used in the textual
+ fields. If the server does not know the language used, or if
+ multiple languages are used, the language tag MUST be the empty
+ string.
+
+ The num-prompts field may be `0', in which case there will be no
+ prompt/echo fields in the message, but the client SHOULD still
+ display the name and instruction fields (as described below).
+
+3.3 User Interface
+
+ Upon receiving a request message, the client SHOULD prompt the user
+ as follows:
+
+ A command line interface (CLI) client SHOULD print the name and
+ instruction (if non-empty), adding newlines. Then for each prompt in
+ turn, the client SHOULD display the prompt and read the user input.
+
+ A graphical user interface (GUI) client has many choices on how to
+ prompt the user. One possibility is to use the name field (possibly
+
+ prefixed with the application's name) as the title of a dialog window
+ in which the prompt(s) are presented. In that dialog window, the
+ instruction field would be a text message, and the prompts would be
+ labels for text entry fields. All fields SHOULD be presented to the
+ user, for example an implementation SHOULD NOT discard the name field
+ because its windows lack titles; it SHOULD instead find another way
+ to display this information. If prompts are presented in a dialog
+ window, then the client SHOULD NOT present each prompt in a separate
+ window.
+
+ All clients MUST properly handle an instruction field with embedded
+ newlines. They SHOULD also be able to display at least 30 characters
+ for the name and prompts. If the server presents names or prompts
+ longer than 30 characters, the client MAY truncate these fields to
+ the length it can display. If the client does truncate any fields,
+ there MUST be an obvious indication that such truncation has occured.
+ The instruction field SHOULD NOT be truncated.
+
+ Clients SHOULD use control character filtering as discussed in
+ [SSH-ARCH] to avoid attacks by including terminal control characters
+ in the fields to be displayed.
+
+ For each prompt, the corresponding echo field indicates whether or
+ not the user input should be echoed as characters are typed. Clients
+ SHOULD correctly echo/mask user input for each prompt independently
+ of other prompts in the request message. If a client does not honor
+ the echo field for whatever reason, then the client MUST err on the
+ side of masking input. A GUI client might like to have a checkbox
+ toggling echo/mask. Clients SHOULD NOT add any additional characters
+ to the prompt such as ": " (colon-space); the server is responsible
+ for supplying all text to be displayed to the user. Clients MUST
+ also accept empty responses from the user and pass them on as empty
+ strings.
+
+3.4 Information Responses
+
+ After obtaining the requested information from the user, the client
+ MUST respond with a SSH_MSG_USERAUTH_INFO_RESPONSE message.
+
+ The format of the SSH_MSG_USERAUTH_INFO_RESPONSE message is as
+ follows:
+
+ byte SSH_MSG_USERAUTH_INFO_RESPONSE
+ int num-responses
+ string response[1] (ISO-10646 UTF-8)
+ ...
+ string response[num-responses] (ISO-10646 UTF-8)
+
+ Note that the responses are encoded in ISO-10646 UTF-8. It is up to
+ the server how it interprets the responses and validates them.
+ However, if the client reads the responses in some other encoding
+ (e.g., ISO 8859-1), it MUST convert the responses to ISO-10646 UTF-8
+ before transmitting.
+
+ If the num-responses field does not match the num-prompts field in
+ the request message, the server MUST send a failure message.
+
+ In the case that the server sends a `0' num-prompts field in the
+ request message, the client MUST send a response message with a `0'
+ num-responses field.
+
+ The responses MUST be ordered as the prompts were ordered. That is,
+ response[n] MUST be the answer to prompt[n].
+
+ After receiving the response, the server MUST send either a
+ SSH_MSG_USERAUTH_SUCCESS, SSH_MSG_USERAUTH_FAILURE, or another
+ SSH_MSG_USERAUTH_INFO_REQUEST message.
+
+ If the server fails to authenticate the user (through the underlying
+ authentication mechanism(s)), it SHOULD NOT send another request
+ message(s) in an attempt to obtain new authentication data, instead
+ it SHOULD send a failure message. The only time the server should
+ send multiple request messages is if additional authentication data
+ is needed (i.e., because there are multiple underlying authentication
+ mechanisms that must be used to authenticate the user).
+
+ If the server intends to respond with a failure message, it MAY delay
+ for an implementation-dependent time before sending to the client.
+ It is suspected that implementations are likely to make the time
+ delay a configurable, a suggested default is 2 seconds.
+
+4. Authentication Examples
+
+ Here are two example exchanges between a client and server. The
+ first is an example of challenge/response with a handheld token.
+ This is an authentication that is not otherwise possible with other
+ authentication methods.
+
+ C: byte SSH_MSG_USERAUTH_REQUEST
+ C: string "user23"
+ C: string "ssh-userauth"
+ C: string "keyboard-interactive"
+ C: string ""
+ C: string ""
+
+ S: byte SSH_MSG_USERAUTH_INFO_REQUEST
+ S: string "CRYPTOCard Authentication"
+ S: string "The challenge is '14315716'"
+ S: string "en-US"
+ S: int 1
+ S: string "Response: "
+ S: boolean TRUE
+
+ [Client prompts user for password]
+
+ C: byte SSH_MSG_USERAUTH_INFO_RESPONSE
+ C: int 1
+ C: string "6d757575"
+
+ S: byte SSH_MSG_USERAUTH_SUCCESS
+
+ The second example is of a standard password authentication, in
+ this case the user's password is expired.
+
+ C: byte SSH_MSG_USERAUTH_REQUEST
+ C: string "user23"
+ C: string "ssh-userauth"
+ C: string "keyboard-interactive"
+ C: string "en-US"
+ C: string ""
+
+ S: byte SSH_MSG_USERAUTH_INFO_REQUEST
+ S: string "Password Authentication"
+ S: string ""
+ S: string "en-US"
+ S: int 1
+ S: string "Password: "
+ S: boolean FALSE
+
+ [Client prompts user for password]
+
+ C: byte SSH_MSG_USERAUTH_INFO_RESPONSE
+ C: int 1
+ C: string "password"
+
+ S: byte SSH_MSG_USERAUTH_INFO_REQUEST
+ S: string "Password Expired"
+ S: string "Your password has expired."
+ S: string "en-US"
+ S: int 2
+ S: string "Enter new password: "
+ S: boolean FALSE
+ S: string "Enter it again: "
+ S: boolean FALSE
+
+ [Client prompts user for new password]
+
+ C: byte SSH_MSG_USERAUTH_INFO_RESPONSE
+ C: int 2
+ C: string "newpass"
+ C: string "newpass"
+
+ S: byte SSH_MSG_USERAUTH_INFO_REQUEST
+ S: string "Password changed"
+ S: string "Password successfully changed for user23."
+ S: string "en-US"
+ S: int 0
+
+ [Client displays message to user]
+
+ C: byte SSH_MSG_USERAUTH_INFO_RESPONSE
+ C: int 0
+
+ S: byte SSH_MSG_USERAUTH_SUCCESS
+
+5. IANA Considerations
+
+ The userauth type "keyboard-interactive" is used for this
+ authentication method.
+
+ The following method-specific constants are used with this
+ authentication method:
+
+ SSH_MSG_USERAUTH_INFO_REQUEST 60
+ SSH_MSG_USERAUTH_INFO_RESPONSE 61
diff --git a/doc/draft-ietf-secsh-auth-kbdinteract-05.txt b/doc/draft-ietf-secsh-auth-kbdinteract-05.txt
new file mode 100644
index 00000000..99504dbf
--- /dev/null
+++ b/doc/draft-ietf-secsh-auth-kbdinteract-05.txt
@@ -0,0 +1,619 @@
+
+
+
+Network Working Group F. Cusack
+INTERNET-DRAFT Google, Inc.
+Expires November 1, 2003 M. Forssen
+ Appgate AB
+ May 1, 2003
+
+
+
+
+ Generic Message Exchange Authentication For SSH
+ <draft-ietf-secsh-auth-kbdinteract-05.txt>
+
+Status of this Memo
+
+ This document is an Internet-Draft and is subject to all provisions
+ of Section 10 of RFC2026.
+
+ Internet-Drafts are working documents of the Internet Engineering
+ Task Force (IETF), its areas, and its working groups. Note that
+ other groups may also distribute working documents as
+ Internet-Drafts.
+
+ Internet-Drafts are draft documents valid for a maximum of six months
+ and may be updated, replaced, or obsoleted by other documents at any
+ time. It is inappropriate to use Internet-Drafts as reference
+ material or to cite them other than as "work in progress."
+
+ The list of current Internet-Drafts can be accessed at
+ <http://www.ietf.org/ietf/1id-abstracts.txt>.
+
+ The list of Internet-Draft Shadow Directories can be accessed at
+ <http://www.ietf.org/shadow.html>.
+
+ This Internet-Draft will expire on November 1, 2003.
+
+Abstract
+
+ SSH is a protocol for secure remote login and other secure network
+ services over an insecure network. This document describes a general
+ purpose authentication method for the SSH protocol, suitable for
+ interactive authentications where the authentication data should be
+ entered via a keyboard. The major goal of this method is to allow
+ the SSH client to support a whole class of authentication
+ mechanism(s) without knowing the specifics of the actual
+ authentication mechanism(s).
+
+
+
+
+
+
+
+
+
+F. Cusack, M. Forssen Expires November 1, 2003 [Page 1]
+
+Internet Draft SSH Generic Interactive Authentication May 1, 2003
+
+
+1. Introduction
+
+ The SSH authentication protocol [SSH-USERAUTH] is a general-purpose
+ user authentication protocol. It is intended to be run over the SSH
+ transport layer protocol [SSH-TRANS]. The authentication protocol
+ assumes that the underlying protocols provide integrity and
+ confidentiality protection.
+
+ This document describes a general purpose authentication method for
+ the SSH authentication protocol. This method is suitable for
+ interactive authentication methods which do not need any special
+ software support on the client side. Instead all authentication data
+ should be entered via the keyboard. The major goal of this method is
+ to allow the SSH client to have little or no knowledge of the
+ specifics of the underlying authentication mechanism(s) used by the
+ SSH server. This will allow the server to arbitrarily select or
+ change the underlying authentication mechanism(s) without having to
+ update client code.
+
+ The name for this authentication method is "keyboard-interactive".
+
+ This document should be read only after reading the SSH architecture
+ document [SSH-ARCH] and the SSH authentication document
+ [SSH-USERAUTH]. This document freely uses terminology and notation
+ from both documents without reference or further explanation.
+
+ This document also describes some of the client interaction with the
+ user in obtaining the authentication information. While this is
+ somewhat out of the scope of a protocol specification, it is
+ described here anyway since some aspects of the protocol are
+ specifically designed based on user interface issues, and omitting
+ this information may lead to incompatible or awkward implementations.
+
+ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
+ "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
+ document are to be interpreted as described in [RFC-2119].
+
+2. Rationale
+
+ Currently defined authentication methods for SSH are tightly coupled
+ with the underlying authentication mechanism. This makes it
+ difficult to add new mechanisms for authentication as all clients
+ must be updated to support the new mechanism. With the generic
+ method defined here, clients will not require code changes to support
+ new authentication mechanisms, and if a separate authentication layer
+ is used, such as [PAM], then the server may not need any code changes
+ either.
+
+
+
+
+F. Cusack, M. Forssen Expires November 1, 2003 [Page 2]
+
+Internet Draft SSH Generic Interactive Authentication May 1, 2003
+
+
+ This presents a significant advantage to other methods, such as the
+ "password" method (defined in [SSH-USERAUTH]), as new (presumably
+ stronger) methods may be added "at will" and system security can be
+ transparently enhanced.
+
+ Challenge-response and One Time Password mechanisms are also easily
+ supported with this authentication method.
+
+ This authentication method is however limited to authentication
+ mechanisms which do not require any special code, such as hardware
+ drivers or password mangling, on the client.
+
+3. Protocol Exchanges
+
+ The client initiates the authentication with a
+ SSH_MSG_USERAUTH_REQUEST message. The server then requests
+ authentication information from the client with a
+ SSH_MSG_USERAUTH_INFO_REQUEST message. The client obtains the
+ information from the user and then responds with a
+ SSM_MSG_USERAUTH_INFO_RESPONSE message. The server MUST NOT send
+ another SSH_MSG_USERAUTH_INFO_REQUEST before it has received the
+ answer from the client.
+
+3.1 Initial Exchange
+
+ The authentication starts with the client sending the following
+ packet:
+
+ byte SSH_MSG_USERAUTH_REQUEST
+ string user name (ISO-10646 UTF-8, as defined in [RFC-2279])
+ string service name (US-ASCII)
+ string "keyboard-interactive" (US-ASCII)
+ string language tag (as defined in [RFC-3066])
+ string submethods (ISO-10646 UTF-8)
+
+ The language tag is deprecated and SHOULD be the empty string. It
+ may be removed in a future revision of this specification. The
+ server SHOULD instead select the language used based on the tags
+ communicated during key exchange [SSH-TRANS].
+
+ If the language tag is not the empty string, the server SHOULD use
+ the specified language for any messages sent to the client as part of
+ this protocol. The language tag SHOULD NOT be used for language
+ selection for messages outside of this protocol. The language to be
+ used if the server does not support the requested language is
+ implementation-dependent.
+
+ The submethods field is included so the user can give a hint of which
+
+
+
+F. Cusack, M. Forssen Expires November 1, 2003 [Page 3]
+
+Internet Draft SSH Generic Interactive Authentication May 1, 2003
+
+
+ actual methods he wants to use. It is a a comma-separated list of
+ authentication submethods (software or hardware) which the user
+ prefers. If the client has knowledge of the submethods preferred by
+ the user, presumably through a configuration setting, it MAY use the
+ submethods field to pass this information to the server. Otherwise
+ it MUST send the empty string.
+
+ The actual names of the submethods is something which the user and
+ the server needs to agree upon.
+
+ Server interpretation of the submethods field is implementation-
+ dependent.
+
+ One possible implementation strategy of the submethods field on the
+ server is that, unless the user may use multiple different
+ submethods, the server ignores this field. If the user may
+ authenticate using one of several different submethods the server
+ should treat the submethods field as a hint on which submethod the
+ user wants to use this time.
+
+ Note that when this message is sent to the server, the client has not
+ yet prompted the user for a password, and so that information is NOT
+ included with this initial message (unlike the "password" method).
+
+ The server MUST reply with either a SSH_MSG_USERAUTH_SUCCESS,
+ SSH_MSG_USERAUTH_FAILURE, or SSH_MSG_USERAUTH_INFO_REQUEST message.
+
+ The server SHOULD NOT reply with the SSH_MSG_USERAUTH_FAILURE message
+ if the failure is based on the user name or service name; instead it
+ SHOULD send SSH_MSG_USERAUTH_INFO_REQUEST message(s) which look just
+ like the one(s) which would have been sent in cases where
+ authentication should proceed, and then send the failure message
+ (after a suitable delay, as described below). The goal is to make it
+ impossible to find valid usernames by just comparing the results when
+ authenticating as different users.
+
+3.2 Information Requests
+
+ Requests are generated from the server using the
+ SSH_MSG_USERAUTH_INFO_REQUEST message.
+
+ The server may send as many requests as are necessary to authenticate
+ the client; the client MUST be prepared to handle multiple exchanges.
+ However the server MUST NOT ever have more than one
+ SSH_MSG_USERAUTH_INFO_REQUEST message outstanding. That is, it may
+ not send another request before the client has answered.
+
+
+
+
+
+F. Cusack, M. Forssen Expires November 1, 2003 [Page 4]
+
+Internet Draft SSH Generic Interactive Authentication May 1, 2003
+
+
+ The SSH_MSG_USERAUTH_INFO_REQUEST message is defined as follows:
+
+ byte SSH_MSG_USERAUTH_INFO_REQUEST
+ string name (ISO-10646 UTF-8)
+ string instruction (ISO-10646 UTF-8)
+ string language tag (as defined in [RFC-3066])
+ int num-prompts
+ string prompt[1] (ISO-10646 UTF-8)
+ boolean echo[1]
+ ...
+ string prompt[num-prompts] (ISO-10646 UTF-8)
+ boolean echo[num-prompts]
+
+ The server SHOULD take into consideration that some clients may not
+ be able to properly display a long name or prompt field (see next
+ section), and limit the lengths of those fields if possible. For
+ example, instead of an instruction field of "Enter Password" and a
+ prompt field of "Password for user23@host.domain: ", a better choice
+ might be an instruction field of
+ "Password authentication for user23@host.domain" and a prompt field
+ of "Password: ". It is expected that this authentication method
+ would typically be backended by [PAM] and so such choices would not
+ be possible.
+
+ The name and instruction fields MAY be empty strings, the client MUST
+ be prepared to handle this correctly. The prompt field(s) MUST NOT
+ be empty strings.
+
+ The language tag SHOULD describe the language used in the textual
+ fields. If the server does not know the language used, or if
+ multiple languages are used, the language tag MUST be the empty
+ string.
+
+ The num-prompts field may be `0', in which case there will be no
+ prompt/echo fields in the message, but the client SHOULD still
+ display the name and instruction fields (as described below).
+
+3.3 User Interface
+
+ Upon receiving a request message, the client SHOULD prompt the user
+ as follows:
+
+ A command line interface (CLI) client SHOULD print the name and
+ instruction (if non-empty), adding newlines. Then for each prompt in
+ turn, the client SHOULD display the prompt and read the user input.
+
+ A graphical user interface (GUI) client has many choices on how to
+ prompt the user. One possibility is to use the name field (possibly
+
+
+
+F. Cusack, M. Forssen Expires November 1, 2003 [Page 5]
+
+Internet Draft SSH Generic Interactive Authentication May 1, 2003
+
+
+ prefixed with the application's name) as the title of a dialog window
+ in which the prompt(s) are presented. In that dialog window, the
+ instruction field would be a text message, and the prompts would be
+ labels for text entry fields. All fields SHOULD be presented to the
+ user, for example an implementation SHOULD NOT discard the name field
+ because its windows lack titles; it SHOULD instead find another way
+ to display this information. If prompts are presented in a dialog
+ window, then the client SHOULD NOT present each prompt in a separate
+ window.
+
+ All clients MUST properly handle an instruction field with embedded
+ newlines. They SHOULD also be able to display at least 30 characters
+ for the name and prompts. If the server presents names or prompts
+ longer than 30 characters, the client MAY truncate these fields to
+ the length it can display. If the client does truncate any fields,
+ there MUST be an obvious indication that such truncation has occured.
+ The instruction field SHOULD NOT be truncated.
+
+ Clients SHOULD use control character filtering as discussed in
+ [SSH-ARCH] to avoid attacks by including terminal control characters
+ in the fields to be displayed.
+
+ For each prompt, the corresponding echo field indicates whether or
+ not the user input should be echoed as characters are typed. Clients
+ SHOULD correctly echo/mask user input for each prompt independently
+ of other prompts in the request message. If a client does not honor
+ the echo field for whatever reason, then the client MUST err on the
+ side of masking input. A GUI client might like to have a checkbox
+ toggling echo/mask. Clients SHOULD NOT add any additional characters
+ to the prompt such as ": " (colon-space); the server is responsible
+ for supplying all text to be displayed to the user. Clients MUST
+ also accept empty responses from the user and pass them on as empty
+ strings.
+
+3.4 Information Responses
+
+ After obtaining the requested information from the user, the client
+ MUST respond with a SSH_MSG_USERAUTH_INFO_RESPONSE message.
+
+ The format of the SSH_MSG_USERAUTH_INFO_RESPONSE message is as
+ follows:
+
+ byte SSH_MSG_USERAUTH_INFO_RESPONSE
+ int num-responses
+ string response[1] (ISO-10646 UTF-8)
+ ...
+ string response[num-responses] (ISO-10646 UTF-8)
+
+
+
+
+F. Cusack, M. Forssen Expires November 1, 2003 [Page 6]
+
+Internet Draft SSH Generic Interactive Authentication May 1, 2003
+
+
+ Note that the responses are encoded in ISO-10646 UTF-8. It is up to
+ the server how it interprets the responses and validates them.
+ However, if the client reads the responses in some other encoding
+ (e.g., ISO 8859-1), it MUST convert the responses to ISO-10646 UTF-8
+ before transmitting.
+
+ If the num-responses field does not match the num-prompts field in
+ the request message, the server MUST send a failure message.
+
+ In the case that the server sends a `0' num-prompts field in the
+ request message, the client MUST send a response message with a `0'
+ num-responses field.
+
+ The responses MUST be ordered as the prompts were ordered. That is,
+ response[n] MUST be the answer to prompt[n].
+
+ After receiving the response, the server MUST send either a
+ SSH_MSG_USERAUTH_SUCCESS, SSH_MSG_USERAUTH_FAILURE, or another
+ SSH_MSG_USERAUTH_INFO_REQUEST message.
+
+ If the server fails to authenticate the user (through the underlying
+ authentication mechanism(s)), it SHOULD NOT send another request
+ message(s) in an attempt to obtain new authentication data, instead
+ it SHOULD send a failure message. The only time the server should
+ send multiple request messages is if additional authentication data
+ is needed (i.e., because there are multiple underlying authentication
+ mechanisms that must be used to authenticate the user).
+
+ If the server intends to respond with a failure message, it MAY delay
+ for an implementation-dependent time before sending to the client.
+ It is suspected that implementations are likely to make the time
+ delay a configurable, a suggested default is 2 seconds.
+
+4. Authentication Examples
+
+ Here are two example exchanges between a client and server. The
+ first is an example of challenge/response with a handheld token.
+ This is an authentication that is not otherwise possible with other
+ authentication methods.
+
+ C: byte SSH_MSG_USERAUTH_REQUEST
+ C: string "user23"
+ C: string "ssh-userauth"
+ C: string "keyboard-interactive"
+ C: string ""
+ C: string ""
+
+
+
+
+
+F. Cusack, M. Forssen Expires November 1, 2003 [Page 7]
+
+Internet Draft SSH Generic Interactive Authentication May 1, 2003
+
+
+ S: byte SSH_MSG_USERAUTH_INFO_REQUEST
+ S: string "CRYPTOCard Authentication"
+ S: string "The challenge is '14315716'"
+ S: string "en-US"
+ S: int 1
+ S: string "Response: "
+ S: boolean TRUE
+
+ [Client prompts user for password]
+
+ C: byte SSH_MSG_USERAUTH_INFO_RESPONSE
+ C: int 1
+ C: string "6d757575"
+
+ S: byte SSH_MSG_USERAUTH_SUCCESS
+
+ The second example is of a standard password authentication, in
+ this case the user's password is expired.
+
+ C: byte SSH_MSG_USERAUTH_REQUEST
+ C: string "user23"
+ C: string "ssh-userauth"
+ C: string "keyboard-interactive"
+ C: string "en-US"
+ C: string ""
+
+ S: byte SSH_MSG_USERAUTH_INFO_REQUEST
+ S: string "Password Authentication"
+ S: string ""
+ S: string "en-US"
+ S: int 1
+ S: string "Password: "
+ S: boolean FALSE
+
+ [Client prompts user for password]
+
+ C: byte SSH_MSG_USERAUTH_INFO_RESPONSE
+ C: int 1
+ C: string "password"
+
+
+
+
+
+
+
+
+
+
+
+
+F. Cusack, M. Forssen Expires November 1, 2003 [Page 8]
+
+Internet Draft SSH Generic Interactive Authentication May 1, 2003
+
+
+ S: byte SSH_MSG_USERAUTH_INFO_REQUEST
+ S: string "Password Expired"
+ S: string "Your password has expired."
+ S: string "en-US"
+ S: int 2
+ S: string "Enter new password: "
+ S: boolean FALSE
+ S: string "Enter it again: "
+ S: boolean FALSE
+
+ [Client prompts user for new password]
+
+ C: byte SSH_MSG_USERAUTH_INFO_RESPONSE
+ C: int 2
+ C: string "newpass"
+ C: string "newpass"
+
+ S: byte SSH_MSG_USERAUTH_INFO_REQUEST
+ S: string "Password changed"
+ S: string "Password successfully changed for user23."
+ S: string "en-US"
+ S: int 0
+
+ [Client displays message to user]
+
+ C: byte SSH_MSG_USERAUTH_INFO_RESPONSE
+ C: int 0
+
+ S: byte SSH_MSG_USERAUTH_SUCCESS
+
+5. IANA Considerations
+
+ The userauth type "keyboard-interactive" is used for this
+ authentication method.
+
+ The following method-specific constants are used with this
+ authentication method:
+
+ SSH_MSG_USERAUTH_INFO_REQUEST 60
+ SSH_MSG_USERAUTH_INFO_RESPONSE 61
+
+6. Security Considerations
+
+ The authentication protocol, and this authentication method, depends
+ on the security of the underlying SSH transport layer. Without the
+ confidentiality provided therein, any authentication data passed with
+ this method is subject to interception.
+
+
+
+
+F. Cusack, M. Forssen Expires November 1, 2003 [Page 9]
+
+Internet Draft SSH Generic Interactive Authentication May 1, 2003
+
+
+ The number of client-server exchanges required to complete an
+ authentication using this method may be variable. It is possible
+ that an observer may gain valuable information simply by counting
+ that number. For example, an observer may guess that a user's
+ password has expired, and with further observation may be able to
+ determine the frequency of a site's password expiration policy.
+
+7. References
+
+7.1 Normative References
+
+
+ [RFC-2119] Bradner, S., "Key words for use in RFCs to Indicate
+ Requirement Level", BCP 14, RFC 2119, March 1997.
+
+
+ [RFC-2279] Yergeau, F., "UTF-8, a transformation format of
+ Unicode and ISO 10646", RFC 2279, October 1996.
+
+
+ [RFC-3066] Alvestrand, H., "Tags for the Identification of
+ Languages", BCP 47, RFC 3066, January 2001.
+
+
+ [SSH-ARCH] Ylonen, T., Kivinen, T, Saarinen, M., Rinne, T., and
+ Lehtinen, S., "SSH Protocol Architecture", work in
+ progress, draft-ietf-secsh-architecture-13.txt,
+ September, 2002.
+
+
+ [SSH-CONNECT] Ylonen, T., Kivinen, T, Saarinen, M., Rinne, T., and
+ Lehtinen, S., "SSH Connection Protocol", work in
+ progress, draft-ietf-secsh-connect-16.txt, September,
+ 2002.
+
+
+ [SSH-TRANS] Ylonen, T., Kivinen, T, Saarinen, M., Rinne, T., and
+ Lehtinen, S., "SSH Transport Layer Protocol", work in
+ progress, draft-ietf-secsh-transport-15.txt,
+ September, 2002.
+
+
+ [SSH-USERAUTH] Ylonen, T., Kivinen, T, Saarinen, M., Rinne, T., and
+ Lehtinen, S., "SSH Authentication Protocol", work in
+ progress, draft-ietf-secsh-userauth-16.txt,
+ September, 2002.
+
+
+
+
+
+F. Cusack, M. Forssen Expires November 1, 2003 [Page 10]
+
+Internet Draft SSH Generic Interactive Authentication May 1, 2003
+
+
+7.2 Informative References
+
+
+ [PAM] Samar, V., Schemers, R., "Unified Login With
+ Pluggable Authentication Modules (PAM)", OSF RFC
+ 86.0, October 1995
+
+8. Author's Addresses
+
+ Frank Cusack
+ Google, Inc.
+ 2400 Bayshore Parkway
+ Mountain View, CA 94043
+ Email: frank@google.com
+
+ Martin Forssen
+ Appgate AB
+ Stora Badhusgatan 18-20
+ SE-411 21 Gothenburg
+ SWEDEN
+ Email: maf@appgate.com
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+F. Cusack, M. Forssen Expires November 1, 2003 [Page 11]
+ \ No newline at end of file
diff --git a/doc/draft-ietf-secsh-break-00.txt b/doc/draft-ietf-secsh-break-00.txt
new file mode 100644
index 00000000..f10763ba
--- /dev/null
+++ b/doc/draft-ietf-secsh-break-00.txt
@@ -0,0 +1,394 @@
+
+
+
+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
new file mode 100644
index 00000000..5a8a43e0
--- /dev/null
+++ b/doc/draft-ietf-secsh-connect-17.txt
@@ -0,0 +1,1232 @@
+
+
+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
new file mode 100644
index 00000000..ee6b2fb8
--- /dev/null
+++ b/doc/draft-ietf-secsh-dh-group-exchange-04.txt
@@ -0,0 +1,451 @@
+
+
+
+
+
+
+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
new file mode 100644
index 00000000..7667a5e8
--- /dev/null
+++ b/doc/draft-ietf-secsh-dns-04.txt
@@ -0,0 +1,616 @@
+
+
+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
new file mode 100644
index 00000000..45e979e8
--- /dev/null
+++ b/doc/draft-ietf-secsh-filexfer-02.txt
@@ -0,0 +1,1626 @@
+
+
+Network Working Group T. Ylonen
+Internet-Draft S. Lehtinen
+Expires: April 1, 2002 SSH Communications Security Corp
+ October 2001
+
+
+ SSH File Transfer Protocol
+ draft-ietf-secsh-filexfer-02.txt
+
+Status of this Memo
+
+ This document is an Internet-Draft and is in full conformance with
+ all provisions of Section 10 of RFC2026.
+
+ Internet-Drafts are working documents of the Internet Engineering
+ Task Force (IETF), its areas, and its working groups. Note that
+ other groups may also distribute working documents as Internet-
+ Drafts.
+
+ Internet-Drafts are draft documents valid for a maximum of six months
+ and may be updated, replaced, or obsoleted by other documents at any
+ time. It is inappropriate to use Internet-Drafts as reference
+ material or to cite them other than as "work in progress."
+
+ The list of current Internet-Drafts can be accessed at http://
+ www.ietf.org/ietf/1id-abstracts.txt.
+
+ The list of Internet-Draft Shadow Directories can be accessed at
+ http://www.ietf.org/shadow.html.
+
+ This Internet-Draft will expire on April 1, 2002.
+
+Copyright Notice
+
+ Copyright (C) The Internet Society (2001). All Rights Reserved.
+
+Abstract
+
+ The SSH File Transfer Protocol provides secure file transfer
+ functionality over any reliable data stream. It is the standard file
+ transfer protocol for use with the SSH2 protocol. This document
+ describes the file transfer protocol and its interface to the SSH2
+ protocol suite.
+
+
+
+
+
+
+
+
+
+Ylonen & Lehtinen Expires April 1, 2002 [Page 1]
+
+Internet-Draft SSH File Transfer Protocol October 2001
+
+
+Table of Contents
+
+ 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
+ 2. Use with the SSH Connection Protocol . . . . . . . . . . . . 4
+ 3. General Packet Format . . . . . . . . . . . . . . . . . . . 5
+ 4. Protocol Initialization . . . . . . . . . . . . . . . . . . 7
+ 5. File Attributes . . . . . . . . . . . . . . . . . . . . . . 8
+ 6. Requests From the Client to the Server . . . . . . . . . . . 10
+ 6.1 Request Synchronization and Reordering . . . . . . . . . . . 10
+ 6.2 File Names . . . . . . . . . . . . . . . . . . . . . . . . . 11
+ 6.3 Opening, Creating, and Closing Files . . . . . . . . . . . . 11
+ 6.4 Reading and Writing . . . . . . . . . . . . . . . . . . . . 13
+ 6.5 Removing and Renaming Files . . . . . . . . . . . . . . . . 14
+ 6.6 Creating and Deleting Directories . . . . . . . . . . . . . 15
+ 6.7 Scanning Directories . . . . . . . . . . . . . . . . . . . . 15
+ 6.8 Retrieving File Attributes . . . . . . . . . . . . . . . . . 16
+ 6.9 Setting File Attributes . . . . . . . . . . . . . . . . . . 17
+ 6.10 Dealing with Symbolic links . . . . . . . . . . . . . . . . 18
+ 6.11 Canonicalizing the Server-Side Path Name . . . . . . . . . . 18
+ 7. Responses from the Server to the Client . . . . . . . . . . 20
+ 8. Vendor-Specific Extensions . . . . . . . . . . . . . . . . . 24
+ 9. Security Considerations . . . . . . . . . . . . . . . . . . 25
+ 10. Changes from previous protocol versions . . . . . . . . . . 26
+ 10.1 Changes between versions 3 and 2 . . . . . . . . . . . . . . 26
+ 10.2 Changes between versions 2 and 1 . . . . . . . . . . . . . . 26
+ 10.3 Changes between versions 1 and 0 . . . . . . . . . . . . . . 26
+ 11. Trademark Issues . . . . . . . . . . . . . . . . . . . . . . 27
+ References . . . . . . . . . . . . . . . . . . . . . . . . . 28
+ Authors' Addresses . . . . . . . . . . . . . . . . . . . . . 28
+ Full Copyright Statement . . . . . . . . . . . . . . . . . . 29
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Ylonen & Lehtinen Expires April 1, 2002 [Page 2]
+
+Internet-Draft SSH File Transfer Protocol October 2001
+
+
+1. Introduction
+
+ This protocol provides secure file transfer (and more generally file
+ system access) functionality over a reliable data stream, such as a
+ channel in the SSH2 protocol [3].
+
+ This protocol is designed so that it could be used to implement a
+ secure remote file system service, as well as a secure file transfer
+ service.
+
+ This protocol assumes that it runs over a secure channel, and that
+ the server has already authenticated the user at the client end, and
+ that the identity of the client user is externally available to the
+ server implementation.
+
+ In general, this protocol follows a simple request-response model.
+ Each request and response contains a sequence number and multiple
+ requests may be pending simultaneously. There are a relatively large
+ number of different request messages, but a small number of possible
+ response messages. Each request has one or more response messages
+ that may be returned in result (e.g., a read either returns data or
+ reports error status).
+
+ The packet format descriptions in this specification follow the
+ notation presented in the secsh architecture draft.[3].
+
+ Even though this protocol is described in the context of the SSH2
+ protocol, this protocol is general and independent of the rest of the
+ SSH2 protocol suite. It could be used in a number of different
+ applications, such as secure file transfer over TLS RFC 2246 [1] and
+ transfer of management information in VPN applications.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Ylonen & Lehtinen Expires April 1, 2002 [Page 3]
+
+Internet-Draft SSH File Transfer Protocol October 2001
+
+
+2. Use with the SSH Connection Protocol
+
+ When used with the SSH2 Protocol suite, this protocol is intended to
+ be used from the SSH Connection Protocol [5] as a subsystem, as
+ described in section ``Starting a Shell or a Command''. The
+ subsystem name used with this protocol is "sftp".
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Ylonen & Lehtinen Expires April 1, 2002 [Page 4]
+
+Internet-Draft SSH File Transfer Protocol October 2001
+
+
+3. General Packet Format
+
+ All packets transmitted over the secure connection are of the
+ following format:
+
+ uint32 length
+ byte type
+ byte[length - 1] data payload
+
+ That is, they are just data preceded by 32-bit length and 8-bit type
+ fields. The `length' is the length of the data area, and does not
+ include the `length' field itself. The format and interpretation of
+ the data area depends on the packet type.
+
+ All packet descriptions below only specify the packet type and the
+ data that goes into the data field. Thus, they should be prefixed by
+ the `length' and `type' fields.
+
+ The maximum size of a packet is in practice determined by the client
+ (the maximum size of read or write requests that it sends, plus a few
+ bytes of packet overhead). All servers SHOULD support packets of at
+ least 34000 bytes (where the packet size refers to the full length,
+ including the header above). This should allow for reads and writes
+ of at most 32768 bytes.
+
+ There is no limit on the number of outstanding (non-acknowledged)
+ requests that the client may send to the server. In practice this is
+ limited by the buffering available on the data stream and the queuing
+ performed by the server. If the server's queues are full, it should
+ not read any more data from the stream, and flow control will prevent
+ the client from sending more requests. Note, however, that while
+ there is no restriction on the protocol level, the client's API may
+ provide a limit in order to prevent infinite queuing of outgoing
+ requests at the client.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Ylonen & Lehtinen Expires April 1, 2002 [Page 5]
+
+Internet-Draft SSH File Transfer Protocol October 2001
+
+
+ The following values are defined for packet types.
+
+ #define SSH_FXP_INIT 1
+ #define SSH_FXP_VERSION 2
+ #define SSH_FXP_OPEN 3
+ #define SSH_FXP_CLOSE 4
+ #define SSH_FXP_READ 5
+ #define SSH_FXP_WRITE 6
+ #define SSH_FXP_LSTAT 7
+ #define SSH_FXP_FSTAT 8
+ #define SSH_FXP_SETSTAT 9
+ #define SSH_FXP_FSETSTAT 10
+ #define SSH_FXP_OPENDIR 11
+ #define SSH_FXP_READDIR 12
+ #define SSH_FXP_REMOVE 13
+ #define SSH_FXP_MKDIR 14
+ #define SSH_FXP_RMDIR 15
+ #define SSH_FXP_REALPATH 16
+ #define SSH_FXP_STAT 17
+ #define SSH_FXP_RENAME 18
+ #define SSH_FXP_READLINK 19
+ #define SSH_FXP_SYMLINK 20
+ #define SSH_FXP_STATUS 101
+ #define SSH_FXP_HANDLE 102
+ #define SSH_FXP_DATA 103
+ #define SSH_FXP_NAME 104
+ #define SSH_FXP_ATTRS 105
+ #define SSH_FXP_EXTENDED 200
+ #define SSH_FXP_EXTENDED_REPLY 201
+
+ Additional packet types should only be defined if the protocol
+ version number (see Section ``Protocol Initialization'') is
+ incremented, and their use MUST be negotiated using the version
+ number. However, the SSH_FXP_EXTENDED and SSH_FXP_EXTENDED_REPLY
+ packets can be used to implement vendor-specific extensions. See
+ Section ``Vendor-Specific-Extensions'' for more details.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Ylonen & Lehtinen Expires April 1, 2002 [Page 6]
+
+Internet-Draft SSH File Transfer Protocol October 2001
+
+
+4. Protocol Initialization
+
+ When the file transfer protocol starts, it first sends a SSH_FXP_INIT
+ (including its version number) packet to the server. The server
+ responds with a SSH_FXP_VERSION packet, supplying the lowest of its
+ own and the client's version number. Both parties should from then
+ on adhere to particular version of the protocol.
+
+ The SSH_FXP_INIT packet (from client to server) has the following
+ data:
+
+ uint32 version
+ <extension data>
+
+ The SSH_FXP_VERSION packet (from server to client) has the following
+ data:
+
+ uint32 version
+ <extension data>
+
+ The version number of the protocol specified in this document is 3.
+ The version number should be incremented for each incompatible
+ revision of this protocol.
+
+ The extension data in the above packets may be empty, or may be a
+ sequence of
+
+ string extension_name
+ string extension_data
+
+ pairs (both strings MUST always be present if one is, but the
+ `extension_data' string may be of zero length). If present, these
+ strings indicate extensions to the baseline protocol. The
+ `extension_name' field(s) identify the name of the extension. The
+ name should be of the form "name@domain", where the domain is the DNS
+ domain name of the organization defining the extension. Additional
+ names that are not of this format may be defined later by the IETF.
+ Implementations MUST silently ignore any extensions whose name they
+ do not recognize.
+
+
+
+
+
+
+
+
+
+
+
+
+Ylonen & Lehtinen Expires April 1, 2002 [Page 7]
+
+Internet-Draft SSH File Transfer Protocol October 2001
+
+
+5. File Attributes
+
+ A new compound data type is defined for encoding file attributes. It
+ is basically just a combination of elementary types, but is defined
+ once because of the non-trivial description of the fields and to
+ ensure maintainability.
+
+ The same encoding is used both when returning file attributes from
+ the server and when sending file attributes to the server. When
+ sending it to the server, the flags field specifies which attributes
+ are included, and the server will use default values for the
+ remaining attributes (or will not modify the values of remaining
+ attributes). When receiving attributes from the server, the flags
+ specify which attributes are included in the returned data. The
+ server normally returns all attributes it knows about.
+
+ uint32 flags
+ uint64 size present only if flag SSH_FILEXFER_ATTR_SIZE
+ uint32 uid present only if flag SSH_FILEXFER_ATTR_UIDGID
+ uint32 gid present only if flag SSH_FILEXFER_ATTR_UIDGID
+ uint32 permissions present only if flag SSH_FILEXFER_ATTR_PERMISSIONS
+ uint32 atime present only if flag SSH_FILEXFER_ACMODTIME
+ uint32 mtime present only if flag SSH_FILEXFER_ACMODTIME
+ uint32 extended_count present only if flag SSH_FILEXFER_ATTR_EXTENDED
+ string extended_type
+ string extended_data
+ ... more extended data (extended_type - extended_data pairs),
+ so that number of pairs equals extended_count
+
+ The `flags' specify which of the fields are present. Those fields
+ for which the corresponding flag is not set are not present (not
+ included in the packet). New flags can only be added by incrementing
+ the protocol version number (or by using the extension mechanism
+ described below).
+
+ The `size' field specifies the size of the file in bytes.
+
+ The `uid' and `gid' fields contain numeric Unix-like user and group
+ identifiers, respectively.
+
+ The `permissions' field contains a bit mask of file permissions as
+ defined by posix [1].
+
+ The `atime' and `mtime' contain the access and modification times of
+ the files, respectively. They are represented as seconds from Jan 1,
+ 1970 in UTC.
+
+ The SSH_FILEXFER_ATTR_EXTENDED flag provides a general extension
+
+
+
+Ylonen & Lehtinen Expires April 1, 2002 [Page 8]
+
+Internet-Draft SSH File Transfer Protocol October 2001
+
+
+ mechanism for vendor-specific extensions. If the flag is specified,
+ then the `extended_count' field is present. It specifies the number
+ of extended_type-extended_data pairs that follow. Each of these
+ pairs specifies an extended attribute. For each of the attributes,
+ the extended_type field should be a string of the format
+ "name@domain", where "domain" is a valid, registered domain name and
+ "name" identifies the method. The IETF may later standardize certain
+ names that deviate from this format (e.g., that do not contain the
+ "@" sign). The interpretation of `extended_data' depends on the
+ type. Implementations SHOULD ignore extended data fields that they
+ do not understand.
+
+ Additional fields can be added to the attributes by either defining
+ additional bits to the flags field to indicate their presence, or by
+ defining extended attributes for them. The extended attributes
+ mechanism is recommended for most purposes; additional flags bits
+ should only be defined by an IETF standards action that also
+ increments the protocol version number. The use of such new fields
+ MUST be negotiated by the version number in the protocol exchange.
+ It is a protocol error if a packet with unsupported protocol bits is
+ received.
+
+ The flags bits are defined to have the following values:
+
+ #define SSH_FILEXFER_ATTR_SIZE 0x00000001
+ #define SSH_FILEXFER_ATTR_UIDGID 0x00000002
+ #define SSH_FILEXFER_ATTR_PERMISSIONS 0x00000004
+ #define SSH_FILEXFER_ATTR_ACMODTIME 0x00000008
+ #define SSH_FILEXFER_ATTR_EXTENDED 0x80000000
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Ylonen & Lehtinen Expires April 1, 2002 [Page 9]
+
+Internet-Draft SSH File Transfer Protocol October 2001
+
+
+6. Requests From the Client to the Server
+
+ Requests from the client to the server represent the various file
+ system operations. Each request begins with an `id' field, which is
+ a 32-bit identifier identifying the request (selected by the client).
+ The same identifier will be returned in the response to the request.
+ One possible implementation of it is a monotonically increasing
+ request sequence number (modulo 2^32).
+
+ Many operations in the protocol operate on open files. The
+ SSH_FXP_OPEN request can return a file handle (which is an opaque
+ variable-length string) which may be used to access the file later
+ (e.g. in a read operation). The client MUST NOT send requests the
+ server with bogus or closed handles. However, the server MUST
+ perform adequate checks on the handle in order to avoid security
+ risks due to fabricated handles.
+
+ This design allows either stateful and stateless server
+ implementation, as well as an implementation which caches state
+ between requests but may also flush it. The contents of the file
+ handle string are entirely up to the server and its design. The
+ client should not modify or attempt to interpret the file handle
+ strings.
+
+ The file handle strings MUST NOT be longer than 256 bytes.
+
+6.1 Request Synchronization and Reordering
+
+ The protocol and implementations MUST process requests relating to
+ the same file in the order in which they are received. In other
+ words, if an application submits multiple requests to the server, the
+ results in the responses will be the same as if it had sent the
+ requests one at a time and waited for the response in each case. For
+ example, the server may process non-overlapping read/write requests
+ to the same file in parallel, but overlapping reads and writes cannot
+ be reordered or parallelized. However, there are no ordering
+ restrictions on the server for processing requests from two different
+ file transfer connections. The server may interleave and parallelize
+ them at will.
+
+ There are no restrictions on the order in which responses to
+ outstanding requests are delivered to the client, except that the
+ server must ensure fairness in the sense that processing of no
+ request will be indefinitely delayed even if the client is sending
+ other requests so that there are multiple outstanding requests all
+ the time.
+
+
+
+
+
+Ylonen & Lehtinen Expires April 1, 2002 [Page 10]
+
+Internet-Draft SSH File Transfer Protocol October 2001
+
+
+6.2 File Names
+
+ This protocol represents file names as strings. File names are
+ assumed to use the slash ('/') character as a directory separator.
+
+ File names starting with a slash are "absolute", and are relative to
+ the root of the file system. Names starting with any other character
+ are relative to the user's default directory (home directory). Note
+ that identifying the user is assumed to take place outside of this
+ protocol.
+
+ Servers SHOULD interpret a path name component ".." as referring to
+ the parent directory, and "." as referring to the current directory.
+ If the server implementation limits access to certain parts of the
+ file system, it must be extra careful in parsing file names when
+ enforcing such restrictions. There have been numerous reported
+ security bugs where a ".." in a path name has allowed access outside
+ the intended area.
+
+ An empty path name is valid, and it refers to the user's default
+ directory (usually the user's home directory).
+
+ Otherwise, no syntax is defined for file names by this specification.
+ Clients should not make any other assumptions; however, they can
+ splice path name components returned by SSH_FXP_READDIR together
+ using a slash ('/') as the separator, and that will work as expected.
+
+ It is understood that the lack of well-defined semantics for file
+ names may cause interoperability problems between clients and servers
+ using radically different operating systems. However, this approach
+ is known to work acceptably with most systems, and alternative
+ approaches that e.g. treat file names as sequences of structured
+ components are quite complicated.
+
+6.3 Opening, Creating, and Closing Files
+
+ Files are opened and created using the SSH_FXP_OPEN message, whose
+ data part is as follows:
+
+ uint32 id
+ string filename
+ uint32 pflags
+ ATTRS attrs
+
+ The `id' field is the request identifier as for all requests.
+
+ The `filename' field specifies the file name. See Section ``File
+ Names'' for more information.
+
+
+
+Ylonen & Lehtinen Expires April 1, 2002 [Page 11]
+
+Internet-Draft SSH File Transfer Protocol October 2001
+
+
+ The `pflags' field is a bitmask. The following bits have been
+ defined.
+
+ #define SSH_FXF_READ 0x00000001
+ #define SSH_FXF_WRITE 0x00000002
+ #define SSH_FXF_APPEND 0x00000004
+ #define SSH_FXF_CREAT 0x00000008
+ #define SSH_FXF_TRUNC 0x00000010
+ #define SSH_FXF_EXCL 0x00000020
+
+ These have the following meanings:
+
+ SSH_FXF_READ
+ Open the file for reading.
+
+ SSH_FXF_WRITE
+ Open the file for writing. If both this and SSH_FXF_READ are
+ specified, the file is opened for both reading and writing.
+
+ SSH_FXF_APPEND
+ Force all writes to append data at the end of the file.
+
+ SSH_FXF_CREAT
+ If this flag is specified, then a new file will be created if one
+ does not already exist (if O_TRUNC is specified, the new file will
+ be truncated to zero length if it previously exists).
+
+ SSH_FXF_TRUNC
+ Forces an existing file with the same name to be truncated to zero
+ length when creating a file by specifying SSH_FXF_CREAT.
+ SSH_FXF_CREAT MUST also be specified if this flag is used.
+
+ SSH_FXF_EXCL
+ Causes the request to fail if the named file already exists.
+ SSH_FXF_CREAT MUST also be specified if this flag is used.
+
+ The `attrs' field specifies the initial attributes for the file.
+ Default values will be used for those attributes that are not
+ specified. See Section ``File Attributes'' for more information.
+
+ Regardless the server operating system, the file will always be
+ opened in "binary" mode (i.e., no translations between different
+ character sets and newline encodings).
+
+ The response to this message will be either SSH_FXP_HANDLE (if the
+ operation is successful) or SSH_FXP_STATUS (if the operation fails).
+
+
+
+
+
+Ylonen & Lehtinen Expires April 1, 2002 [Page 12]
+
+Internet-Draft SSH File Transfer Protocol October 2001
+
+
+ A file is closed by using the SSH_FXP_CLOSE request. Its data field
+ has the following format:
+
+ uint32 id
+ string handle
+
+ where `id' is the request identifier, and `handle' is a handle
+ previously returned in the response to SSH_FXP_OPEN or
+ SSH_FXP_OPENDIR. The handle becomes invalid immediately after this
+ request has been sent.
+
+ The response to this request will be a SSH_FXP_STATUS message. One
+ should note that on some server platforms even a close can fail.
+ This can happen e.g. if the server operating system caches writes,
+ and an error occurs while flushing cached writes during the close.
+
+6.4 Reading and Writing
+
+ Once a file has been opened, it can be read using the SSH_FXP_READ
+ message, which has the following format:
+
+ uint32 id
+ string handle
+ uint64 offset
+ uint32 len
+
+ where `id' is the request identifier, `handle' is an open file handle
+ returned by SSH_FXP_OPEN, `offset' is the offset (in bytes) relative
+ to the beginning of the file from where to start reading, and `len'
+ is the maximum number of bytes to read.
+
+ In response to this request, the server will read as many bytes as it
+ can from the file (up to `len'), and return them in a SSH_FXP_DATA
+ message. If an error occurs or EOF is encountered before reading any
+ data, the server will respond with SSH_FXP_STATUS. For normal disk
+ files, it is guaranteed that this will read the specified number of
+ bytes, or up to end of file. For e.g. device files this may return
+ fewer bytes than requested.
+
+ Writing to a file is achieved using the SSH_FXP_WRITE message, which
+ has the following format:
+
+ uint32 id
+ string handle
+ uint64 offset
+ string data
+
+ where `id' is a request identifier, `handle' is a file handle
+
+
+
+Ylonen & Lehtinen Expires April 1, 2002 [Page 13]
+
+Internet-Draft SSH File Transfer Protocol October 2001
+
+
+ returned by SSH_FXP_OPEN, `offset' is the offset (in bytes) from the
+ beginning of the file where to start writing, and `data' is the data
+ to be written.
+
+ The write will extend the file if writing beyond the end of the file.
+ It is legal to write way beyond the end of the file; the semantics
+ are to write zeroes from the end of the file to the specified offset
+ and then the data. On most operating systems, such writes do not
+ allocate disk space but instead leave "holes" in the file.
+
+ The server responds to a write request with a SSH_FXP_STATUS message.
+
+6.5 Removing and Renaming Files
+
+ Files can be removed using the SSH_FXP_REMOVE message. It has the
+ following format:
+
+ uint32 id
+ string filename
+
+ where `id' is the request identifier and `filename' is the name of
+ the file to be removed. See Section ``File Names'' for more
+ information. This request cannot be used to remove directories.
+
+ The server will respond to this request with a SSH_FXP_STATUS
+ message.
+
+ Files (and directories) can be renamed using the SSH_FXP_RENAME
+ message. Its data is as follows:
+
+ uint32 id
+ string oldpath
+ string newpath
+
+ where `id' is the request identifier, `oldpath' is the name of an
+ existing file or directory, and `newpath' is the new name for the
+ file or directory. It is an error if there already exists a file
+ with the name specified by newpath. The server may also fail rename
+ requests in other situations, for example if `oldpath' and `newpath'
+ point to different file systems on the server.
+
+ The server will respond to this request with a SSH_FXP_STATUS
+ message.
+
+
+
+
+
+
+
+
+Ylonen & Lehtinen Expires April 1, 2002 [Page 14]
+
+Internet-Draft SSH File Transfer Protocol October 2001
+
+
+6.6 Creating and Deleting Directories
+
+ New directories can be created using the SSH_FXP_MKDIR request. It
+ has the following format:
+
+ uint32 id
+ string path
+ ATTRS attrs
+
+ where `id' is the request identifier, `path' and `attrs' specifies
+ the modifications to be made to its attributes. See Section ``File
+ Names'' for more information on file names. Attributes are discussed
+ in more detail in Section ``File Attributes''. specifies the
+ directory to be created. An error will be returned if a file or
+ directory with the specified path already exists. The server will
+ respond to this request with a SSH_FXP_STATUS message.
+
+ Directories can be removed using the SSH_FXP_RMDIR request, which
+ has the following format:
+
+ uint32 id
+ string path
+
+ where `id' is the request identifier, and `path' specifies the
+ directory to be removed. See Section ``File Names'' for more
+ information on file names. An error will be returned if no directory
+ with the specified path exists, or if the specified directory is not
+ empty, or if the path specified a file system object other than a
+ directory. The server responds to this request with a SSH_FXP_STATUS
+ message.
+
+6.7 Scanning Directories
+
+ The files in a directory can be listed using the SSH_FXP_OPENDIR and
+ SSH_FXP_READDIR requests. Each SSH_FXP_READDIR request returns one
+ or more file names with full file attributes for each file. The
+ client should call SSH_FXP_READDIR repeatedly until it has found the
+ file it is looking for or until the server responds with a
+ SSH_FXP_STATUS message indicating an error (normally SSH_FX_EOF if
+ there are no more files in the directory). The client should then
+ close the handle using the SSH_FXP_CLOSE request.
+
+
+
+
+
+
+
+
+
+
+Ylonen & Lehtinen Expires April 1, 2002 [Page 15]
+
+Internet-Draft SSH File Transfer Protocol October 2001
+
+
+ The SSH_FXP_OPENDIR opens a directory for reading. It has the
+ following format:
+
+ uint32 id
+ string path
+
+ where `id' is the request identifier and `path' is the path name of
+ the directory to be listed (without any trailing slash). See Section
+ ``File Names'' for more information on file names. This will return
+ an error if the path does not specify a directory or if the directory
+ is not readable. The server will respond to this request with either
+ a SSH_FXP_HANDLE or a SSH_FXP_STATUS message.
+
+ Once the directory has been successfully opened, files (and
+ directories) contained in it can be listed using SSH_FXP_READDIR
+ requests. These are of the format
+
+ uint32 id
+ string handle
+
+ where `id' is the request identifier, and `handle' is a handle
+ returned by SSH_FXP_OPENDIR. (It is a protocol error to attempt to
+ use an ordinary file handle returned by SSH_FXP_OPEN.)
+
+ The server responds to this request with either a SSH_FXP_NAME or a
+ SSH_FXP_STATUS message. One or more names may be returned at a time.
+ Full status information is returned for each name in order to speed
+ up typical directory listings.
+
+ When the client no longer wishes to read more names from the
+ directory, it SHOULD call SSH_FXP_CLOSE for the handle. The handle
+ should be closed regardless of whether an error has occurred or not.
+
+6.8 Retrieving File Attributes
+
+ Very often, file attributes are automatically returned by
+ SSH_FXP_READDIR. However, sometimes there is need to specifically
+ retrieve the attributes for a named file. This can be done using the
+ SSH_FXP_STAT, SSH_FXP_LSTAT and SSH_FXP_FSTAT requests.
+
+ SSH_FXP_STAT and SSH_FXP_LSTAT only differ in that SSH_FXP_STAT
+ follows symbolic links on the server, whereas SSH_FXP_LSTAT does not
+ follow symbolic links. Both have the same format:
+
+ uint32 id
+ string path
+
+ where `id' is the request identifier, and `path' specifies the file
+
+
+
+Ylonen & Lehtinen Expires April 1, 2002 [Page 16]
+
+Internet-Draft SSH File Transfer Protocol October 2001
+
+
+ system object for which status is to be returned. The server
+ responds to this request with either SSH_FXP_ATTRS or SSH_FXP_STATUS.
+
+ SSH_FXP_FSTAT differs from the others in that it returns status
+ information for an open file (identified by the file handle). Its
+ format is as follows:
+
+ uint32 id
+ string handle
+
+ where `id' is the request identifier and `handle' is a file handle
+ returned by SSH_FXP_OPEN. The server responds to this request with
+ SSH_FXP_ATTRS or SSH_FXP_STATUS.
+
+6.9 Setting File Attributes
+
+ File attributes may be modified using the SSH_FXP_SETSTAT and
+ SSH_FXP_FSETSTAT requests. These requests are used for operations
+ such as changing the ownership, permissions or access times, as well
+ as for truncating a file.
+
+ The SSH_FXP_SETSTAT request is of the following format:
+
+ uint32 id
+ string path
+ ATTRS attrs
+
+ where `id' is the request identifier, `path' specifies the file
+ system object (e.g. file or directory) whose attributes are to be
+ modified, and `attrs' specifies the modifications to be made to its
+ attributes. Attributes are discussed in more detail in Section
+ ``File Attributes''.
+
+ An error will be returned if the specified file system object does
+ not exist or the user does not have sufficient rights to modify the
+ specified attributes. The server responds to this request with a
+ SSH_FXP_STATUS message.
+
+ The SSH_FXP_FSETSTAT request modifies the attributes of a file which
+ is already open. It has the following format:
+
+ uint32 id
+ string handle
+ ATTRS attrs
+
+ where `id' is the request identifier, `handle' (MUST be returned by
+ SSH_FXP_OPEN) identifies the file whose attributes are to be
+ modified, and `attrs' specifies the modifications to be made to its
+
+
+
+Ylonen & Lehtinen Expires April 1, 2002 [Page 17]
+
+Internet-Draft SSH File Transfer Protocol October 2001
+
+
+ attributes. Attributes are discussed in more detail in Section
+ ``File Attributes''. The server will respond to this request with
+ SSH_FXP_STATUS.
+
+6.10 Dealing with Symbolic links
+
+ The SSH_FXP_READLINK request may be used to read the target of a
+ symbolic link. It would have a data part as follows:
+
+ uint32 id
+ string path
+
+ where `id' is the request identifier and `path' specifies the path
+ name of the symlink to be read.
+
+ The server will respond with a SSH_FXP_NAME packet containing only
+ one name and a dummy attributes value. The name in the returned
+ packet contains the target of the link. If an error occurs, the
+ server may respond with SSH_FXP_STATUS.
+
+ The SSH_FXP_SYMLINK request will create a symbolic link on the
+ server. It is of the following format
+
+ uint32 id
+ string linkpath
+ string targetpath
+
+ where `id' is the request identifier, `linkpath' specifies the path
+ name of the symlink to be created and `targetpath' specifies the
+ target of the symlink. The server shall respond with a
+ SSH_FXP_STATUS indicating either success (SSH_FX_OK) or an error
+ condition.
+
+6.11 Canonicalizing the Server-Side Path Name
+
+ The SSH_FXP_REALPATH request can be used to have the server
+ canonicalize any given path name to an absolute path. This is useful
+ for converting path names containing ".." components or relative
+ pathnames without a leading slash into absolute paths. The format of
+ the request is as follows:
+
+ uint32 id
+ string path
+
+ where `id' is the request identifier and `path' specifies the path
+ name to be canonicalized. The server will respond with a
+ SSH_FXP_NAME packet containing only one name and a dummy attributes
+ value. The name is the returned packet will be in canonical form.
+
+
+
+Ylonen & Lehtinen Expires April 1, 2002 [Page 18]
+
+Internet-Draft SSH File Transfer Protocol October 2001
+
+
+ If an error occurs, the server may also respond with SSH_FXP_STATUS.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Ylonen & Lehtinen Expires April 1, 2002 [Page 19]
+
+Internet-Draft SSH File Transfer Protocol October 2001
+
+
+7. Responses from the Server to the Client
+
+ The server responds to the client using one of a few response
+ packets. All requests can return a SSH_FXP_STATUS response upon
+ failure. When the operation is successful, any of the responses may
+ be returned (depending on the operation). If no data needs to be
+ returned to the client, the SSH_FXP_STATUS response with SSH_FX_OK
+ status is appropriate. Otherwise, the SSH_FXP_HANDLE message is used
+ to return a file handle (for SSH_FXP_OPEN and SSH_FXP_OPENDIR
+ requests), SSH_FXP_DATA is used to return data from SSH_FXP_READ,
+ SSH_FXP_NAME is used to return one or more file names from a
+ SSH_FXP_READDIR or SSH_FXP_REALPATH request, and SSH_FXP_ATTRS is
+ used to return file attributes from SSH_FXP_STAT, SSH_FXP_LSTAT, and
+ SSH_FXP_FSTAT requests.
+
+ Exactly one response will be returned for each request. Each
+ response packet contains a request identifier which can be used to
+ match each response with the corresponding request. Note that it is
+ legal to have several requests outstanding simultaneously, and the
+ server is allowed to send responses to them in a different order from
+ the order in which the requests were sent (the result of their
+ execution, however, is guaranteed to be as if they had been processed
+ one at a time in the order in which the requests were sent).
+
+ Response packets are of the same general format as request packets.
+ Each response packet begins with the request identifier.
+
+ The format of the data portion of the SSH_FXP_STATUS response is as
+ follows:
+
+ uint32 id
+ uint32 error/status code
+ string error message (ISO-10646 UTF-8 [RFC-2279])
+ string language tag (as defined in [RFC-1766])
+
+ where `id' is the request identifier, and `error/status code'
+ indicates the result of the requested operation. The value SSH_FX_OK
+ indicates success, and all other values indicate failure.
+
+
+
+
+
+
+
+
+
+
+
+
+
+Ylonen & Lehtinen Expires April 1, 2002 [Page 20]
+
+Internet-Draft SSH File Transfer Protocol October 2001
+
+
+ Currently, the following values are defined (other values may be
+ defined by future versions of this protocol):
+
+ #define SSH_FX_OK 0
+ #define SSH_FX_EOF 1
+ #define SSH_FX_NO_SUCH_FILE 2
+ #define SSH_FX_PERMISSION_DENIED 3
+ #define SSH_FX_FAILURE 4
+ #define SSH_FX_BAD_MESSAGE 5
+ #define SSH_FX_NO_CONNECTION 6
+ #define SSH_FX_CONNECTION_LOST 7
+ #define SSH_FX_OP_UNSUPPORTED 8
+
+ SSH_FX_OK
+ Indicates successful completion of the operation.
+
+ SSH_FX_EOF
+ indicates end-of-file condition; for SSH_FX_READ it means that no
+ more data is available in the file, and for SSH_FX_READDIR it
+ indicates that no more files are contained in the directory.
+
+ SSH_FX_NO_SUCH_FILE
+ is returned when a reference is made to a file which should exist
+ but doesn't.
+
+ SSH_FX_PERMISSION_DENIED
+ is returned when the authenticated user does not have sufficient
+ permissions to perform the operation.
+
+ SSH_FX_FAILURE
+ is a generic catch-all error message; it should be returned if an
+ error occurs for which there is no more specific error code
+ defined.
+
+ SSH_FX_BAD_MESSAGE
+ may be returned if a badly formatted packet or protocol
+ incompatibility is detected.
+
+ SSH_FX_NO_CONNECTION
+ is a pseudo-error which indicates that the client has no
+ connection to the server (it can only be generated locally by the
+ client, and MUST NOT be returned by servers).
+
+ SSH_FX_CONNECTION_LOST
+ is a pseudo-error which indicates that the connection to the
+ server has been lost (it can only be generated locally by the
+ client, and MUST NOT be returned by servers).
+
+
+
+
+Ylonen & Lehtinen Expires April 1, 2002 [Page 21]
+
+Internet-Draft SSH File Transfer Protocol October 2001
+
+
+ SSH_FX_OP_UNSUPPORTED
+ indicates that an attempt was made to perform an operation which
+ is not supported for the server (it may be generated locally by
+ the client if e.g. the version number exchange indicates that a
+ required feature is not supported by the server, or it may be
+ returned by the server if the server does not implement an
+ operation).
+
+ The SSH_FXP_HANDLE response has the following format:
+
+ uint32 id
+ string handle
+
+ where `id' is the request identifier, and `handle' is an arbitrary
+ string that identifies an open file or directory on the server. The
+ handle is opaque to the client; the client MUST NOT attempt to
+ interpret or modify it in any way. The length of the handle string
+ MUST NOT exceed 256 data bytes.
+
+ The SSH_FXP_DATA response has the following format:
+
+ uint32 id
+ string data
+
+ where `id' is the request identifier, and `data' is an arbitrary byte
+ string containing the requested data. The data string may be at most
+ the number of bytes requested in a SSH_FXP_READ request, but may also
+ be shorter if end of file is reached or if the read is from something
+ other than a regular file.
+
+ The SSH_FXP_NAME response has the following format:
+
+ uint32 id
+ uint32 count
+ repeats count times:
+ string filename
+ string longname
+ ATTRS attrs
+
+ where `id' is the request identifier, `count' is the number of names
+ returned in this response, and the remaining fields repeat `count'
+ times (so that all three fields are first included for the first
+ file, then for the second file, etc). In the repeated part,
+ `filename' is a file name being returned (for SSH_FXP_READDIR, it
+ will be a relative name within the directory, without any path
+ components; for SSH_FXP_REALPATH it will be an absolute path name),
+ `longname' is an expanded format for the file name, similar to what
+ is returned by "ls -l" on Unix systems, and `attrs' is the attributes
+
+
+
+Ylonen & Lehtinen Expires April 1, 2002 [Page 22]
+
+Internet-Draft SSH File Transfer Protocol October 2001
+
+
+ of the file as described in Section ``File Attributes''.
+
+ The format of the `longname' field is unspecified by this protocol.
+ It MUST be suitable for use in the output of a directory listing
+ command (in fact, the recommended operation for a directory listing
+ command is to simply display this data). However, clients SHOULD NOT
+ attempt to parse the longname field for file attributes; they SHOULD
+ use the attrs field instead.
+
+ The recommended format for the longname field is as follows:
+
+ -rwxr-xr-x 1 mjos staff 348911 Mar 25 14:29 t-filexfer
+ 1234567890 123 12345678 12345678 12345678 123456789012
+
+ Here, the first line is sample output, and the second field indicates
+ widths of the various fields. Fields are separated by spaces. The
+ first field lists file permissions for user, group, and others; the
+ second field is link count; the third field is the name of the user
+ who owns the file; the fourth field is the name of the group that
+ owns the file; the fifth field is the size of the file in bytes; the
+ sixth field (which actually may contain spaces, but is fixed to 12
+ characters) is the file modification time, and the seventh field is
+ the file name. Each field is specified to be a minimum of certain
+ number of character positions (indicated by the second line above),
+ but may also be longer if the data does not fit in the specified
+ length.
+
+ The SSH_FXP_ATTRS response has the following format:
+
+ uint32 id
+ ATTRS attrs
+
+ where `id' is the request identifier, and `attrs' is the returned
+ file attributes as described in Section ``File Attributes''.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Ylonen & Lehtinen Expires April 1, 2002 [Page 23]
+
+Internet-Draft SSH File Transfer Protocol October 2001
+
+
+8. Vendor-Specific Extensions
+
+ The SSH_FXP_EXTENDED request provides a generic extension mechanism
+ for adding vendor-specific commands. The request has the following
+ format:
+
+ uint32 id
+ string extended-request
+ ... any request-specific data ...
+
+ where `id' is the request identifier, and `extended-request' is a
+ string of the format "name@domain", where domain is an internet
+ domain name of the vendor defining the request. The rest of the
+ request is completely vendor-specific, and servers should only
+ attempt to interpret it if they recognize the `extended-request'
+ name.
+
+ The server may respond to such requests using any of the response
+ packets defined in Section ``Responses from the Server to the
+ Client''. Additionally, the server may also respond with a
+ SSH_FXP_EXTENDED_REPLY packet, as defined below. If the server does
+ not recognize the `extended-request' name, then the server MUST
+ respond with SSH_FXP_STATUS with error/status set to
+ SSH_FX_OP_UNSUPPORTED.
+
+ The SSH_FXP_EXTENDED_REPLY packet can be used to carry arbitrary
+ extension-specific data from the server to the client. It is of the
+ following format:
+
+ uint32 id
+ ... any request-specific data ...
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Ylonen & Lehtinen Expires April 1, 2002 [Page 24]
+
+Internet-Draft SSH File Transfer Protocol October 2001
+
+
+9. Security Considerations
+
+ This protocol assumes that it is run over a secure channel and that
+ the endpoints of the channel have been authenticated. Thus, this
+ protocol assumes that it is externally protected from network-level
+ attacks.
+
+ This protocol provides file system access to arbitrary files on the
+ server (only constrained by the server implementation). It is the
+ responsibility of the server implementation to enforce any access
+ controls that may be required to limit the access allowed for any
+ particular user (the user being authenticated externally to this
+ protocol, typically using the SSH User Authentication Protocol [6].
+
+ Care must be taken in the server implementation to check the validity
+ of received file handle strings. The server should not rely on them
+ directly; it MUST check the validity of each handle before relying on
+ it.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Ylonen & Lehtinen Expires April 1, 2002 [Page 25]
+
+Internet-Draft SSH File Transfer Protocol October 2001
+
+
+10. Changes from previous protocol versions
+
+ The SSH File Transfer Protocol has changed over time, before it's
+ standardization. The following is a description of the incompatible
+ changes between different versions.
+
+10.1 Changes between versions 3 and 2
+
+ o The SSH_FXP_READLINK and SSH_FXP_SYMLINK messages were added.
+
+ o The SSH_FXP_EXTENDED and SSH_FXP_EXTENDED_REPLY messages were
+ added.
+
+ o The SSH_FXP_STATUS message was changed to include fields `error
+ message' and `language tag'.
+
+
+10.2 Changes between versions 2 and 1
+
+ o The SSH_FXP_RENAME message was added.
+
+
+10.3 Changes between versions 1 and 0
+
+ o Implementation changes, no actual protocol changes.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Ylonen & Lehtinen Expires April 1, 2002 [Page 26]
+
+Internet-Draft SSH File Transfer Protocol October 2001
+
+
+11. Trademark Issues
+
+ "ssh" is a registered trademark of SSH Communications Security Corp
+ in the United States and/or other countries.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Ylonen & Lehtinen Expires April 1, 2002 [Page 27]
+
+Internet-Draft SSH File Transfer Protocol October 2001
+
+
+References
+
+ [1] Dierks, T., Allen, C., Treese, W., Karlton, P., Freier, A. and
+ P. Kocher, "The TLS Protocol Version 1.0", RFC 2246, January
+ 1999.
+
+ [2] Institute of Electrical and Electronics Engineers, "Information
+ Technology - Portable Operating System Interface (POSIX) - Part
+ 1: System Application Program Interface (API) [C Language]",
+ IEEE Standard 1003.2, 1996.
+
+ [3] Rinne, T., Ylonen, T., Kivinen, T., Saarinen, M. and S.
+ Lehtinen, "SSH Protocol Architecture", draft-ietf-secsh-
+ architecture-09 (work in progress), July 2001.
+
+ [4] Rinne, T., Ylonen, T., Kivinen, T., Saarinen, M. and S.
+ Lehtinen, "SSH Protocol Transport Protocol", draft-ietf-secsh-
+ architecture-09 (work in progress), July 2001.
+
+ [5] Rinne, T., Ylonen, T., Kivinen, T., Saarinen, M. and S.
+ Lehtinen, "SSH Connection Protocol", draft-ietf-secsh-connect-11
+ (work in progress), July 2001.
+
+ [6] Rinne, T., Ylonen, T., Kivinen, T., Saarinen, M. and S.
+ Lehtinen, "SSH Authentication Protocol", draft-ietf-secsh-
+ userauth-11 (work in progress), July 2001.
+
+
+Authors' Addresses
+
+ Tatu Ylonen
+ SSH Communications Security Corp
+ Fredrikinkatu 42
+ HELSINKI FIN-00100
+ Finland
+
+ EMail: ylo@ssh.com
+
+
+ Sami Lehtinen
+ SSH Communications Security Corp
+ Fredrikinkatu 42
+ HELSINKI FIN-00100
+ Finland
+
+ EMail: sjl@ssh.com
+
+
+
+
+
+Ylonen & Lehtinen Expires April 1, 2002 [Page 28]
+
+Internet-Draft SSH File Transfer Protocol October 2001
+
+
+Full Copyright Statement
+
+ Copyright (C) The Internet Society (2001). All Rights Reserved.
+
+ This document and translations of it may be copied and furnished to
+ others, and derivative works that comment on or otherwise explain it
+ or assist in its implementation may be prepared, copied, published
+ and distributed, in whole or in part, without restriction of any
+ kind, provided that the above copyright notice and this paragraph are
+ included on all such copies and derivative works. However, this
+ document itself may not be modified in any way, such as by removing
+ the copyright notice or references to the Internet Society or other
+ Internet organizations, except as needed for the purpose of
+ developing Internet standards in which case the procedures for
+ copyrights defined in the Internet Standards process must be
+ followed, or as required to translate it into languages other than
+ English.
+
+ The limited permissions granted above are perpetual and will not be
+ revoked by the Internet Society or its successors or assigns.
+
+ This document and the information contained herein is provided on an
+ "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
+ TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
+ BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
+ HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
+ MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
+
+Acknowledgement
+
+ Funding for the RFC Editor function is currently provided by the
+ Internet Society.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Ylonen & Lehtinen Expires April 1, 2002 [Page 29]
+
+
+
diff --git a/doc/draft-ietf-secsh-filexfer-03.txt b/doc/draft-ietf-secsh-filexfer-03.txt
new file mode 100644
index 00000000..83960ae9
--- /dev/null
+++ b/doc/draft-ietf-secsh-filexfer-03.txt
@@ -0,0 +1,1962 @@
+
+
+
+Secure Shell Working Group J. Galbraith
+Internet-Draft VanDyke Software
+Expires: April 16, 2003 T. Ylonen
+ S. Lehtinen
+ SSH Communications Security Corp
+ October 16, 2002
+
+
+ SSH File Transfer Protocol
+ draft-ietf-secsh-filexfer-03.txt
+
+Status of this Memo
+
+ This document is an Internet-Draft and is in full conformance with
+ all provisions of Section 10 of RFC2026.
+
+ Internet-Drafts are working documents of the Internet Engineering
+ Task Force (IETF), its areas, and its working groups. Note that
+ other groups may also distribute working documents as Internet-
+ Drafts.
+
+ Internet-Drafts are draft documents valid for a maximum of six months
+ and may be updated, replaced, or obsoleted by other documents at any
+ time. It is inappropriate to use Internet-Drafts as reference
+ material or to cite them other than as "work in progress."
+
+ The list of current Internet-Drafts can be accessed at http://
+ www.ietf.org/ietf/1id-abstracts.txt.
+
+ The list of Internet-Draft Shadow Directories can be accessed at
+ http://www.ietf.org/shadow.html.
+
+ This Internet-Draft will expire on April 16, 2003.
+
+Copyright Notice
+
+ Copyright (C) The Internet Society (2002). All Rights Reserved.
+
+Abstract
+
+ The SSH File Transfer Protocol provides secure file transfer
+ functionality over any reliable data stream. It is the standard file
+ transfer protocol for use with the SSH2 protocol. This document
+ describes the file transfer protocol and its interface to the SSH2
+ protocol suite.
+
+
+
+
+
+
+
+Galbraith, et al. Expires April 16, 2003 [Page 1]
+
+Internet-Draft SSH File Transfer Protocol October 2002
+
+
+Table of Contents
+
+ 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . 3
+ 2. Use with the SSH Connection Protocol . . . . . . . . . . . 4
+ 3. General Packet Format . . . . . . . . . . . . . . . . . . 5
+ 4. Protocol Initialization . . . . . . . . . . . . . . . . . 7
+ 4.1 Client Initialization . . . . . . . . . . . . . . . . . . 7
+ 4.2 Server Initialization . . . . . . . . . . . . . . . . . . 7
+ 4.3 Determining Server Newline Convention . . . . . . . . . . 8
+ 5. File Attributes . . . . . . . . . . . . . . . . . . . . . 9
+ 5.1 Flags . . . . . . . . . . . . . . . . . . . . . . . . . . 9
+ 5.2 Type . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
+ 5.3 Size . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
+ 5.4 Owner and Group . . . . . . . . . . . . . . . . . . . . . 10
+ 5.5 Permissions . . . . . . . . . . . . . . . . . . . . . . . 11
+ 5.6 Times . . . . . . . . . . . . . . . . . . . . . . . . . . 11
+ 5.7 ACL . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
+ 5.8 Extended attributes . . . . . . . . . . . . . . . . . . . 12
+ 6. Requests From the Client to the Server . . . . . . . . . . 13
+ 6.1 Request Synchronization and Reordering . . . . . . . . . . 13
+ 6.2 File Names . . . . . . . . . . . . . . . . . . . . . . . . 14
+ 6.3 Opening, Creating, and Closing Files . . . . . . . . . . . 14
+ 6.4 Reading and Writing . . . . . . . . . . . . . . . . . . . 17
+ 6.5 Removing and Renaming Files . . . . . . . . . . . . . . . 18
+ 6.6 Creating and Deleting Directories . . . . . . . . . . . . 19
+ 6.7 Scanning Directories . . . . . . . . . . . . . . . . . . . 19
+ 6.8 Retrieving File Attributes . . . . . . . . . . . . . . . . 20
+ 6.9 Setting File Attributes . . . . . . . . . . . . . . . . . 21
+ 6.10 Dealing with Symbolic links . . . . . . . . . . . . . . . 22
+ 6.11 Canonicalizing the Server-Side Path Name . . . . . . . . . 23
+ 6.11.1 Best practice for dealing with paths . . . . . . . . . . . 23
+ 7. Responses from the Server to the Client . . . . . . . . . 24
+ 8. Vendor-Specific Extensions . . . . . . . . . . . . . . . . 28
+ 9. Security Considerations . . . . . . . . . . . . . . . . . 29
+ 10. Changes from previous protocol versions . . . . . . . . . 30
+ 10.1 Changes between versions 4 and 3 . . . . . . . . . . . . . 30
+ 10.2 Changes between versions 3 and 2 . . . . . . . . . . . . . 31
+ 10.3 Changes between versions 2 and 1 . . . . . . . . . . . . . 31
+ 10.4 Changes between versions 1 and 0 . . . . . . . . . . . . . 31
+ 11. Trademark Issues . . . . . . . . . . . . . . . . . . . . . 32
+ References . . . . . . . . . . . . . . . . . . . . . . . . 33
+ Authors' Addresses . . . . . . . . . . . . . . . . . . . . 33
+ Full Copyright Statement . . . . . . . . . . . . . . . . . 35
+
+
+
+
+
+
+
+
+Galbraith, et al. Expires April 16, 2003 [Page 2]
+
+Internet-Draft SSH File Transfer Protocol October 2002
+
+
+1. Introduction
+
+ This protocol provides secure file transfer (and more generally file
+ system access) functionality over a reliable data stream, such as a
+ channel in the SSH2 protocol [5].
+
+ This protocol is designed so that it could be used to implement a
+ secure remote file system service, as well as a secure file transfer
+ service.
+
+ This protocol assumes that it runs over a secure channel, and that
+ the server has already authenticated the user at the client end, and
+ that the identity of the client user is externally available to the
+ server implementation.
+
+ In general, this protocol follows a simple request-response model.
+ Each request and response contains a sequence number and multiple
+ requests may be pending simultaneously. There are a relatively large
+ number of different request messages, but a small number of possible
+ response messages. Each request has one or more response messages
+ that may be returned in result (e.g., a read either returns data or
+ reports error status).
+
+ The packet format descriptions in this specification follow the
+ notation presented in the secsh architecture draft. [5]
+
+ Even though this protocol is described in the context of the SSH2
+ protocol, this protocol is general and independent of the rest of the
+ SSH2 protocol suite. It could be used in a number of different
+ applications, such as secure file transfer over TLS RFC 2246 [1] and
+ transfer of management information in VPN applications.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Galbraith, et al. Expires April 16, 2003 [Page 3]
+
+Internet-Draft SSH File Transfer Protocol October 2002
+
+
+2. Use with the SSH Connection Protocol
+
+ When used with the SSH2 Protocol suite, this protocol is intended to
+ be used from the SSH Connection Protocol [7] as a subsystem, as
+ described in section ``Starting a Shell or a Command''. The
+ subsystem name used with this protocol is "sftp".
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Galbraith, et al. Expires April 16, 2003 [Page 4]
+
+Internet-Draft SSH File Transfer Protocol October 2002
+
+
+3. General Packet Format
+
+ All packets transmitted over the secure connection are of the
+ following format:
+
+ uint32 length
+ byte type
+ byte[length - 1] data payload
+
+ That is, they are just data preceded by 32-bit length and 8-bit type
+ fields. The `length' is the length of the data area, and does not
+ include the `length' field itself. The format and interpretation of
+ the data area depends on the packet type.
+
+ All packet descriptions below only specify the packet type and the
+ data that goes into the data field. Thus, they should be prefixed by
+ the `length' and `type' fields.
+
+ The maximum size of a packet is in practice determined by the client
+ (the maximum size of read or write requests that it sends, plus a few
+ bytes of packet overhead). All servers SHOULD support packets of at
+ least 34000 bytes (where the packet size refers to the full length,
+ including the header above). This should allow for reads and writes
+ of at most 32768 bytes.
+
+ There is no limit on the number of outstanding (non-acknowledged)
+ requests that the client may send to the server. In practice this is
+ limited by the buffering available on the data stream and the queuing
+ performed by the server. If the server's queues are full, it should
+ not read any more data from the stream, and flow control will prevent
+ the client from sending more requests. Note, however, that while
+ there is no restriction on the protocol level, the client's API may
+ provide a limit in order to prevent infinite queuing of outgoing
+ requests at the client.
+
+ The following values are defined for packet types.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Galbraith, et al. Expires April 16, 2003 [Page 5]
+
+Internet-Draft SSH File Transfer Protocol October 2002
+
+
+ #define SSH_FXP_INIT 1
+ #define SSH_FXP_VERSION 2
+ #define SSH_FXP_OPEN 3
+ #define SSH_FXP_CLOSE 4
+ #define SSH_FXP_READ 5
+ #define SSH_FXP_WRITE 6
+ #define SSH_FXP_LSTAT 7
+ #define SSH_FXP_FSTAT 8
+ #define SSH_FXP_SETSTAT 9
+ #define SSH_FXP_FSETSTAT 10
+ #define SSH_FXP_OPENDIR 11
+ #define SSH_FXP_READDIR 12
+ #define SSH_FXP_REMOVE 13
+ #define SSH_FXP_MKDIR 14
+ #define SSH_FXP_RMDIR 15
+ #define SSH_FXP_REALPATH 16
+ #define SSH_FXP_STAT 17
+ #define SSH_FXP_RENAME 18
+ #define SSH_FXP_READLINK 19
+ #define SSH_FXP_SYMLINK 20
+
+ #define SSH_FXP_STATUS 101
+ #define SSH_FXP_HANDLE 102
+ #define SSH_FXP_DATA 103
+ #define SSH_FXP_NAME 104
+ #define SSH_FXP_ATTRS 105
+
+ #define SSH_FXP_EXTENDED 200
+ #define SSH_FXP_EXTENDED_REPLY 201
+
+ RESERVED_FOR_EXTENSIONS 210-255
+
+ Additional packet types should only be defined if the protocol
+ version number (see Section ``Protocol Initialization'') is
+ incremented, and their use MUST be negotiated using the version
+ number. However, the SSH_FXP_EXTENDED and SSH_FXP_EXTENDED_REPLY
+ packets can be used to implement vendor-specific extensions. See
+ Section ``Vendor-Specific-Extensions'' for more details.
+
+
+
+
+
+
+
+
+
+
+
+
+
+Galbraith, et al. Expires April 16, 2003 [Page 6]
+
+Internet-Draft SSH File Transfer Protocol October 2002
+
+
+4. Protocol Initialization
+
+ When the file transfer protocol starts, the client first sends a
+ SSH_FXP_INIT (including its version number) packet to the server.
+ The server responds with a SSH_FXP_VERSION packet, supplying the
+ lowest of its own and the client's version number. Both parties
+ should from then on adhere to particular version of the protocol.
+
+ The version number of the protocol specified in this document is 4.
+ The version number should be incremented for each incompatible
+ revision of this protocol.
+
+4.1 Client Initialization
+
+ The SSH_FXP_INIT packet (from client to server) has the following
+ data:
+
+ uint32 version
+
+ Version 3 of this protocol allowed clients to include extensions in
+ the SSH_FXP_INIT packet; however, this can cause interoperability
+ problems with version 1 and version 2 servers because the client must
+ send this packet before knowing the servers version.
+
+ In this version of the protocol, clients MUST use the
+ SSH_FXP_EXTENDED packet to send extensions to the server after
+ version exchange has completed. Clients MUST NOT include extensions
+ in the version packet. This will prevent interoperability problems
+ with older servers
+
+4.2 Server Initialization
+
+ The SSH_FXP_VERSION packet (from server to client) has the following
+ data:
+
+ uint32 version
+ <extension data>
+
+ 'version' is the lower of the protocol version supported by the
+ server and the version number received from the client.
+
+ The extension data may be empty, or may be a sequence of
+
+ string extension_name
+ string extension_data
+
+ pairs (both strings MUST always be present if one is, but the
+ `extension_data' string may be of zero length). If present, these
+
+
+
+Galbraith, et al. Expires April 16, 2003 [Page 7]
+
+Internet-Draft SSH File Transfer Protocol October 2002
+
+
+ strings indicate extensions to the baseline protocol. The
+ `extension_name' field(s) identify the name of the extension. The
+ name should be of the form "name@domain", where the domain is the DNS
+ domain name of the organization defining the extension. Additional
+ names that are not of this format may be defined later by the IETF.
+ Implementations MUST silently ignore any extensions whose name they
+ do not recognize.
+
+4.3 Determining Server Newline Convention
+
+ In order to correctly process text files in a cross platform
+ compatible way, the newline convention must be converted from that of
+ the server to that of the client, or, during an upload, from that of
+ the client to that of the server.
+
+ Versions 3 and prior of this protocol made no provisions for
+ processing text files. Many clients implemented some sort of
+ conversion algorithm, but without either a 'canonical' on the wire
+ format or knowledge of the servers newline convention, correct
+ conversion was not always possible.
+
+ Starting with Version 4, the SSH_FXF_TEXT file open flag (Section
+ 6.3) makes it possible to request that the server translate a file to
+ a 'canonical' on the wire format. This format uses \r\n as the line
+ separator.
+
+ Servers for systems using multiple newline characters (for example,
+ Mac OS X or VMS) or systems using counted records, MUST translate to
+ the canonical form.
+
+ However, to ease the burden of implementation on servers that use a
+ single, simple separator sequence, the following extension allows the
+ canonical format to be changed.
+
+ string "newline"
+ string new-canonical-separator (usually "\r" or "\n" or "\r\n")
+
+ All clients MUST support this extension.
+
+ When processing text files, clients SHOULD NOT translate any
+ character or sequence that is not an exact match of the servers
+ newline separator.
+
+ In particular, if the newline sequence being used is the canonical
+ "\r\n" sequence, a lone \r or a lone \n SHOULD be written through
+ without change.
+
+
+
+
+
+Galbraith, et al. Expires April 16, 2003 [Page 8]
+
+Internet-Draft SSH File Transfer Protocol October 2002
+
+
+5. File Attributes
+
+ A new compound data type is defined for encoding file attributes.
+ The same encoding is used both when returning file attributes from
+ the server and when sending file attributes to the server. When
+ sending it to the server, the flags field specifies which attributes
+ are included, and the server will use default values for the
+ remaining attributes (or will not modify the values of remaining
+ attributes). When receiving attributes from the server, the flags
+ specify which attributes are included in the returned data. The
+ server normally returns all attributes it knows about.
+
+ uint32 flags
+ byte type always present
+ uint64 size present only if flag SSH_FILEXFER_ATTR_SIZE
+ string owner present only if flag SSH_FILEXFER_ATTR_OWNERGROUP
+ string group present only if flag SSH_FILEXFER_ATTR_OWNERGROUP
+ uint32 permissions present only if flag SSH_FILEXFER_ATTR_PERMISSIONS
+ uint32 atime present only if flag SSH_FILEXFER_ATTR_ACCESSTIME
+ uint32 createtime present only if flag SSH_FILEXFER_ATTR_CREATETIME
+ uint32 mtime present only if flag SSH_FILEXFER_ATTR_MODIFYTIME
+ string acl present only if flag SSH_FILEXFER_ATTR_ACL
+ uint32 extended_count present only if flag SSH_FILEXFER_ATTR_EXTENDED
+ string extended_type
+ string extended_data
+ ... more extended data (extended_type - extended_data pairs),
+ so that number of pairs equals extended_count
+
+
+5.1 Flags
+
+ The `flags' specify which of the fields are present. Those fields
+ for which the corresponding flag is not set are not present (not
+ included in the packet). New flags can only be added by incrementing
+ the protocol version number (or by using the extension mechanism
+ described below).
+
+ The flags bits are defined to have the following values:
+
+ #define SSH_FILEXFER_ATTR_SIZE 0x00000001
+ #define SSH_FILEXFER_ATTR_PERMISSIONS 0x00000004
+ #define SSH_FILEXFER_ATTR_ACCESSTIME 0x00000008
+ #define SSH_FILEXFER_ATTR_CREATETIME 0x00000010
+ #define SSH_FILEXFER_ATTR_MODIFYTIME 0x00000020
+ #define SSH_FILEXFER_ATTR_ACL 0x00000040
+ #define SSH_FILEXFER_ATTR_OWNERGROUP 0x00000080
+ #define SSH_FILEXFER_ATTR_EXTENDED 0x80000000
+
+
+
+
+Galbraith, et al. Expires April 16, 2003 [Page 9]
+
+Internet-Draft SSH File Transfer Protocol October 2002
+
+
+ In previous versions of this protocol flags value 0x00000002 was
+ SSH_FILEXFER_ATTR_UIDGID. This value is now unused, and OWNERGROUP
+ was given a new value in order to ease implementation burden.
+ 0x00000002 MUST NOT appear in the mask. Some future version of this
+ protocol may reuse flag 0x00000002.
+
+5.2 Type
+
+ The type field is always present. The following types are defined:
+
+ #define SSH_FILEXFER_TYPE_REGULAR 1
+ #define SSH_FILEXFER_TYPE_DIRECTORY 2
+ #define SSH_FILEXFER_TYPE_SYMLINK 3
+ #define SSH_FILEXFER_TYPE_SPECIAL 4
+ #define SSH_FILEXFER_TYPE_UNKNOWN 5
+
+ On a POSIX system, these values would be derived from the permission
+ field.
+
+5.3 Size
+
+ The `size' field specifies the size of the file on disk, in bytes.
+ If it is present during file creation, it should be considered a hint
+ as to the files eventual size.
+
+ Files opened with the SSH_FXF_TEXT flag may have a size that is
+ greater or less than the value of the size field.
+
+5.4 Owner and Group
+
+ The `owner' and `group' fields are represented as UTF-8 strings; this
+ is the form used by NFS v4. See NFS version 4 Protocol. [3] The
+ following text is selected quotations from section 5.6.
+
+ To avoid a representation that is tied to a particular underlying
+ implementation at the client or server, the use of UTF-8 strings has
+ been chosen. The string should be of the form user@dns_domain".
+ This will allow for a client and server that do not use the same
+ local representation the ability to translate to a common syntax that
+ can be interpreted by both. In the case where there is no
+ translation available to the client or server, the attribute value
+ must be constructed without the "@". Therefore, the absence of the @
+ from the owner or owner_group attribute signifies that no translation
+ was available and the receiver of the attribute should not place any
+ special meaning with the attribute value. Even though the attribute
+ value can not be translated, it may still be useful. In the case of
+ a client, the attribute string may be used for local display of
+ ownership.
+
+
+
+Galbraith, et al. Expires April 16, 2003 [Page 10]
+
+Internet-Draft SSH File Transfer Protocol October 2002
+
+
+5.5 Permissions
+
+ The `permissions' field contains a bit mask of file permissions as
+ defined by POSIX [1].
+
+5.6 Times
+
+ The 'atime', 'createtime', and 'mtime' contain the access, creation,
+ and modification times of the files, respectively. They are
+ represented as seconds from Jan 1, 1970 in UTC.
+
+5.7 ACL
+
+ The 'ACL' field contains an ACL similar to that defined in section
+ 5.9 of NFS version 4 Protocol [3].
+
+ uint32 ace-count
+
+ repeated ace-count time:
+ uint32 ace-type
+ uint32 ace-flag
+ uint32 ace-mask
+ string who [UTF-8]
+
+ ace-type is one of the following four values (taken from NFS Version
+ 4 Protocol [3]:
+
+ const ACE4_ACCESS_ALLOWED_ACE_TYPE = 0x00000000;
+ const ACE4_ACCESS_DENIED_ACE_TYPE = 0x00000001;
+ const ACE4_SYSTEM_AUDIT_ACE_TYPE = 0x00000002;
+ const ACE4_SYSTEM_ALARM_ACE_TYPE = 0x00000003;
+
+ ace-flag is a combination of the following flag values. See NFS
+ Version 4 Protocol [3] section 5.9.2:
+
+ const ACE4_FILE_INHERIT_ACE = 0x00000001;
+ const ACE4_DIRECTORY_INHERIT_ACE = 0x00000002;
+ const ACE4_NO_PROPAGATE_INHERIT_ACE = 0x00000004;
+ const ACE4_INHERIT_ONLY_ACE = 0x00000008;
+ const ACE4_SUCCESSFUL_ACCESS_ACE_FLAG = 0x00000010;
+ const ACE4_FAILED_ACCESS_ACE_FLAG = 0x00000020;
+ const ACE4_IDENTIFIER_GROUP = 0x00000040;
+
+ ace-mask is any combination of the following flags (taken from NFS
+ Version 4 Protocol [3] section 5.9.3:
+
+
+
+
+
+
+Galbraith, et al. Expires April 16, 2003 [Page 11]
+
+Internet-Draft SSH File Transfer Protocol October 2002
+
+
+ const ACE4_READ_DATA = 0x00000001;
+ const ACE4_LIST_DIRECTORY = 0x00000001;
+ const ACE4_WRITE_DATA = 0x00000002;
+ const ACE4_ADD_FILE = 0x00000002;
+ const ACE4_APPEND_DATA = 0x00000004;
+ const ACE4_ADD_SUBDIRECTORY = 0x00000004;
+ const ACE4_READ_NAMED_ATTRS = 0x00000008;
+ const ACE4_WRITE_NAMED_ATTRS = 0x00000010;
+ const ACE4_EXECUTE = 0x00000020;
+ const ACE4_DELETE_CHILD = 0x00000040;
+ const ACE4_READ_ATTRIBUTES = 0x00000080;
+ const ACE4_WRITE_ATTRIBUTES = 0x00000100;
+ const ACE4_DELETE = 0x00010000;
+ const ACE4_READ_ACL = 0x00020000;
+ const ACE4_WRITE_ACL = 0x00040000;
+ const ACE4_WRITE_OWNER = 0x00080000;
+ const ACE4_SYNCHRONIZE = 0x00100000;
+
+ who is a UTF-8 string of the form described in 'Owner and Group'
+ (Section 5.4)
+
+5.8 Extended attributes
+
+ The SSH_FILEXFER_ATTR_EXTENDED flag provides a general extension
+ mechanism for vendor-specific extensions. If the flag is specified,
+ then the `extended_count' field is present. It specifies the number
+ of extended_type-extended_data pairs that follow. Each of these
+ pairs specifies an extended attribute. For each of the attributes,
+ the extended_type field should be a string of the format
+ "name@domain", where "domain" is a valid, registered domain name and
+ "name" identifies the method. The IETF may later standardize certain
+ names that deviate from this format (e.g., that do not contain the
+ "@" sign). The interpretation of `extended_data' depends on the
+ type. Implementations SHOULD ignore extended data fields that they
+ do not understand.
+
+ Additional fields can be added to the attributes by either defining
+ additional bits to the flags field to indicate their presence, or by
+ defining extended attributes for them. The extended attributes
+ mechanism is recommended for most purposes; additional flags bits
+ should only be defined by an IETF standards action that also
+ increments the protocol version number. The use of such new fields
+ MUST be negotiated by the version number in the protocol exchange.
+ It is a protocol error if a packet with unsupported protocol bits is
+ received.
+
+
+
+
+
+
+Galbraith, et al. Expires April 16, 2003 [Page 12]
+
+Internet-Draft SSH File Transfer Protocol October 2002
+
+
+6. Requests From the Client to the Server
+
+ Requests from the client to the server represent the various file
+ system operations. Each request begins with an `id' field, which is
+ a 32-bit identifier identifying the request (selected by the client).
+ The same identifier will be returned in the response to the request.
+ One possible implementation is a monotonically increasing request
+ sequence number (modulo 2^32).
+
+ Many operations in the protocol operate on open files. The
+ SSH_FXP_OPEN request can return a file handle (which is an opaque
+ variable-length string) which may be used to access the file later
+ (e.g. in a read operation). The client MUST NOT send requests the
+ server with bogus or closed handles. However, the server MUST
+ perform adequate checks on the handle in order to avoid security
+ risks due to fabricated handles.
+
+ This design allows either stateful and stateless server
+ implementation, as well as an implementation which caches state
+ between requests but may also flush it. The contents of the file
+ handle string are entirely up to the server and its design. The
+ client should not modify or attempt to interpret the file handle
+ strings.
+
+ The file handle strings MUST NOT be longer than 256 bytes.
+
+6.1 Request Synchronization and Reordering
+
+ The protocol and implementations MUST process requests relating to
+ the same file in the order in which they are received. In other
+ words, if an application submits multiple requests to the server, the
+ results in the responses will be the same as if it had sent the
+ requests one at a time and waited for the response in each case. For
+ example, the server may process non-overlapping read/write requests
+ to the same file in parallel, but overlapping reads and writes cannot
+ be reordered or parallelized. However, there are no ordering
+ restrictions on the server for processing requests from two different
+ file transfer connections. The server may interleave and parallelize
+ them at will.
+
+ There are no restrictions on the order in which responses to
+ outstanding requests are delivered to the client, except that the
+ server must ensure fairness in the sense that processing of no
+ request will be indefinitely delayed even if the client is sending
+ other requests so that there are multiple outstanding requests all
+ the time.
+
+
+
+
+
+Galbraith, et al. Expires April 16, 2003 [Page 13]
+
+Internet-Draft SSH File Transfer Protocol October 2002
+
+
+6.2 File Names
+
+ This protocol represents file names as strings. File names are
+ assumed to use the slash ('/') character as a directory separator.
+
+ File names starting with a slash are "absolute", and are relative to
+ the root of the file system. Names starting with any other character
+ are relative to the user's default directory (home directory). Note
+ that identifying the user is assumed to take place outside of this
+ protocol.
+
+ Servers SHOULD interpret a path name component ".." as referring to
+ the parent directory, and "." as referring to the current directory.
+ If the server implementation limits access to certain parts of the
+ file system, it must be extra careful in parsing file names when
+ enforcing such restrictions. There have been numerous reported
+ security bugs where a ".." in a path name has allowed access outside
+ the intended area.
+
+ An empty path name is valid, and it refers to the user's default
+ directory (usually the user's home directory).
+
+ Otherwise, no syntax is defined for file names by this specification.
+ Clients should not make any other assumptions; however, they can
+ splice path name components returned by SSH_FXP_READDIR together
+ using a slash ('/') as the separator, and that will work as expected.
+
+ In order to comply with IETF Policy on Character Sets and Languages
+ [2], all filenames are to be encoded in UTF-8. The shortest valid
+ UTF-8 encoding of the UNICODE data MUST be used. The server is
+ responsible for converting the UNICODE data to whatever canonical
+ form it requires.
+
+ For example, if the server requires that precomposed characters
+ always be used, the server MUST NOT assume the filename as sent by
+ the client has this attribute, but must do this normalization itself.
+
+ It is understood that the lack of well-defined semantics for file
+ names may cause interoperability problems between clients and servers
+ using radically different operating systems. However, this approach
+ is known to work acceptably with most systems, and alternative
+ approaches that e.g. treat file names as sequences of structured
+ components are quite complicated.
+
+6.3 Opening, Creating, and Closing Files
+
+ Files are opened and created using the SSH_FXP_OPEN message, whose
+ data part is as follows:
+
+
+
+Galbraith, et al. Expires April 16, 2003 [Page 14]
+
+Internet-Draft SSH File Transfer Protocol October 2002
+
+
+ uint32 id
+ string filename [UTF-8]
+ uint32 pflags
+ ATTRS attrs
+
+ The `id' field is the request identifier as for all requests.
+
+ The `filename' field specifies the file name. See Section ``File
+ Names'' for more information.
+
+ The `pflags' field is a bitmask. The following bits have been
+ defined.
+
+ #define SSH_FXF_READ 0x00000001
+ #define SSH_FXF_WRITE 0x00000002
+ #define SSH_FXF_APPEND 0x00000004
+ #define SSH_FXF_CREAT 0x00000008
+ #define SSH_FXF_TRUNC 0x00000010
+ #define SSH_FXF_EXCL 0x00000020
+ #define SSH_FXF_TEXT 0x00000040
+
+ These have the following meanings:
+
+ SSH_FXF_READ
+ Open the file for reading.
+
+ SSH_FXF_WRITE
+ Open the file for writing. If both this and SSH_FXF_READ are
+ specified, the file is opened for both reading and writing.
+
+ SSH_FXF_APPEND
+ Force all writes to append data at the end of the file. The
+ offset parameter to write will be ignored.
+
+ SSH_FXF_CREAT
+ If this flag is specified, then a new file will be created if one
+ does not already exist (if O_TRUNC is specified, the new file will
+ be truncated to zero length if it previously exists).
+
+ SSH_FXF_TRUNC
+ Forces an existing file with the same name to be truncated to zero
+ length when creating a file by specifying SSH_FXF_CREAT.
+ SSH_FXF_CREAT MUST also be specified if this flag is used.
+
+ SSH_FXF_EXCL
+ Causes the request to fail if the named file already exists.
+ SSH_FXF_CREAT MUST also be specified if this flag is used.
+
+
+
+
+Galbraith, et al. Expires April 16, 2003 [Page 15]
+
+Internet-Draft SSH File Transfer Protocol October 2002
+
+
+ SSH_FXF_TEXT
+ Indicates that the server should treat the file as text and
+ convert it to the canonical newline convention in use. (See
+ Determining Server Newline Convention. (Section 4.3)
+
+ When a file is opened with the FXF_TEXT flag, the offset field in
+ both the read and write function are ignored.
+
+ Servers MUST correctly process multiple parallel reads and writes
+ correctly in this mode. Naturally, it is permissible for them to
+ do this by serializing the requests. It would not be possible for
+ a client to reliably detect a server that does not implement
+ parallel writes in time to prevent damage.
+
+ Clients SHOULD use the SSH_FXF_APPEND flag to append data to a
+ text file rather then using write with a calculated offset.
+
+ To support seeks on text file the following SSH_FXP_EXTENDED
+ packet is defined.
+
+
+
+ string "text-seek"
+ string file-handle
+ uint64 line-number
+
+ line-number is the index of the line number to seek to, where byte
+ 0 in the file is line number 0, and the byte directly following
+ the first newline sequence in the file is line number 1 and so on.
+
+ The response to a "text-seek" request is an SSH_FXP_STATUS
+ message.
+
+ An attempt to seek past the end-of-file should result in a
+ SSH_FX_EOF status.
+
+ Servers SHOULD support at least one "text-seek" in order to
+ support resume. However, a client MUST be prepared to receive
+ SSH_FX_OP_UNSUPPORTED when attempting a "text-seek" operation.
+ The client can then try a fall-back strategy, if it has one.
+
+ Clients MUST be prepared to handle SSH_FX_OP_UNSUPPORTED returned
+ for read or write operations that are not sequential.
+
+ The `attrs' field specifies the initial attributes for the file.
+ Default values will be used for those attributes that are not
+ specified. See Section ``File Attributes'' for more information.
+
+
+
+
+Galbraith, et al. Expires April 16, 2003 [Page 16]
+
+Internet-Draft SSH File Transfer Protocol October 2002
+
+
+ The response to this message will be either SSH_FXP_HANDLE (if the
+ operation is successful) or SSH_FXP_STATUS (if the operation fails).
+
+ A file is closed by using the SSH_FXP_CLOSE request. Its data field
+ has the following format:
+
+ uint32 id
+ string handle
+
+ where `id' is the request identifier, and `handle' is a handle
+ previously returned in the response to SSH_FXP_OPEN or
+ SSH_FXP_OPENDIR. The handle becomes invalid immediately after this
+ request has been sent.
+
+ The response to this request will be a SSH_FXP_STATUS message. One
+ should note that on some server platforms even a close can fail.
+ This can happen e.g. if the server operating system caches writes,
+ and an error occurs while flushing cached writes during the close.
+
+6.4 Reading and Writing
+
+ Once a file has been opened, it can be read using the SSH_FXP_READ
+ message, which has the following format:
+
+ uint32 id
+ string handle
+ uint64 offset
+ uint32 len
+
+ where `id' is the request identifier, `handle' is an open file handle
+ returned by SSH_FXP_OPEN, `offset' is the offset (in bytes) relative
+ to the beginning of the file from where to start reading, and `len'
+ is the maximum number of bytes to read.
+
+ In response to this request, the server will read as many bytes as it
+ can from the file (up to `len'), and return them in a SSH_FXP_DATA
+ message. If an error occurs or EOF is encountered before reading any
+ data, the server will respond with SSH_FXP_STATUS. For normal disk
+ files, it is guaranteed that this will read the specified number of
+ bytes, or up to end of file. For e.g. device files this may return
+ fewer bytes than requested.
+
+ Writing to a file is achieved using the SSH_FXP_WRITE message, which
+ has the following format:
+
+
+
+
+
+
+
+Galbraith, et al. Expires April 16, 2003 [Page 17]
+
+Internet-Draft SSH File Transfer Protocol October 2002
+
+
+ uint32 id
+ string handle
+ uint64 offset
+ string data
+
+ where `id' is a request identifier, `handle' is a file handle
+ returned by SSH_FXP_OPEN, `offset' is the offset (in bytes) from the
+ beginning of the file where to start writing, and `data' is the data
+ to be written.
+
+ The write will extend the file if writing beyond the end of the file.
+ It is legal to write way beyond the end of the file; the semantics
+ are to write zeroes from the end of the file to the specified offset
+ and then the data. On most operating systems, such writes do not
+ allocate disk space but instead leave "holes" in the file.
+
+ The server responds to a write request with a SSH_FXP_STATUS message.
+
+6.5 Removing and Renaming Files
+
+ Files can be removed using the SSH_FXP_REMOVE message. It has the
+ following format:
+
+ uint32 id
+ string filename [UTF-8]
+
+ where `id' is the request identifier and `filename' is the name of
+ the file to be removed. See Section ``File Names'' for more
+ information. This request cannot be used to remove directories.
+
+ The server will respond to this request with a SSH_FXP_STATUS
+ message.
+
+ Files (and directories) can be renamed using the SSH_FXP_RENAME
+ message. Its data is as follows:
+
+ uint32 id
+ string oldpath [UTF-8]
+ string newpath [UTF-8]
+
+ where `id' is the request identifier, `oldpath' is the name of an
+ existing file or directory, and `newpath' is the new name for the
+ file or directory. It is an error if there already exists a file
+ with the name specified by newpath. The server may also fail rename
+ requests in other situations, for example if `oldpath' and `newpath'
+ point to different file systems on the server.
+
+ The server will respond to this request with a SSH_FXP_STATUS
+
+
+
+Galbraith, et al. Expires April 16, 2003 [Page 18]
+
+Internet-Draft SSH File Transfer Protocol October 2002
+
+
+ message.
+
+6.6 Creating and Deleting Directories
+
+ New directories can be created using the SSH_FXP_MKDIR request. It
+ has the following format:
+
+ uint32 id
+ string path [UTF-8]
+ ATTRS attrs
+
+ where `id' is the request identifier.
+
+ `path' specifies the directory to be created. See Section ``File
+ Names'' for more information on file names.
+
+ `attrs' specifies the attributes that should be applied to it upon
+ creation. Attributes are discussed in more detail in Section ``File
+ Attributes''.
+
+ The server will respond to this request with a SSH_FXP_STATUS
+ message. If a file or directory with the specified path already
+ exists, an error will be returned.
+
+ Directories can be removed using the SSH_FXP_RMDIR request, which has
+ the following format:
+
+ uint32 id
+ string path [UTF-8]
+
+ where `id' is the request identifier, and `path' specifies the
+ directory to be removed. See Section ``File Names'' for more
+ information on file names.
+
+ The server responds to this request with a SSH_FXP_STATUS message.
+ Errors may be returned from this operation for various reasons,
+ including, but not limited to, the path does not exist, the path does
+ not refer to a directory object, the directory is not empty, or the
+ user has insufficient access or permission to perform the requested
+ operation.
+
+6.7 Scanning Directories
+
+ The files in a directory can be listed using the SSH_FXP_OPENDIR and
+ SSH_FXP_READDIR requests. Each SSH_FXP_READDIR request returns one
+ or more file names with full file attributes for each file. The
+ client should call SSH_FXP_READDIR repeatedly until it has found the
+ file it is looking for or until the server responds with a
+
+
+
+Galbraith, et al. Expires April 16, 2003 [Page 19]
+
+Internet-Draft SSH File Transfer Protocol October 2002
+
+
+ SSH_FXP_STATUS message indicating an error (normally SSH_FX_EOF if
+ there are no more files in the directory). The client should then
+ close the handle using the SSH_FXP_CLOSE request.
+
+ The SSH_FXP_OPENDIR opens a directory for reading. It has the
+ following format:
+
+ uint32 id
+ string path [UTF-8]
+
+ where `id' is the request identifier and `path' is the path name of
+ the directory to be listed (without any trailing slash). See Section
+ ``File Names'' for more information on file names. This will return
+ an error if the path does not specify a directory or if the directory
+ is not readable. The server will respond to this request with either
+ a SSH_FXP_HANDLE or a SSH_FXP_STATUS message.
+
+ Once the directory has been successfully opened, files (and
+ directories) contained in it can be listed using SSH_FXP_READDIR
+ requests. These are of the format
+
+ uint32 id
+ string handle
+
+ where `id' is the request identifier, and `handle' is a handle
+ returned by SSH_FXP_OPENDIR. (It is a protocol error to attempt to
+ use an ordinary file handle returned by SSH_FXP_OPEN.)
+
+ The server responds to this request with either a SSH_FXP_NAME or a
+ SSH_FXP_STATUS message. One or more names may be returned at a time.
+ Full status information is returned for each name in order to speed
+ up typical directory listings.
+
+ If there are no more names available to be read, the server MUST
+ respond with a SSH_FXP_STATUS message with error code of SSH_FX_EOF.
+
+ When the client no longer wishes to read more names from the
+ directory, it SHOULD call SSH_FXP_CLOSE for the handle. The handle
+ should be closed regardless of whether an error has occurred or not.
+
+6.8 Retrieving File Attributes
+
+ Very often, file attributes are automatically returned by
+ SSH_FXP_READDIR. However, sometimes there is need to specifically
+ retrieve the attributes for a named file. This can be done using the
+ SSH_FXP_STAT, SSH_FXP_LSTAT and SSH_FXP_FSTAT requests.
+
+ SSH_FXP_STAT and SSH_FXP_LSTAT only differ in that SSH_FXP_STAT
+
+
+
+Galbraith, et al. Expires April 16, 2003 [Page 20]
+
+Internet-Draft SSH File Transfer Protocol October 2002
+
+
+ follows symbolic links on the server, whereas SSH_FXP_LSTAT does not
+ follow symbolic links. Both have the same format:
+
+ uint32 id
+ string path [UTF-8]
+ uint32 flags
+
+ where `id' is the request identifier, and `path' specifies the file
+ system object for which status is to be returned. The server
+ responds to this request with either SSH_FXP_ATTRS or SSH_FXP_STATUS.
+
+ The flags field specify the attribute flags in which the client has
+ particular interest. This is a hint to the server. For example,
+ because retrieving owner / group and acl information can be an
+ expensive operation under some operating systems, the server may
+ choose not to retrieve this information unless the client expresses a
+ specific interest in it.
+
+ The client has no guarantee the server will provide all the fields
+ that it has expressed an interest in.
+
+ SSH_FXP_FSTAT differs from the others in that it returns status
+ information for an open file (identified by the file handle). Its
+ format is as follows:
+
+ uint32 id
+ string handle
+ uint32 flags
+
+ where `id' is the request identifier and `handle' is a file handle
+ returned by SSH_FXP_OPEN. The server responds to this request with
+ SSH_FXP_ATTRS or SSH_FXP_STATUS.
+
+6.9 Setting File Attributes
+
+ File attributes may be modified using the SSH_FXP_SETSTAT and
+ SSH_FXP_FSETSTAT requests. These requests are used for operations
+ such as changing the ownership, permissions or access times, as well
+ as for truncating a file.
+
+ The SSH_FXP_SETSTAT request is of the following format:
+
+ uint32 id
+ string path [UTF-8]
+ ATTRS attrs
+
+ where `id' is the request identifier, `path' specifies the file
+ system object (e.g. file or directory) whose attributes are to be
+
+
+
+Galbraith, et al. Expires April 16, 2003 [Page 21]
+
+Internet-Draft SSH File Transfer Protocol October 2002
+
+
+ modified, and `attrs' specifies the modifications to be made to its
+ attributes. Attributes are discussed in more detail in Section
+ ``File Attributes''.
+
+ An error will be returned if the specified file system object does
+ not exist or the user does not have sufficient rights to modify the
+ specified attributes. The server responds to this request with a
+ SSH_FXP_STATUS message.
+
+ The SSH_FXP_FSETSTAT request modifies the attributes of a file which
+ is already open. It has the following format:
+
+ uint32 id
+ string handle
+ ATTRS attrs
+
+ where `id' is the request identifier, `handle' (MUST be returned by
+ SSH_FXP_OPEN) identifies the file whose attributes are to be
+ modified, and `attrs' specifies the modifications to be made to its
+ attributes. Attributes are discussed in more detail in Section
+ ``File Attributes''. The server will respond to this request with
+ SSH_FXP_STATUS.
+
+6.10 Dealing with Symbolic links
+
+ The SSH_FXP_READLINK request may be used to read the target of a
+ symbolic link. It would have a data part as follows:
+
+ uint32 id
+ string path [UTF-8]
+
+ where `id' is the request identifier and `path' specifies the path
+ name of the symlink to be read.
+
+ The server will respond with a SSH_FXP_NAME packet containing only
+ one name and a dummy attributes value. The name in the returned
+ packet contains the target of the link. If an error occurs, the
+ server may respond with SSH_FXP_STATUS.
+
+ The SSH_FXP_SYMLINK request will create a symbolic link on the
+ server. It is of the following format
+
+ uint32 id
+ string linkpath [UTF-8]
+ string targetpath [UTF-8]
+
+ where `id' is the request identifier, `linkpath' specifies the path
+ name of the symlink to be created and `targetpath' specifies the
+
+
+
+Galbraith, et al. Expires April 16, 2003 [Page 22]
+
+Internet-Draft SSH File Transfer Protocol October 2002
+
+
+ target of the symlink. The server shall respond with a
+ SSH_FXP_STATUS indicating either success (SSH_FX_OK) or an error
+ condition.
+
+6.11 Canonicalizing the Server-Side Path Name
+
+ The SSH_FXP_REALPATH request can be used to have the server
+ canonicalize any given path name to an absolute path. This is useful
+ for converting path names containing ".." components or relative
+ pathnames without a leading slash into absolute paths. The format of
+ the request is as follows:
+
+ uint32 id
+ string path [UTF-8]
+
+ where `id' is the request identifier and `path' specifies the path
+ name to be canonicalized. The server will respond with a
+ SSH_FXP_NAME packet containing the name in canonical form and a dummy
+ attributes value. If an error occurs, the server may also respond
+ with SSH_FXP_STATUS.
+
+6.11.1 Best practice for dealing with paths
+
+ The client SHOULD treat the results of SSH_FXP_REALPATH as a
+ canonical absolute path, even if the path does not appear to be
+ absolute. A client that use REALPATH(".") and treats the result as
+ absolute, even if there is no leading slash, will continue to
+ function correctly, even when talking to a Windows NT or VMS style
+ system, where absolute paths may not begin with a slash.
+
+ For example, if the client wishes to change directory up, and the
+ server has returned "c:/x/y/z" from REALPATH, the client SHOULD use
+ "c:/x/y/z/..".
+
+ As a second example, if the client wishes to open the file "x.txt" in
+ the current directory, and server has returned "dka100:/x/y/z" as the
+ canonical path of the directory, the client SHOULD open "dka100:/x/y/
+ z/x.txt"
+
+
+
+
+
+
+
+
+
+
+
+
+
+Galbraith, et al. Expires April 16, 2003 [Page 23]
+
+Internet-Draft SSH File Transfer Protocol October 2002
+
+
+7. Responses from the Server to the Client
+
+ The server responds to the client using one of a few response
+ packets. All requests can return a SSH_FXP_STATUS response upon
+ failure. When the operation is successful, any of the responses may
+ be returned (depending on the operation). If no data needs to be
+ returned to the client, the SSH_FXP_STATUS response with SSH_FX_OK
+ status is appropriate. Otherwise, the SSH_FXP_HANDLE message is used
+ to return a file handle (for SSH_FXP_OPEN and SSH_FXP_OPENDIR
+ requests), SSH_FXP_DATA is used to return data from SSH_FXP_READ,
+ SSH_FXP_NAME is used to return one or more file names from a
+ SSH_FXP_READDIR or SSH_FXP_REALPATH request, and SSH_FXP_ATTRS is
+ used to return file attributes from SSH_FXP_STAT, SSH_FXP_LSTAT, and
+ SSH_FXP_FSTAT requests.
+
+ Exactly one response will be returned for each request. Each
+ response packet contains a request identifier which can be used to
+ match each response with the corresponding request. Note that it is
+ legal to have several requests outstanding simultaneously, and the
+ server is allowed to send responses to them in a different order from
+ the order in which the requests were sent (the result of their
+ execution, however, is guaranteed to be as if they had been processed
+ one at a time in the order in which the requests were sent).
+
+ Response packets are of the same general format as request packets.
+ Each response packet begins with the request identifier.
+
+ The format of the data portion of the SSH_FXP_STATUS response is as
+ follows:
+
+ uint32 id
+ uint32 error/status code
+ string error message (ISO-10646 UTF-8 [RFC-2279])
+ string language tag (as defined in [RFC-1766])
+
+ where `id' is the request identifier, and `error/status code'
+ indicates the result of the requested operation. The value SSH_FX_OK
+ indicates success, and all other values indicate failure.
+
+ Currently, the following values are defined (other values may be
+ defined by future versions of this protocol):
+
+
+
+
+
+
+
+
+
+
+Galbraith, et al. Expires April 16, 2003 [Page 24]
+
+Internet-Draft SSH File Transfer Protocol October 2002
+
+
+ #define SSH_FX_OK 0
+ #define SSH_FX_EOF 1
+ #define SSH_FX_NO_SUCH_FILE 2
+ #define SSH_FX_PERMISSION_DENIED 3
+ #define SSH_FX_FAILURE 4
+ #define SSH_FX_BAD_MESSAGE 5
+ #define SSH_FX_NO_CONNECTION 6
+ #define SSH_FX_CONNECTION_LOST 7
+ #define SSH_FX_OP_UNSUPPORTED 8
+ #define SSH_FX_INVALID_HANDLE 9
+ #define SSH_FX_NO_SUCH_PATH 10
+ #define SSH_FX_FILE_ALREADY_EXISTS 11
+ #define SSH_FX_WRITE_PROTECT 12
+
+ SSH_FX_OK
+ Indicates successful completion of the operation.
+
+ SSH_FX_EOF
+ indicates end-of-file condition; for SSH_FX_READ it means that no
+ more data is available in the file, and for SSH_FX_READDIR it
+ indicates that no more files are contained in the directory.
+
+ SSH_FX_NO_SUCH_FILE
+ is returned when a reference is made to a file which does not
+ exist.
+
+ SSH_FX_PERMISSION_DENIED
+ is returned when the authenticated user does not have sufficient
+ permissions to perform the operation.
+
+ SSH_FX_FAILURE
+ is a generic catch-all error message; it should be returned if an
+ error occurs for which there is no more specific error code
+ defined.
+
+ SSH_FX_BAD_MESSAGE
+ may be returned if a badly formatted packet or protocol
+ incompatibility is detected.
+
+ SSH_FX_NO_CONNECTION
+ is a pseudo-error which indicates that the client has no
+ connection to the server (it can only be generated locally by the
+ client, and MUST NOT be returned by servers).
+
+ SSH_FX_CONNECTION_LOST
+ is a pseudo-error which indicates that the connection to the
+ server has been lost (it can only be generated locally by the
+ client, and MUST NOT be returned by servers).
+
+
+
+Galbraith, et al. Expires April 16, 2003 [Page 25]
+
+Internet-Draft SSH File Transfer Protocol October 2002
+
+
+ SSH_FX_OP_UNSUPPORTED
+ indicates that an attempt was made to perform an operation which
+ is not supported for the server (it may be generated locally by
+ the client if e.g. the version number exchange indicates that a
+ required feature is not supported by the server, or it may be
+ returned by the server if the server does not implement an
+ operation).
+
+ SSH_FX_INVALID_HANDLE
+ The handle value was invalid.
+
+ SSH_FX_NO_SUCH_PATH
+ The file path does not exist or is invalid.
+
+ SSH_FX_FILE_ALREADY_EXISTS
+ The file already exists.
+
+ SSH_FX_WRITE_PROTECT
+ The file is on read only media, or the media is write protected.
+
+ The SSH_FXP_HANDLE response has the following format:
+
+ uint32 id
+ string handle
+
+ where `id' is the request identifier, and `handle' is an arbitrary
+ string that identifies an open file or directory on the server. The
+ handle is opaque to the client; the client MUST NOT attempt to
+ interpret or modify it in any way. The length of the handle string
+ MUST NOT exceed 256 data bytes.
+
+ The SSH_FXP_DATA response has the following format:
+
+ uint32 id
+ string data
+
+ where `id' is the request identifier, and `data' is an arbitrary byte
+ string containing the requested data. The data string may be at most
+ the number of bytes requested in a SSH_FXP_READ request, but may also
+ be shorter if end of file is reached or if the read is from something
+ other than a regular file.
+
+ The SSH_FXP_NAME response has the following format:
+
+
+
+
+
+
+
+
+Galbraith, et al. Expires April 16, 2003 [Page 26]
+
+Internet-Draft SSH File Transfer Protocol October 2002
+
+
+ uint32 id
+ uint32 count
+ repeats count times:
+ string filename [UTF-8]
+ ATTRS attrs
+
+ where `id' is the request identifier, `count' is the number of names
+ returned in this response, and the remaining fields repeat `count'
+ times (so that all three fields are first included for the first
+ file, then for the second file, etc). In the repeated part,
+ `filename' is a file name being returned (for SSH_FXP_READDIR, it
+ will be a relative name within the directory, without any path
+ components; for SSH_FXP_REALPATH it will be an absolute path name),
+ and `attrs' is the attributes of the file as described in Section
+ ``File Attributes''.
+
+ The SSH_FXP_ATTRS response has the following format:
+
+ uint32 id
+ ATTRS attrs
+
+ where `id' is the request identifier, and `attrs' is the returned
+ file attributes as described in Section ``File Attributes''.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Galbraith, et al. Expires April 16, 2003 [Page 27]
+
+Internet-Draft SSH File Transfer Protocol October 2002
+
+
+8. Vendor-Specific Extensions
+
+ The SSH_FXP_EXTENDED request provides a generic extension mechanism
+ for adding vendor-specific commands. The request has the following
+ format:
+
+ uint32 id
+ string extended-request
+ ... any request-specific data ...
+
+ where `id' is the request identifier, and `extended-request' is a
+ string of the format "name@domain", where domain is an internet
+ domain name of the vendor defining the request. The rest of the
+ request is completely vendor-specific, and servers should only
+ attempt to interpret it if they recognize the `extended-request'
+ name.
+
+ The server may respond to such requests using any of the response
+ packets defined in Section ``Responses from the Server to the
+ Client''. Additionally, the server may also respond with a
+ SSH_FXP_EXTENDED_REPLY packet, as defined below. If the server does
+ not recognize the `extended-request' name, then the server MUST
+ respond with SSH_FXP_STATUS with error/status set to
+ SSH_FX_OP_UNSUPPORTED.
+
+ The SSH_FXP_EXTENDED_REPLY packet can be used to carry arbitrary
+ extension-specific data from the server to the client. It is of the
+ following format:
+
+ uint32 id
+ ... any request-specific data ...
+
+ There is a range of packet types reserved for use by extensions. In
+ order to avoid collision, extensions that turn on the use of
+ additional packet types should determine those numbers dynamically.
+
+ The suggested way of doing this is have an extension request from the
+ client to the server that enables the extension; the extension
+ response from the server to the client would specify the actual type
+ values to use, in additional to any other data.
+
+ Extension authors should be mindful of the limited range of packet
+ types available (there are only 45 values available) and avoid
+ requiring a new packet type where possible.
+
+
+
+
+
+
+
+Galbraith, et al. Expires April 16, 2003 [Page 28]
+
+Internet-Draft SSH File Transfer Protocol October 2002
+
+
+9. Security Considerations
+
+ This protocol assumes that it is run over a secure channel and that
+ the endpoints of the channel have been authenticated. Thus, this
+ protocol assumes that it is externally protected from network-level
+ attacks.
+
+ This protocol provides file system access to arbitrary files on the
+ server (only constrained by the server implementation). It is the
+ responsibility of the server implementation to enforce any access
+ controls that may be required to limit the access allowed for any
+ particular user (the user being authenticated externally to this
+ protocol, typically using the SSH User Authentication Protocol [8].
+
+ Care must be taken in the server implementation to check the validity
+ of received file handle strings. The server should not rely on them
+ directly; it MUST check the validity of each handle before relying on
+ it.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Galbraith, et al. Expires April 16, 2003 [Page 29]
+
+Internet-Draft SSH File Transfer Protocol October 2002
+
+
+10. Changes from previous protocol versions
+
+ The SSH File Transfer Protocol has changed over time, before it's
+ standardization. The following is a description of the incompatible
+ changes between different versions.
+
+10.1 Changes between versions 4 and 3
+
+ Many of the changes between version 4 and version 3 are to the
+ attribute structure to make it more flexible for non-unix platforms.
+
+ o Make all filenames UTF-8.
+
+ o Added 'newline' extension.
+
+ o Made file attribute owner and group strings so they can actually
+ be used on disparate systems.
+
+ o Added createtime field, and added separate flags for atime,
+ createtime, and mtime so they can be set separately.
+
+ o Split the file type out of the permissions field and into it's own
+ field (which is always present.)
+
+ o Added acl attribute.
+
+ o Added SSH_FXF_TEXT file open flag.
+
+ o Added flags field to the get stat commands so that the client can
+ specifically request information the server might not normally
+ included for performance reasons.
+
+ o Removed the long filename from the names structure-- it can now be
+ built from information available in the attrs structure.
+
+ o Added reserved range of packet numbers for extensions.
+
+ o Added several additional error codes.
+
+ o Change the way version negotiate works slightly. Previously, if
+ the client version were higher than the server version, the server
+ was supposed to 'echo back' the clients version. The server now
+ sends it's own version and the lower of the two is considered to
+ be the one in use.
+
+
+
+
+
+
+
+Galbraith, et al. Expires April 16, 2003 [Page 30]
+
+Internet-Draft SSH File Transfer Protocol October 2002
+
+
+10.2 Changes between versions 3 and 2
+
+ o The SSH_FXP_READLINK and SSH_FXP_SYMLINK messages were added.
+
+ o The SSH_FXP_EXTENDED and SSH_FXP_EXTENDED_REPLY messages were
+ added.
+
+ o The SSH_FXP_STATUS message was changed to include fields `error
+ message' and `language tag'.
+
+
+10.3 Changes between versions 2 and 1
+
+ o The SSH_FXP_RENAME message was added.
+
+
+10.4 Changes between versions 1 and 0
+
+ o Implementation changes, no actual protocol changes.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Galbraith, et al. Expires April 16, 2003 [Page 31]
+
+Internet-Draft SSH File Transfer Protocol October 2002
+
+
+11. Trademark Issues
+
+ "ssh" is a registered trademark of SSH Communications Security Corp
+ in the United States and/or other countries.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Galbraith, et al. Expires April 16, 2003 [Page 32]
+
+Internet-Draft SSH File Transfer Protocol October 2002
+
+
+References
+
+ [1] Dierks, T., Allen, C., Treese, W., Karlton, P., Freier, A. and
+ P. Kocher, "The TLS Protocol Version 1.0", RFC 2246, January
+ 1999.
+
+ [2] Alvestrand, H., "IETF Policy on Character Sets and Languages",
+ BCP 18, RFC 2277, January 1998.
+
+ [3] Shepler, S., Callaghan, B., Robinson, D., Thurlow, R., Beame,
+ C., Eisler, M. and D. Noveck, "NFS version 4 Protocol", RFC
+ 3010, December 2000.
+
+ [4] Institute of Electrical and Electronics Engineers, "Information
+ Technology - Portable Operating System Interface (POSIX) - Part
+ 1: System Application Program Interface (API) [C Language]",
+ IEEE Standard 1003.2, 1996.
+
+ [5] Rinne, T., Ylonen, T., Kivinen, T., Saarinen, M. and S.
+ Lehtinen, "SSH Protocol Architecture", draft-ietf-secsh-
+ architecture-13 (work in progress), September 2002.
+
+ [6] Rinne, T., Ylonen, T., Kivinen, T., Saarinen, M. and S.
+ Lehtinen, "SSH Protocol Transport Protocol", draft-ietf-secsh-
+ transport-15 (work in progress), September 2002.
+
+ [7] Rinne, T., Ylonen, T., Kivinen, T., Saarinen, M. and S.
+ Lehtinen, "SSH Connection Protocol", draft-ietf-secsh-connect-16
+ (work in progress), September 2002.
+
+ [8] Rinne, T., Ylonen, T., Kivinen, T., Saarinen, M. and S.
+ Lehtinen, "SSH Authentication Protocol", draft-ietf-secsh-
+ userauth-16 (work in progress), September 2002.
+
+
+Authors' Addresses
+
+ Joseph Galbraith
+ VanDyke Software
+ 4848 Tramway Ridge Blvd
+ Suite 101
+ Albuquerque, NM 87111
+ US
+
+ Phone: +1 505 332 5700
+ EMail: galb-list@vandyke.com
+
+
+
+
+
+Galbraith, et al. Expires April 16, 2003 [Page 33]
+
+Internet-Draft SSH File Transfer Protocol October 2002
+
+
+ Tatu Ylonen
+ SSH Communications Security Corp
+ Fredrikinkatu 42
+ HELSINKI FIN-00100
+ Finland
+
+ EMail: ylo@ssh.com
+
+
+ Sami Lehtinen
+ SSH Communications Security Corp
+ Fredrikinkatu 42
+ HELSINKI FIN-00100
+ Finland
+
+ EMail: sjl@ssh.com
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Galbraith, et al. Expires April 16, 2003 [Page 34]
+
+Internet-Draft SSH File Transfer Protocol October 2002
+
+
+Full Copyright Statement
+
+ Copyright (C) The Internet Society (2002). All Rights Reserved.
+
+ This document and translations of it may be copied and furnished to
+ others, and derivative works that comment on or otherwise explain it
+ or assist in its implementation may be prepared, copied, published
+ and distributed, in whole or in part, without restriction of any
+ kind, provided that the above copyright notice and this paragraph are
+ included on all such copies and derivative works. However, this
+ document itself may not be modified in any way, such as by removing
+ the copyright notice or references to the Internet Society or other
+ Internet organizations, except as needed for the purpose of
+ developing Internet standards in which case the procedures for
+ copyrights defined in the Internet Standards process must be
+ followed, or as required to translate it into languages other than
+ English.
+
+ The limited permissions granted above are perpetual and will not be
+ revoked by the Internet Society or its successors or assigns.
+
+ This document and the information contained herein is provided on an
+ "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
+ TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
+ BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
+ HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
+ MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
+
+Acknowledgement
+
+ Funding for the RFC Editor function is currently provided by the
+ Internet Society.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Galbraith, et al. Expires April 16, 2003 [Page 35]
+
+
diff --git a/doc/draft-ietf-secsh-filexfer-04.txt b/doc/draft-ietf-secsh-filexfer-04.txt
new file mode 100644
index 00000000..9f51883c
--- /dev/null
+++ b/doc/draft-ietf-secsh-filexfer-04.txt
@@ -0,0 +1,2130 @@
+
+
+
+Secure Shell Working Group J. Galbraith
+Internet-Draft VanDyke Software
+Expires: June 18, 2003 T. Ylonen
+ S. Lehtinen
+ SSH Communications Security Corp
+ December 18, 2002
+
+
+ SSH File Transfer Protocol
+ draft-ietf-secsh-filexfer-04.txt
+
+Status of this Memo
+
+ This document is an Internet-Draft and is in full conformance with
+ all provisions of Section 10 of RFC2026.
+
+ Internet-Drafts are working documents of the Internet Engineering
+ Task Force (IETF), its areas, and its working groups. Note that
+ other groups may also distribute working documents as
+ Internet-Drafts.
+
+ Internet-Drafts are draft documents valid for a maximum of six months
+ and may be updated, replaced, or obsoleted by other documents at any
+ time. It is inappropriate to use Internet-Drafts as reference
+ material or to cite them other than as "work in progress."
+
+ The list of current Internet-Drafts can be accessed at http://
+ www.ietf.org/ietf/1id-abstracts.txt.
+
+ The list of Internet-Draft Shadow Directories can be accessed at
+ http://www.ietf.org/shadow.html.
+
+ This Internet-Draft will expire on June 18, 2003.
+
+Copyright Notice
+
+ Copyright (C) The Internet Society (2002). All Rights Reserved.
+
+Abstract
+
+ The SSH File Transfer Protocol provides secure file transfer
+ functionality over any reliable data stream. It is the standard file
+ transfer protocol for use with the SSH2 protocol. This document
+ describes the file transfer protocol and its interface to the SSH2
+ protocol suite.
+
+
+
+
+
+
+
+Galbraith, et al. Expires June 18, 2003 [Page 1]
+
+Internet-Draft SSH File Transfer Protocol December 2002
+
+
+Table of Contents
+
+ 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . 3
+ 2. Use with the SSH Connection Protocol . . . . . . . . . . . 4
+ 3. General Packet Format . . . . . . . . . . . . . . . . . . 5
+ 3.1 The use of stderr in the server . . . . . . . . . . . . . 6
+ 4. Protocol Initialization . . . . . . . . . . . . . . . . . 8
+ 4.1 Client Initialization . . . . . . . . . . . . . . . . . . 8
+ 4.2 Server Initialization . . . . . . . . . . . . . . . . . . 8
+ 4.3 Determining Server Newline Convention . . . . . . . . . . 9
+ 5. File Attributes . . . . . . . . . . . . . . . . . . . . . 10
+ 5.1 Flags . . . . . . . . . . . . . . . . . . . . . . . . . . 10
+ 5.2 Type . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
+ 5.3 Size . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
+ 5.4 Owner and Group . . . . . . . . . . . . . . . . . . . . . 11
+ 5.5 Permissions . . . . . . . . . . . . . . . . . . . . . . . 12
+ 5.6 Times . . . . . . . . . . . . . . . . . . . . . . . . . . 12
+ 5.7 ACL . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
+ 5.8 Extended attributes . . . . . . . . . . . . . . . . . . . 14
+ 6. Requests From the Client to the Server . . . . . . . . . . 15
+ 6.1 Request Synchronization and Reordering . . . . . . . . . . 15
+ 6.2 File Names . . . . . . . . . . . . . . . . . . . . . . . . 16
+ 6.3 Opening, Creating, and Closing Files . . . . . . . . . . . 16
+ 6.4 Reading and Writing . . . . . . . . . . . . . . . . . . . 19
+ 6.5 Removing and Renaming Files . . . . . . . . . . . . . . . 20
+ 6.6 Creating and Deleting Directories . . . . . . . . . . . . 21
+ 6.7 Scanning Directories . . . . . . . . . . . . . . . . . . . 21
+ 6.8 Retrieving File Attributes . . . . . . . . . . . . . . . . 22
+ 6.9 Setting File Attributes . . . . . . . . . . . . . . . . . 23
+ 6.10 Dealing with Symbolic links . . . . . . . . . . . . . . . 24
+ 6.11 Canonicalizing the Server-Side Path Name . . . . . . . . . 25
+ 6.11.1 Best practice for dealing with paths . . . . . . . . . . . 25
+ 7. Responses from the Server to the Client . . . . . . . . . 26
+ 8. Vendor-Specific Extensions . . . . . . . . . . . . . . . . 30
+ 9. Security Considerations . . . . . . . . . . . . . . . . . 31
+ 10. Changes from previous protocol versions . . . . . . . . . 32
+ 10.1 Changes between versions 4 and 3 . . . . . . . . . . . . . 32
+ 10.2 Changes between versions 3 and 2 . . . . . . . . . . . . . 33
+ 10.3 Changes between versions 2 and 1 . . . . . . . . . . . . . 33
+ 10.4 Changes between versions 1 and 0 . . . . . . . . . . . . . 33
+ 11. Trademark Issues . . . . . . . . . . . . . . . . . . . . . 34
+ References . . . . . . . . . . . . . . . . . . . . . . . . 35
+ Authors' Addresses . . . . . . . . . . . . . . . . . . . . 35
+ Intellectual Property and Copyright Statements . . . . . . 37
+
+
+
+
+
+
+
+Galbraith, et al. Expires June 18, 2003 [Page 2]
+
+Internet-Draft SSH File Transfer Protocol December 2002
+
+
+1. Introduction
+
+ This protocol provides secure file transfer (and more generally file
+ system access) functionality over a reliable data stream, such as a
+ channel in the SSH2 protocol [5].
+
+ This protocol is designed so that it could be used to implement a
+ secure remote file system service, as well as a secure file transfer
+ service.
+
+ This protocol assumes that it runs over a secure channel, and that
+ the server has already authenticated the user at the client end, and
+ that the identity of the client user is externally available to the
+ server implementation.
+
+ In general, this protocol follows a simple request-response model.
+ Each request and response contains a sequence number and multiple
+ requests may be pending simultaneously. There are a relatively large
+ number of different request messages, but a small number of possible
+ response messages. Each request has one or more response messages
+ that may be returned in result (e.g., a read either returns data or
+ reports error status).
+
+ The packet format descriptions in this specification follow the
+ notation presented in the secsh architecture draft. [5]
+
+ Even though this protocol is described in the context of the SSH2
+ protocol, this protocol is general and independent of the rest of the
+ SSH2 protocol suite. It could be used in a number of different
+ applications, such as secure file transfer over TLS RFC 2246 [1] and
+ transfer of management information in VPN applications.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Galbraith, et al. Expires June 18, 2003 [Page 3]
+
+Internet-Draft SSH File Transfer Protocol December 2002
+
+
+2. Use with the SSH Connection Protocol
+
+ When used with the SSH2 Protocol suite, this protocol is intended to
+ be used from the SSH Connection Protocol [7] as a subsystem, as
+ described in section ``Starting a Shell or a Command''. The
+ subsystem name used with this protocol is "sftp".
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Galbraith, et al. Expires June 18, 2003 [Page 4]
+
+Internet-Draft SSH File Transfer Protocol December 2002
+
+
+3. General Packet Format
+
+ All packets transmitted over the secure connection are of the
+ following format:
+
+ uint32 length
+ byte type
+ byte[length - 1] data payload
+
+ That is, they are just data preceded by 32-bit length and 8-bit type
+ fields. The `length' is the length of the data area, and does not
+ include the `length' field itself. The format and interpretation of
+ the data area depends on the packet type.
+
+ All packet descriptions below only specify the packet type and the
+ data that goes into the data field. Thus, they should be prefixed by
+ the `length' and `type' fields.
+
+ The maximum size of a packet is in practice determined by the client
+ (the maximum size of read or write requests that it sends, plus a few
+ bytes of packet overhead). All servers SHOULD support packets of at
+ least 34000 bytes (where the packet size refers to the full length,
+ including the header above). This should allow for reads and writes
+ of at most 32768 bytes.
+
+ There is no limit on the number of outstanding (non-acknowledged)
+ requests that the client may send to the server. In practice this is
+ limited by the buffering available on the data stream and the queuing
+ performed by the server. If the server's queues are full, it should
+ not read any more data from the stream, and flow control will prevent
+ the client from sending more requests. Note, however, that while
+ there is no restriction on the protocol level, the client's API may
+ provide a limit in order to prevent infinite queuing of outgoing
+ requests at the client.
+
+ The following values are defined for packet types.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Galbraith, et al. Expires June 18, 2003 [Page 5]
+
+Internet-Draft SSH File Transfer Protocol December 2002
+
+
+ #define SSH_FXP_INIT 1
+ #define SSH_FXP_VERSION 2
+ #define SSH_FXP_OPEN 3
+ #define SSH_FXP_CLOSE 4
+ #define SSH_FXP_READ 5
+ #define SSH_FXP_WRITE 6
+ #define SSH_FXP_LSTAT 7
+ #define SSH_FXP_FSTAT 8
+ #define SSH_FXP_SETSTAT 9
+ #define SSH_FXP_FSETSTAT 10
+ #define SSH_FXP_OPENDIR 11
+ #define SSH_FXP_READDIR 12
+ #define SSH_FXP_REMOVE 13
+ #define SSH_FXP_MKDIR 14
+ #define SSH_FXP_RMDIR 15
+ #define SSH_FXP_REALPATH 16
+ #define SSH_FXP_STAT 17
+ #define SSH_FXP_RENAME 18
+ #define SSH_FXP_READLINK 19
+ #define SSH_FXP_SYMLINK 20
+
+ #define SSH_FXP_STATUS 101
+ #define SSH_FXP_HANDLE 102
+ #define SSH_FXP_DATA 103
+ #define SSH_FXP_NAME 104
+ #define SSH_FXP_ATTRS 105
+
+ #define SSH_FXP_EXTENDED 200
+ #define SSH_FXP_EXTENDED_REPLY 201
+
+ RESERVED_FOR_EXTENSIONS 210-255
+
+ Additional packet types should only be defined if the protocol
+ version number (see Section ``Protocol Initialization'') is
+ incremented, and their use MUST be negotiated using the version
+ number. However, the SSH_FXP_EXTENDED and SSH_FXP_EXTENDED_REPLY
+ packets can be used to implement vendor-specific extensions. See
+ Section ``Vendor-Specific-Extensions'' for more details.
+
+3.1 The use of stderr in the server
+
+ Packets are sent and received on stdout and stdin. Data sent on
+ stderr by the server SHOULD be considered debug or supplemental error
+ information, and MAY be displayed to the user.
+
+ For example, during initialization, there is no client request
+ active, so errors or warning information cannot be sent to the client
+ as part of the SFTP protocol at this early stage. However, the
+
+
+
+Galbraith, et al. Expires June 18, 2003 [Page 6]
+
+Internet-Draft SSH File Transfer Protocol December 2002
+
+
+ errors or warnings MAY be sent as stderr text.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Galbraith, et al. Expires June 18, 2003 [Page 7]
+
+Internet-Draft SSH File Transfer Protocol December 2002
+
+
+4. Protocol Initialization
+
+ When the file transfer protocol starts, the client first sends a
+ SSH_FXP_INIT (including its version number) packet to the server.
+ The server responds with a SSH_FXP_VERSION packet, supplying the
+ lowest of its own and the client's version number. Both parties
+ should from then on adhere to particular version of the protocol.
+
+ The version number of the protocol specified in this document is 4.
+ The version number should be incremented for each incompatible
+ revision of this protocol.
+
+4.1 Client Initialization
+
+ The SSH_FXP_INIT packet (from client to server) has the following
+ data:
+
+ uint32 version
+
+ Version 3 of this protocol allowed clients to include extensions in
+ the SSH_FXP_INIT packet; however, this can cause interoperability
+ problems with version 1 and version 2 servers because the client must
+ send this packet before knowing the servers version.
+
+ In this version of the protocol, clients MUST use the
+ SSH_FXP_EXTENDED packet to send extensions to the server after
+ version exchange has completed. Clients MUST NOT include extensions
+ in the version packet. This will prevent interoperability problems
+ with older servers
+
+4.2 Server Initialization
+
+ The SSH_FXP_VERSION packet (from server to client) has the following
+ data:
+
+ uint32 version
+ <extension data>
+
+ 'version' is the lower of the protocol version supported by the
+ server and the version number received from the client.
+
+ The extension data may be empty, or may be a sequence of
+
+ string extension_name
+ string extension_data
+
+ pairs (both strings MUST always be present if one is, but the
+ `extension_data' string may be of zero length). If present, these
+
+
+
+Galbraith, et al. Expires June 18, 2003 [Page 8]
+
+Internet-Draft SSH File Transfer Protocol December 2002
+
+
+ strings indicate extensions to the baseline protocol. The
+ `extension_name' field(s) identify the name of the extension. The
+ name should be of the form "name@domain", where the domain is the DNS
+ domain name of the organization defining the extension. Additional
+ names that are not of this format may be defined later by the IETF.
+ Implementations MUST silently ignore any extensions whose name they
+ do not recognize.
+
+4.3 Determining Server Newline Convention
+
+ In order to correctly process text files in a cross platform
+ compatible way, the newline convention must be converted from that of
+ the server to that of the client, or, during an upload, from that of
+ the client to that of the server.
+
+ Versions 3 and prior of this protocol made no provisions for
+ processing text files. Many clients implemented some sort of
+ conversion algorithm, but without either a 'canonical' on the wire
+ format or knowledge of the servers newline convention, correct
+ conversion was not always possible.
+
+ Starting with Version 4, the SSH_FXF_TEXT file open flag (Section
+ 6.3) makes it possible to request that the server translate a file to
+ a 'canonical' on the wire format. This format uses \r\n as the line
+ separator.
+
+ Servers for systems using multiple newline characters (for example,
+ Mac OS X or VMS) or systems using counted records, MUST translate to
+ the canonical form.
+
+ However, to ease the burden of implementation on servers that use a
+ single, simple separator sequence, the following extension allows the
+ canonical format to be changed.
+
+ string "newline"
+ string new-canonical-separator (usually "\r" or "\n" or "\r\n")
+
+ All clients MUST support this extension.
+
+ When processing text files, clients SHOULD NOT translate any
+ character or sequence that is not an exact match of the servers
+ newline separator.
+
+ In particular, if the newline sequence being used is the canonical
+ "\r\n" sequence, a lone \r or a lone \n SHOULD be written through
+ without change.
+
+
+
+
+
+Galbraith, et al. Expires June 18, 2003 [Page 9]
+
+Internet-Draft SSH File Transfer Protocol December 2002
+
+
+5. File Attributes
+
+ A new compound data type is defined for encoding file attributes.
+ The same encoding is used both when returning file attributes from
+ the server and when sending file attributes to the server. When
+ sending it to the server, the flags field specifies which attributes
+ are included, and the server will use default values for the
+ remaining attributes (or will not modify the values of remaining
+ attributes). When receiving attributes from the server, the flags
+ specify which attributes are included in the returned data. The
+ server normally returns all attributes it knows about.
+
+ uint32 flags
+ byte type always present
+ uint64 size present only if flag SIZE
+ string owner present only if flag OWNERGROUP
+ string group present only if flag OWNERGROUP
+ uint32 permissions present only if flag PERMISSIONS
+ uint64 atime present only if flag ACCESSTIME
+ uint32 atime_nseconds present only if flag SUBSECOND_TIMES
+ uint64 createtime present only if flag CREATETIME
+ uint32 createtime_nseconds present only if flag SUBSECOND_TIMES
+ uint64 mtime present only if flag MODIFYTIME
+ uint32 mtime_nseconds present only if flag SUBSECOND_TIMES
+ string acl present only if flag ACL
+ uint32 extended_count present only if flag EXTENDED
+ string extended_type
+ string extended_data
+ ... more extended data (extended_type - extended_data pairs),
+ so that number of pairs equals extended_count
+
+
+5.1 Flags
+
+ The `flags' specify which of the fields are present. Those fields
+ for which the corresponding flag is not set are not present (not
+ included in the packet). New flags can only be added by incrementing
+ the protocol version number (or by using the extension mechanism
+ described below).
+
+ The flags bits are defined to have the following values:
+
+
+
+
+
+
+
+
+
+
+Galbraith, et al. Expires June 18, 2003 [Page 10]
+
+Internet-Draft SSH File Transfer Protocol December 2002
+
+
+ #define SSH_FILEXFER_ATTR_SIZE 0x00000001
+ #define SSH_FILEXFER_ATTR_PERMISSIONS 0x00000040
+ #define SSH_FILEXFER_ATTR_ACCESSTIME 0x00000008
+ #define SSH_FILEXFER_ATTR_CREATETIME 0x00000010
+ #define SSH_FILEXFER_ATTR_MODIFYTIME 0x00000020
+ #define SSH_FILEXFER_ATTR_ACL 0x00000040
+ #define SSH_FILEXFER_ATTR_OWNERGROUP 0x00000080
+ #define SSH_FILEXFER_ATTR_SUBSECOND_TIMES 0x00000100
+ #define SSH_FILEXFER_ATTR_EXTENDED 0x80000000
+
+ In previous versions of this protocol flags value 0x00000002 was
+ SSH_FILEXFER_ATTR_UIDGID. This value is now unused, and OWNERGROUP
+ was given a new value in order to ease implementation burden.
+ 0x00000002 MUST NOT appear in the mask. Some future version of this
+ protocol may reuse flag 0x00000002.
+
+5.2 Type
+
+ The type field is always present. The following types are defined:
+
+ #define SSH_FILEXFER_TYPE_REGULAR 1
+ #define SSH_FILEXFER_TYPE_DIRECTORY 2
+ #define SSH_FILEXFER_TYPE_SYMLINK 3
+ #define SSH_FILEXFER_TYPE_SPECIAL 4
+ #define SSH_FILEXFER_TYPE_UNKNOWN 5
+
+ On a POSIX system, these values would be derived from the permission
+ field.
+
+5.3 Size
+
+ The `size' field specifies the size of the file on disk, in bytes.
+ If it is present during file creation, it should be considered a hint
+ as to the files eventual size.
+
+ Files opened with the SSH_FXF_TEXT flag may have a size that is
+ greater or less than the value of the size field.
+
+5.4 Owner and Group
+
+ The `owner' and `group' fields are represented as UTF-8 strings; this
+ is the form used by NFS v4. See NFS version 4 Protocol. [3] The
+ following text is selected quotations from section 5.6.
+
+ To avoid a representation that is tied to a particular underlying
+ implementation at the client or server, the use of UTF-8 strings has
+ been chosen. The string should be of the form user@dns_domain".
+ This will allow for a client and server that do not use the same
+
+
+
+Galbraith, et al. Expires June 18, 2003 [Page 11]
+
+Internet-Draft SSH File Transfer Protocol December 2002
+
+
+ local representation the ability to translate to a common syntax that
+ can be interpreted by both. In the case where there is no
+ translation available to the client or server, the attribute value
+ must be constructed without the "@". Therefore, the absence of the @
+ from the owner or owner_group attribute signifies that no translation
+ was available and the receiver of the attribute should not place any
+ special meaning with the attribute value. Even though the attribute
+ value can not be translated, it may still be useful. In the case of
+ a client, the attribute string may be used for local display of
+ ownership.
+
+5.5 Permissions
+
+ The `permissions' field contains a bit mask of file permissions as
+ defined by POSIX [1].
+
+5.6 Times
+
+ The 'atime', 'createtime', and 'mtime' contain the access, creation,
+ and modification times of the files, respectively. They are
+ represented as seconds from Jan 1, 1970 in UTC.
+
+ A negative value indicates number of seconds before Jan 1, 1970. In
+ both cases, if the SSH_FILEXFER_ATTR_SUBSECOND_TIMES flag is set, the
+ nseconds field is to be added to the seconds field for the final time
+ representation. For example, if the time to be represented is
+ one-half second before 0 hour January 1, 1970, the seconds field
+ would have a value of negative one (-1) and the nseconds fields would
+ have a value of one-half second (500000000). Values greater than
+ 999,999,999 for nseconds are considered invalid.
+
+5.7 ACL
+
+ The 'ACL' field contains an ACL similar to that defined in section
+ 5.9 of NFS version 4 Protocol [3].
+
+ uint32 ace-count
+
+ repeated ace-count time:
+ uint32 ace-type
+ uint32 ace-flag
+ uint32 ace-mask
+ string who [UTF-8]
+
+ ace-type is one of the following four values (taken from NFS Version
+ 4 Protocol [3]:
+
+
+
+
+
+Galbraith, et al. Expires June 18, 2003 [Page 12]
+
+Internet-Draft SSH File Transfer Protocol December 2002
+
+
+ const ACE4_ACCESS_ALLOWED_ACE_TYPE = 0x00000000;
+ const ACE4_ACCESS_DENIED_ACE_TYPE = 0x00000001;
+ const ACE4_SYSTEM_AUDIT_ACE_TYPE = 0x00000002;
+ const ACE4_SYSTEM_ALARM_ACE_TYPE = 0x00000003;
+
+ ace-flag is a combination of the following flag values. See NFS
+ Version 4 Protocol [3] section 5.9.2:
+
+ const ACE4_FILE_INHERIT_ACE = 0x00000001;
+ const ACE4_DIRECTORY_INHERIT_ACE = 0x00000002;
+ const ACE4_NO_PROPAGATE_INHERIT_ACE = 0x00000004;
+ const ACE4_INHERIT_ONLY_ACE = 0x00000008;
+ const ACE4_SUCCESSFUL_ACCESS_ACE_FLAG = 0x00000010;
+ const ACE4_FAILED_ACCESS_ACE_FLAG = 0x00000020;
+ const ACE4_IDENTIFIER_GROUP = 0x00000040;
+
+ ace-mask is any combination of the following flags (taken from NFS
+ Version 4 Protocol [3] section 5.9.3:
+
+ const ACE4_READ_DATA = 0x00000001;
+ const ACE4_LIST_DIRECTORY = 0x00000001;
+ const ACE4_WRITE_DATA = 0x00000002;
+ const ACE4_ADD_FILE = 0x00000002;
+ const ACE4_APPEND_DATA = 0x00000004;
+ const ACE4_ADD_SUBDIRECTORY = 0x00000004;
+ const ACE4_READ_NAMED_ATTRS = 0x00000008;
+ const ACE4_WRITE_NAMED_ATTRS = 0x00000010;
+ const ACE4_EXECUTE = 0x00000020;
+ const ACE4_DELETE_CHILD = 0x00000040;
+ const ACE4_READ_ATTRIBUTES = 0x00000080;
+ const ACE4_WRITE_ATTRIBUTES = 0x00000100;
+ const ACE4_DELETE = 0x00010000;
+ const ACE4_READ_ACL = 0x00020000;
+ const ACE4_WRITE_ACL = 0x00040000;
+ const ACE4_WRITE_OWNER = 0x00080000;
+ const ACE4_SYNCHRONIZE = 0x00100000;
+
+ who is a UTF-8 string of the form described in 'Owner and Group'
+ (Section 5.4)
+
+ Also, as per '5.9.4 ACE who' [3] there are several identifiers that
+ need to be understood universally. Some of these identifiers cannot
+ be understood when an client access the server, but have meaning when
+ a local process accesses the file. The ability to display and modify
+ these permissions is permitted over SFTP.
+
+ OWNER The owner of the file.
+
+
+
+
+Galbraith, et al. Expires June 18, 2003 [Page 13]
+
+Internet-Draft SSH File Transfer Protocol December 2002
+
+
+ GROUP The group associated with the file.
+
+ EVERYONE The world.
+
+ INTERACTIVE Accessed from an interactive terminal.
+
+ NETWORK Accessed via the network.
+
+ DIALUP Accessed as a dialup user to the server.
+
+ BATCH Accessed from a batch job.
+
+ ANONYMOUS Accessed without any authentication.
+
+ AUTHENTICATED Any authenticated user (opposite of ANONYMOUS).
+
+ SERVICE Access from a system service.
+
+ To avoid conflict, these special identifiers are distinguish by an
+ appended "@" and should appear in the form "xxxx@" (note: no domain
+ name after the "@"). For example: ANONYMOUS@.
+
+5.8 Extended attributes
+
+ The SSH_FILEXFER_ATTR_EXTENDED flag provides a general extension
+ mechanism for vendor-specific extensions. If the flag is specified,
+ then the `extended_count' field is present. It specifies the number
+ of extended_type-extended_data pairs that follow. Each of these
+ pairs specifies an extended attribute. For each of the attributes,
+ the extended_type field should be a string of the format
+ "name@domain", where "domain" is a valid, registered domain name and
+ "name" identifies the method. The IETF may later standardize certain
+ names that deviate from this format (e.g., that do not contain the
+ "@" sign). The interpretation of `extended_data' depends on the
+ type. Implementations SHOULD ignore extended data fields that they
+ do not understand.
+
+ Additional fields can be added to the attributes by either defining
+ additional bits to the flags field to indicate their presence, or by
+ defining extended attributes for them. The extended attributes
+ mechanism is recommended for most purposes; additional flags bits
+ should only be defined by an IETF standards action that also
+ increments the protocol version number. The use of such new fields
+ MUST be negotiated by the version number in the protocol exchange.
+ It is a protocol error if a packet with unsupported protocol bits is
+ received.
+
+
+
+
+
+Galbraith, et al. Expires June 18, 2003 [Page 14]
+
+Internet-Draft SSH File Transfer Protocol December 2002
+
+
+6. Requests From the Client to the Server
+
+ Requests from the client to the server represent the various file
+ system operations. Each request begins with an `id' field, which is
+ a 32-bit identifier identifying the request (selected by the client).
+ The same identifier will be returned in the response to the request.
+ One possible implementation is a monotonically increasing request
+ sequence number (modulo 2^32).
+
+ Many operations in the protocol operate on open files. The
+ SSH_FXP_OPEN request can return a file handle (which is an opaque
+ variable-length string) which may be used to access the file later
+ (e.g. in a read operation). The client MUST NOT send requests the
+ server with bogus or closed handles. However, the server MUST
+ perform adequate checks on the handle in order to avoid security
+ risks due to fabricated handles.
+
+ This design allows either stateful and stateless server
+ implementation, as well as an implementation which caches state
+ between requests but may also flush it. The contents of the file
+ handle string are entirely up to the server and its design. The
+ client should not modify or attempt to interpret the file handle
+ strings.
+
+ The file handle strings MUST NOT be longer than 256 bytes.
+
+6.1 Request Synchronization and Reordering
+
+ The protocol and implementations MUST process requests relating to
+ the same file in the order in which they are received. In other
+ words, if an application submits multiple requests to the server, the
+ results in the responses will be the same as if it had sent the
+ requests one at a time and waited for the response in each case. For
+ example, the server may process non-overlapping read/write requests
+ to the same file in parallel, but overlapping reads and writes cannot
+ be reordered or parallelized. However, there are no ordering
+ restrictions on the server for processing requests from two different
+ file transfer connections. The server may interleave and parallelize
+ them at will.
+
+ There are no restrictions on the order in which responses to
+ outstanding requests are delivered to the client, except that the
+ server must ensure fairness in the sense that processing of no
+ request will be indefinitely delayed even if the client is sending
+ other requests so that there are multiple outstanding requests all
+ the time.
+
+
+
+
+
+Galbraith, et al. Expires June 18, 2003 [Page 15]
+
+Internet-Draft SSH File Transfer Protocol December 2002
+
+
+6.2 File Names
+
+ This protocol represents file names as strings. File names are
+ assumed to use the slash ('/') character as a directory separator.
+
+ File names starting with a slash are "absolute", and are relative to
+ the root of the file system. Names starting with any other character
+ are relative to the user's default directory (home directory). Note
+ that identifying the user is assumed to take place outside of this
+ protocol.
+
+ Servers SHOULD interpret a path name component ".." as referring to
+ the parent directory, and "." as referring to the current directory.
+ If the server implementation limits access to certain parts of the
+ file system, it must be extra careful in parsing file names when
+ enforcing such restrictions. There have been numerous reported
+ security bugs where a ".." in a path name has allowed access outside
+ the intended area.
+
+ An empty path name is valid, and it refers to the user's default
+ directory (usually the user's home directory).
+
+ Otherwise, no syntax is defined for file names by this specification.
+ Clients should not make any other assumptions; however, they can
+ splice path name components returned by SSH_FXP_READDIR together
+ using a slash ('/') as the separator, and that will work as expected.
+
+ In order to comply with IETF Policy on Character Sets and Languages
+ [2], all filenames are to be encoded in UTF-8. The shortest valid
+ UTF-8 encoding of the UNICODE data MUST be used. The server is
+ responsible for converting the UNICODE data to whatever canonical
+ form it requires.
+
+ For example, if the server requires that precomposed characters
+ always be used, the server MUST NOT assume the filename as sent by
+ the client has this attribute, but must do this normalization itself.
+
+ It is understood that the lack of well-defined semantics for file
+ names may cause interoperability problems between clients and servers
+ using radically different operating systems. However, this approach
+ is known to work acceptably with most systems, and alternative
+ approaches that e.g. treat file names as sequences of structured
+ components are quite complicated.
+
+6.3 Opening, Creating, and Closing Files
+
+ Files are opened and created using the SSH_FXP_OPEN message, whose
+ data part is as follows:
+
+
+
+Galbraith, et al. Expires June 18, 2003 [Page 16]
+
+Internet-Draft SSH File Transfer Protocol December 2002
+
+
+ uint32 id
+ string filename [UTF-8]
+ uint32 pflags
+ ATTRS attrs
+
+ The `id' field is the request identifier as for all requests.
+
+ The `filename' field specifies the file name. See Section ``File
+ Names'' for more information.
+
+ The `pflags' field is a bitmask. The following bits have been
+ defined.
+
+ #define SSH_FXF_READ 0x00000001
+ #define SSH_FXF_WRITE 0x00000002
+ #define SSH_FXF_APPEND 0x00000004
+ #define SSH_FXF_CREAT 0x00000008
+ #define SSH_FXF_TRUNC 0x00000010
+ #define SSH_FXF_EXCL 0x00000020
+ #define SSH_FXF_TEXT 0x00000040
+
+ These have the following meanings:
+
+ SSH_FXF_READ
+ Open the file for reading.
+
+ SSH_FXF_WRITE
+ Open the file for writing. If both this and SSH_FXF_READ are
+ specified, the file is opened for both reading and writing.
+
+ SSH_FXF_APPEND
+ Force all writes to append data at the end of the file. The
+ offset parameter to write will be ignored.
+
+ SSH_FXF_CREAT
+ If this flag is specified, then a new file will be created if one
+ does not already exist (if O_TRUNC is specified, the new file will
+ be truncated to zero length if it previously exists).
+
+ SSH_FXF_TRUNC
+ Forces an existing file with the same name to be truncated to zero
+ length when creating a file by specifying SSH_FXF_CREAT.
+ SSH_FXF_CREAT MUST also be specified if this flag is used.
+
+ SSH_FXF_EXCL
+ Causes the request to fail if the named file already exists.
+ SSH_FXF_CREAT MUST also be specified if this flag is used.
+
+
+
+
+Galbraith, et al. Expires June 18, 2003 [Page 17]
+
+Internet-Draft SSH File Transfer Protocol December 2002
+
+
+ SSH_FXF_TEXT
+ Indicates that the server should treat the file as text and
+ convert it to the canonical newline convention in use. (See
+ Determining Server Newline Convention. (Section 4.3)
+
+ When a file is opened with the FXF_TEXT flag, the offset field in
+ both the read and write function are ignored.
+
+ Servers MUST correctly process multiple parallel reads and writes
+ correctly in this mode. Naturally, it is permissible for them to
+ do this by serializing the requests. It would not be possible for
+ a client to reliably detect a server that does not implement
+ parallel writes in time to prevent damage.
+
+ Clients SHOULD use the SSH_FXF_APPEND flag to append data to a
+ text file rather then using write with a calculated offset.
+
+ To support seeks on text file the following SSH_FXP_EXTENDED
+ packet is defined.
+
+
+
+ string "text-seek"
+ string file-handle
+ uint64 line-number
+
+ line-number is the index of the line number to seek to, where byte
+ 0 in the file is line number 0, and the byte directly following
+ the first newline sequence in the file is line number 1 and so on.
+
+ The response to a "text-seek" request is an SSH_FXP_STATUS
+ message.
+
+ An attempt to seek past the end-of-file should result in a
+ SSH_FX_EOF status.
+
+ Servers SHOULD support at least one "text-seek" in order to
+ support resume. However, a client MUST be prepared to receive
+ SSH_FX_OP_UNSUPPORTED when attempting a "text-seek" operation.
+ The client can then try a fall-back strategy, if it has one.
+
+ Clients MUST be prepared to handle SSH_FX_OP_UNSUPPORTED returned
+ for read or write operations that are not sequential.
+
+ The `attrs' field specifies the initial attributes for the file.
+ Default values will be used for those attributes that are not
+ specified. See Section ``File Attributes'' for more information.
+
+
+
+
+Galbraith, et al. Expires June 18, 2003 [Page 18]
+
+Internet-Draft SSH File Transfer Protocol December 2002
+
+
+ The response to this message will be either SSH_FXP_HANDLE (if the
+ operation is successful) or SSH_FXP_STATUS (if the operation fails).
+
+ A file is closed by using the SSH_FXP_CLOSE request. Its data field
+ has the following format:
+
+ uint32 id
+ string handle
+
+ where `id' is the request identifier, and `handle' is a handle
+ previously returned in the response to SSH_FXP_OPEN or
+ SSH_FXP_OPENDIR. The handle becomes invalid immediately after this
+ request has been sent.
+
+ The response to this request will be a SSH_FXP_STATUS message. One
+ should note that on some server platforms even a close can fail.
+ This can happen e.g. if the server operating system caches writes,
+ and an error occurs while flushing cached writes during the close.
+
+6.4 Reading and Writing
+
+ Once a file has been opened, it can be read using the following
+ message:
+
+ byte SSH_FXP_READ
+ uint32 id
+ string handle
+ uint64 offset
+ uint32 len
+
+ where `id' is the request identifier, `handle' is an open file handle
+ returned by SSH_FXP_OPEN, `offset' is the offset (in bytes) relative
+ to the beginning of the file from where to start reading, and `len'
+ is the maximum number of bytes to read.
+
+ In response to this request, the server will read as many bytes as it
+ can from the file (up to `len'), and return them in a SSH_FXP_DATA
+ message. If an error occurs or EOF is encountered before reading any
+ data, the server will respond with SSH_FXP_STATUS.
+
+ For normal disk files, it is normally guaranteed that this will read
+ the specified number of bytes, or up to end of file. However, if the
+ read length is very long, the server may truncate it if it doesn't
+ support packets of that length. See General Packet Format (Section
+ 3).
+
+ For e.g. device files this may return fewer bytes than requested.
+
+
+
+
+Galbraith, et al. Expires June 18, 2003 [Page 19]
+
+Internet-Draft SSH File Transfer Protocol December 2002
+
+
+ Writing to a file is achieved using the following message:
+
+ byte SSH_FXP_WRITE
+ uint32 id
+ string handle
+ uint64 offset
+ string data
+
+ where `id' is a request identifier, `handle' is a file handle
+ returned by SSH_FXP_OPEN, `offset' is the offset (in bytes) from the
+ beginning of the file where to start writing, and `data' is the data
+ to be written.
+
+ The write will extend the file if writing beyond the end of the file.
+ It is legal to write way beyond the end of the file; the semantics
+ are to write zeroes from the end of the file to the specified offset
+ and then the data. On most operating systems, such writes do not
+ allocate disk space but instead leave "holes" in the file.
+
+ The server responds to a write request with a SSH_FXP_STATUS message.
+
+6.5 Removing and Renaming Files
+
+ Files can be removed using the SSH_FXP_REMOVE message. It has the
+ following format:
+
+ uint32 id
+ string filename [UTF-8]
+
+ where `id' is the request identifier and `filename' is the name of
+ the file to be removed. See Section ``File Names'' for more
+ information. This request cannot be used to remove directories.
+
+ The server will respond to this request with a SSH_FXP_STATUS
+ message.
+
+ Files (and directories) can be renamed using the SSH_FXP_RENAME
+ message. Its data is as follows:
+
+ uint32 id
+ string oldpath [UTF-8]
+ string newpath [UTF-8]
+
+ where `id' is the request identifier, `oldpath' is the name of an
+ existing file or directory, and `newpath' is the new name for the
+ file or directory. It is an error if there already exists a file
+ with the name specified by newpath. The server may also fail rename
+ requests in other situations, for example if `oldpath' and `newpath'
+
+
+
+Galbraith, et al. Expires June 18, 2003 [Page 20]
+
+Internet-Draft SSH File Transfer Protocol December 2002
+
+
+ point to different file systems on the server.
+
+ The server will respond to this request with a SSH_FXP_STATUS
+ message.
+
+6.6 Creating and Deleting Directories
+
+ New directories can be created using the SSH_FXP_MKDIR request. It
+ has the following format:
+
+ uint32 id
+ string path [UTF-8]
+ ATTRS attrs
+
+ where `id' is the request identifier.
+
+ `path' specifies the directory to be created. See Section ``File
+ Names'' for more information on file names.
+
+ `attrs' specifies the attributes that should be applied to it upon
+ creation. Attributes are discussed in more detail in Section ``File
+ Attributes''.
+
+ The server will respond to this request with a SSH_FXP_STATUS
+ message. If a file or directory with the specified path already
+ exists, an error will be returned.
+
+ Directories can be removed using the SSH_FXP_RMDIR request, which has
+ the following format:
+
+ uint32 id
+ string path [UTF-8]
+
+ where `id' is the request identifier, and `path' specifies the
+ directory to be removed. See Section ``File Names'' for more
+ information on file names.
+
+ The server responds to this request with a SSH_FXP_STATUS message.
+ Errors may be returned from this operation for various reasons,
+ including, but not limited to, the path does not exist, the path does
+ not refer to a directory object, the directory is not empty, or the
+ user has insufficient access or permission to perform the requested
+ operation.
+
+6.7 Scanning Directories
+
+ The files in a directory can be listed using the SSH_FXP_OPENDIR and
+ SSH_FXP_READDIR requests. Each SSH_FXP_READDIR request returns one
+
+
+
+Galbraith, et al. Expires June 18, 2003 [Page 21]
+
+Internet-Draft SSH File Transfer Protocol December 2002
+
+
+ or more file names with full file attributes for each file. The
+ client should call SSH_FXP_READDIR repeatedly until it has found the
+ file it is looking for or until the server responds with a
+ SSH_FXP_STATUS message indicating an error (normally SSH_FX_EOF if
+ there are no more files in the directory). The client should then
+ close the handle using the SSH_FXP_CLOSE request.
+
+ The SSH_FXP_OPENDIR opens a directory for reading. It has the
+ following format:
+
+ uint32 id
+ string path [UTF-8]
+
+ where `id' is the request identifier and `path' is the path name of
+ the directory to be listed (without any trailing slash). See Section
+ ``File Names'' for more information on file names. This will return
+ an error if the path does not specify a directory or if the directory
+ is not readable. The server will respond to this request with either
+ a SSH_FXP_HANDLE or a SSH_FXP_STATUS message.
+
+ Once the directory has been successfully opened, files (and
+ directories) contained in it can be listed using SSH_FXP_READDIR
+ requests. These are of the format
+
+ uint32 id
+ string handle
+
+ where `id' is the request identifier, and `handle' is a handle
+ returned by SSH_FXP_OPENDIR. (It is a protocol error to attempt to
+ use an ordinary file handle returned by SSH_FXP_OPEN.)
+
+ The server responds to this request with either a SSH_FXP_NAME or a
+ SSH_FXP_STATUS message. One or more names may be returned at a time.
+ Full status information is returned for each name in order to speed
+ up typical directory listings.
+
+ If there are no more names available to be read, the server MUST
+ respond with a SSH_FXP_STATUS message with error code of SSH_FX_EOF.
+
+ When the client no longer wishes to read more names from the
+ directory, it SHOULD call SSH_FXP_CLOSE for the handle. The handle
+ should be closed regardless of whether an error has occurred or not.
+
+6.8 Retrieving File Attributes
+
+ Very often, file attributes are automatically returned by
+ SSH_FXP_READDIR. However, sometimes there is need to specifically
+ retrieve the attributes for a named file. This can be done using the
+
+
+
+Galbraith, et al. Expires June 18, 2003 [Page 22]
+
+Internet-Draft SSH File Transfer Protocol December 2002
+
+
+ SSH_FXP_STAT, SSH_FXP_LSTAT and SSH_FXP_FSTAT requests.
+
+ SSH_FXP_STAT and SSH_FXP_LSTAT only differ in that SSH_FXP_STAT
+ follows symbolic links on the server, whereas SSH_FXP_LSTAT does not
+ follow symbolic links. Both have the same format:
+
+ uint32 id
+ string path [UTF-8]
+ uint32 flags
+
+ where `id' is the request identifier, and `path' specifies the file
+ system object for which status is to be returned. The server
+ responds to this request with either SSH_FXP_ATTRS or SSH_FXP_STATUS.
+
+ The flags field specify the attribute flags in which the client has
+ particular interest. This is a hint to the server. For example,
+ because retrieving owner / group and acl information can be an
+ expensive operation under some operating systems, the server may
+ choose not to retrieve this information unless the client expresses a
+ specific interest in it.
+
+ The client has no guarantee the server will provide all the fields
+ that it has expressed an interest in.
+
+ SSH_FXP_FSTAT differs from the others in that it returns status
+ information for an open file (identified by the file handle). Its
+ format is as follows:
+
+ uint32 id
+ string handle
+ uint32 flags
+
+ where `id' is the request identifier and `handle' is a file handle
+ returned by SSH_FXP_OPEN. The server responds to this request with
+ SSH_FXP_ATTRS or SSH_FXP_STATUS.
+
+6.9 Setting File Attributes
+
+ File attributes may be modified using the SSH_FXP_SETSTAT and
+ SSH_FXP_FSETSTAT requests. These requests are used for operations
+ such as changing the ownership, permissions or access times, as well
+ as for truncating a file.
+
+ The SSH_FXP_SETSTAT request is of the following format:
+
+
+
+
+
+
+
+Galbraith, et al. Expires June 18, 2003 [Page 23]
+
+Internet-Draft SSH File Transfer Protocol December 2002
+
+
+ uint32 id
+ string path [UTF-8]
+ ATTRS attrs
+
+ where `id' is the request identifier, `path' specifies the file
+ system object (e.g. file or directory) whose attributes are to be
+ modified, and `attrs' specifies the modifications to be made to its
+ attributes. Attributes are discussed in more detail in Section
+ ``File Attributes''.
+
+ An error will be returned if the specified file system object does
+ not exist or the user does not have sufficient rights to modify the
+ specified attributes. The server responds to this request with a
+ SSH_FXP_STATUS message.
+
+ The SSH_FXP_FSETSTAT request modifies the attributes of a file which
+ is already open. It has the following format:
+
+ uint32 id
+ string handle
+ ATTRS attrs
+
+ where `id' is the request identifier, `handle' (MUST be returned by
+ SSH_FXP_OPEN) identifies the file whose attributes are to be
+ modified, and `attrs' specifies the modifications to be made to its
+ attributes. Attributes are discussed in more detail in Section
+ ``File Attributes''. The server will respond to this request with
+ SSH_FXP_STATUS.
+
+6.10 Dealing with Symbolic links
+
+ The SSH_FXP_READLINK request may be used to read the target of a
+ symbolic link. It would have a data part as follows:
+
+ uint32 id
+ string path [UTF-8]
+
+ where `id' is the request identifier and `path' specifies the path
+ name of the symlink to be read.
+
+ The server will respond with a SSH_FXP_NAME packet containing only
+ one name and a dummy attributes value. The name in the returned
+ packet contains the target of the link. If an error occurs, the
+ server may respond with SSH_FXP_STATUS.
+
+ The SSH_FXP_SYMLINK request will create a symbolic link on the
+ server. It is of the following format
+
+
+
+
+Galbraith, et al. Expires June 18, 2003 [Page 24]
+
+Internet-Draft SSH File Transfer Protocol December 2002
+
+
+ uint32 id
+ string linkpath [UTF-8]
+ string targetpath [UTF-8]
+
+ where `id' is the request identifier, `linkpath' specifies the path
+ name of the symlink to be created and `targetpath' specifies the
+ target of the symlink. The server shall respond with a
+ SSH_FXP_STATUS indicating either success (SSH_FX_OK) or an error
+ condition.
+
+6.11 Canonicalizing the Server-Side Path Name
+
+ The SSH_FXP_REALPATH request can be used to have the server
+ canonicalize any given path name to an absolute path. This is useful
+ for converting path names containing ".." components or relative
+ pathnames without a leading slash into absolute paths. The format of
+ the request is as follows:
+
+ uint32 id
+ string path [UTF-8]
+
+ where `id' is the request identifier and `path' specifies the path
+ name to be canonicalized. The server will respond with a
+ SSH_FXP_NAME packet containing the name in canonical form and a dummy
+ attributes value. If an error occurs, the server may also respond
+ with SSH_FXP_STATUS.
+
+6.11.1 Best practice for dealing with paths
+
+ The client SHOULD treat the results of SSH_FXP_REALPATH as a
+ canonical absolute path, even if the path does not appear to be
+ absolute. A client that use REALPATH(".") and treats the result as
+ absolute, even if there is no leading slash, will continue to
+ function correctly, even when talking to a Windows NT or VMS style
+ system, where absolute paths may not begin with a slash.
+
+ For example, if the client wishes to change directory up, and the
+ server has returned "c:/x/y/z" from REALPATH, the client SHOULD use
+ "c:/x/y/z/..".
+
+ As a second example, if the client wishes to open the file "x.txt" in
+ the current directory, and server has returned "dka100:/x/y/z" as the
+ canonical path of the directory, the client SHOULD open "dka100:/x/y/
+ z/x.txt"
+
+
+
+
+
+
+
+Galbraith, et al. Expires June 18, 2003 [Page 25]
+
+Internet-Draft SSH File Transfer Protocol December 2002
+
+
+7. Responses from the Server to the Client
+
+ The server responds to the client using one of a few response
+ packets. All requests can return a SSH_FXP_STATUS response upon
+ failure. When the operation is successful, any of the responses may
+ be returned (depending on the operation). If no data needs to be
+ returned to the client, the SSH_FXP_STATUS response with SSH_FX_OK
+ status is appropriate. Otherwise, the SSH_FXP_HANDLE message is used
+ to return a file handle (for SSH_FXP_OPEN and SSH_FXP_OPENDIR
+ requests), SSH_FXP_DATA is used to return data from SSH_FXP_READ,
+ SSH_FXP_NAME is used to return one or more file names from a
+ SSH_FXP_READDIR or SSH_FXP_REALPATH request, and SSH_FXP_ATTRS is
+ used to return file attributes from SSH_FXP_STAT, SSH_FXP_LSTAT, and
+ SSH_FXP_FSTAT requests.
+
+ Exactly one response will be returned for each request. Each
+ response packet contains a request identifier which can be used to
+ match each response with the corresponding request. Note that it is
+ legal to have several requests outstanding simultaneously, and the
+ server is allowed to send responses to them in a different order from
+ the order in which the requests were sent (the result of their
+ execution, however, is guaranteed to be as if they had been processed
+ one at a time in the order in which the requests were sent).
+
+ Response packets are of the same general format as request packets.
+ Each response packet begins with the request identifier.
+
+ The format of the data portion of the SSH_FXP_STATUS response is as
+ follows:
+
+ uint32 id
+ uint32 error/status code
+ string error message (ISO-10646 UTF-8 [RFC-2279])
+ string language tag (as defined in [RFC-1766])
+
+ where `id' is the request identifier, and `error/status code'
+ indicates the result of the requested operation. The value SSH_FX_OK
+ indicates success, and all other values indicate failure.
+
+ Currently, the following values are defined (other values may be
+ defined by future versions of this protocol):
+
+
+
+
+
+
+
+
+
+
+Galbraith, et al. Expires June 18, 2003 [Page 26]
+
+Internet-Draft SSH File Transfer Protocol December 2002
+
+
+ #define SSH_FX_OK 0
+ #define SSH_FX_EOF 1
+ #define SSH_FX_NO_SUCH_FILE 2
+ #define SSH_FX_PERMISSION_DENIED 3
+ #define SSH_FX_FAILURE 4
+ #define SSH_FX_BAD_MESSAGE 5
+ #define SSH_FX_NO_CONNECTION 6
+ #define SSH_FX_CONNECTION_LOST 7
+ #define SSH_FX_OP_UNSUPPORTED 8
+ #define SSH_FX_INVALID_HANDLE 9
+ #define SSH_FX_NO_SUCH_PATH 10
+ #define SSH_FX_FILE_ALREADY_EXISTS 11
+ #define SSH_FX_WRITE_PROTECT 12
+ #define SSH_FX_NO_MEDIA 13
+
+ SSH_FX_OK
+ Indicates successful completion of the operation.
+
+ SSH_FX_EOF
+ indicates end-of-file condition; for SSH_FX_READ it means that no
+ more data is available in the file, and for SSH_FX_READDIR it
+ indicates that no more files are contained in the directory.
+
+ SSH_FX_NO_SUCH_FILE
+ is returned when a reference is made to a file which does not
+ exist.
+
+ SSH_FX_PERMISSION_DENIED
+ is returned when the authenticated user does not have sufficient
+ permissions to perform the operation.
+
+ SSH_FX_FAILURE
+ is a generic catch-all error message; it should be returned if an
+ error occurs for which there is no more specific error code
+ defined.
+
+ SSH_FX_BAD_MESSAGE
+ may be returned if a badly formatted packet or protocol
+ incompatibility is detected.
+
+ SSH_FX_NO_CONNECTION
+ is a pseudo-error which indicates that the client has no
+ connection to the server (it can only be generated locally by the
+ client, and MUST NOT be returned by servers).
+
+ SSH_FX_CONNECTION_LOST
+ is a pseudo-error which indicates that the connection to the
+ server has been lost (it can only be generated locally by the
+
+
+
+Galbraith, et al. Expires June 18, 2003 [Page 27]
+
+Internet-Draft SSH File Transfer Protocol December 2002
+
+
+ client, and MUST NOT be returned by servers).
+
+ SSH_FX_OP_UNSUPPORTED
+ indicates that an attempt was made to perform an operation which
+ is not supported for the server (it may be generated locally by
+ the client if e.g. the version number exchange indicates that a
+ required feature is not supported by the server, or it may be
+ returned by the server if the server does not implement an
+ operation).
+
+ SSH_FX_INVALID_HANDLE
+ The handle value was invalid.
+
+ SSH_FX_NO_SUCH_PATH
+ The file path does not exist or is invalid.
+
+ SSH_FX_FILE_ALREADY_EXISTS
+ The file already exists.
+
+ SSH_FX_WRITE_PROTECT
+ The file is on read only media, or the media is write protected.
+
+ SSH_FX_NO_MEDIA
+ The requested operation can not be completed because there is no
+ media available in the drive.
+
+ The SSH_FXP_HANDLE response has the following format:
+
+ uint32 id
+ string handle
+
+ where `id' is the request identifier, and `handle' is an arbitrary
+ string that identifies an open file or directory on the server. The
+ handle is opaque to the client; the client MUST NOT attempt to
+ interpret or modify it in any way. The length of the handle string
+ MUST NOT exceed 256 data bytes.
+
+ The SSH_FXP_DATA response has the following format:
+
+ uint32 id
+ string data
+
+ where `id' is the request identifier, and `data' is an arbitrary byte
+ string containing the requested data. The data string may be at most
+ the number of bytes requested in a SSH_FXP_READ request, but may also
+ be shorter if end of file is reached or if the read is from something
+ other than a regular file.
+
+
+
+
+Galbraith, et al. Expires June 18, 2003 [Page 28]
+
+Internet-Draft SSH File Transfer Protocol December 2002
+
+
+ The SSH_FXP_NAME response has the following format:
+
+ uint32 id
+ uint32 count
+ repeats count times:
+ string filename [UTF-8]
+ ATTRS attrs
+
+ where `id' is the request identifier, `count' is the number of names
+ returned in this response, and the remaining fields repeat `count'
+ times (so that all three fields are first included for the first
+ file, then for the second file, etc). In the repeated part,
+ `filename' is a file name being returned (for SSH_FXP_READDIR, it
+ will be a relative name within the directory, without any path
+ components; for SSH_FXP_REALPATH it will be an absolute path name),
+ and `attrs' is the attributes of the file as described in Section
+ ``File Attributes''.
+
+ The SSH_FXP_ATTRS response has the following format:
+
+ uint32 id
+ ATTRS attrs
+
+ where `id' is the request identifier, and `attrs' is the returned
+ file attributes as described in Section ``File Attributes''.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Galbraith, et al. Expires June 18, 2003 [Page 29]
+
+Internet-Draft SSH File Transfer Protocol December 2002
+
+
+8. Vendor-Specific Extensions
+
+ The SSH_FXP_EXTENDED request provides a generic extension mechanism
+ for adding vendor-specific commands. The request has the following
+ format:
+
+ uint32 id
+ string extended-request
+ ... any request-specific data ...
+
+ where `id' is the request identifier, and `extended-request' is a
+ string of the format "name@domain", where domain is an internet
+ domain name of the vendor defining the request. The rest of the
+ request is completely vendor-specific, and servers should only
+ attempt to interpret it if they recognize the `extended-request'
+ name.
+
+ The server may respond to such requests using any of the response
+ packets defined in Section ``Responses from the Server to the
+ Client''. Additionally, the server may also respond with a
+ SSH_FXP_EXTENDED_REPLY packet, as defined below. If the server does
+ not recognize the `extended-request' name, then the server MUST
+ respond with SSH_FXP_STATUS with error/status set to
+ SSH_FX_OP_UNSUPPORTED.
+
+ The SSH_FXP_EXTENDED_REPLY packet can be used to carry arbitrary
+ extension-specific data from the server to the client. It is of the
+ following format:
+
+ uint32 id
+ ... any request-specific data ...
+
+ There is a range of packet types reserved for use by extensions. In
+ order to avoid collision, extensions that turn on the use of
+ additional packet types should determine those numbers dynamically.
+
+ The suggested way of doing this is have an extension request from the
+ client to the server that enables the extension; the extension
+ response from the server to the client would specify the actual type
+ values to use, in additional to any other data.
+
+ Extension authors should be mindful of the limited range of packet
+ types available (there are only 45 values available) and avoid
+ requiring a new packet type where possible.
+
+
+
+
+
+
+
+Galbraith, et al. Expires June 18, 2003 [Page 30]
+
+Internet-Draft SSH File Transfer Protocol December 2002
+
+
+9. Security Considerations
+
+ This protocol assumes that it is run over a secure channel and that
+ the endpoints of the channel have been authenticated. Thus, this
+ protocol assumes that it is externally protected from network-level
+ attacks.
+
+ This protocol provides file system access to arbitrary files on the
+ server (only constrained by the server implementation). It is the
+ responsibility of the server implementation to enforce any access
+ controls that may be required to limit the access allowed for any
+ particular user (the user being authenticated externally to this
+ protocol, typically using the SSH User Authentication Protocol [8].
+
+ Care must be taken in the server implementation to check the validity
+ of received file handle strings. The server should not rely on them
+ directly; it MUST check the validity of each handle before relying on
+ it.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Galbraith, et al. Expires June 18, 2003 [Page 31]
+
+Internet-Draft SSH File Transfer Protocol December 2002
+
+
+10. Changes from previous protocol versions
+
+ The SSH File Transfer Protocol has changed over time, before it's
+ standardization. The following is a description of the incompatible
+ changes between different versions.
+
+10.1 Changes between versions 4 and 3
+
+ Many of the changes between version 4 and version 3 are to the
+ attribute structure to make it more flexible for non-unix platforms.
+
+ o Clarify the use of stderr by the server.
+
+ o Clarify handling of very large read requests by the server.
+
+ o Make all filenames UTF-8.
+
+ o Added 'newline' extension.
+
+ o Made time fields 64 bit, and optionally have nanosecond resultion.
+
+ o Made file attribute owner and group strings so they can actually
+ be used on disparate systems.
+
+ o Added createtime field, and added separate flags for atime,
+ createtime, and mtime so they can be set separately.
+
+ o Split the file type out of the permissions field and into it's own
+ field (which is always present.)
+
+ o Added acl attribute.
+
+ o Added SSH_FXF_TEXT file open flag.
+
+ o Added flags field to the get stat commands so that the client can
+ specifically request information the server might not normally
+ included for performance reasons.
+
+ o Removed the long filename from the names structure-- it can now be
+ built from information available in the attrs structure.
+
+ o Added reserved range of packet numbers for extensions.
+
+ o Added several additional error codes.
+
+
+
+
+
+
+
+Galbraith, et al. Expires June 18, 2003 [Page 32]
+
+Internet-Draft SSH File Transfer Protocol December 2002
+
+
+10.2 Changes between versions 3 and 2
+
+ o The SSH_FXP_READLINK and SSH_FXP_SYMLINK messages were added.
+
+ o The SSH_FXP_EXTENDED and SSH_FXP_EXTENDED_REPLY messages were
+ added.
+
+ o The SSH_FXP_STATUS message was changed to include fields `error
+ message' and `language tag'.
+
+
+10.3 Changes between versions 2 and 1
+
+ o The SSH_FXP_RENAME message was added.
+
+
+10.4 Changes between versions 1 and 0
+
+ o Implementation changes, no actual protocol changes.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Galbraith, et al. Expires June 18, 2003 [Page 33]
+
+Internet-Draft SSH File Transfer Protocol December 2002
+
+
+11. Trademark Issues
+
+ "ssh" is a registered trademark of SSH Communications Security Corp
+ in the United States and/or other countries.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Galbraith, et al. Expires June 18, 2003 [Page 34]
+
+Internet-Draft SSH File Transfer Protocol December 2002
+
+
+References
+
+ [1] Dierks, T., Allen, C., Treese, W., Karlton, P., Freier, A. and
+ P. Kocher, "The TLS Protocol Version 1.0", RFC 2246, January
+ 1999.
+
+ [2] Alvestrand, H., "IETF Policy on Character Sets and Languages",
+ BCP 18, RFC 2277, January 1998.
+
+ [3] Shepler, S., Callaghan, B., Robinson, D., Thurlow, R., Beame,
+ C., Eisler, M. and D. Noveck, "NFS version 4 Protocol", RFC
+ 3010, December 2000.
+
+ [4] Institute of Electrical and Electronics Engineers, "Information
+ Technology - Portable Operating System Interface (POSIX) - Part
+ 1: System Application Program Interface (API) [C Language]",
+ IEEE Standard 1003.2, 1996.
+
+ [5] Rinne, T., Ylonen, T., Kivinen, T., Saarinen, M. and S.
+ Lehtinen, "SSH Protocol Architecture",
+ draft-ietf-secsh-architecture-13 (work in progress), September
+ 2002.
+
+ [6] Rinne, T., Ylonen, T., Kivinen, T., Saarinen, M. and S.
+ Lehtinen, "SSH Protocol Transport Protocol",
+ draft-ietf-secsh-transport-15 (work in progress), September
+ 2002.
+
+ [7] Rinne, T., Ylonen, T., Kivinen, T., Saarinen, M. and S.
+ Lehtinen, "SSH Connection Protocol", draft-ietf-secsh-connect-16
+ (work in progress), September 2002.
+
+ [8] Rinne, T., Ylonen, T., Kivinen, T., Saarinen, M. and S.
+ Lehtinen, "SSH Authentication Protocol",
+ draft-ietf-secsh-userauth-16 (work in progress), September 2002.
+
+
+Authors' Addresses
+
+ Joseph Galbraith
+ VanDyke Software
+ 4848 Tramway Ridge Blvd
+ Suite 101
+ Albuquerque, NM 87111
+ US
+
+ Phone: +1 505 332 5700
+ EMail: galb-list@vandyke.com
+
+
+
+Galbraith, et al. Expires June 18, 2003 [Page 35]
+
+Internet-Draft SSH File Transfer Protocol December 2002
+
+
+ Tatu Ylonen
+ SSH Communications Security Corp
+ Fredrikinkatu 42
+ HELSINKI FIN-00100
+ Finland
+
+ EMail: ylo@ssh.com
+
+
+ Sami Lehtinen
+ SSH Communications Security Corp
+ Fredrikinkatu 42
+ HELSINKI FIN-00100
+ Finland
+
+ EMail: sjl@ssh.com
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Galbraith, et al. Expires June 18, 2003 [Page 36]
+
+Internet-Draft SSH File Transfer Protocol December 2002
+
+
+Intellectual Property Statement
+
+ The IETF takes no position regarding the validity or scope of any
+ intellectual property or other rights that might be claimed to
+ pertain to the implementation or use of the technology described in
+ this document or the extent to which any license under such rights
+ might or might not be available; neither does it represent that it
+ has made any effort to identify any such rights. Information on the
+ IETF's procedures with respect to rights in standards-track and
+ standards-related documentation can be found in BCP-11. Copies of
+ claims of rights made available for publication and any assurances of
+ licenses to be made available, or the result of an attempt made to
+ obtain a general license or permission for the use of such
+ proprietary rights by implementors or users of this specification can
+ be obtained from the IETF Secretariat.
+
+ The IETF invites any interested party to bring to its attention any
+ copyrights, patents or patent applications, or other proprietary
+ rights which may cover technology that may be required to practice
+ this standard. Please address the information to the IETF Executive
+ Director.
+
+
+Full Copyright Statement
+
+ Copyright (C) The Internet Society (2002). All Rights Reserved.
+
+ This document and translations of it may be copied and furnished to
+ others, and derivative works that comment on or otherwise explain it
+ or assist in its implementation may be prepared, copied, published
+ and distributed, in whole or in part, without restriction of any
+ kind, provided that the above copyright notice and this paragraph are
+ included on all such copies and derivative works. However, this
+ document itself may not be modified in any way, such as by removing
+ the copyright notice or references to the Internet Society or other
+ Internet organizations, except as needed for the purpose of
+ developing Internet standards in which case the procedures for
+ copyrights defined in the Internet Standards process must be
+ followed, or as required to translate it into languages other than
+ English.
+
+ The limited permissions granted above are perpetual and will not be
+ revoked by the Internet Society or its successors or assignees.
+
+ This document and the information contained herein is provided on an
+ "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
+ TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
+ BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
+
+
+
+Galbraith, et al. Expires June 18, 2003 [Page 37]
+
+Internet-Draft SSH File Transfer Protocol December 2002
+
+
+ HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
+ MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
+
+
+Acknowledgement
+
+ Funding for the RFC Editor function is currently provided by the
+ Internet Society.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Galbraith, et al. Expires June 18, 2003 [Page 38]
+
+
diff --git a/doc/draft-ietf-secsh-fingerprint-01.txt b/doc/draft-ietf-secsh-fingerprint-01.txt
new file mode 100644
index 00000000..5edea39d
--- /dev/null
+++ b/doc/draft-ietf-secsh-fingerprint-01.txt
@@ -0,0 +1,120 @@
+
+
+
+
+
+
+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
new file mode 100644
index 00000000..da442579
--- /dev/null
+++ b/doc/draft-ietf-secsh-gsskeyex-06.txt
@@ -0,0 +1,1509 @@
+
+
+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
new file mode 100644
index 00000000..1554ac35
--- /dev/null
+++ b/doc/draft-ietf-secsh-newmodes-00.txt
@@ -0,0 +1,619 @@
+
+
+
+
+
+
+Network Working Group M. Bellare
+Internet-Draft T. Kohno
+Expires: September 20, 2003 UC San Diego
+ C. Namprempre
+ Thammasat University
+ March 20, 2003
+
+
+ SSH Transport Layer Encryption Modes
+
+ draft-ietf-secsh-newmodes-00.txt
+
+
+Status of this Memo
+
+ This document is an Internet-Draft and is in full conformance with
+ all provisions of Section 10 of RFC2026.
+
+ Internet-Drafts are working documents of the Internet Engineering
+ Task Force (IETF), its areas, and its working groups. Note that
+ other groups may also distribute working documents as Internet-
+ Drafts.
+
+ Internet-Drafts are draft documents valid for a maximum of six months
+ and may be updated, replaced, or obsoleted by other documents at any
+ time. It is inappropriate to use Internet-Drafts as reference
+ material or to cite them other than as "work in progress."
+
+ The list of current Internet-Drafts can be accessed at
+ http://www.ietf.org/ietf/1id-abstracts.txt.
+
+ The list of Internet-Draft Shadow Directories can be accessed at
+ http://www.ietf.org/shadow.html.
+
+ This Internet-Draft will expire on September 20, 2003.
+
+Copyright Notice
+
+ Copyright (C) The Internet Society (2003). All Rights Reserved.
+
+Abstract
+
+ Researchers have recently discovered that the authenticated
+ encryption portion of the current SSH Transport Protocol is
+ vulnerable to several attacks.
+
+ This document describes new symmetric encryption methods for the SSH
+ Transport Protocol and gives specific recommendations on how
+
+
+
+Bellare, Kohno, and Namprempre [Page 1]
+
+Internet Draft Month, Year
+
+
+ frequently SSH implementations should rekey.
+
+ Bellare, Kohno, and Namprempre [ACM CCS 2002] prove that if an SSH
+ application implements the modifications described in this document,
+ then the symmetric cryptographic portion of that application will
+ provably resist chosen-plaintext, chosen-ciphertext, reaction-based
+ privacy and integrity/authenticity attacks.
+
+Table of Contents
+
+ 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 2
+ 2. Conventions Used in This Document . . . . . . . . . . . . . . 2
+ 3. Rekeying . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
+ 3.1 First Rekeying Recommendation . . . . . . . . . . . . . . . . 3
+ 3.2 Second Rekeying Recommendation . . . . . . . . . . . . . . . . 3
+ 4. Encryption Modes . . . . . . . . . . . . . . . . . . . . . . . 4
+ 5. Security Considerations . . . . . . . . . . . . . . . . . . . 6
+ 5.1 Rekeying Considerations . . . . . . . . . . . . . . . . . . . 7
+ 5.2 Encryption Method Considerations . . . . . . . . . . . . . . . 8
+ References . . . . . . . . . . . . . . . . . . . . . . . . . . 9
+ Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . 10
+ Full Copyright Statement . . . . . . . . . . . . . . . . . . . 10
+
+1. Introduction
+
+ The symmetric portion of the SSH Transport Protocol was designed to
+ provide both privacy and integrity of encapsulated data. Researchers
+ ([DAI,BKN]) have, however, recently identified several security
+ problems with the symmetric portion of the SSH Transport Protocol as
+ described in [SSH-TRANS]. For example, the encryption mode specified
+ in [SSH-TRANS] is vulnerable to a chosen-plaintext privacy attack.
+ Additionally, if not rekeyed frequently enough, the SSH Transport
+ Protocol may leak information about payload data. This latter
+ property is true regardless of what encryption mode is used.
+
+ In [BKN] Bellare, Kohno, and Namprempre show how to modify the
+ symmetric portion of the SSH Transport Protocol so that it provably
+ preserves privacy and integrity against chosen-plaintext, chosen-
+ ciphertext, and reaction attacks. This document instantiates the
+ recommendations described in [BKN].
+
+2. Conventions Used in This Document
+
+ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
+ "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
+ document are to be interpreted as described in [RFC2119].
+
+ The used data types and terminology are specified in the architecture
+
+
+
+Bellare, Kohno, and Namprempre [Page 2]
+
+Internet Draft Month, Year
+
+
+ document [SSH-ARCH].
+
+ The SSH Transport Protocol is specified in the transport document
+ [SSH-TRANS].
+
+3. Rekeying
+
+ Section 7 of [SSH-TRANS] suggests that SSH implementations rekey
+ after every gigabyte of transmitted data. [SSH-TRANS] does not,
+ however, discuss all the problems that could arise if an SSH
+ implementation does not rekey frequently enough. This section serves
+ to strengthen the suggestion in [SSH-TRANS] by giving firm upper
+ bounds on the tolerable number of encryptions between rekeying
+ operations. In Section 5 we discuss the motivation for these
+ rekeying recommendations in more detail.
+
+ This section makes two recommendations. Informally, the first
+ recommendation is intended to protects against possible information
+ leakage through the MAC tag and the second recommendation is intended
+ to protect against possible information leakage through the block
+ cipher. Note that, depending on the block length of the underlying
+ block cipher and the length of the encrypted packets, the first
+ recommendation may supersede the second recommendation, or visa-
+ versa.
+
+3.1 First Rekeying Recommendation
+
+ Because of possible information leakage through the MAC tag, SSH
+ implementations SHOULD rekey at least once every 2**32 outgoing
+ packets. More explicitly, after a key exchange an SSH implementation
+ SHOULD NOT send more than 2**32 packets before rekeying again.
+
+ SSH implementations SHOULD also attempt to rekey before receiving
+ more than 2**32 packets since the last rekey operation. The
+ preferred way to do this is to rekey after receiving more than 2**31
+ packets since the last rekey operation.
+
+3.2 Second Rekeying Recommendation
+
+ Because of a birthday property of block ciphers and some modes of
+ operation, implementations must be careful not to encrypt too many
+ blocks with the same encryption key.
+
+ Let L be the block length (in bits) of an SSH encryption method's
+ block cipher (eg, 128 for AES). If L is at least 128 then, after
+ rekeying, an SSH implementation SHOULD NOT encrypt more than 2**(L/4)
+ blocks before rekeying again. If L is at least 128, then SSH
+ implementations should also attempt to force a rekey before receiving
+
+
+
+Bellare, Kohno, and Namprempre [Page 3]
+
+Internet Draft Month, Year
+
+
+ more than 2**(L/4) blocks. If L is less than 128 (which is the case
+ for older ciphers such as 3DES, Blowfish, CAST-128, and IDEA), then,
+ although it may be too expensive to rekey every 2**(L/4) blocks, it
+ is still advisable for SSH implementations to follow the original
+ recommendation in [SSH-TRANS]: rekey at least once every gigabyte of
+ transmitted data.
+
+ Note that if L is less than or equal to 128, then the recommendation
+ in this subsection supersedes the recommendation in Section 3.1. If
+ an SSH implementation uses a block cipher with a larger block size
+ (eg, Rijndael with 256-bit blocks), then the recommendations in the
+ above paragraph may supersede the recommendations in this paragraph
+ (depending on the lengths of the packets).
+
+4. Encryption Modes
+
+ This document describes new encryption methods for use with the SSH
+ Transport Protocol. These encryption methods are in addition to the
+ encryption methods described in Section 4.3 of [SSH-TRANS].
+
+ Recall from [SSH-TRANS] that the encryption methods in each direction
+ of an SSH connection MUST run independently of each other and that,
+ when encryption is in effect, the packet length, padding length,
+ payload, and padding fields of each packet MUST be encrypted with the
+ chosen method. Further recall that the total length of the
+ concatenation of the packet length, padding length, payload, and
+ padding MUST be a multiple of the cipher's block size when the
+ cipher's block size is greater than or equal to 8 bytes (which is the
+ case for all of the following methods).
+
+ This document describes the following new methods:
+
+ aes128-ctr RECOMMENDED AES (Rijndael) in SDCTR mode,
+ with 128-bit key
+ aes192-ctr RECOMMENDED AES with 192-bit key
+ aes256-ctr RECOMMENDED AES with 256-bit key
+ 3des-ctr RECOMMENDED Three-key 3DES in SDCTR mode
+ blowfish-ctr RECOMMENDED Blowfish in SDCTR mode
+ twofish128-ctr RECOMMENDED Twofish in SDCTR mode,
+ with 128-bit key
+ twofish192-ctr OPTIONAL Twofish with 192-bit key
+ twofish256-ctr OPTIONAL Twofish with 256-bit key
+ serpent128-ctr RECOMMENDED Serpent in SDCTR mode, with
+ with 128-bit key
+ serpent192-ctr OPTIONAL Serpent with 192-bit key
+ serpent256-ctr OPTIONAL Serpent with 256-bit key
+ idea-ctr OPTIONAL IDEA in SDCTR mode
+ cast128-ctr OPTIONAL CAST-128 in SDCTR mode
+
+
+
+Bellare, Kohno, and Namprempre [Page 4]
+
+Internet Draft Month, Year
+
+
+ The label <cipher>-ctr means that the block cipher <cipher> is to be
+ used in "stateful-decryption counter" (SDCTR) mode. Let L be the
+ block length of <cipher> in bits. In stateful-decryption counter
+ mode both the sender and the receiver maintain an internal L-bit
+ counter X. The initial value of X should be the initial IV (as
+ computed in Section 5.2 of [SSH-TRANS]) interpreted as an L-bit
+ unsigned integer in network-byte-order. If X=(2**L)-1, then
+ "increment X" has the traditional semantics of "set X to 0." We use
+ the notation <X> to mean "convert X to an L-bit string in network-
+ byte-order." Naturally, implementations may differ in how the
+ internal value X is stored. For example, implementations may store X
+ as multiple unsigned 32-bit counters.
+
+ To encrypt a packet P=P1||P2||...||Pn (where P1, P2, ..., Pn are each
+ blocks of length L), the encryptor first encrypts <X> with <cipher>
+ to obtain a block B1. The block B1 is then XORed with P1 to generate
+ the ciphertext block C1. The counter X is then incremented and the
+ process is repeated for each subsequent block in order to generate
+ the entire ciphertext C=C1||C2||...||Cn corresponding to the packet
+ P. Note that the counter X is not included in the ciphertext. Also
+ note that the keystream can be pre-computed and that encryption is
+ parallelizable.
+
+ To decrypt a ciphertext C=C1||C2||...||Cn, the decryptor (who also
+ maintains its own copy of X), first encrypts its copy of <X> with
+ <cipher> to generate a block B1 and then XORs B1 to C1 to get P1.
+ The decryptor then increments its copy of the counter X and repeats
+ the above process for each block to obtain the plaintext packet
+ P=P1||P2||...||Pn. As before, the keystream can be pre-computed and
+ decryption is parallelizable.
+
+ The "aes128-ctr" method uses AES (the Advanced Encryption Standard,
+ formerly Rijndael) with 128-bit keys [AES]. The block size is 16
+ bytes.
+
+ The "aes192-ctr" method uses AES with 192-bit keys.
+
+ The "aes256-ctr" method uses AES with 256-bit keys.
+
+ The "3des-ctr" method uses three-key triple-DES (encrypt-decrypt-
+ encrypt), where the first 8 bytes of the key are used for the first
+ encryption, the next 8 bytes for the decryption, and the following 8
+ bytes for the final encryption. This requires 24 bytes of key data
+ (of which 168 bits are actually used). The block size is 8 bytes.
+ This algorithm is defined in [SCHNEIER].
+
+ The "blowfish-ctr" method uses Blowfish with 256 bit keys [SCHNEIER].
+ The block size is 8 bytes.
+
+
+
+Bellare, Kohno, and Namprempre [Page 5]
+
+Internet Draft Month, Year
+
+
+ The "twofish128-ctr" method uses Twofish with 128-bit keys [TWOFISH].
+ The block size is 16 bytes.
+
+ The "twofish192-ctr" method uses Twofish with 192-bit keys.
+
+ The "twofish256-ctr" method uses Twofish with 256-bit keys.
+
+ The "serpent128-ctr" method uses the Serpent block cipher [SERPENT]
+ with 128-bit keys. The block size is 16 bytes.
+
+ The "serpent192-ctr" method uses Serpent with 192-bit keys.
+
+ The "serpent256-ctr" method uses Serpent with 256-bit keys.
+
+ The "idea-ctr" method uses the IDEA cipher [SCHNEIER]. IDEA is
+ patented by Ascom AG. The block size is 8 bytes.
+
+ The "cast128-ctr" method uses the CAST-128 cipher [RFC2144]. The
+ block size is 8 bytes.
+
+5. Security Considerations
+
+ This document describes additional encryption methods and
+ recommendations for the SSH Transport Protocol [SSH-TRANS]. [BKN]
+ prove that if an SSH application incorporates the methods and
+ recommendations described in this document, then the symmetric
+ cryptographic portion of that application will resist a large class
+ of privacy and integrity attacks.
+
+ This section is designed to help implementors understand the
+ security-related motivations for, as well as possible consequences of
+ deviating from, the methods and recommendations described in this
+ document. Additional motivation and discussion, as well as proofs of
+ security, appear in the research paper [BKN].
+
+ Please note that the notion of "prove" in the context of [BKN] is
+ that of practice-oriented reductionist security: if an attacker is
+ able to break the symmetric portion of the SSH Transport Protocol
+ using a certain type of attack (eg, a chosen-ciphertext attack), then
+ the attacker will also be able to break one of the transport
+ protocol's underlying components (eg, the underlying block cipher or
+ MAC). If we make the reasonable assumption that the underlying
+ components (such as AES and HMAC-SHA1) are secure, then the attacker
+ against the symmetric portion of the SSH protocol cannot be very
+ successful (since otherwise there would be a contradiction). Please
+ see [BKN] for details. In particular, attacks are not impossible;
+ just extremely improbable (unless the building blocks, like AES, are
+ insecure).
+
+
+
+Bellare, Kohno, and Namprempre [Page 6]
+
+Internet Draft Month, Year
+
+
+ Note also that cryptography often plays only a small (but critical)
+ role in an application's overall security. In the case of the SSH
+ Transport Protocol, even though an application might implement the
+ symmetric portion of the SSH protocol exactly as described in this
+ document, the application may still be vulnerable to non-protocol-
+ based attacks (as an egregious example, an application might save
+ cryptographic keys in cleartext to an unprotected file).
+ Consequently, even though the methods described herein come with
+ proofs of security, developers must still execute caution when
+ developing applications that implement these methods.
+
+5.1 Rekeying Considerations
+
+ Section 3 of this document makes two rekeying recommendations: (1)
+ rekey at least once every 2**32 packets and (2) rekey after a certain
+ number of encrypted blocks (eg, 2**(L/4) blocks if the block cipher's
+ block length L is at least 128 bits). The motivations for
+ recommendations (1) and (2) are different, and we consider each
+ recommendation in turn. Briefly, (1) is designed to protect against
+ information leakage through the SSH protocol's underlying MAC and (2)
+ is designed to protect against information leakage through the SSH
+ protocol's underlying encryption scheme. Please note that, depending
+ on the encryption method's block length L and the number of blocks
+ encrypted per packet, recommendation (1) may supersede recommendation
+ (2) or visa-versa.
+
+ Recommendation (1) states that SSH implementations should rekey at
+ least once every 2**32 packets. As [BKN] show, if more than 2**32
+ packets are encrypted and MACed by the SSH Transport Protocol between
+ rekeyings, then the SSH Transport Protocol's underlying MAC may begin
+ to leak information about the protocol's payload data. In more
+ detail, an adversary looks for a collision between the MACs
+ associated to two packets that were MACed with the same 32-bit
+ sequence number (see Section 4.4 of [SSH-TRANS]); if a collision is
+ found, then the payload data associated with those two ciphertexts is
+ probably identical. Note that this problem occurs regardless of how
+ secure the underlying encryption method is. Implementors who decide
+ not to rekey at least once every 2**32 packets should understand this
+ issue.
+
+ Note that compressing payload data before encrypting and MACing will
+ not significantly reduce the risk of information leakage through the
+ underlying MAC. Similarly, the use of random (and unpredictable to
+ an adversary) padding will not prevent information leakage through
+ the underlying MAC [BKN].
+
+ One alternative to recommendation (1) would be to make the SSH
+ Transport Protocol's sequence number more than 32 bits long. This
+
+
+
+Bellare, Kohno, and Namprempre [Page 7]
+
+Internet Draft Month, Year
+
+
+ document does not suggest increasing the length of the sequence
+ number because doing so could hinder interoperability with older
+ version of the SSH protocol. Another alternative to recommendation
+ (1) would be to switch from HMAC to a privacy-preserving randomized
+ MAC.
+
+ Recommendation (2) states that SSH implementations should rekey
+ before encrypting more than 2**(L/4) blocks with the same key
+ (assuming L is at least 128). This recommendation is designed to
+ minimize the risk of birthday attacks against the encryption method's
+ underlying block cipher. For example, there is a theoretical privacy
+ attack against stateful-decryption counter mode if an adversary is
+ allowed to encrypt approximately 2**(L/2) messages with the same key.
+ It is because of these birthday attacks that implementors are highly
+ encouraged to use secure block ciphers with large block lengths.
+
+5.2 Encryption Method Considerations
+
+ Researchers have recently shown that the original CBC-based
+ encryption methods in [SSH-TRANS] are vulnerable to chosen-plaintext
+ privacy attacks [DAI,BKN]. The new stateful-decryption counter mode
+ encryption methods described in Section 4 of this document were
+ designed to be secure replacements to the original encryption methods
+ described in [SSH-TRANS].
+
+ Many people shy away from counter mode-based encryption schemes
+ because, when used incorrectly (such as when the keystream is allowed
+ to repeat), counter mode can be very insecure. Fortunately, the
+ common concerns with counter mode do not apply to SSH because of the
+ rekeying recommendations and because of the additional protection
+ provided by the transport protocol's MAC. This discussion is
+ formalized with proofs of security in [BKN].
+
+ As an additional note, when one of the stateful-decryption counter
+ mode encryption methods (Section 4) is used, then the padding
+ included in an SSH packet (Section 4 of [SSH-TRANS]) need not be (but
+ can still be) random. This eliminates the need to generate
+ cryptographically-secure pseudorandom bytes for each packet.
+
+ One property of counter mode encryption is that it does not require
+ messages to be padded to a multiple of the block cipher's block
+ length. Although not padding messages can reduce the protocol's
+ network consumption, this document requires padding to be a multiple
+ of the block cipher's block length in order to (1) not alter the
+ packet description in [SSH-TRANS] and (2) not leak precise
+ information about the length of the packet's payload data. (Although
+ there may be some networks savings for padding to only 8-bytes even
+ if the block cipher uses 16-byte blocks, because of (1) we do not
+
+
+
+Bellare, Kohno, and Namprempre [Page 8]
+
+Internet Draft Month, Year
+
+
+ make that recommendation here.)
+
+ In addition to stateful-decryption counter mode, [BKN] describe other
+ provably-secure encryption methods for use with the SSH Transport
+ Protocol. The stateful-decryption counter mode methods in Section 4
+ are, however, the preferred alternatives to the insecure methods in
+ [SSH-TRANS] because stateful-decryption counter mode is the most
+ efficient (both in terms of network consumption and in terms of the
+ number of required cryptographic operations per packet).
+
+References
+
+ [AES] Daemon, J. and Rijmen, V., "AES Proposal: Rijndael",
+ NIST AES Proposal, 1998.
+
+ [BKN] Bellare, M., Kohno, T., and Namprempre, C.,
+ "Authenticated Encryption in SSH: Provably Fixing the
+ SSH Binary Packet Protocol", Ninth ACM Conference on
+ Computer and Communications Security, 2002.
+
+ [BN] Bellare, M. and Namprempre, C., "Authenticated
+ Encryption: Relations among notions and analysis of
+ the generic composition paradigm", Asiacrypt 2000.
+
+ [DAI] Dai, W., "An Attack Against SSH2 Protocol", Email to
+ the ietf-ssh@netbsd.org email list, 2002.
+
+ [KRAWCZYK] Krawczyk, H., "The Order of Encryption and
+ Authentication for Protecting Communications (Or: How
+ secure is SSL?)", Crypto 2001.
+
+ [RFC2119] Bradner, S., "Key Words for Use in RFCs to Indicate
+ Requirement Levels", BCP 14, RFC 2119, March 1997.
+
+ [RFC2144] Adams, C., "The CAST-128 Encryption Algorithm", RFC
+ 2144, May 1997.
+
+ [SCHNEIER] Schneier, B., "Applied Cryptography Second Edition:
+ Protocols algorithms and source in code in C", Wiley,
+ 1996.
+
+ [SERPENT] Anderson, R., Biham, E., and Knudsen, L. "Serpent: A
+ proposal for the Advanced Encryption Standard", NIST
+ AES Proposal, 1998.
+
+ [SSH-ARCH] Ylonen, T., et. al., "SSH Protocol Architecture",
+ I-D draft-ietf-architecture-12.txt, January 2002.
+
+
+
+
+Bellare, Kohno, and Namprempre [Page 9]
+
+Internet Draft Month, Year
+
+
+ [SSH-TRANS] Ylonen, T., et. al., "SSH Transport Layer Protocol",
+ I-D draft-ietf-transport-14.txt, March 2002.
+
+ [TWOFISH] Schneier, B., et. al., "The Twofish Encryptions
+ Algorithm: A 128-bit block cipher, 1st Edition",
+ Wiley, 1999.
+
+Authors' Addresses:
+
+ Mihir Bellare
+ Department of Computer Science and Engineering
+ University of California at San Diego
+ 9500 Gilman Drive, MC 0114
+ La Jolla, CA 92093-0114
+
+ Phone: +1 858-822-2977
+ EMail: mihir@cs.ucsd.edu
+
+ Tadayoshi Kohno
+ Department of Computer Science and Engineering
+ University of California at San Diego
+ 9500 Gilman Drive, MC 0114
+ La Jolla, CA 92093-0114
+
+ Phone: +1 858-822-2977
+ EMail: tkohno@cs.ucsd.edu
+
+ Chanathip Namprempre
+ Thammasat University
+ Faculty of Engineering
+ Electrical Engineering Department
+ Rangsit Campus, Klong Luang
+ Pathumthani, Thailand 12121
+
+ EMail: meaw@alum.mit.edu
+
+Full Copyright Statement
+
+ Copyright (C) The Internet Society (2003). All Rights Reserved.
+
+ This document and translations of it may be copied and furnished to
+ others, and derivative works that comment on or otherwise explain it
+ or assist in its implementation may be prepared, copied, published
+ and distributed, in whole or in part, without restriction of any
+ kind, provided that the above copyright notice and this paragraph are
+ included on all such copies and derivative works. However, this
+ document itself may not be modified in any way, such as by removing
+ the copyright notice or references to the Internet Society or other
+
+
+
+Bellare, Kohno, and Namprempre [Page 10]
+
+Internet Draft Month, Year
+
+
+ Internet organizations, except as needed for the purpose of
+ developing Internet standards in which case the procedures for
+ copyrights defined in the Internet Standards process must be
+ followed, or as required to translate it into languages other than
+ English.
+
+ The limited permissions granted above are perpetual and will not be
+ revoked by the Internet Society or its successors or assigns.
+
+ This document and the information contained herein is provided on an
+ "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
+ TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
+ BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
+ HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
+ MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
+
+Acknowledgments
+
+ Mihir Bellare and Chanathip Namprempre were supported by NSF Grant
+ CCR-0098123, NSF Grant ANR-0129617 and an IBM Faculty Partnership
+ Development Award. Tadayoshi Kohno was supported by a National
+ Defense Science and Engineering Fellowship.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Bellare, Kohno, and Namprempre [Page 11]
+ \ No newline at end of file
diff --git a/doc/draft-ietf-secsh-publickeyfile-03.txt b/doc/draft-ietf-secsh-publickeyfile-03.txt
new file mode 100644
index 00000000..766f494e
--- /dev/null
+++ b/doc/draft-ietf-secsh-publickeyfile-03.txt
@@ -0,0 +1,506 @@
+
+
+
+Secure Shell Working Group J. Galbraith
+Internet-Draft VanDyke Software
+Expires: April 16, 2003 R. Thayer
+ The Tillerman Group
+ October 16, 2002
+
+
+ SSH Public Key File Format
+ draft-ietf-secsh-publickeyfile-03.txt
+
+Status of this Memo
+
+ This document is an Internet-Draft and is in full conformance with
+ all provisions of Section 10 of RFC2026.
+
+ Internet-Drafts are working documents of the Internet Engineering
+ Task Force (IETF), its areas, and its working groups. Note that
+ other groups may also distribute working documents as Internet-
+ Drafts.
+
+ Internet-Drafts are draft documents valid for a maximum of six months
+ and may be updated, replaced, or obsoleted by other documents at any
+ time. It is inappropriate to use Internet-Drafts as reference
+ material or to cite them other than as "work in progress."
+
+ The list of current Internet-Drafts can be accessed at http://
+ www.ietf.org/ietf/1id-abstracts.txt.
+
+ The list of Internet-Draft Shadow Directories can be accessed at
+ http://www.ietf.org/shadow.html.
+
+ This Internet-Draft will expire on April 16, 2003.
+
+Copyright Notice
+
+ Copyright (C) The Internet Society (2002). All Rights Reserved.
+
+Abstract
+
+ This document formally documents the existing public key file format
+ in use for exchanging public keys between different SSH
+ implementations.
+
+
+
+
+
+
+
+
+
+
+Galbraith & Thayer Expires April 16, 2003 [Page 1]
+
+Internet-Draft SSH Public Key File Format October 2002
+
+
+Table of Contents
+
+ 1. Conventions used in this document . . . . . . . . . . . . . 3
+ 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4
+ 3. Key File Format . . . . . . . . . . . . . . . . . . . . . . 5
+ 3.1 Line termination Characters . . . . . . . . . . . . . . . . 5
+ 3.2 Begin and end markers . . . . . . . . . . . . . . . . . . . 5
+ 3.3 Key File Header . . . . . . . . . . . . . . . . . . . . . . 5
+ 3.3.1 Subject Header . . . . . . . . . . . . . . . . . . . . . . . 6
+ 3.3.2 Comment Header . . . . . . . . . . . . . . . . . . . . . . . 6
+ 3.4 Public Key File Body . . . . . . . . . . . . . . . . . . . . 6
+ 3.5 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 7
+ References . . . . . . . . . . . . . . . . . . . . . . . . . 8
+ Authors' Addresses . . . . . . . . . . . . . . . . . . . . . 8
+ Full Copyright Statement . . . . . . . . . . . . . . . . . . 9
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Galbraith & Thayer Expires April 16, 2003 [Page 2]
+
+Internet-Draft SSH Public Key File Format October 2002
+
+
+1. Conventions used in this document
+
+ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
+ "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
+ document are to be interpreted as described in [4].
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Galbraith & Thayer Expires April 16, 2003 [Page 3]
+
+Internet-Draft SSH Public Key File Format October 2002
+
+
+2. Introduction
+
+ In order to use public key authentication, public keys must be
+ exchanged between client and server. This document formally
+ describes the existing public key file format, with few exceptions.
+
+ Where this document departs from current practice, it also suggests a
+ mechanism for backwards compatibility.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Galbraith & Thayer Expires April 16, 2003 [Page 4]
+
+Internet-Draft SSH Public Key File Format October 2002
+
+
+3. Key File Format
+
+ SSH implementations must share public key files between the client
+ and the server in order interoperate.
+
+ A key file is a text file, containing a sequence of lines. Each line
+ in the file MUST NOT be longer than 72 bytes.
+
+3.1 Line termination Characters
+
+ In order to achieve the goal of being able to exchange public key
+ files between servers, implementations are REQUIRED to read files
+ using any of the common line termination sequence, <CR>, <LF> or
+ <CR><LF>.
+
+ Implementations may generate files using which ever line termination
+ convention is most convenient
+
+3.2 Begin and end markers
+
+ The first line of a conforming key file MUST be a begin marker, which
+ is the literal text:
+
+ ---- BEGIN SSH2 PUBLIC KEY ----
+
+ The last line of a conforming key file MUST be a end marker, which is
+ the literal text:
+
+ ---- END SSH2 PUBLIC KEY ----
+
+3.3 Key File Header
+
+ The key file header section consists of multiple RFC822 - style
+ header fields. Each field is a line of the following format:
+
+ Header-tag ':' ' ' Header-value
+
+ The Header-tag MUST NOT be more than 64 bytes. The Header-value MUST
+ NOT be more than 1024 bytes. Each line in the header MUST NOT be
+ more than 72 bytes.
+
+ A line is continued if the last character in the line is a '\'. If
+ the last character of a line is a '\', then the logical contents of
+ the line is formed by removing the '\' and appending the contents of
+ the next line.
+
+ The Header-tag MUST be US-ASCII. The Header-value MUST be encoded in
+ UTF-8. [2]
+
+
+
+Galbraith & Thayer Expires April 16, 2003 [Page 5]
+
+Internet-Draft SSH Public Key File Format October 2002
+
+
+ A line that is not a continuation line that has no ':' in it is
+ assumed to be the first line of the base 64 encoded body (Section 8)
+
+ Compliant implementations MUST ignore unrecognized header fields.
+ Implementations SHOULD preserve unrecognized header fields when
+ manipulating the key file.
+
+ Existing implementations may not correctly handle unrecognized
+ fields. During a transition period, implementations SHOULD generate
+ key file headers that contain only a Subject field followed by a
+ Comment field.
+
+3.3.1 Subject Header
+
+ This field currently is used to store the login-name that the key was
+ generated under. For example:
+
+ Subject: user
+
+3.3.2 Comment Header
+
+ Contain a user specified comment which will be displayed when using
+ the key.
+
+ It is suggested that this field default to user@hostname for the user
+ and machine used to generate the key. For example:
+
+ Comment: user@mycompany.com
+
+ Currently, common practice is to quote the Header-value of the
+ Comment, and some existing implementations fail if these quotes are
+ omitted.
+
+ Compliant implementations MUST function correctly if the quotes are
+ omitted.
+
+ During an interim period implementations MAY include the quotes. If
+ the first and last characters of the Header-value are matching
+ quotes, implementations SHOULD remove them before using the value.
+
+3.4 Public Key File Body
+
+ The body of a public key file consists of the public key blob as
+ described in the SSH transport draft [1], section 4.6, "Public Key
+ Algorithms", encoded in base 64 as specified in RFC-2045, section
+ 6.8, "Base64 Content-Transfer-Encoding". [5]
+
+ As with all other lines, each line in the body MUST NOT be longer
+
+
+
+Galbraith & Thayer Expires April 16, 2003 [Page 6]
+
+Internet-Draft SSH Public Key File Format October 2002
+
+
+ than 72 characters.
+
+3.5 Examples
+
+ The following are some example public key files that are compliant:
+
+ ---- BEGIN SSH2 PUBLIC KEY ----
+ Comment: "1024-bit RSA, converted from OpenSSH by galb@test1"
+ AAAAB3NzaC1yc2EAAAABIwAAAIEA1on8gxCGJJWSRT4uOrR13mUaUk0hRf4RzxSZ1zRbYY
+ Fw8pfGesIFoEuVth4HKyF8k1y4mRUnYHP1XNMNMJl1JcEArC2asV8sHf6zSPVffozZ5TT4
+ SfsUu/iKy9lUcCfXzwre4WWZSXXcPff+EHtWshahu3WzBdnGxm5Xoi89zcE=
+ ---- END SSH2 PUBLIC KEY ----
+
+
+ ---- BEGIN SSH2 PUBLIC KEY ----
+ Comment: DSA Public Key for use with MyIsp
+ AAAAB3NzaC1kc3MAAACBAPY8ZOHY2yFSJA6XYC9HRwNHxaehvx5wOJ0rzZdzoSOXxbETW6
+ ToHv8D1UJ/z+zHo9Fiko5XybZnDIaBDHtblQ+Yp7StxyltHnXF1YLfKD1G4T6JYrdHYI14
+ Om1eg9e4NnCRleaqoZPF3UGfZia6bXrGTQf3gJq2e7Yisk/gF+1VAAAAFQDb8D5cvwHWTZ
+ DPfX0D2s9Rd7NBvQAAAIEAlN92+Bb7D4KLYk3IwRbXblwXdkPggA4pfdtW9vGfJ0/RHd+N
+ jB4eo1D+0dix6tXwYGN7PKS5R/FXPNwxHPapcj9uL1Jn2AWQ2dsknf+i/FAAvioUPkmdMc
+ 0zuWoSOEsSNhVDtX3WdvVcGcBq9cetzrtOKWOocJmJ80qadxTRHtUAAACBAN7CY+KKv1gH
+ pRzFwdQm7HK9bb1LAo2KwaoXnadFgeptNBQeSXG1vO+JsvphVMBJc9HSn24VYtYtsMu74q
+ XviYjziVucWKjjKEb11juqnF0GDlB3VVmxHLmxnAz643WK42Z7dLM5sY29ouezv4Xz2PuM
+ ch5VGPP+CDqzCM4loWgV
+ ---- END SSH2 PUBLIC KEY ----
+
+
+ ---- BEGIN SSH2 PUBLIC KEY ----
+ Subject: galb
+ Comment: 1024-bit rsa, created by galb@shimi Mon Jan 15 08:31:24 2001
+ AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt459
+ 6k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4soW6
+ NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0=
+ ---- END SSH2 PUBLIC KEY ----
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Galbraith & Thayer Expires April 16, 2003 [Page 7]
+
+Internet-Draft SSH Public Key File Format October 2002
+
+
+References
+
+ [1] Rinne, T., Ylonen, T., Kivinen, T., Saarinen, M. and S.
+ Lehtinen, "SSH Protocol Transport Protocol", September 2002.
+
+ [2] Yergeau, F., "UTF-8, a Transformation Format of Unicode and ISO
+ 10646", October 1996.
+
+ [3] Bradner, S., "The Internet Standards Process -- Revision 3",
+ October 1996.
+
+ [4] Bradner, S., "Key words for use in RFCs to Indicate Requirement
+ Levels", March 1997.
+
+ [5] Freed and Borenstein, "Multipurpose Internet Mail Extensions
+ (MIME) Part One: Format of Internet Message Bodies", November
+ 1996.
+
+
+Authors' Addresses
+
+ Joseph Galbraith
+ VanDyke Software
+ 4848 Tramway Ridge Blvd
+ Suite 101
+ Albuquerque, NM 87111
+ US
+
+ Phone: +1 505 332 5700
+ EMail: galb-list@vandyke.com
+
+
+ Rodney Thayer
+ The Tillerman Group
+ 370 Altair Way, PMB 321
+ Sunnyvale, CA 94086
+
+ Phone: +1 408 757 9693
+ EMail: rodney@tillerman.to
+
+
+
+
+
+
+
+
+
+
+
+
+Galbraith & Thayer Expires April 16, 2003 [Page 8]
+
+Internet-Draft SSH Public Key File Format October 2002
+
+
+Full Copyright Statement
+
+ Copyright (C) The Internet Society (2002). All Rights Reserved.
+
+ This document and translations of it may be copied and furnished to
+ others, and derivative works that comment on or otherwise explain it
+ or assist in its implementation may be prepared, copied, published
+ and distributed, in whole or in part, without restriction of any
+ kind, provided that the above copyright notice and this paragraph are
+ included on all such copies and derivative works. However, this
+ document itself may not be modified in any way, such as by removing
+ the copyright notice or references to the Internet Society or other
+ Internet organizations, except as needed for the purpose of
+ developing Internet standards in which case the procedures for
+ copyrights defined in the Internet Standards process must be
+ followed, or as required to translate it into languages other than
+ English.
+
+ The limited permissions granted above are perpetual and will not be
+ revoked by the Internet Society or its successors or assigns.
+
+ This document and the information contained herein is provided on an
+ "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
+ TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
+ BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
+ HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
+ MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
+
+Acknowledgement
+
+ Funding for the RFC Editor function is currently provided by the
+ Internet Society.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Galbraith & Thayer Expires April 16, 2003 [Page 9]
+
+
diff --git a/doc/draft-ietf-secsh-scp-sftp-ssh-uri-00.txt b/doc/draft-ietf-secsh-scp-sftp-ssh-uri-00.txt
new file mode 100644
index 00000000..f582a49b
--- /dev/null
+++ b/doc/draft-ietf-secsh-scp-sftp-ssh-uri-00.txt
@@ -0,0 +1,426 @@
+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
new file mode 100644
index 00000000..b4564f17
--- /dev/null
+++ b/doc/draft-ietf-secsh-transport-16.txt
@@ -0,0 +1,1624 @@
+
+
+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 messag