Copyright 1997, 1998 Tadayoshi Kohno (kohno@cs.colorado.edu)
All Rights Reserved.
See the LICENSE file.



libSSH DESCIPTION:

libSSH is a platform-independant SSH library that supports the
client-side of an SSH (protocol version 1.5) connection.  Among these
features are
    
    * Password and RSA authentication
    * RSA key (identity generation)
    * IDEA, 3DES, DES, and NONE ciphers

One notable thing about libSSH is that it allows for multiple,
simultanious ssh connections within one application.  This may be
useful in implementing an interactive secure-copy program or something
similar.

libSSH uses Eric Young's SSLeay libraries.  They are available
from
    ftp://ftp.psy.uq.oz.au/pub/Crypto/SSL


DESCIPTION of FILES:
    
    README.txt          Getting-started information
					
    Makefile            libSSH Makefile for Unix
    Makefile.VC         libSSH Makefile for Windows 95/NT (Visual C++)

    ssh.h               main header file for libSSH

    ssh_auth.h          specifies authentication methods

    ssh_cmsg.c          handles client-side messages
    ssh_cmsg.h    

    ssh_comm.c          handles communication (ssh_{send,recv},
    ssh_comm.h          ssh_write_stdin, ...)

    ssh_connect.c       handles connecting with the ssh server
    ssh_connect.h    

    ssh_crc32.c         CRC stuff from Gary S. Brown

    ssh_crypt.c         handles encipher/decipherment of messages
    ssh_crypt.h

    ssh_debug.c         handles displaying debug information
    ssh_debug.h

    ssh_errno.c         handles storing/formating error messages
    ssh_errno.h

    ssh_ident.c         handles creating, loading, saving RSA keys
    ssh_ident.h

    ssh_misc.c          handles misc. stuff (resizing window, ...)
    ssh_misc.h

    ssh_mp_int.c        handles Multi-Precision Integers (SSH v1.5 definition)
    ssh_mp_int.h        header file defining MP_Int type

    ssh_mp_int_dec.c    handles printing multi-precision integers
    ssh_mp_int_dec.h    in decimal (printable) format

    ssh_mp_stream.c     handles multi-precision string
    ssh_mp_stream.h    

    ssh_msg.c           handles generic (client and server) messages
    ssh_msg.h           defines message types (client, server, and generic)

    ssh_packet.c        handles forming ssh packets (binary packet format)
    ssh_packet.h

    ssh_prepare.c       handles preparing ssh connection (after authenticated
    ssh_prepare.h       but before executing the shell)

    ssh_presetup.c      handles pre-connection details (debug level, ...)
    ssh_presetup.h    

    ssh_proto.c         handles ssh protocol version exchange
    ssh_proto.h    

    ssh_smsg.c          handles server messages
    ssh_smsg.h

    ssh_types.h         handles all ssh types (some platform-dependancies here)

    ssh_util.c          utilities (primarily for Windows 95/NT boxes)
    ssh_util.h


IMPORTANT DATA TYPES:

    struct ssh_struct                               (ssh_types.h)

        All instances of an ssh connection require the use of an ssh_struct
        variable.  This variables has knowledge about the cipher-type
        in use (IDEA, 3DES, ...) and the various initialization vectors.
        It also has a ssh_debug_struct variable that specified whether
        to do debugging and what function to call to display the debugging
        info.

    typedef SSHDebugPrinter                         (ssh_types.h)
    
        This is the type of function to use to display debug messages.
        These functions should be of the format
    
            int func_name(char * category, char * body);
    
        where category is the category of the error defined by the function
        that generated the debug message.  body is the body of the
        message.  This function allows Windows programs to display
        debugging messages in a MessageBox and for Unix programs to
        splat the information to stderr or deal with then any way
        it wants.
    
    typedef socket_type                             (ssh_types.h)
    
        This is the type of a socket.  The main reason it is here is
        to help support both Windows 95/NT and Unix boxes (and 
        concievably others)
    
    uint8_t, uint16_t, uint32_t                     (ssh_types.h)
        8, 16, and 32 bit unsigned integers



CONNECTION FUNCTIONS:

    ssh_presetup_client                             (ssh_presetup.c)
    
        Handles pre-ssh_connection details.  This currently means
        that this function initialized the debugging level (which may
        be SSH_NO_DEBUG or SSH_YES_DEBUG) and the function to
        use to display the debug messages (SSHDebugPrinter).
    
    
    ssh_connect_client                             (ssh_connect.c)
    
        This should be called after opening a socket and actually
        connect()ing with the server.  This should also be called
        after ssh_presetup_client().
    
        This is where the bulk of the ssh protocol-interaction
        happens.
    
        The parameters are (which are also specified in the comments
        in ssh_connect.c)
        
            socket_type sockfd
                this is the socket to the connect()ed server
        
        
            struct ssh_struct * ssh_info
                this is a pointer to the above described ssh_struct.
                it holds information about the ssh connection and
                must be passed to this and most other functions
        
            char * applic_ver
                this is the version string for the client application.
                it gets sent to the server in the protocol-negotiation
                stage
        
            char * user
                login of the user to authenticate
        
            int auth_mode
                authentication mode  currently the supported modes
                are
                    SSH_AUTH_PASSWORD
        
                    SSH_AUTH_RSA
        
            char * passwd
                this is the password (for SSH_AUTH_PASSWORD) or
                passphrase (for SSH_AUTH_RSA) for the user.
        
                a special note is that ssh_connect_client
                bzero's the passwd after it is done with it.
                this is in some ways a feature, but can also
                make it more cumbersome if the application
                wishes to open multiple connection to the same
                host with the same password.
    
            uint8_t cipher_choice
                this is the choice of cipher types.  among
                the currently supported ones are
    
                SSH_CIPHER_3DES    (required of SSH implementations)
                SSH_CIPHER_DES    (not recommended)
    
                SSH_CIPHER_IDEA
    
                SSH_CIPHER_NONE    (definitely not recommended)
    
            char * identity_file
                this is the path to the file containing
                the user's private RSA keys (only used with
		SSH_AUTH_RSA).
    
    
        A detailed description of what this function does can be
        found in ssh_connect.c.  Also, the draft-ylonen-ssh-protocol-00.txt
        draft has the definitive and complete explanation.  (Copies
        of the draft are available from many SSH-related websites like
        http://ugrad-www.cs.colorado.edu/~kohno/projects/ssh.html)
        
    
    ssh_request_pty                                 (ssh_prepare.c)
        sends a request for pty to the server


    ssh_request_exec_shell                          (ssh_prepare.c)
        sends a request for a shell to the server.  following this
        we are in "interactive-mode".  In other words, we can use
        ssh_write_stdin() to write stdin data to the server and
        use ssh_read_merge() to read stdout, stderr data from the
        server

    ssh_disconnect_client_confirm                   (ssh_connect.c)
	confirm an SSH_SMSG_EXITSTATUS message to close the connection.

    ssh_disconnect_client_active                    (ssh_connect.c)
	close an active connection (no exit message from the server)


DATA TRANSFER FUNCTIONS

    ssh_write_stdin                                 (ssh_comm.c)
        sends data as stdin data for program running on server

    ssh_read_merge                                  (ssh_comm.c)
	[replaced by ssh_read_interactive]
        reads stdout, stderr data from the server

        there is actually more things going on here that just reading
        stdout/stderr data.  Namely, once interactive-mode
        has started, this function is our only access to data
        from the server.  As such, we can also receive
        SSH_SMSG_EXITSTATUS and SSH_MSG_DISCONNECT messages.  These
        will be discussed shortly.
    
        ideally, forwarded and X packets will also be accessible
        via this function.  (hence the use of the word "merge" in
        the function name).

        this may be depricated, however, in the near future

    ssh_read_interactive                            (ssh_comm.c)
	ssh_read_merge replacement.

	this function reads data from the server during an
	interactive session.  the return value is the type of
	message read (stdout, stderr, disconnection, ...).  The
	"payload" is returned through the parameters.

	known return types are:
	    SSH_MSG_NOTYPE:             no data available/unknown type
	    SSH_SMSG_STDOUT_DATA:	stdout data
	    SSH_SMSG_STDERR_DATA:	stderr data
	    SSH_SMSG_EXITSTATUS:	server command/shell exited
	    SSH_MSG_DISCONNECT:		server disconnection

	information on how to handle each message type is provided
	in the comments in ssh_comm.c

	NOTE: because the packets are enciphered, we can only receive
	chunks of 1 packet at a time.  because of this, we can't call
	ssh_read_interactive requesting only one byte (libssh currently
	doesn't support internal buffering).  This will hopefully change.
	Currently a request for less than SSH_MAX_PACKET bytes *may*
	return an error saying it was impossible to decipher the packet
	Also [again gasp!], there are a few places where bounds aren't set,
	so if the receive buffer size is SSH_MAX_PACKET, everything should
	be okay [fixing this is something *very* high on my todo list]


ON-THE-SIDE FUNCTIONS

    ssh_errno_to_str                                (ssh_errno.c)
        convert the errno value (ssh_errno) to a printable string
	of length SSH_ERRNO_LEN

    ssh_errno_get                                   (ssh_errno.c)
        get the ssh_errno value


    ssh_debug_activate                              (ssh_debug.c)
        turns on/off debugging


    ssh_identity_gen                                (ssh_ident.c)
        generate an RSA identity and save in specified
        file


A FEW BACK-END FUNCTIONS

    ssh_recv                                        (ssh_comm.c)
        recv, decipher, and unpack a packet

    ssh_send                                        (ssh_comm.c)
        pack, encipher, and send a packet


OTHER NOTES
    The calling application can/should timeout all libSSH
    functions.  this may not be necessary, but rather than
    sprinkling alarms throught libSSH, it is up to the application.


RSA AUTHENTICATION
    Because of the copyright rules for the original version of
    ssh (ylonen), libSSH uses a different format to store the private
    RSA "identity."  [It is currently unknown whether the SSH
    copyright extends to the identity file format, but libSSH uses
    another format "just to be safe."]

    ssh_ident.c handles all identity-related issues.  It is not
    hard to change it to use Ylonen's method.

    For those who are using/developing additional SSH clients
    (like the Platform Independent Secure Shell group at CU which
    is producing an SSH client in Java), libSSH generates
    private identities of the format:

	4 bytes.	byte 0 == byte 2, byte 1 == byte 3
			these bytes are used to check decipherment
	modulus		as a multi-precision integer of the same
			format that is used in the binary packet format
			for the SSH v1.5 protocol
	priv exponent	private exponent in mp_int form (like above)
	public exponent	public exponent in mp_int form (like above)
	padding		padding to make the above packet a multiple of
			8 bytes.

    The private identity is then enciphered in the following manner.
    An MD5 is created of the user's passphrase.  The identity file
    is then enciphered using the SSH_CIPHER_3DES algorithm with the
    keys: (1) the first 8 bytes of the md5 (encipher), (2) the second
    8 bytes of the md5 (decipher), (3) the first 8 bytes of the md5
    (encipher).

    The public file shares the same format as all other ssh
    implementations.  This file needs to be copied into the user's
    authorized_keys file on the server in order to be able to connect
    with RSA authentication.

SAMPLE CLIENT
    A sample ssh client for unix boxes has been provided in the
    unix_ssh subdirectory.  It is not the best ssh client, or
    even a good one :) , but it does work and does illustrate
    the principles of this library.  I am intending on creating
    a better example, but don't want to bloat it.  This version
    is just intended to be an example of how to use libSSH

    WinSSH was the original libSSH Windows 95/NT client.  It is
    available as a seperate packege.




ADDITIONAL INFORMATION

    I am a student, so am not able to put as much time into this
    as I would like.  Nevertheless, I do want to provide a 
    "professional-quality" library that can find its way into
    many other applications. 

    Because of this, I would *really* love to receive comments.
    Namely, I would like to learn what others consider to be the
    bad features (or good features) about libSSH.  I would also
    like to hear of suggestions for improvements and new features
    to add (of which, I already know of a few).

    I will try to be up on all fixes and the likes.  My only
    problem is that I'm not able to distribute as freely as I
    would like.  There is a website that has graciously allowed
    me to distribute US-only, but I do not want to bother
    that administrator by uploading files more frequently than
    necessary.


    The mailing list for discussing libSSH is

        libssh@cs.colorado.edu

    You can subscribe by sending mail to "majordomo@cs.colorado.edu"
    with "subscribe libssh" in the body of the message.

    You can also mail me directly at

        kohno@cs.colorado.edu

    There is also a webpage about libSSH -- but it is currently
    not very extensive.  It is listed twice because the domain
    name changes frequently (but they should all be cname'd).

        http://ugrad-www.cs.colorado.edu/~kohno
        http://csel.cs.colorado.edu/~kohno


PORTING
    Porting libSSH to other platforms hasn't been too difficult.
    At least this was the case for HP-UX, Linux, and SunOS.
    This can, in part, be attributed to the portability of
    SSLeay.

    There are, however, a few things to keep in mind.  Namely,
    all platform-dependancies are handles in ssh_types.h and
    the Makefile.  Converting to a configure script is another
    thing on my agenda.

    For ssh_types.h, the main things to keep in mind are that
    socket_type should be the type for a socket on the specific
    system (SOCKET for Visual C++ on Windows NT, int for Unix
    boxes).  Also, uint8_t, uint16_t, and uint32_t need to
    be specified for the architecutre.

    The Makefile is used to define the architecture so that
    all the type-handling stuff can be #ifdef'd in ssh_types.h

    If you do happen to port libSSH to another platform, please
    send me the patches as I would love to incorperate the
    changes into the next release.  Better yet, if you're willing
    to beta test new versions, we can coordinate an effort so
    that any future changes elsewhere will not effect ports
    to your platform(s).

ACKNOWLEDGEMENTS

    There have been many people who have helped me with libSSH and have
    given me ideas.

    Of these, I would especially like to thank Evi Nemeth of the University
    of Colorado.  I would also like to thank Scott Morris (also of CU) for
    giving me many suggestions and for being a pre-pre-alpha tester :).

BUGS
    Please see the BUGS_TODO file.

COPYRIGHT
    libSSH copyright 1997, 1998 Tadayoshi Kohno
    All rights reserved.  See the LICENSE file.

    This product includes cryptographic software written by
    Eric Young (eay@cryptsoft.com).  Actually, his library is not
    included with libSSH but is ftpable from

        ftp://ftp.psy.uq.oz.au/pub/Crypto/SSL


