234 lines
9.0 KiB
Plaintext
234 lines
9.0 KiB
Plaintext
paramiko 1.3
|
|
"marowak" release, 9 apr 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, 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.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
|
|
|
|
* ctr forms of ciphers are missing (blowfish-ctr, aes128-ctr, aes256-ctr)
|
|
* server mode needs better documentation
|
|
* why are big files so slow to transfer? profiling needed...
|
|
|
|
* would be nice to have an ftp-like interface to sftp (put, get, chdir...)
|
|
|