path: root/README

paramiko 1.4
"oddish" release, 17 jul 2005

Copyright (c) 2003-2005 Robey Pointer <robey@lag.net>

http://www.lag.net/paramiko/


***  WHAT

"paramiko" is a combination of the esperanto words for "paranoid" and
"friend".  it's a module for python 2.2+ that implements the SSH2 protocol
for secure (encrypted and authenticated) connections to remote machines.
unlike SSL (aka TLS), SSH2 protocol does not require heirarchical
certificates signed by a powerful central authority. you may know SSH2 as
the protocol that replaced telnet and rsh for secure access to remote
shells, but the protocol also includes the ability to open arbitrary
channels to remote services across the encrypted tunnel (this is how sftp
works, for example).

it is written entirely in python (no C or platform-dependent code) and is
released under the GNU LGPL (lesser GPL). 

the package and its API is fairly well documented in the "doc/" folder
that should have come with this archive.


***  REQUIREMENTS

python 2.3	<http://www.python.org/>
    (python 2.2 is also supported, but not recommended)
pycrypto 1.9+	<http://www.amk.ca/python/code/crypto.html>
    (2.0 works too)

pycrypto compiled for Win32 can be downloaded from the HashTar homepage:
    http://nitace.bsd.uchicago.edu:8080/hashtar
you can also build it yourself using the free MinGW tools and this command
line (thanks to Roger Binns for the info):
    python setup.py build --compiler=mingw32 bdist_wininst


***  PORTABILITY

i code and test this library on Linux and MacOS X.  for that reason, i'm
pretty sure that it works for all posix platforms, including MacOS.  i
also think it will work on Windows, though i've never tested it there.  if
you run into Windows problems, send me a patch: portability is important
to me.

python 2.2 may work, thanks to some patches from Roger Binns.  things to
watch out for:
* sockets in 2.2 don't support timeouts, so the 'select' module is
  imported to do polling.  
* logging is mostly stubbed out.  it works just enough to let paramiko
  create log files for debugging, if you want them.  to get real logging,
  you can backport python 2.3's logging package.  Roger has done that
  already:
  http://sourceforge.net/project/showfiles.php?group_id=75211&package_id=113804

you really should upgrade to python 2.3.  laziness is no excuse! :)

some python distributions don't include the utf-8 string encodings, for
reasons of space (misdirected as that is).  if your distribution is
missing encodings, you'll see an error like this:

LookupError: no codec search functions registered: can't find encoding

this means you need to copy string encodings over from a working system.
(it probably only happens on embedded systems, not normal python
installls.)
Valeriy Pogrebitskiy says the best place to look is
'.../lib/python*/encodings/__init__.py'.


***  DEMO

several demo scripts come with paramiko to demonstrate how to use it.
probably the simplest demo of all is this:

    import paramiko, base64
    key = paramiko.RSAKey(data=base64.decodestring('AAA...'))
    t = paramiko.Transport('ssh.example.com')
    t.connect(username='strongbad', password='thecheat', hostkey=key)
    chan = t.open_session()
    chan.exec_command('ls')
    for line in chan.makefile('r+'):
        print '... ' + line.strip('\n')
    chan.close()
    t.close()

...which prints out the results of executing 'ls' on a remote server.
(the host key 'AAA...' should of course be replaced by the actual base64
encoding of the host key.  if you skip host key verification, the
connection is not secure!)

the following example scripts get progressively more detailed:

demo_simple.py
    calls invoke_shell() and emulates a terminal/tty through which you can
    execute commands interactively on a remote server.  think of it as a
    poor man's ssh command-line client.

demo.py
    same as demo_simple.py, but allows you to authenticiate using a
    private key, attempts to use an SSH-agent if present, and uses the long
    form of some of the API calls.

forward.py
    command-line script to set up port-forwarding across an ssh transport.
    (requires python 2.3.)

demo_server.py
    an ssh server that listens on port 2200 and accepts a login for
    'robey' (password 'foo'), and pretends to be a BBS.  meant to be a
    very simple demo of writing an ssh server.


***  USE

the demo scripts are probably the best example of how to use this package.
there is also a lot of documentation, generated with epydoc, in the doc/
folder.  point your browser there.  seriously, do it.  mad props to
epydoc, which actually motivated me to write more documentation than i
ever would have before.

there are also unit tests here:
    $ python ./test.py
which will verify that some of the core components are working correctly.
not much is tested yet, but it's a start.  the tests for SFTP are probably
the best and easiest examples of how to use the SFTP class.


***  WHAT'S NEW

highlights of what's new in each release:

v1.5 PARAS
* added support for "keyboard-interactive" authentication
* added mode (on by default) where password authentication will try to
  fallback to "keyboard-interactive" if it's supported
* added pipelining to SFTPFile.write and SFTPClient.put
* fixed bug with SFTPFile.close() not guarding against being called more
  than once (thanks to Nathaniel Smith)
* fixed broken 'a' flag in SFTPClient.file() (thanks to Nathaniel Smith)
* fixed up epydocs to look nicer
* reorganized auth_transport into auth_handler, which seems to be a cleaner
  separation
* demo scripts fixed to have a better chance of loading the host keys
  correctly on windows/cygwin
  
v1.4 ODDISH
* added SSH-agent support (for posix) from john rochester
* added chdir() and getcwd() to SFTPClient, to emulate a "working directory"
* added get() and put() to SFTPClient, to emulate ftp whole-file transfers
* added check() to SFTPFile (a file hashing protocol extension)
* fixed Channels and SFTPFiles (among others) to auto-close when GC'd
* fixed Channel.fileno() for Windows, this time really
* don't log socket errors as "unknown exception"
* some misc. backward-compatible API improvements (like allowing
  Transport.start_client() and start_server() to be called in a blocking way)

v1.3.1 NIDORAN
* added SFTPClient.close()
* fixed up some outdated documentation
* made SFTPClient.file() an alias for open()
* added Transport.open_sftp_client() for convenience
* refactored packetizing out of Transport
* fixed bug (reported by alain s.) where connecting to a non-SSH host could
  cause paramiko to freeze up
* fixed Channel.fileno() for Windows (again)
* some more unit tests

v1.3 MAROWAK
* fixed a bug where packets larger than about 12KB would cause the session
  to die on all platforms except osx
* added a potential workaround for windows to let Channel.fileno() (and
  therefore the select module) work!
* changed API for subsystem handlers (sorry!) to pass more info and make it
  easier to write a functional SFTP server

v1.2 LAPRAS
* added SFTPClient.listdir_attr() for fetching a list of files and their
  attributes in one call
* added Channel.recv_exit_status() and Channel.send_exit_status() for
  manipulating the exit status of a command from either client or server
  mode
* moved check_global_request into ServerInterface, where it should've been
  all along (oops)
* SFTPHandle's default implementations are fleshed out more
* made logging a bit more consistent, and started logging thread ids
* fixed a few race conditions, one of which would sometimes cause a Transport
  to fail to start on slow machines
* more unit tests

v1.1 KABUTO
* server-side SFTP support
* added support for stderr streams on client & server channels
* added a new distinct exception for failed client authentication
  when caused by the server rejecting that *type* of auth
* added support for multi-part authentication
* fixed bug where get_username() wasn't working in server mode

v1.0 JIGGLYPUFF
* fixed bug that broke server-mode authentication by private key
* fixed bug where closing a Channel could end up killing the entire
  Transport
* actually include demo_windows.py this time (oops!)
* fixed recently-introduced bug in group-exchange key negotiation that
  would generate the wrong hash (and therefore fail the initial handshake)
* server-mode subsystem handler is a bit more flexible

v0.9 IVYSAUR
* new ServerInterface class for implementing server policy, so it's no
  longer necessary to subclass Transport or Channel -- server code will
  need to be updated to follow this new API!  (see demo_server.py)
* some bugfixes for re-keying an active session
* Transport.get_security_options() allows fine-tuned control over the
  crypto negotiation on a new session
* Transport.connect() takes a single hostkey object now instead of two
  string parameters
* the Channel request methods (like 'exec_command') now return True on
  success or False on failure
* added a mechanism for providing subsystems in server mode (and a new
  class to be subclassed: SubsystemHandler)
* renamed SFTP -> SFTPClient (but left an alias for existing code)
* added SFTPClient.normalize() to resolve paths on the server
* fleshed out the API a bit more for SFTPClient and private keys
* a bunch of new unit tests!

v0.9 HORSEA
* fixed a lockup that could happen if the channel was closed while the
  send window was full
* better checking of maximum packet sizes
* better line buffering for file objects
* now chops sftp requests into smaller packets for some older servers
* more sftp unit tests

v0.9 GYARADOS
* Transport.open_channel() -- supports local & remote port forwarding now
* now imports UTF-8 encodings explicitly as a hint to "freeze" utilities
* no longer rejects older SFTP servers
* default packet size bumped to 8kB
* fixed deadlock in closing a channel
* Transport.connect() -- fixed bug where it would always fail when given a
  host key to verify

v0.9 FEAROW
* Transport.send_ignore() -- send random ignored bytes
* RSAKey/DSSKey added from_private_key_file() as a factory constructor;
  write_private_key_file() & generate() to create and save ssh2 keys;
  get_base64() to retrieve the exported public key
* Transport added global_request() [client] and check_global_request()
  [server]
* Transport.get_remove_server_key() now returns a PKey object instead of a
  tuple of strings
* Transport.get_username() -- return the username you auth'd as [client]
* Transport.set_keepalive() -- makes paramiko send periodic junk packets
  to the remote host, to keep the session active
* python 2.2 support (thanks to Roger Binns)
* misc. bug fixes


***  MISSING LINKS

* add comments to demo & demo_simple about how they don't work on windows
* host-based auth (yuck!)
* support compression
* SFTP pipelining
    - basically, just don't wait synchronously for server responses.  queue
    up "expected" responses and wait for them on close().
* SFTP implicit file locking?
* ChannelException like the java version has

* ctr forms of ciphers are missing (blowfish-ctr, aes128-ctr, aes256-ctr)
* SFTP url parsing function to return (user, pass, host, port, path)
  components
* sftp protocol 6 support (ugh....) -- once it settles down more

* what is psyco?
* make a simple example demonstrating use of SocketServer (besides forward.py?)