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



libSSH 0.0.1 beta 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, Blowfish, and NONE ciphers
    * Compression

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.  This feature is not fully thread-safe yet.

libSSH uses Eric Young's SSLeay libraries.  They are available
from
    ftp://ftp.psy.uq.oz.au/pub/Crypto/SSL
The current version of libSSH uses SSLeay-0.8.1

libSSH uses Jean-loup Gailly and Mark Adler's zlib compression
library.  It is available from
    http://www.cdrom.com/pub/infozip/zlib/
    ftp://ftp.cdrom.com/pub/infozip/zlib/
    http://www.winimage.com/zLibDll/
The current version of libSSH uses zlib-1.1.2



libSSH is supported in part by an Undergraduate Software Project
Grant from the USENIX Association's Scholastic Committee.


DESCIPTION of FILES:
    
    Makefile            libSSH Makefile for Unix
    Makefile.VC         libSSH Makefile for Windows 95/NT (Visual C++ 5.0)

    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_compress.c      handles interfacing with the zlib compression library
    ssh_compress.h

    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_final.c         handles post-connection cleanup
    ssh_final.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_random.c        handles initialization of random numbers
    ssh_random.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(const char * category, const 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).

	This function only needs to be called before the *first*
	connection.  To reset things after a connection closes
	but before a new connection opens, see ssh_final_client().
    
    
    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
        
            const char * applic_ver
                this is the version string for the client application.
                it gets sent to the server in the protocol-negotiation
                stage.  an example might be "MySSH-1.2.3".
        
            const char * user
                login of the user to authenticate
        
            int auth_mode
                authentication mode  currently the supported modes
                are
                    SSH_AUTH_PASSWORD
        
                    SSH_AUTH_RSA
        
            const char * passwd
                this is the password (for SSH_AUTH_PASSWORD) or
                passphrase (for SSH_AUTH_RSA) for the user.
        
		As a change from previous versions (0.0.1alpha),
		the passwd is _not_ bzero'd.  This means that the
		calling application is in charge of clearing
		the passwd itself.

            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_BLOWFISH
    
                SSH_CIPHER_NONE    (definitely not recommended)
    
            const 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://csel.cs.colorado.edu/~kohno/projects/ssh.html)
        
    ssh_request_compression                         (ssh_prepare.c)
	sends a compression request to the server and, if accepted,
	turns on compression.  if the compression request is denied,
	a special value is returned that shows that the request
	was denied but that the session can continue as usual

	possible compression levels range between SSH_COMPRESS_MIN_LEVEL
	and SSH_COMPRESS_MAX_LEVEL.  The default level of
	SSH_COMPRESS_DEFAULT_LEVEL should provide a balance between
	compression size and speed.
    
    ssh_request_pty                                 (ssh_prepare.c)
        sends a request for a 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)

    ssh_final_client                                (ssh_final.c)
	cleans up after a connection terminates (memory, compression flags).
	this function should always be called after the connection to a
	remote host closes.  if the client tries to establish another
	connection without calling this function first, there is a hight
	possibility that the new connection will fail (especially if
	compression was used).


DATA TRANSFER FUNCTIONS

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

    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

            SSH_MSG_ERROR:              error occured

	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.  Furthermore,
	it does not look like libSSH will support internal buffering.
	This is because some application may use select() to see if
	data is available, and select() knows nothing about libSSH's
	internal buffers.  There is the idea of creating an ssh_select().

	If the receive buffer size is SSH_MAX_PACKET, everything should
	be okay.


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.  the errno is global to all
	connections.

    ssh_errno_get                                   (ssh_errno.c)
        get the ssh_errno value


    ssh_debug_activate_new                          (ssh_debug.c)
        turns on/off debugging


    ssh_identity_gen                                (ssh_ident.c)
        generate an RSA identity and save in specified
        file [KOHNO identity file format 0.0.1beta currently cannot
	generate YLONEN identity files]


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

SAMPLE CALL SEQUENCE
    A sample call-sequence for the ssh client functions is (xxx check this)

	begin:

	    ssh_presetup_client             (call this once at the beginning)

        connect_loop:
	    connect to remote host on port SSH_PORT (22)

	    ssh_connect_client              (connect and authenticate using ssh)
	    ssh_request_compression         (optional, request compression)
	    ssh_request_pty                 (request a pseudo-terminal)
	    ssh_request_shell               (request a shell)
	        ...

	        interactive session with writes to ssh_write_stdin_n and
	        reads from ssh_read_interactive

                ...
	        ssh_disconnect_client_confirm       (confirm a disconnection)

	    ssh_final_client                (cleanup after a connection)
	    close the socket to the server

	    goto connect_loop               (connect to another host


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
    As a change from the 0.0.1alpha release of libSSH, libSSH now
    uses the real (by Tatu Ylonen) identity file format to store
    the private RSA "identity".   The development is not yet complete
    because currently (0.0.1beta) the identity file must have been
    enciphered with 3DES. 

    This change provides a uniformity and now allows the sharing
    of RSA private keys between the clients.

    The use of the old (kohno) format identity file is no longer
    supported.  If you would, for some reason, like to use it,
    you will need to define SSH_USE_KOHNO_IDENTITY when you compile
    libSSH.


SAMPLE CLIENT
    A sample ssh client for unix systems 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.  Moreover, it was designed as
    a vehicle to test with.  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 will
    soon be available as a seperate packege.

    Additional Windows SSH clients using libSSH are currently
    in-development by third parties.


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 thrice because the domain
    name changes frequently (but they should all be cname'd).

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


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
    [This will eventually change to a configure script and a generated
    header file.]

    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

    I would like to thank the USENIX Association's Scholastic Committee
    for helping fund the development of libSSH (and WinSSH) though an
    Undergraduate Software Project Grant.

    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
    (evi@cs.colorado.edu) of the University of Colorado at Boulder.
    I would also like to thank Scott Morris (samorris@cs.colorado.edu) for
    giving me many suggestions and for being a pre-pre-alpha tester and
    author of ConsoleSSH.

BUGS
    You will probably want to turn on "FascistLogging" in the SSHD config
    file for the server you are trying to connect with.  A nice "tail -f"
    on the syslog log file will show you exactly what is happening when
    it happens.  See sshd(8) and syslogd(8) for more information.

    You might also like to look at the actual SSH 1.5 protocol draft.
    A copy has been linked from my website and others.
    (http://csel.cs.colorado.edu/~kohno/projects/ssh.html)

    Please see the TODO file for a list of things yet to be done.

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

    This product uses the zlib compession library by Jean-loup Gailly
    and Mark Adler.  http://www.cdrom.com/pub/infozip/zlib/

