lib/libssh
1
0
Fork 0
mirror of https://git.libssh.org/projects/libssh.git synced 2025-08-08 19:02:06 +03:00
Code Activity

first import

Browse Source 
git-svn-id: svn+ssh://svn.berlios.de/svnroot/repos/libssh/trunk@1 7dcaeef0-15fb-0310-b436-a5af3365683c
This commit is contained in:
Aris Adamantiadis
2005-07-05 01:21:44 +00:00
commit c65f56aefa
78 changed files with 41120 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

886
doc/API.html Normal file
View File

@@ -0,0 +1,886 @@
<!DOCTYPE HTML SYSTEM>
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1">
<head>
<title>
Libssh's Documentation
</title>
<link href="style.css" rel="stylesheet" type="text/css">
</head>
<div id="titre">
<div align="center">
LIBSSH API GUIDE <br>
Or everything you ever wanted to know about a simple and fast ssh library.
</div>
</div>
<h2> 0 Introduction</h2>
<div class="tout">
Before inserting ssh hooks into your programs, you must know some basics about
the ssh protocol, and understand why the ssh library must implement them. <br>
Lot of the protocols specifications are hidden by the ssh library API (of
course !) but some still needs an attention from the end-user programmer.<br>
Note that libssh is still an alpha product, and the API may vary from one
version to another. The only guess I can make is that the API won't radically
change. <br>
The SSH protocol was designed for some goals which I resume here : <br>
-Privacy of data<br>
-Security<br>
-Authentication of the server<br>
-Authentication of the client.<br>
The client MUST be sure who's speaking to before entering into any
authentication way. That's where the end programmer must ensure the given
fingerprints *are* from the legitimate server. A ssh connection must follow
the following steps:<br>
<br>
1- Before connecting the socket, you can set up if you wish one or other
server public key authentication ie. DSA or RSA.
You can choose cryptographic algorithms you trust and compression algorithms
if any.<br>
2- The connection is made. A secure handshake is made, and resulting from it,
a public key from the server is gained.
You MUST verify that the public key is legitimate.<br>
3- The client must authenticate : the two implemented ways are password, and
public keys (from dsa and rsa key-pairs generated by openssh). It is
harmless to authenticate to a fake server with these keys because the
protocol ensures the data you sign can't be used twice. It just avoids
man-in-the-middle attacks.<br>
4- Now that the user has been authenticated, you must open one or several
channels. channels are different subways for information into a single ssh
connection. Each channel has a standard stream (stdout) and an error
stream (stderr). You can theoretically open an infinity of channel.<br>
5- With the channel you opened, you can do several things :<br>
-Open a shell. You may want to request a pseudo virtual terminal before <br>
-Execute a command. The virtual terminal is usable, too<br>
-Invoke the sftp subsystem. (look at chapter 6)<br>
-invoke your own subsystem. This is out the scope of this
document but it is easy to do.<br>
6- When everything is finished, just close the channels, and then the
connection.<br>
<br>
At every place, a function which returns an error code (typically -1 for int
values, NULL for pointers) also sets an error message and an error code.
I high-lined the main steps, now that's you to follow them :)
<br>
</div>
<h2> 1- Setting the options </h2>
<div class="tout">
The options mechanism will change during updates of the library, but the
functions which exists now will certainly be kept.
<br><br>
The ssh system needs to know the preferences of the user, the trust into one
or another algorithm and such. More important informations have to be given
before connecting : the host name of the server, the port (if non default),
the binding address, the default username, ... <br>
The options structure is given to a ssh_connect function, then this option
structure is used again and again by the ssh implementation. you shall not
free it manually, and you shall not share it with multiple sessions.<br>
Two ways are given for setting the options : the easy one (of course !) and
the long-but-accurate one.<br><br>
</div>
<h3>a) the easy way</h3><br>
<div class="tout">
Lot of ssh options in fact come from the command line of the program... <br>
you could parse them and then use the long way for every argument, but libssh
has a mechanism to do that for you, automatically.<br>
<br>
<div class="prot">
SSH_OPTIONS *ssh_getopt(int *argcptr, char **argv);
</div>
this function will return you a new options pointer based on the arguments
you give in parameters. <br> better, they clean the argv array from used parameters
so you can use them after in your own program<br>
<div class="ex">
int main(int argc, char **argv){<br>
SSH_OPTIONS *opt;<br>
opt=ssh_getopt(&argc, argv);<br>
if(!opt){<br>
...<br>
}<br>
</div>
the function will return NULL if some problem is appearing.<br>
As a matter of portability for you own programs, the hostname isn't always<br>
the first argument from the command line, so the single arguments (not
preceded by a -something) won't be parsed.<br>
<div class="ex">
example: <br>
user@host:~$ myssh -u aris localhost <br>
-u aris will be caught, localhost will not.<br>
</div>
cfr the options_set_user() function in the next part for more informations
about it.<br>
</div>
<h3>b) the long way</h3>
<div class="tout">
<div class="prot">
SSH_OPTIONS *options_new();
</div>
This function returns an empty but initialized option structure pointer.<br>
The structure is freed by ssh_disconnect described later, so don't use the
existing function options_free() (it's an internal function).<br>
So : use it only for <b>one</b> ssh_connect(), <b>never</b> free it.<br>
<br>
<div class="prot">
SSH_OPTIONS *options_copy(SSH_OPTIONS *opt);
</div>
If you need to replicate an option object before using it, use this function.
<br><br>
The following functions are all of the following form : <br>
<div class="prot">
int options_set_something(SSH_OPTIONS *opt, something);
</div>
the something parameters are always internaly copied, so you don't have to
strdup them.<br>
some return eather 0 or -1, in which case an error message appears in the
error functions, others never fail (return void)<br>
the error codes and descriptions for these functions are recoverable throught <i>ssh_get_error(NULL);</i>
<br>
<div class="prot">
int options_set_wanted_method(SSH_OPTIONS *opt,int method, char *list);
</div>
Passing an option structure, a ssh macro for the method, and a list of allowed
parameters indicates libssh you want to use these.<br>
The macros are :<br>
KEX_ALGO<br>
KEX_HOSTKEY Server public key type expected<br>
KEX_CRYPT_C_S 2 Cryptographic algorithm client->server<br>
KEX_CRYPT_S_C 3 Cryptographic algorithm server->client<br>
KEX_MAC_C_S 4<br>
KEX_MAC_S_C 5<br>
KEX_COMP_C_S 6 Compression method for the stream ("zlib" or "none"), client to server<br>
KEX_COMP_S_C 7 Compression method for the stream ("zlib" or "none"), server to client<br>
KEX_LANG_C_S 8<br>
KEX_LANG_S_C 9<br>
<br>
Currently, only KEX_HOSTKEY and ,KEX_CRYPT_C_S,S_C, KEX_COMP_C_S and S_C work
as expected. the list is a comma separated string of prefered
algorithms/methods, in order of preference.<br>
<br>
<div class="ex">
example : this sets the ssh stream to be compressed in client->server mode only
<br>
ret = option_set_wanted_method(options,KEX_COMP_C_S,"zlib");
</div>
<div class="ex">
example: this will set the cryptographic algorithms wanted from server to
client to aes128-cbc and then aes192-cbc if the first one isn't supported by
server:<br>
ret = option_set_wanted_method(options,KEX_CRYPT_S_C,"aes128-cbc,aes192-cbc");
</div>
<div class="ex">
if you prefer getting the Dss key from a server instead of rsa, but you still
accept rsa if dss isn't available :<br>
options_set_wanted_method(options,KEX_HOSTKEY,"ssh-dss,ssh-rsa");
</div>
return value: <br>0 if the option is valid, -1 else.<br> An error is set in that case.
<br><br>
<div class="prot">
void options_set_port(SSH_OPTIONS *opt, unsigned int port);
</div>
this function sets the server port.
<div class="prot">
void options_set_host(SSH_OPTIONS *opt, const char *hostname);
</div>
this function sets the hostname of the server. It also supports
"user@hostname" syntax in which case the user options is set too.
<div class="prot">
void options_set_fd(SSH_OPTIONS *opt, int fd);
</div>
permits you to specify an opened file descriptor you've opened yourself.
<br>
It's a good way of bypassing the internal FD opening in libssh, but there are things you should take care of : <br>
-The file descriptor should be returned to libssh without nonblocking settings<br>
-If you wish to use <i>is_server_known()</i> You should also set <i>options_set_host</i>... Otherwise libssh won't have any mean of certifying the server is known or not.<br><br>
<div class="prot">
void options_set_bindaddr(SSH_OPTIONS *opt, char *bindaddr);
</div>
this function allows you to set the binding address, in case your computer has
multiple IP or interfaces. it supports both hostnames and IP's
<br><br>
<div class="prot">
void options_set_username(SSH_OPTIONS *opt,char *username);
</div>
sets username for authenticating in this session.
<br><br>
<div class="prot">
void option_set_timeout(SSH_OPTIONS *opt,long seconds, long usec);
</div>
sets the timeout for connecting to the socket. It does not include a timeout for the name resolving or handshake.
<br>
<br>
<div class="prot">
void options_set_ssh_dir(SSH_OPTIONS *opt, char *dir);
</div>
this function sets the .ssh/ directory used by libssh. You may use a %s
which will be replaced by the home directory of the user.
NEVER accept parameters others than the user's one, they may contain
format strings which are a security hole if a malicious agent gives it.
<br><br>
<div class="prot">
void options_set_known_hosts_file(SSH_OPTIONS *opt, char *dir);
</div>
same than <i>options_set_ssh_dir()</i> for known_hosts file.
<br><br>
<div class="prot">
void options_set_identity(SSH_OPTIONS *opt, char *identity);
</div>
same than upper for the identity file (they come by pair, the one asked is the file without the .pub suffix)
<br><br>
<div class="prot">
void options_set_status_callback(SSH_OPTIONS *opt, void (*callback)(void *arg, float status), void *arg);
</div>
Because more and more developpers use libssh with GUI, I've added this function to make the ssh_connect function more
interactive. This permits to set a callback of the form
<div class="prot">void function(void *userarg, float status);</div> with status going from 0 to 1 during ssh_connect. The callback won't ever be called after the connection is made.
<br><br>
</div>
<h2>
2- Connecting the ssh server
</H2>
<div class="tout">
The API provides an abstract data type, SSH_SESSION, which describes the
connection to one particular server. You can make several connections to
different servers under the same process because of this structure.
<br>
<br>
<div class="prot">
SSH_SESSION *ssh_connect(SSH_OPTIONS *options);
</div>
This function returns a handle on the newly connection. This function expects
to have a pre-set options structure.
<br>
It returns NULL in case of error, in which case you can look at error messages
for more informations.
<br><br>
<div class="prot">
void ssh_disconnect(SSH_SESSION *session);
</div>
This function sends a polite disconnect message, and does clean the session.<br>
This is the proper way of finishing a ssh connection.<br>
<br>
<div class="prot">
int ssh_get_pubkey_hash(SSH_SESSION *session, char hash[MD5_DIGEST_LEN]);
</div>
This function places the MD5 hash of the server public key into the hash array.<br>
It's IMPORTANT to verify it matches the previous known value. One server always
have the same hash. No other server/attacker can emulate it (or it'd be caught
by the public key verification procedure automatically made by libssh).
<br>
You can skip this step if you correctly handle <i>is_server_known()</i>
<br><br>
<div class="prot">
int ssh_is_server_known(SSH_SESSION *session);
</div>
Checks the user's known host file to look for a previous connection to the specified server. Return values:<br>
SSH_SERVER_KNOWN_OK : the host is known and the key has not changed<br>
SSH_SERVER_KNOWN_CHANGED : The host's key has changed. Either you are under
an active attack or the key changed. The API doesn't give any way to modify the key in known hosts yet. I Urge end developers to WARN the user about the possibility of an attack.<br>
SSH_SERVER_FOUND_OTHER: The host gave us a public key of one type, which does
not exist yet in our known host file, but there is an other type of key which is know.<br>
IE server sent a DSA key and we had a RSA key.<br>
Be carreful it's a possible attack (coder should use option_set_wanted_method() to specify
which key to use).<br>
SSH_SERVER_NOT_KNOWN: the server is unknown in known hosts. Possible reasons :
case not matching, alias, ... In any case the user MUST confirm the Md5 hash is correct.<br>
SSH_SERVER_ERROR : Some error happened while opening known host file.<br>
<br>
<div class="prot">
int ssh_write_knownhost(SSH_SESSION *session);
</div>
write the current connected host as known in the known host file. returns a negative value if something went wrong. You generaly use it when ssh_is_server_known returned SSH_SERVER_NOT_KNOWN.
<br><br>
<div class="prot">
int pubkey_get_hash(SSH_SESSION *session,char hash[MD5_DIGEST_LEN]);
</div>
deprecated but left for binary compatibility (will be removed in newer versions).
</div>
<h2>3- Authenticating to server</h2>
<div class="tout">
The ssh library supports the two most used authentication methods from SSH.
In every function, there is a "username" argument. If null is given instead,
the server will use the default username (which is guessed from what you gave
to options_set_user or options_set_hostname or even the local user running the code).
<br>
Authentication methods :<br>
<h3>A) Public keys</h3><br>
The public key is the only method which does not compromise your key if the
remote host has been compromised (the server can't do anything more than
getting your public key). This is not the case of a password authentication
(the server can get your plaintext password).<br>
Libssh is obviously fully compatible with the openssh public and private keys.<br>
The things go this way : you scan a list of files which contain public keys.<br>
For each key, you send it to ssh server until the server acknowledges a key
(a key it knows). Then, you get the private key for this key and send a
message proving you own that private key.<br>
Here again, two ways for the public key authentication... the easy and the
complicated one.<br>
<br>
<h4> easy way:</h4>
<div class="prot">
int ssh_userauth_autopubkey(SSH_SESSION *session);
</div>
This function will try the most common places for finding the public and
private keys (your home directory) or eventualy the identity files asked by
the <i>options_set_identity()</i> function.<br>
The return values are :<br>
SSH_AUTH_ERROR : some serious error happened during authentication<br>
SSH_AUTH_DENIED : no key matched<br>
SSH_AUTH_SUCCESS : you are now authenticated<br>
SSH_AUTH_PARTIAL : some key matched but you still have to give an other mean
of authentication (like password).<br>
<br>
<h4> peanful way:</h4>
there are three steps : you get a public key, you ask the server if the key
matches a known one, if true, you get the private key and authenticate with
it.<br>
<div class="prot">
STRING *publickey_from_file(char *filename,int *_type);
</div>
will return an handle on a public key. if you give a pointer to an int,
a symbolic value will be placed there. Do it because you need it in next
step.<br><br>
<div class="prot">
int ssh_userauth_offer_pubkey(SSH_SESSION *session, char *username,
int type, STRING *publickey);
</div>
this function will offer a public key to the server. SSH_AUTH_SUCCESS is
returned if the key is accepted (in which case you'll want to get the
private key), SSH_AUTH_DENIED otherwise.<br>
Still watch for SSH_AUTH_ERROR as connection problems might happen.
<br>
in case of SSH_AUTH_SUCCESS,
<br>
<div class="prot">
PRIVATE_KEY *privatekey_from_file(SSH_SESSION *session,char *filename,
int type,char *passphrase);
</div>
will get the privatekey from the filename previously set by
publickey_from_next_file(). You can call it with a passphrase for
unlocking the key. If passphrase==NULL, the default prompt will be used.<br>
The function returns NULL if the private key wasn't opened
(ie bad passphrase or missing file).<br>
<br>
<div class="prot">
int ssh_userauth_pubkey(SSH_SESSION *session, char *username,
STRING *publickey, PRIVATE_KEY *privatekey);
</div>
Will try to authenticate using the public and private key. It shall return
SSH_AUTH_SUCCESS if you are authenticated, SSH_AUTH_ERROR, SSH_AUTH_DENIED or
SSH_AUTH_PARTIAL depending of return condition.<br>
each public key (of type STRING) must be freed with the libc "free" function.<br>
The private key must be freed with private_key_free(PRIVATE_KEY *) which
will clean the memory before (don't worry about passphrase leaking).<br>
<br>
<h3> B) Password</h3><br>
<div class="prot">
int ssh_userauth_password(SSH_SESSION *session,char *username,char *password);
</div>
Will return SSH_AUTH_SUCCESS if the password matched, one of other constants
otherwise. It's your work to ask the password and to free it in a secure
manner.<br><br>
<h3> C) Keyboard-interactive</h3><br>
<div class="prot">
int ssh_userauth_kbdint(SSH_SESSION *session, char *user, char *submethods);
</div>
This is the main keyboard-interactive function. It will return SSH_AUTH_SUCCESS,SSH_AUTH_DENIED, SSH_AUTH_PARTIAL, SSH_AUTH_ERROR depending on the result of the request.<br>
The keyboard-interactive authentication method of SSH2 is a feature which permits the server to ask a certain number of questions in an interactive manner to the client, until it decides to accept or deny the login.<br>
To begin, you call this function (you can omit user if it was set previously and omit submethods - instead you know what you do - just put them to NULL) and store the answer.
If the answer is SSH_AUTH_INFO, it means the server has sent a few questions to ask your user, which you can retrieve with the following functions. Then, set the answers and call back ssh_userauth_kbdint with same arguments. It may again ask a few other questions etc. until you get an other SSH_AUTH code than SSH_AUTH_INFO.<br>
Few remarks :<br>
-Even the first call can return SSH_AUTH_DENIED or SSH_AUTH_SUCCESS.<br>
-The server can send an empty question set (this is the default behavior on my system) after you have sent the answers to the first questions.
you must still parse the answer, it might contain some message from the server saying hello or such things. Just call ssh_userauth_kbdint() once more<br>
<br>
<div class="prot">
int ssh_userauth_kbdint_getnprompts(SSH_SESSION *session);
</div>
After you called ssh_userauth_kbdint and got SSH_AUTH_INFO, the session contains a few questions (or prompts) from the server. This function returns the number of prompts and answers.<br>
It could be zero, in which case you must act as said previously.<br>
<div class="prot">
char *ssh_userauth_kbdint_getname(SSH_SESSION *session);
</div>
this functions returns the "name" of the message block. The meaning is explained later.<br>
This function returns a pointer that stays valid until the next ssh_userauth_kbdint() call and must not be freed.<br>
<div class="prot">
char *ssh_userauth_kbdint_getinstruction(SSH_SESSION *session);
</div>
this functions returns the "instruction" of the message block. The meaning is explained later.<br>
This function returns a pointer that stays valid until the next ssh_userauth_kbdint() call and must not be freed.<br>
<div class="prot">
char *ssh_userauth_kbdint_getprompt(SSH_SESSION *session,int i, char *echo);
</div>
This functions returns a pointer to the nth prompt. The character pointed by echo, if different from null, will contain a boolean value after the call, which means that the user prompt must be echoed or not.<br>
zero means that the echo is Off (like for a password prompt).<br>
any other value means the echo is on.<br>
This function returns a pointer that stays valid until the next ssh_userauth_kbdint() call and must not be freed.<br>
<div class="prot">
void ssh_userauth_kbdint_setanswer(SSH_SESSION *session, unsigned int i, char *a
nswer);
</div>
This function sets the ith answer. The string you give will be duplicated, and this copy will be discarded once it is no longer necessary.<br>
care must be taken so you discard the content of the original string after this function call.<br>
<h3> A little note about how to use the informations from keyboard-interactive authentication</h3>
<br>
The words from the original drafts explain everything
<div class="prot">
3.3 User Interface
Upon receiving a request message, the client SHOULD prompt the user
as follows:<br>
A command line interface (CLI) client SHOULD print the name and
instruction (if non-empty), adding newlines. Then for each prompt in
turn, the client SHOULD display the prompt and read the user input.<br>
<br>
A graphical user interface (GUI) client has many choices on how to
prompt the user. One possibility is to use the name field (possibly
prefixed with the application's name) as the title of a dialog window
in which the prompt(s) are presented. In that dialog window, the
instruction field would be a text message, and the prompts would be
labels for text entry fields. All fields SHOULD be presented to the
user, for example an implementation SHOULD NOT discard the name field
because its windows lack titles; it SHOULD instead find another way
to display this information. If prompts are presented in a dialog
window, then the client SHOULD NOT present each prompt in a separate
window.<br>
<br>
All clients MUST properly handle an instruction field with embedded
newlines. They SHOULD also be able to display at least 30 characters
for the name and prompts. If the server presents names or prompts
longer than 30 characters, the client MAY truncate these fields to
the length it can display. If the client does truncate any fields,
there MUST be an obvious indication that such truncation has occured.<br>
The instruction field SHOULD NOT be truncated.<br>
Clients SHOULD use control character filtering as discussed in
[SSH-ARCH] to avoid attacks by including terminal control characters
in the fields to be displayed.<br>
<br>
For each prompt, the corresponding echo field indicates whether or
not the user input should be echoed as characters are typed. Clients
SHOULD correctly echo/mask user input for each prompt independently
of other prompts in the request message. If a client does not honor
the echo field for whatever reason, then the client MUST err on the
side of masking input. A GUI client might like to have a checkbox
toggling echo/mask. Clients SHOULD NOT add any additional characters
to the prompt such as ": " (colon-space); the server is responsible
for supplying all text to be displayed to the user. Clients MUST
also accept empty responses from the user and pass them on as empty
strings.<br>
</div>
<br>
<h3> D) "none"</h3><br>
In fact this mode only serve to get the list of supported authentications.<br>
however, it also serves to get the banner message from the server, if any.<br>
You should firstly try this method, at least for getting the banner, then to enter if there is no password at all.<br>
<div class="prot">
int ssh_userauth_none(SSH_SESSION *session, char *username);
</div>
if the account has no password (and the server is configured to let you
pass), the function might answer SSH_AUTH_SUCCESS. That's why
ssh_auth_autopubkey already calls it for you.
<br><br>
<div class="prot">
char *ssh_get_issue_banner(SSH_SESSION *session);
</div>
if during authentication, the server has given a banner, you can get it
this way. the function returns NULL if no banner exists, and you have to
free the returned pointer.<br><br>
</div>
<h2>4- Opening a channel</h2>
<div class="tout">
Maybe you want to use the sftp subsystem : all this is done for you, you
better read at the end of the paper how to use the sftp functions.<br>
You probably want to open one or more shells, or call one or more programs.<br>
So you need a channel.<br>
<div class="prot">
CHANNEL *channel;
</div>
This is an handler to a channel object. it describes your channel.
<br>
<div class="prot">
CHANNEL *channel_open_session(SSH_SESSION *session);
</div>
This will open a channel for use into a session (which can be used for executing
a command or a shell. Not for tcp forwarding).<br>
The function returns NULL if for a reason or another the channel can't be
opened.<br>
<i>
CHANNEL *open_session_channel(...)</i> is deprecated and should not be used in future
applications.<br><br>
<div class="prot">
CHANNEL *channel_open_forward(SSH_SESSION *session, char *remotehost,
int remoteport, char *sourcehost, int localport);
</div>
Ask the server to tunnel a TCP connection. The server will connect to
remotehost:remoteport and libssh will return an handle to the channel if it is allowed.<br>
Otherwise, NULL will be returned. sourcehost and localport are generaly
used in message debugging purpose and have no effect on the result.<br>
<br>
When you've finished with your channel, you may send an EOF message and
then close it :<br>
<div class="prot">
void channel_send_eof(CHANNEL *channel);
</div>
sends an end of file into channel. It doesn't close the channel and you can still read it.<br><br>
<div class="prot">
void channel_free(CHANNEL *channel);
</div>
closes and destroy the channel.
<br>
<div class="prot">
void channel_close(CHANNEL *channel);
</div>
sends an EOF and close the channel. (if you don't know what to do, use channel_free). It doesn't free the channel.
</div>
<h2>5- The shell</h2>
<div class="tout">
<div class="prot">
int channel_request_env(CHANNEL *channel, char *name, char *value);
</div>
Ask the server to set the "name" environment variable to "value". For security
reasons, some variables won't be accepted by the server. It returns 0 otherwise.<br><br>
<div class="prot">
int channel_request_pty(CHANNEL *channel);
</div>
ask the server to allocate a pseudo terminal for the current channel.<br>
the function returns 0 on success.<br><br>
<div class="prot">
int channel_request_pty_size(CHANNEL *channel, char *terminal, int cols, int rows);
</div>
ask the server to allocate a pty. The terminal parameter is the type of pty
(vt100,xterm,...), cols and rows are the size of the new terminal (80x24 by example).<br><br>
<div class="prot">
int channel_change_pty_size(CHANNEL *channel, int cols,int rows);
</div>
changes the window size (terminal) of the current session;<br><br>
<div class="prot">
int channel_request_shell(CHANNEL *channel);
</div>
This function requests a shell. After its success, a shell is running at the other side of the channel.<br><br>
<div class="prot">
int channel_request_exec(CHANNEL *channel, char *cmd);
</div>
run a shell command without an interactive shell, ie $SHELL -c "command".<br>
returns 0 on success.<br><br>
You might ask the server to open a subsystem for you. this is done this way :
<div class="prot">
int channel_request_subsystem(CHANNEL *channel, char *subsystem);
</div>
There are some functions used to manipulate the channels :
<br><br>
<div class="prot">
int channel_write(CHANNEL *channel,void *data,int len);
</div>
writes len bytes of data into the channel. It returns the number of bytes written. The current implementation is a blocking write
of the complete data buffer, but it may vary.<br><br>
<div class="prot">
int channel_read(CHANNEL *channel, BUFFER *buffer,int bytes,int is_stderr);
</div>
It makes a blocking read on the channel, of "bytes" bytes and returns the
result into an allocated buffer you passed in. (with <i>buffer_new()</i>).<br>
it will read on stderr, if is_stderr is set.<br>
The function might read less bytes than "bytes" variable if an End of File
happened. Otherwise, the function will always block reading until "bytes"
bytes are read.<br>
with "bytes"=0, <i>channel_read()</i> will read the current state of the read buffer, but will read at least one byte (and block if nothing is available, except EOF case).<br>
You don't need to free and allocate a new buffer each time you call this function, just pass the same object each time.<br>
look at the <i>buffer_</i> functions further for the correct way of retrieving the data.<br><br>
<div class="prot">
int channel_read_nonblocking (CHANNEL *channel, char *dest, int len, int is_stderr);
</div>
Non-blocking read on channel, at most len bytes of data are read. Returns 0 if EOF or if no data available.
<br><br>
<div class="prot">
int channel_is_open(CHANNEL *channel);
</div>
returns 0 if the channel has been closed by remote host, something else otherwise.<br><br>
<div class="prot">
int channel_poll(CHANNEL *channel, int is_stderr);
</div>
This nonblocking function returns the number of bytes immediatly available for
reading on the channel and stdin/stderr.<br><br>
More interesting, if you are going to do channel multiplexing, this function
is for you :<br><br>
<div class="prot">
int ssh_select(CHANNEL **channels,CHANNEL **outchannels, int maxfd,
fd_set *readfds, struct timeval *timeout);
</div>
channels is an array of channel pointers, finished by a NULL pointer.<br>
It can be used ever and ever, as it is never written.<br>
outchannels is an array of size at least greater or equal to "channels".<br>
It hasn't to be initialized.<br>
maxfd is the maximum file descriptor from your own filedescriptors.<br>
readfds is a pointer to a fd_set structure, like in the original
select implementation (man select).<br>
the struct timeval *timeout has the same meaning than in
select(2) (man select).<br>
There is no support for writing or special events as in <i>select(2)</i> yet.<br>
The function returns -1 if an error occured, or SSH_EINTR if select was interrupted by a syscall. This is not an error, you may restart the function.<br>
<b>note about signals:</b> libssh is not threadsafe, and most functions are not
reetrant when using the same data structures : it means you *cannot* do anything
with a channel from a ssh session passed to <i>ssh_select</i> during a signal.
<br>take a look at sample.c on how to bypass that limitation.<br>
the function works this way : it returns in the readfds the filedescriptors which have data ready for reading (the given filedescriptors have a greatest priority).<br>
Then, if no file descriptor can be read, the function looks for every
channel from the array to get a channel with data bufferized. If nothing is
available, it waits for activity on any channel/file descriptor and returns
immediatly, or waits until timeout.<br>
You will find the channels that can be read in the outchannels array (finished by NULL) and the filedescriptors in your fd_set (man FD_ISSET).<br>
this is the "heart" of your main loop.<br>
<br>
<h3>The BUFFER object.</h3>
Reading is done through the BUFFER object. here is the public interface :
<br>
<div class="prot">
BUFFER *buffer_new();
</div>
creates a buffer object.
<br><br>
<div class="prot">
void *buffer_get(BUFFER *buffer);
</div>
returns a pointer to the begining of buffer.
<br><br>
<div class="prot">
int buffer_get_len(BUFFER *buffer);
</div>
returns buffer's data size.
<br><br>
<div class="prot">
void buffer_free(BUFFER *buffer);
</div>
destoys the buffer.
<br>
<br>
How to use the buffer system when you've read something:<br>
I've seen people doing such code:<br>
<div class="prot">
char buffer[256];<br>
channel_read(channel,buf,1234,0);<br>
strcpy(buffer,buf.data);<br>
</div>
The correct way of doing this:
<div class="prot">
char buffer[256];<br>
int i;<br>
i=channel_read(channel,buf,1234,0);<br>
if(i<=0)<br>
&nbsp;&nbsp;&nbsp;&nbsp;go_out()...<br>
if(i>=256)<br>
&nbsp;&nbsp;&nbsp;&nbsp;i=255;<br>
memcpy(buffer,buffer_get(buf),i);<br>
buffer[i]=0;
</div>
Do not expect the buffer to be null-terminated. Don't access the internal structure of buffer. Check the sizes before copying.<br>
</div>
<h2>6- The SFTP subsystem</h2>
<div class="tout">
SFTP is a secure implementation of a file transfer protocol. The current
implemented version is 3. All functions aren't implemented yet but the most
important are.<br>
<br>
<h3>A) Opening the session</h3>
<div class="prot">
SFTP_SESSION *sftp_new(SSH_SESSION *session);
int sftp_init(SFTP_SESSION *sftp);
</div>
The former returns a SFTP_SESSION handle. It returns NULL if things didn't
work as expected.<br>
sftp_init makes some initialisation work. It returns 0 if things went right.
Both of them must be called.<br>
<h3>B) Opening and reading a directory</h3>
<div class="prot">
SFTP_DIR *sftp_opendir(SFTP_SESSION *session, char *path);
</div>
opens a directory for file listing. Returns NULL in error case.
<br><br>
<div class="prot">
SFTP_ATTRIBUTES *sftp_readdir(SFTP_SESSION *session, SFTP_DIR *dir);
</div>
This function reads one file attribute from an opened directory. It
returns NULL if the directory is EOF, or if something wrong happened.
<br><br>
<div class="prot">
int sftp_dir_eof(SFTP_DIR *dir);
</div>
When a <i>sftp_readdir()</i> returned NULL, you can use this function to
tell if an EOF occured. the function returns 0 if no EOF occured.
<br><br>
<div class="prot">
void sftp_attributes_free(SFTP_ATTRIBUTES *file);
</div>
You have to free any SFTP_ATTRIBUTE structure given by an other function
with it.<br><br>
<div class="prot">
int sftp_dir_close(SFTP_DIR *dir);
</div>
closes an opened directory. returns 0 when no error occured.
<br><br>
<h3>C) Opening, reading, writing files</h3>
<div class="prot">
SFTP_FILE *sftp_open(SFTP_SESSION *session, char *file, int access,
SFTP_ATTRIBUTES *attr);
</div>
Opens a file. The access flags are the same than the stdio flags.<br>
see open(2) for more details.<br>
attr are the wanted attributes for the new file. If you supply NULL,
default values will be used.<br>
rem: more work is going on parsing/making the attributes structure
<br><br>
<div class="prot">
int sftp_read(SFTP_FILE *file, void *dest, int len);
</div>
read on a file. Works as the fread() function. It is blocking by default but you can change the default behaviour with <i>sftp_file_set_nonblocking()</i>.
<br><br>
<div class="prot">
void sftp_file_set_nonblocking(SFTP_FILE *file);
</div>
sets the file non blocking. reads on this file won't ever block. You can't detect end of files this way.<br>
*** TODO more work going there for EOF ****
<br><br>
<div class="prot">
void sftp_file_set_blocking(SFTP_FILE *file);
</div>
restore the default setting of sftp_read.
<br><br>
<div class="prot">
int sftp_write(SFTP_FILE *file, void *source, int len);
</div>
works as fwrite() function. It is a blocking write.<br>
<br>
<div class="prot">
void sftp_seek(SFTP_FILE *file, int new_offset);
</div>
seek into the file for reading/writing at an other place.
<br><br>
<div class="prot">
unsigned long sftp_tell(SFTP_FILE *file);
</div>
returns the current offset (both writing and reading) into the opened file.
<br><br>
<div class="prot">
void sftp_rewind(SFTP_FILE *file);
</div>
same as sftp_seek(file,0);
<br><br>
<div class="prot">
int sftp_file_close(SFTP_FILE *file);
</div>
closes a file handle. returns 0 in no error case.
<br><br>
<div class="prot">
int sftp_rm(SFTP_SESSION *sftp, char *file);
</div>
deletes a file.
<br><br>
<div class="prot">
int sftp_rmdir(SFTP_SESSION *sftp, char *directory);
</div>
<br>
deletes a directory.
<br><br>
<div class="prot">
int sftp_mkdir(SFTP_SESSION *sftp, char *directory, SFTP_ATTRIBUTES *attr);
</div>
makes a directory, with the given attributes. You can't pass NULL for attr and hope it works.
<br><br>
<div class="prot">
int sftp_rename(SFTP_SESSION *sftp, char *original, char *newname);
</div>
changes the name of a file or directory.
<br><br>
<div class="prot">
int sftp_setstat(SFTP_SESSION *sftp, char *file, SFTP_ATTRIBUTES *attr);
</div>
changes the attributes of a file or directory.
<br><br>
<div class="prot">
char *sftp_canonicalize_path(SFTP_SESSION *sftp, char *path);
</div>
gives the canonicalized form of some path. You have to
free the pointer given in return.<br>
(returns NULL if error).
<br><br>
(a function to make proper SFTP_ATTRIBUTES structures is on the way )
<h3>D) Closing the session</h3>
<div class="prot">
void sftp_free(SFTP_SESSION *sftp);
</div>
it closes the sftp channel and subsystem.
</div>
<h2>7- Handling the errors</h2>
<div class="tout">
When some function returns an error code, it's allways possible to get an
english message describing the problem. the function ssh_get_error()
returns a pointer to the static error buffer.<br>
ssh_error_code() returns the error code number. it's declared as an enum:<br>
SSH_NO_ERROR, SSH_REQUEST_DENIED, SSH_INVALID_REQUEST, SSH_CONNECTION_LOST,
SSH_FATAL, SSH_INVALID_DATA.<br><br>
SSH_REQUEST_DENIED means the ssh server refused your request but the situation is
recoverable. the others mean something happened to the connection (some
encryption problems, server problems, library bug, ...).<br>
SSH_INVALID_REQUEST means the library got some garbage from server. (But might be
recoverable).<br>
SSH_FATAL means the connection has an important problem and isn't probably
recoverable.<br>
<br>
Most of time, the error returned are SSH_FATAL, but some functions (generaly the
<i>ssh_request_*</i> ones) may fail because of server denying request. In these cases, SSH_REQUEST_DENIED is returned.<br><br>
You'll see in the prototype SSH_SESSION *session. That's because for thread
safety, error messages that can be attached to a session aren't static
anymore. So, any error that could happen during ssh_getopt(), options_* or
ssh_connect() will be retreavable giving NULL as argument.<br>
<br>
<div class="prot">
char *ssh_get_error(SSH_SESSION *session);
</div>
returns a pointer to a static message error from the given session. No
message freeing is needed.<br><br>
<div class="prot">
enum ssh_error ssh_get_error_code(SSH_SESSION *session);
</div>
returns the error code that last happened along with the message.
<br><br>
</div>
<h2>8- Final word</h2>
<div class="tout">
I made this library because nothing in the Open source or free software community was existing yet. This project is a very personnal one as it's the first "useful" thing I ever wrote.
I hope it fits your needs, but remember the experimental state of libssh : if
something doesn't work, please mail me. If something lacks, please ask for it.
If something stinks, please write a patch and send it !
</div>
</body>
</html>

107
doc/base64.txt Normal file
View File

@@ -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.

647
doc/draft-ietf-secsh-agent-01.txt Normal file
View File

@@ -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]

1736
doc/draft-ietf-secsh-architecture-14.txt Normal file
View File

File diff suppressed because it is too large Load Diff

559
doc/draft-ietf-secsh-assignednumbers-04.txt Normal file
View File

@@ -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]

366
doc/draft-ietf-secsh-auth-kbdinteract-05-cleaned.txt Normal file
View File

@@ -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

619
doc/draft-ietf-secsh-auth-kbdinteract-05.txt Normal file
View File

@@ -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]

394
doc/draft-ietf-secsh-break-00.txt Normal file
View File

@@ -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]

1232
doc/draft-ietf-secsh-connect-17.txt Normal file
View File

File diff suppressed because it is too large Load Diff

451
doc/draft-ietf-secsh-dh-group-exchange-04.txt Normal file
View File

@@ -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]

616
doc/draft-ietf-secsh-dns-04.txt Normal file
View File

@@ -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]

1626
doc/draft-ietf-secsh-filexfer-02.txt Normal file
View File

File diff suppressed because it is too large Load Diff

1962
doc/draft-ietf-secsh-filexfer-03.txt Normal file
View File

File diff suppressed because it is too large Load Diff

2130
doc/draft-ietf-secsh-filexfer-04.txt Normal file
View File

File diff suppressed because it is too large Load Diff

120
doc/draft-ietf-secsh-fingerprint-01.txt Normal file
View File

@@ -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]

1509
doc/draft-ietf-secsh-gsskeyex-06.txt Normal file
View File

File diff suppressed because it is too large Load Diff

619
doc/draft-ietf-secsh-newmodes-00.txt Normal file
View File

@@ -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]

506
doc/draft-ietf-secsh-publickeyfile-03.txt Normal file
View File

@@ -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]

426
doc/draft-ietf-secsh-scp-sftp-ssh-uri-00.txt Normal file
View File

@@ -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]

1624
doc/draft-ietf-secsh-transport-16.txt Normal file
View File

File diff suppressed because it is too large Load Diff

840
doc/draft-ietf-secsh-userauth-17.txt Normal file
View File

@@ -0,0 +1,840 @@
Network Working Group T. Ylonen
Internet-Draft T. Kivinen
Expires: March 2, 2003 SSH Communications Security Corp
M. Saarinen
University of Jyvaskyla
T. Rinne
S. Lehtinen
SSH Communications Security Corp
September 2002
SSH Authentication Protocol
draft-ietf-secsh-userauth-17.txt
Status of this Memo
This document is an Internet-Draft and is in full conformance with
all provisions of Section 10 of RFC2026.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that
other groups may also distribute working documents as Internet-
Drafts.
Internet-Drafts are draft documents valid for a maximum of six
months and may be updated, replaced, or obsoleted by other
documents at any time. It is inappropriate to use Internet-Drafts
as reference material or to cite them other than as "work in
progress."
The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt.
The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html.
This Internet-Draft will expire on March 2, 2003.
Copyright Notice
Copyright (C) The Internet Society (2002). All Rights Reserved.
Abstract
SSH is a protocol for secure remote login and other secure network
services over an insecure network. This document describes the
SSH authentication protocol framework and public key, password,
and host-based client authentication methods. Additional
authentication methods are described in separate documents. The
Ylonen, et. al. Expires March 2, 2003 [Page 1]
Internet-Draft SSH Authentication Protocol September 2002
SSH authentication protocol runs on top of the SSH transport layer
protocol and provides a single authenticated tunnel for the SSH
connection protocol.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
2. The Authentication Protocol Framework . . . . . . . . . . . . 3
2.1 Authentication Requests . . . . . . . . . . . . . . . . . . . 4
2.2 Responses to Authentication Requests . . . . . . . . . . . . . 5
2.3 The "none" Authentication Request . . . . . . . . . . . . . . 6
2.4 Completion of User Authentication . . . . . . . . . . . . . . 6
2.5 Banner Message . . . . . . . . . . . . . . . . . . . . . . . . 6
3. Authentication Protocol Message Numbers . . . . . . . . . . . 7
4. Public Key Authentication Method: publickey . . . . . . . . . 7
5. Password Authentication Method: password . . . . . . . . . . . 9
6. Host-Based Authentication: hostbased . . . . . . . . . . . . . 11
7. Security Considerations . . . . . . . . . . . . . . . . . . . 12
8. Intellectual Property . . . . . . . . . . . . . . . . . . . . 12
9. Additional Information . . . . . . . . . . . . . . . . . . . . 13
References . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . 14
Full Copyright Statement . . . . . . . . . . . . . . . . . . . 15
Ylonen, et. al. Expires March 2, 2003 [Page 2]
Internet-Draft SSH Authentication Protocol September 2002
1. Introduction
The SSH authentication protocol is a general-purpose user
authentication protocol. It is intended to be run over the SSH
transport layer protocol [SSH-TRANS]. This protocol assumes that
the underlying protocols provide integrity and confidentiality
protection.
This document should be read only after reading the SSH
architecture document [SSH-ARCH]. This document freely uses
terminology and notation from the architecture document without
reference or further explanation.
The service name for this protocol is "ssh-userauth".
When this protocol starts, it receives the session identifier from
the lower-level protocol (this is the exchange hash H from the
first key exchange). The session identifier uniquely identifies
this session and is suitable for signing in order to prove
ownership of a private key. This protocol also needs to know
whether the lower-level protocol provides confidentiality
protection.
2. The Authentication Protocol Framework
The server drives the authentication by telling the client which
authentication methods can be used to continue the exchange at any
given time. The client has the freedom to try the methods listed
by the server in any order. This gives the server complete
control over the authentication process if desired, but also gives
enough flexibility for the client to use the methods it supports
or that are most convenient for the user, when multiple methods
are offered by the server.
Authentication methods are identified by their name, as defined in
[SSH-ARCH]. The "none" method is reserved, and MUST NOT be listed
as supported. However, it MAY be sent by the client. The server
MUST always reject this request, unless the client is to be
allowed in without any authentication, in which case the server
MUST accept this request. The main purpose of sending this
request is to get the list of supported methods from the server.
The server SHOULD have a timeout for authentication, and
disconnect if the authentication has not been accepted within the
timeout period. The RECOMMENDED timeout period is 10 minutes.
Additionally, the implementation SHOULD limit the number of failed
authentication attempts a client may perform in a single session
(the RECOMMENDED limit is 20 attempts). If the threshold is
Ylonen, et. al. Expires March 2, 2003 [Page 3]
Internet-Draft SSH Authentication Protocol September 2002
exceeded, the server SHOULD disconnect.
2.1 Authentication Requests
All authentication requests MUST use the following message format.
Only the first few fields are defined; the remaining fields depend
on the authentication method.
byte SSH_MSG_USERAUTH_REQUEST
string user name (in ISO-10646 UTF-8 encoding [RFC2279])
string service name (in US-ASCII)
string method name (US-ASCII)
The rest of the packet is method-specific.
The user name and service are repeated in every new authentication
attempt, and MAY change. The server implementation MUST carefully
check them in every message, and MUST flush any accumulated
authentication states if they change. If it is unable to flush
some authentication state, it MUST disconnect if the user or
service name changes.
The service name specifies the service to start after
authentication. There may be several different authenticated
services provided. If the requested service is not available, the
server MAY disconnect immediately or at any later time. Sending a
proper disconnect message is RECOMMENDED. In any case, if the
service does not exist, authentication MUST NOT be accepted.
If the requested user does not exist, the server MAY disconnect,
or MAY send a bogus list of acceptable authentication methods, but
never accept any. This makes it possible for the server to avoid
disclosing information on which accounts exist. In any case, if
the user does not exist, the authentication request MUST NOT be
accepted.
While there is usually little point for clients to send requests
that the server does not list as acceptable, sending such requests
is not an error, and the server SHOULD simply reject requests that
it does not recognize.
An authentication request MAY result in a further exchange of
messages. All such messages depend on the authentication method
used, and the client MAY at any time continue with a new
SSH_MSG_USERAUTH_REQUEST message, in which case the server MUST
abandon the previous authentication attempt and continue with the
new one.
Ylonen, et. al. Expires March 2, 2003 [Page 4]
Internet-Draft SSH Authentication Protocol September 2002
2.2 Responses to Authentication Requests
If the server rejects the authentication request, it MUST respond
with the following:
byte SSH_MSG_USERAUTH_FAILURE
string authentications that can continue
boolean partial success
"Authentications that can continue" is a comma-separated list of
authentication method names that may productively continue the
authentication dialog.
It is RECOMMENDED that servers only include those methods in the
list that are actually useful. However, it is not illegal to
include methods that cannot be used to authenticate the user.
Already successfully completed authentications SHOULD NOT be
included in the list, unless they really should be performed again
for some reason.
"Partial success" MUST be TRUE if the authentication request to
which this is a response was successful. It MUST be FALSE if the
request was not successfully processed.
When the server accepts authentication, it MUST respond with the
following:
byte SSH_MSG_USERAUTH_SUCCESS
Note that this is not sent after each step in a multi-method
authentication sequence, but only when the authentication is
complete.
The client MAY send several authentication requests without
waiting for responses from previous requests. The server MUST
process each request completely and acknowledge any failed
requests with a SSH_MSG_USERAUTH_FAILURE message before processing
the next request.
A request that results in further exchange of messages will be
aborted by a second request. It is not possible to send a second
request without waiting for a response from the server, if the
first request will result in further exchange of messages. No
SSH_MSG_USERAUTH_FAILURE message will be sent for the aborted
method.
SSH_MSG_USERAUTH_SUCCESS MUST be sent only once. When
Ylonen, et. al. Expires March 2, 2003 [Page 5]
Internet-Draft SSH Authentication Protocol September 2002
SSH_MSG_USERAUTH_SUCCESS has been sent, any further authentication
requests received after that SHOULD be silently ignored.
Any non-authentication messages sent by the client after the
request that resulted in SSH_MSG_USERAUTH_SUCCESS being sent MUST
be passed to the service being run on top of this protocol. Such
messages can be identified by their message numbers (see Section
Message Numbers (Section 3)).
2.3 The "none" Authentication Request
A client may request a list of authentication methods that may
continue by using the "none" authentication method.
If no authentication at all is needed for the user, the server
MUST return SSH_MSG_USERAUTH_SUCCESS. Otherwise, the server MUST
return SSH_MSG_USERAUTH_FAILURE and MAY return with it a list of
authentication methods that can continue.
This method MUST NOT be listed as supported by the server.
2.4 Completion of User Authentication
Authentication is complete when the server has responded with
SSH_MSG_USERAUTH_SUCCESS; all authentication related messages
received after sending this message SHOULD be silently ignored.
After sending SSH_MSG_USERAUTH_SUCCESS, the server starts the
requested service.
2.5 Banner Message
In some jurisdictions, sending a warning message before
authentication may be relevant for getting legal protection. Many
UNIX machines, for example, normally display text from
`/etc/issue', or use "tcp wrappers" or similar software to display
a banner before issuing a login prompt.
The SSH server may send a SSH_MSG_USERAUTH_BANNER message at any
time before authentication is successful. This message contains
text to be displayed to the client user before authentication is
attempted. The format is as follows:
byte SSH_MSG_USERAUTH_BANNER
string message (ISO-10646 UTF-8)
string language tag (as defined in [RFC1766])
The client SHOULD by default display the message on the screen.
Ylonen, et. al. Expires March 2, 2003 [Page 6]
Internet-Draft SSH Authentication Protocol September 2002
However, since the message is likely to be sent for every login
attempt, and since some client software will need to open a
separate window for this warning, the client software may allow
the user to explicitly disable the display of banners from the
server. The message may consist of multiple lines.
If the message string is displayed, control character filtering
discussed in [SSH-ARCH] SHOULD be used to avoid attacks by sending
terminal control characters.
3. Authentication Protocol Message Numbers
All message numbers used by this authentication protocol are in
the range from 50 to 79, which is part of the range reserved for
protocols running on top of the SSH transport layer protocol.
Message numbers of 80 and higher are reserved for protocols
running after this authentication protocol, so receiving one of
them before authentication is complete is an error, to which the
server MUST respond by disconnecting (preferably with a proper
disconnect message sent first to ease troubleshooting).
After successful authentication, such messages are passed to the
higher-level service.
These are the general authentication message codes:
#define SSH_MSG_USERAUTH_REQUEST 50
#define SSH_MSG_USERAUTH_FAILURE 51
#define SSH_MSG_USERAUTH_SUCCESS 52
#define SSH_MSG_USERAUTH_BANNER 53
In addition to the above, there is a range of message numbers
(60..79) reserved for method-specific messages. These messages
are only sent by the server (client sends only
SSH_MSG_USERAUTH_REQUEST messages). Different authentication
methods reuse the same message numbers.
4. Public Key Authentication Method: publickey
The only REQUIRED authentication method is public key
authentication. All implementations MUST support this method;
however, not all users need to have public keys, and most local
policies are not likely to require public key authentication for
all users in the near future.
With this method, the possession of a private key serves as
authentication. This method works by sending a signature created
Ylonen, et. al. Expires March 2, 2003 [Page 7]
Internet-Draft SSH Authentication Protocol September 2002
with a private key of the user. The server MUST check that the
key is a valid authenticator for the user, and MUST check that the
signature is valid. If both hold, the authentication request MUST
be accepted; otherwise it MUST be rejected. (Note that the server
MAY require additional authentications after successful
authentication.)
Private keys are often stored in an encrypted form at the client
host, and the user must supply a passphrase before the signature
can be generated. Even if they are not, the signing operation
involves some expensive computation. To avoid unnecessary
processing and user interaction, the following message is provided
for querying whether authentication using the key would be
acceptable.
byte SSH_MSG_USERAUTH_REQUEST
string user name
string service
string "publickey"
boolean FALSE
string public key algorithm name
string public key blob
Public key algorithms are defined in the transport layer
specification [SSH-TRANS]. The public key blob may contain
certificates.
Any public key algorithm may be offered for use in authentication.
In particular, the list is not constrained by what was negotiated
during key exchange. If the server does not support some
algorithm, it MUST simply reject the request.
The server MUST respond to this message with either
SSH_MSG_USERAUTH_FAILURE or with the following:
byte SSH_MSG_USERAUTH_PK_OK
string public key algorithm name from the request
string public key blob from the request
To perform actual authentication, the client MAY then send a
signature generated using the private key. The client MAY send
the signature directly without first verifying whether the key is
acceptable. The signature is sent using the following packet:
byte SSH_MSG_USERAUTH_REQUEST
string user name
string service
string "publickey"
Ylonen, et. al. Expires March 2, 2003 [Page 8]
Internet-Draft SSH Authentication Protocol September 2002
boolean TRUE
string public key algorithm name
string public key to be used for authentication
string signature
Signature is a signature by the corresponding private key over the
following data, in the following order:
string session identifier
byte SSH_MSG_USERAUTH_REQUEST
string user name
string service
string "publickey"
boolean TRUE
string public key algorithm name
string public key to be used for authentication
When the server receives this message, it MUST check whether the
supplied key is acceptable for authentication, and if so, it MUST
check whether the signature is correct.
If both checks succeed, this method is successful. Note that the
server may require additional authentications. The server MUST
respond with SSH_MSG_USERAUTH_SUCCESS (if no more authentications
are needed), or SSH_MSG_USERAUTH_FAILURE (if the request failed,
or more authentications are needed).
The following method-specific message numbers are used by the
publickey authentication method.
/* Key-based */
#define SSH_MSG_USERAUTH_PK_OK 60
5. Password Authentication Method: password
Password authentication uses the following packets. Note that a
server MAY request the user to change the password. All
implementations SHOULD support password authentication.
byte SSH_MSG_USERAUTH_REQUEST
string user name
string service
string "password"
boolean FALSE
string plaintext password (ISO-10646 UTF-8)
Note that the password is encoded in ISO-10646 UTF-8. It is up to
Ylonen, et. al. Expires March 2, 2003 [Page 9]
Internet-Draft SSH Authentication Protocol September 2002
the server how it interprets the password and validates it against
the password database. However, if the client reads the password
in some other encoding (e.g., ISO 8859-1 (ISO Latin1)), it MUST
convert the password to ISO-10646 UTF-8 before transmitting, and
the server MUST convert the password to the encoding used on that
system for passwords.
Note that even though the cleartext password is transmitted in the
packet, the entire packet is encrypted by the transport layer.
Both the server and the client should check whether the underlying
transport layer provides confidentiality (i.e., if encryption is
being used). If no confidentiality is provided (none cipher),
password authentication SHOULD be disabled. If there is no
confidentiality or no MAC, password change SHOULD be disabled.
Normally, the server responds to this message with success or
failure. However, if the password has expired the server SHOULD
indicate this by responding with
SSH_MSG_USERAUTH_PASSWD_CHANGEREQ. In anycase the server MUST NOT
allow an expired password to be used for authentication.
byte SSH_MSG_USERAUTH_PASSWD_CHANGEREQ
string prompt (ISO-10646 UTF-8)
string language tag (as defined in [RFC1766])
In this case, the client MAY continue with a different
authentication method, or request a new password from the user and
retry password authentication using the following message. The
client MAY also send this message instead of the normal password
authentication request without the server asking for it.
byte SSH_MSG_USERAUTH_REQUEST
string user name
string service
string "password"
boolean TRUE
string plaintext old password (ISO-10646 UTF-8)
string plaintext new password (ISO-10646 UTF-8)
The server must reply to request message with
SSH_MSG_USERAUTH_SUCCESS, SSH_MSG_USERAUTH_FAILURE, or another
SSH_MSG_USERAUTH_PASSWD_CHANGEREQ. The meaning of these is as
follows:
SSH_MSG_USERAUTH_SUCCESS The password has been changed, and
authentication has been successfully completed.
SSH_MSG_USERAUTH_FAILURE with partial success The password has
Ylonen, et. al. Expires March 2, 2003 [Page 10]
Internet-Draft SSH Authentication Protocol September 2002
been changed, but more authentications are needed.
SSH_MSG_USERAUTH_FAILURE without partial success The password
has not been changed. Either password changing was not
supported, or the old password was bad. Note that if the
server has already sent SSH_MSG_USERAUTH_PASSWD_CHANGEREQ, we
know that it supports changing the password.
SSH_MSG_USERAUTH_CHANGEREQ The password was not changed because
the new password was not acceptable (e.g. too easy to guess).
The following method-specific message numbers are used by the
password authentication method.
#define SSH_MSG_USERAUTH_PASSWD_CHANGEREQ 60
6. Host-Based Authentication: hostbased
Some sites wish to allow authentication based on the host where
the user is coming from, and the user name on the remote host.
While this form of authentication is not suitable for high-
security sites, it can be very convenient in many environments.
This form of authentication is OPTIONAL. When used, special care
SHOULD be taken to prevent a regular user from obtaining the
private host key.
The client requests this form of authentication by sending the
following message. It is similar to the UNIX "rhosts" and
"hosts.equiv" styles of authentication, except that the identity
of the client host is checked more rigorously.
This method works by having the client send a signature created
with the private key of the client host, which the server checks
with that host's public key. Once the client host's identity is
established, authorization (but no further authentication) is
performed based on the user names on the server and the client,
and the client host name.
byte SSH_MSG_USERAUTH_REQUEST
string user name
string service
string "hostbased"
string public key algorithm for host key
string public host key and certificates for client host
string client host name (FQDN; US-ASCII)
string user name on the client host (ISO-10646 UTF-8)
string signature
Ylonen, et. al. Expires March 2, 2003 [Page 11]
Internet-Draft SSH Authentication Protocol September 2002
Public key algorithm names for use in "public key algorithm for
host key" are defined in the transport layer specification. The
"public host key for client host" may include certificates.
Signature is a signature with the private host key of the
following data, in this order:
string session identifier
byte SSH_MSG_USERAUTH_REQUEST
string user name
string service
string "hostbased"
string public key algorithm for host key
string public host key and certificates for client host
string client host name (FQDN; US-ASCII)
string user name on the client host(ISO-10646 UTF-8)
The server MUST verify that the host key actually belongs to the
client host named in the message, that the given user on that host
is allowed to log in, and that the signature is a valid signature
on the appropriate value by the given host key. The server MAY
ignore the client user name, if it wants to authenticate only the
client host.
It is RECOMMENDED that whenever possible, the server perform
additional checks to verify that the network address obtained from
the (untrusted) network matches the given client host name. This
makes exploiting compromised host keys more difficult. Note that
this may require special handling for connections coming through a
firewall.
7. Security Considerations
The purpose of this protocol is to perform client user
authentication. It assumed that this runs over a secure transport
layer protocol, which has already authenticated the server
machine, established an encrypted communications channel, and
computed a unique session identifier for this session. The
transport layer provides forward secrecy for password
authentication and other methods that rely on secret data.
Full security considerations for this protocol are provided in
Section 8 of [SSH-ARCH]
8. Intellectual Property
The IETF takes no position regarding the validity or scope of any
intellectual property or other rights that might be claimed to
Ylonen, et. al. Expires March 2, 2003 [Page 12]
Internet-Draft SSH Authentication Protocol September 2002
pertain to the implementation or use of the technology described
in this document or the extent to which any license under such
rights might or might not be available; neither does it represent
that it has made any effort to identify any such rights.
Information on the IETF's procedures with respect to rights in
standards-track and standards-related documentation can be found
in BCP-11. Copies of claims of rights made available for
publication and any assurances of licenses to be made available,
or the result of an attempt made to obtain a general license or
permission for the use of such proprietary rights by implementers
or users of this specification can be obtained from the IETF
Secretariat.
The IETF has been notified of intellectual property rights claimed
in regard to some or all of the specification contained in this
document. For more information consult the online list of claimed
rights.
9. Additional Information
The current document editor is: Darren.Moffat@Sun.COM. Comments
on this internet draft should be sent to the IETF SECSH working
group, details at: http://ietf.org/html.charters/secsh-
charter.html
References
[RFC1766] Alvestrand, H., "Tags for the Identification of
Languages", RFC 1766, March 1995.
[RFC2279] Yergeau, F., "UTF-8, a transformation format of
ISO 10646", RFC 2279, January 1998.
[SSH-ARCH] Ylonen, T., "SSH Protocol Architecture", I-D
draft-ietf-architecture-14.txt, July 2003.
[SSH-TRANS] Ylonen, T., "SSH Transport Layer Protocol", I-D
draft-ietf-transport-16.txt, July 2003.
[SSH-USERAUTH] Ylonen, T., "SSH Authentication Protocol", I-D
draft-ietf-userauth-17.txt, July 2003.
[SSH-CONNECT] Ylonen, T., "SSH Connection Protocol", I-D draft-
ietf-connect-17.txt, July 2003.
[SSH-NUMBERS] Lehtinen, S. and D. Moffat, "SSH Protocol Assigned
Numbers", I-D draft-ietf-secsh-assignednumbers-
03.txt, July 2003.
Ylonen, et. al. Expires March 2, 2003 [Page 13]
Internet-Draft SSH Authentication Protocol September 2002
Authors' Addresses
Tatu Ylonen
SSH Communications Security Corp
Fredrikinkatu 42
HELSINKI FIN-00100
Finland
EMail: ylo@ssh.com
Tero Kivinen
SSH Communications Security Corp
Fredrikinkatu 42
HELSINKI FIN-00100
Finland
EMail: kivinen@ssh.com
Markku-Juhani O. Saarinen
University of Jyvaskyla
Timo J. Rinne
SSH Communications Security Corp
Fredrikinkatu 42
HELSINKI FIN-00100
Finland
EMail: tri@ssh.com
Sami Lehtinen
SSH Communications Security Corp
Fredrikinkatu 42
HELSINKI FIN-00100
Finland
EMail: sjl@ssh.com
Ylonen, et. al. Expires March 2, 2003 [Page 14]
Internet-Draft SSH Authentication Protocol September 2002
Full Copyright Statement
Copyright (C) The Internet Society (2002). All Rights Reserved.
This document and translations of it may be copied and furnished
to others, and derivative works that comment on or otherwise
explain it or assist in its implementation may be prepared,
copied, published and distributed, in whole or in part, without
restriction of any kind, provided that the above copyright notice
and this paragraph are included on all such copies and derivative
works. However, this document itself may not be modified in any
way, such as by removing the copyright notice or references to the
Internet Society or other Internet organizations, except as needed
for the purpose of developing Internet standards in which case the
procedures for copyrights defined in the Internet Standards
process must be followed, or as required to translate it into
languages other than English.
The limited permissions granted above are perpetual and will not
be revoked by the Internet Society or its successors or assigns.
This document and the information contained herein is provided on
an "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET
ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF
THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Acknowledgement
Funding for the RFC Editor function is currently provided by the
Internet Society.
Ylonen, et. al. Expires March 2, 2003 [Page 15]

370
doc/libssh-0.2-api-1.txt Normal file
View File

@@ -0,0 +1,370 @@
The new libssh 0.2 API
----------------------
Version 1
A. Introduction
---------------
With the time from the first release of libssh, I have received lots of
comments about the current API. Myself, I found it quite limiting when doing
my first libssh-server drafts. Thus, I am moving to a stronger API.
This API must still be simple. I am not introducing complex changes. An API
well designed must hide the implementation details. Implementation can change
easily within bugfixes - but API cannot change each release.
To the people already using libssh 0.11 : sorry. Once I have the complete API
redesigned, I will write a migration paper. It won't be too hard normally.
Here are the things that were lacking in the previous API and *must* change:
* A non-blocking mode connection type
* Functions to relegate File descriptor listening to Calling functions and to
the programmer. (I'll explain later).
* Along with that, good buffering system (well, it's not an API but).
* Leave the "functions returns a pointer when it works and NULL when it does
not work". It gives serious problems to implement bindings (A C++
constructor should not fail and should not depend on a network thing
* Make the Session structure an abstract structure that can work with both
client and *servers*. That mean we should have a Server object which listen
to clients on a bound port, does the different handshakes and return a
session.
Since C is not per se an Object language, I won't use inheritance between
objects.
* This same server thing must provide the reverse capabilities than the
client. That is, accept the handshake, in a nonblocking way. Accept channel
requests, or send them to the controller program.
* Support for program forking : Imagine you have a Ssh server object. You
accept a connection and receive a session, then you receive a channel. You
may want to keep the good old days fork() tricks. Libssh will give a way to
destroy handlers from sessions which belong to an other process without
disturbing the session.
* So often I received the comment back saying that it was not clear why a
session or a channel was terminated. This is over.
* And of course I received lot of mails about the fact I'm doing namespace
polution. this will be resolved this time.
So, please read this draft not as a formal documentation but like a roadmap of
things that each kind of object must do.
B. Description of objects and functions
Options structure
~~~~~~~~~~~~~~~~~
struct ssh_options *ssh_options_new()
ssh_options_getopt(options, *argc, argv)
ssh_options_copy(options)
char ** ssh_options_get_supported_algos(options,type)
returns a list of the algos supported by libssh, type being one of
SSH_HOSTKEYS, SSH_KEX, SSH_CRYPT, SSH_MAC, SSH_COMP, SSH_LANG
ssh_options_set_wanted_algos(options,type, char *list)
list being comma-separated list of algos, and type being the upper constants
but with _C_S or _S_V added to them.
ssh_options_set_port(options, port)
ssh_options_set_host(options, host)
ssh_options_set_fd(options, fd)
ssh_options_set_bind(options, bindaddr, port)
this options sets the address to bind for a client *or* a server. a port of
zero means whatever port is free (what most clients want).
ssh_options_set_username(options, username)
ssh_options_set_connect_timeout(options, seconds, usec)
ssh_options_set_ssh_dir(options, dir)
ssh_options_set_known_hosts_file(options, file)
ssh_options_set_identity(options, file)
ssh_options_set_banner(options, banner)
ssh_options_allow_ssh1(options, bool allow)
ssh_options_allow_ssh2(options, bool allow)
options_set_status_callback has moved into ssh_* functions.
ssh_session Structure
~~~~~~~~~~~~~~~~~~~~~
This session structure represents a ssh socket to a server *or* a client.
ssh_session *ssh_new()
ssh_set_options(ssh_session,ssh_options)
ssh_connect(session);
it will return some status describing at which point of the connection it is,
or an error code. If the connection method is non-blocking, the function
will be called more than once, though the return value SSH_AGAIN.
ssh_set_blocking(session, bool blocking)
set blocking mode or non blocking mode.
ssh_get_fd(session)
get the currently used connection file descriptor or equivalent (windows)
ssh_set_fd_toread(session)
ssh_set_fd_towrite(session)
ssh_set_fd_except(session)
Serve to notify the library that data is actualy available to be read on the
file descriptor socket. why ? because on most platforms select can't be done
twice on the same socket when the first reported data to read or to write
ssh_get_status(session)
Returns the current status bitmask : connection Open or closed, data
pending to read or not (even if connection closed), connection closed on
error or on an exit message
ssh_get_disconnect_message(session)
Returns the connection disconnect error/exit message
ssh_get_pubkey_hash(session, hash)
get the public key hash from the server.
ssh_is_server_known(session)
ssh_write_knownhost(session)
these 2 functions will be kept
ssh_disconnect(session)
standard disconnect
ssh_disconnect_error(session,error code, message)
disconnect with a message
ssh_set_username(session)
set the user name to log in
ssh_userauth_* functions will be kept as they are now, excepted the fact that
the username field will disapear.
the public key mechanism may get some more functions, like retrieving a public
key from a private key and authenticating without a public key.
ssh_get_issue_banner(session)
get the issue banner from the server, that is the welcome message.
ssh_silent_free(session)
This function silently free all data structures used by the session and
closes the socket. It may be used for instance when the process forked and
doesn't want to keep track of this session. This is obviously not possible to
do with separate channels.
The channel_struct structure
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The channels will change a bit. the constructor thing will change, and the way
to multiplex different connections will change too. channel functions will be
prefixed with "ssh_"
struct channel_struct *ssh_channel_new()
ssh_channel_open_session(channel)
will return if the channel allocation failed or not.
ssh_channel_open_forward(channel, ...) won't change. it will report an error if
the channel allocation failed.
ssh_channel_send_eof(channel)
send EOF
ssh_channel_close(channel)
closes a channel but doesn't destroy it. you may read unread data still in
the buffer. Once you closed the buffer, the other party can't send you data,
while it could still do it if you only sent an EOF.
ssh_channel_is_closed(channel)
returns true if the channel was closed at one of both sides. a closed chan
may still have data to read, if you closed yourself the connection. otherwise
(you didn't close it) the closed notification only comes when you read the
last buffer byte, or when trying to write into the channel (the SIGPIPE-like
behaviour).
ssh_channel_is_eof(channel)
reports if the other side has sent an EOF. This functions returns FALSE if
there is still data to read. A closed channel is always EOF.
ssh_channel_free(channel)
completely free the channel. closes it before if it was not done.
ssh_channel_request_env(channel, name, value)
set an environment variable.
ssh_channel_request_pty(channel)
ssh_channel_request_pty_size()
ssh_channel_change_pty_size()
ssh_channel_request_shell()
ssh_channel_request_exec()
ssh_channel_request_subsystem()
These functions won't change.
int ssh_channel_write(channel,data, len,stderr)
Depending on the blocking/non blocking mode of the channel, the behaviour may
change.
stderr is the extended buffer. It's generaly only a server->client stream.
ssh_channel_set_blocking(bool blocking)
int ssh_channel_read(channel, buffer, maxlen, is_stderr)
the behaviour will be this one:
-if the chan is in non blocking mode, it will poll what's available to read
and return this. otherwise (nothing to read) it will return 0.
-if the chan is blocking, it will block until at least one byte is
available.
ssh_channel_nonblocking disapears for the later reason.
int channel_poll(channel, is_stderr)
polls the network and reports the number of bytes ready to be read in the
chan.
ssh_session ssh_channel_get_session(channel)
returns the session pointer associated to the channel, for simplicity
reasons.
int ssh_channel_select(CHANNELS *readchans, CHANNELS *writechans, CHANNELS
*exceptchans, struct timeval *timeout)
This function won't work the same way ssh_select did.
I removed the custom file descriptor thing for 2 reasons:
1- it's not windows compliant. D'ouh !
2- most programmers won't want to depend on libssh for socket multiplexing.
that's why i let the programmer poll the fds himself and then use
ssh_set_fd_toread, towrite or except. Then, he may use ssh_channel_select
with a NULL timeout to poll which channels have something to read, write or
error report.
Here is how it's going to work. The coder sets 3 different arrays with the
channels he wants to select(), the last entry being a NULL pointer. The
function will first poll them and return the chans that must be
read/write/excepted. If nothing has this state, the function will select()
using the timeout.
The function will return 0 if everything is ok, SSH_TIMEOUT or SSH_EINTR if
the select was interrupted by a signal. It is dangerous to execute any
channel-related functions into signal handlers. they should set a flag that
you read into your loop. this "trap" (SSH_EINTR) will permit you to catch
them faster and make your program responsive and look fast.
the function will return -1 if a serious problem happens.
Error handling
~~~~~~~~~~~~~~
when an error happens, the programmer can get the error code and description
with ssh_get_error(session). the creation of a failess constructor for
ssh_session was needed for this reason.
ssh_get_error_code(session) will return an error code into this subset:
SSH_NO_ERROR : no error :)
SSH_REQUEST_DENIED : you request for a functionality or a service that is not
allowed. The session can continue.
SSH_FATAL : Unrecoverable error. The session can't continue and you should
disconnect the session. It includes the connection being cut without a
disconnect() message.
If a disconnect() message or the channel was closed, a read on such a channel
won't produce an error. otherwise it will return -1 with a SSH_FATAL error
code.
Server socket binding
~~~~~~~~~~~~~~~~~~~~~
It is not possible to bind a socket for ssh with a SSH_SESSION type, because a
single bound port may lead to multiple ssh connections. That's why the
SSH_BIND structure must be created. It uses options from the SSH_OPTIONS
structure.
SSH_BIND *ssh_bind_new()
creates a structure
ssh_bind_set_options(bind, options)
set the option structure
int ssh_bind_listen(bind)
bind and listen to the port. This call is not blocking. if some error
happens, it returns -1 and the error code can be found with perror().
ssh_bind_set_blocking(bind, bool blocking)
should ssh_bind_accept() block or not.
int ssh_bind_get_fd(bind)
return the bound file descriptor, that is the listener socket. you may put it
into a select() in your code to detect a connection attempt.
ssh_bind_set_fd_toaccept(bind)
say that the listener socket has a connection to accept (to avoid
ssh_bind_accept() to do a select on it).
SSH_SESSION *ssh_bind_accept(bind)
return a server handle to a ssh session. if the mode is blocking, the
function will always return a pointer to a session. if the mode is not
blocking, the function can return NULL if there is no connection to accept.
This SSH_SESSION handle must then pass through the functions explained above.
*server functions *
int ssh_accept(session)
when a new connection is accepted, the handshake must be done. this function
will do the banner handshake and the key exchange.
it will return SSH_AGAIN if the session mode is non blocking, and the
function must be called again until an error occurs or the kex is done.
Here, I had a few choises about *how* to implement the message parsing as a
server. There are multiple ways to do it, one being callbacks and one being
"Message" reading, parsing and then choice going to the user to use it and
answer. I've choosen the latter because i believe it's the stronger method.
A ssh server can receive 30 different kind of messages having to be dealt by
the high level routines, like channel request_shell or authentication. Having
a callback for all of them would produce a huge kludge of callbacks, with
no relations on when there were called etc.
A message based parsing allows the user to filtrate the messages he's
interested into and to use a default answer for the others. Then, the callback
thing is still possible to handle through a simple message code/callback
function array.
I did not define yet what it would look like, but i'm sure there will be a
SSH_MESSAGE (they won't have a 1/1 correspondance with ssh packets) which will
be read through
SSH_MESSAGE *ssh_server_read_message(session).
with all of the non-blocking stuff in head like returning NULL if the message
is not full.
Then, the message can be parsed, ie
int ssh_message_get_code(message)
which will return SSH_MESSAGE_AUTH
then
int ssh_message_get_subcode(message)
which then will returh SSH_MESSAGE_AUTH_PASSWORD or _NONE or _PUBKEY etc.
Then, once the message was parsed, the message will have to be answered, ie
with the generic functions like
ssh_message_accept(message) which says 'Ok your request is accepted' or
ssh_message_deny(message) which says 'Your request is refused'.
There would be specific message answer functions for some kind of messages
like the authentication one. you may want to reply that the authentication is
Partial rather than denied, and that you still accept some kind of auths, like
ssh_message_auth_reply(message,SSH_AUTH_PARTIAL,SSH_AUTH_PASSWORD |
SSH_AUTH_PUBKEY | SSH_AUTH_KEYBINT);
I won't let the user have to deal with the channels himself. When a channel is
going to be created by the remote size, a message will come asking to open a
channel. the programmer can either deny or accept, in which case a CHANNEL
object will be created and returned to the programmer. then, all standard
channel functions will run.
C. Change log of this document
2. ssh_options_set_username finaly is kept into the options, because it can be
set by ssh_options_getopt()
1. first release
D. End notes
I think libssh must have a very simple to use, powerful and exhaustive API. It
must have no design flaw either.
While I got some good experience at the SSH protocol, I've never writen
more-than-100 lines programs than use libssh and I don't really know the
problems of the library. I'd like people who don't understand some detail into
the API I describe here, who have comments or opinions about it to write me
the soonest possible to limit the damages if I made something the completely
wrong way.
Thanks for your patience.

1501
doc/protocol-1.5.txt Normal file
View File

File diff suppressed because it is too large Load Diff

184
doc/style.css Normal file
View File

@@ -0,0 +1,184 @@
body {
background-color:#ddf;
/*background-image:url(../back6.jpg);*/
margin:10px 10px 10px 10px;
}
h1 {
font-family:verdana, sans-serif;
font-size:80%;
color:black;
background-color:transparent;
text-align:left;
}
h2 {
font-family:verdana, sans-serif;
font-size:100%;
color:black;
background-color:transparent;
text-align:left;
}
h3 {
font-family:verdana, sans-serif;
font-size:80%;
color:black;
background-color:transparent;
text-align:left;
}
p {
font-family:verdana, sans-serif;
font-size:80%;
color:black;
background-color:transparent;
text-align:left;
margin-left:0px;
margin-right:0px;
}
li {
font-family:verdana, sans-serif;
font-size:80%;
color:black;
background-color:transparent;
text-align:left;
margin-left:0px;
margin-right:0px;
}
a:link {
font-family:verdana, sans-serif;
font-size:100%;
color:black;
background-color:transparent;
text-decoration:underline;
}
a:visited {
font-family:verdana, sans-serif;
font-size:100%;
color:black;
background-color:transparent;
text-decoration:underline;
}
a:hover {
font-family:verdana, sans-serif;
font-size:100%;
color:black;
background-color:transparent;
text-decoration:underline;
}
table {
border-color:transparent;
border-style:solid;
border-width:1px;
}
td {
font-family:verdana, sans-serif;
font-size:80%;
color:black;
text-align:left;
background-color:transparent;
border-color:transparent;
border-style:solid;
border-width:1px;
}
.tout {
margin: 5px;
padding: 0px;
border: 2px solid #aac;
background: #eef;
}
.prot {
border-style:solid;
border-width:2px;
border-color:#88F;
padding: 4px;
background-color:#cce;
margin: 5px 5px 5px 5px;
}
.ex {
border-style:solid;
border-width:2px;
border-color:#aaF;
padding: 4px;
background-color:#dde;
margin: 5px 5px 5px 5px;
}
.desc {
border-style:solid;
border-width:3px;
border-color:#66F;
padding: 4px;
background-color:#aac;
margin: 15px 5px 20px 5px;
}
#titre {
margin: 5px;
padding: 0px;
border: 5px solid #aac;
background: #eef;
}
#gauche {
float:left;
margin: 5px;
padding: 4px;
border: 5px solid #aac;
background: #bbf;
width: 130px;
}
#droite {
position: relative;
top:5px;
left:165px;
margin: 5px 170px 5px 5px;
padding: 10px;
border: 5px solid #aac;
background: #bbf;
}
/* boutons */
a.bouton:link{
width:128px;
height:34px;
text-decoration:none;
color:#aaa;
text-align:center;
font-weight:bold;
/*background-color:#444;*/
background-image:url(noclicked.png);
}
a.bouton:visited{
width:128px;
height:34px;
text-decoration:none;
color:#aaa;
text-align:center;
font-weight:bold;
/*background-color:#444;*/
background-image:url(noclicked.png);
}
a.bouton:hover{
width:128px;
height:34px;
text-decoration:none;
color:white;
text-align:center;
font-weight:bold;
/*background-color:#888;*/
background-image:url(clicked.png);
}
.bouton{
text-align:center;
display:block;
}