225 lines
8.7 KiB
Plaintext
225 lines
8.7 KiB
Plaintext
paramiko 1.1
|
|
"kabuto" release, 12 dec 2004
|
|
|
|
Copyright (c) 2003-2004 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.
|
|
|
|
the Channel object supports a "fileno()" call so that it can be passed
|
|
into select or poll, for polling on posix. once you call "fileno()" on a
|
|
Channel, it changes behavior in some fundamental ways, and these ways
|
|
require posix. so don't call "fileno()" on a Channel on Windows. this is
|
|
detailed in the documentation for the "fileno" method.
|
|
|
|
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. this may not work on windows. (works fine on
|
|
osx.)
|
|
* 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_windows.py
|
|
executes 'ls' on any remote server, loading the host key from your
|
|
openssh key file. (this script works on windows because it avoids
|
|
using terminal i/o or the 'select' module.) it also creates a logfile
|
|
'demo_windows.log'.
|
|
|
|
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. (works only on posix [unix or
|
|
macosx].)
|
|
|
|
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. (posix
|
|
only.)
|
|
|
|
forward.py
|
|
command-line script to set up port-forwarding across an ssh transport.
|
|
(requires python 2.3 and posix.)
|
|
|
|
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. (should work on all
|
|
platforms.)
|
|
|
|
|
|
*** 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.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
|
|
* add method to block until a channel's "exit-status" is set
|