diff options
| author | Aris Adamantiadis <aris@0xbadc0de.be> | 2005-07-05 01:21:44 +0000 |
|---|---|---|
| committer | Aris Adamantiadis <aris@0xbadc0de.be> | 2005-07-05 01:21:44 +0000 |
| commit | c65f56aefa50a2e2a78a0e45564526ecc921d74f (patch) | |
| tree | 11bd53cf92869ccbab30f29253ce30f7078a4a26 /doc | |
| download | libssh-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')
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> + go_out()...<br> +if(i>=256)<br> + 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 |