Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/ePaul/jsch-documentation

A variant of JSch with javadoc for the public methods.
https://github.com/ePaul/jsch-documentation

Last synced: 15 days ago
JSON representation

A variant of JSch with javadoc for the public methods.

Awesome Lists containing this project

README 

        
A documented version of JSch

============================



As the official version of JSch contains only some example

files as documentation, I had the idea to add some Javadoc

comments to the public methods explaining what they do.



Here it is (not yet ready).



I based this on JSch 0.1.44.



I hope this will be merged back to the official distribution,

as quite some big projects are using JSch, and this will be

easier with documentation.



Do 



   ant javadoc



to produce the documentation. (It is in the "javadoc" directory).

Alternatively, the web version is (for now) at



   http://epaul.github.com/jsch-documentation/javadoc



Below is the original contents of the README file.



Paŭlo Ebermann 



---------------------------------------------------------------------



                                      JSch



                                Java Secure Channel

                         by [email protected], JCraft,Inc.



                            http://www.jcraft.com/jsch/



Last modified: Thu Mar 18 13:58:16 UTC 2015



Description

===========

JSch is a pure Java implementation of SSH2.  JSch allows you to 

connect to an sshd server and use port forwarding, X11 forwarding, 

file transfer, etc., and you can integrate its functionality

into your own Java programs. JSch is licensed under BSD style license.



Documentation

=============

* README files all over the source tree have info related to the stuff

  in the directories. 

* ChangeLog: what changed from the previous version?



Directories & Files in the Source Tree

======================================

* src/com/ has source trees of JSch

* example/ has some samples, which demonstrate the usages.

* tools/ has scripts for Ant.



Why JSch?

==========

Our intension in developing this stuff is to enable users of our pure

java X servers, WiredX(http://wiredx.net/) and WeirdX, to enjoy secure X

sessions.  Our efforts have mostly targeted the SSH2 protocol in relation

to X Window System and X11 forwarding.  Of course, we are also interested in 

adding other functionality - port forward, file transfer, terminal emulation, etc.



Features

========

* JSch is in pure Java, but it depends on JavaTM Cryptography

  Extension (JCE).  JSch is know to work with:

  o J2SE 1.4.0 or later (no additional libraries required).

  o J2SE 1.3 and Sun's JCE reference implementation that can be

    obtained at http://java.sun.com/products/jce/

  o J2SE 1.2.2 and later and Bouncycastle's JCE implementation that

    can be obtained at http://www.bouncycastle.org/

* SSH2 protocol support.

* Key exchange: diffie-hellman-group-exchange-sha1,

                diffie-hellman-group1-sha1,

                diffie-hellman-group14-sha1,

                diffie-hellman-group-exchange-sha256,

                ecdh-sha2-nistp256,

                ecdh-sha2-nistp384,

                ecdh-sha2-nistp521

* Cipher: blowfish-cbc,3des-cbc,aes128-cbc,aes192-cbc,aes256-cbc

          3des-ctr,aes128-ctr,aes192-ctr,aes256-ctc,

          arcfour,arcfour128,arcfour256

* MAC: hmac-md5,hmac-md5-96,hmac-sha1,hmac-sha1-96

* Host key type: ssh-dss,ssh-rsa,

                 ecdsa-sha2-nistp256,ecdsa-sha2-nistp384,ecdsa-sha2-nistp521

* Userauth: password

* Userauth: publickey(DSA,RSA,ECDSA)

* Userauth: keyboard-interactive

* Userauth: gssapi-with-mic

* X11 forwarding.

* xauth spoofing.

* connection through HTTP proxy.

* connection through SOCKS5, SOCKS4 proxy.

* port forwarding.

* stream forwarding.

* signal sending.

  The unofficial patch for sshd of openssh will be find in the thread

  http://marc.theaimsgroup.com/?l=openssh-unix-dev&m=104295745607575&w=2

* envrironment variable passing.

* remote exec.

* generating DSA and RSA key pairs.

* supporting private keys in OpenSSL(traditional SSLeay) and PKCS#8 format.

* SSH File Transfer Protocol(version 0, 1, 2, 3)

* partial authentication

* packet compression: zlib, [email protected]

  JZlib(http://www.jcraft.com/jzlib/) has been used.

* hashed known_hosts file.

* NONE Cipher switching.

  http://www.psc.edu/networking/projects/hpn-ssh/none.php

* JSch is licensed under BSD style license(refer to LICENSE.txt).



How To Try

==========

This archive does not include java byte code, so please compile

the source code by your self.

  $ cd jsch-?.?.?/src

  $ javac com/jcraft/jsch/*java com/jcraft/jsch/jce/*java com/jcraft/jzlib/*.java

'/examples/' directory has included some samples to demonstrate what 

JSch can do.  Please refer to '/examples/README' file.



AES cipher

==========

JSch supports aes128-cbc,aes192-cbc,aes256-cbc,aes128-ctr,aes192-ctr,

aes256-ctr but you require AES support in your J2SE to choose some of them.  

If you are using Sun's J2SE, J2SE 1.4.2 or later is required.  

And then, J2SE 1.4.2(or later) does not support aes256 by the default, 

because of 'import control restrictions of some countries'.

We have confirmed that by applying

  "Java Cryptography Extension (JCE)

  Unlimited Strength Jurisdiction Policy Files 1.4.2"

on

  http://java.sun.com/j2se/1.4.2/download.html#docs

we can enjoy 'aes256-cbc,aes256-ctr'.



Stream Forwarding

=================

JSch has a unique functionality, Stream Forwarding.

Stream Forwarding allows you to plug Java I/O streams directly into a remote TCP

port without assigning and opening a local TCP port.

In port forwarding, as with the -L option of ssh command, you have to assign

and open a local TCP port and that port is also accessible by crackers

on localhost.  In some case, that local TCP port may be plugged to a

secret port via SSH session.

A sample program, /example/StreamForwarding.java , demonstrates

this functionality.



Generating Authentication Keys

==============================

JSch allows you to generate DSA and RSA key pairs, which are in OpenSSH format.

Please refer to 'examples/KeyGen.java'.



Packet Compression

==================

According to the draft from IETF sesch working group, the packet

compression can be applied to each data stream directions; from sshd

server to ssh client and from ssh client to sshd server.  So, jsch

allows you to choose which data stream direction will be compressed or not.

For example, in X11 forwarding session, the packet compression for data

stream from sshd to ssh client will save the network traffic, but

usually the traffic from ssh client to sshd is light, so by omitting

the compression for this direction, you may be able to save some CPU time.

Please refer to a sample program 'examples/Compression.java'.



Property

========

By setting properties, you can control the behavior of jsch.

Here is an example of enabling the packet compression,



      Session session=jsch.getSession(user, host, 22);

      java.util.Properties config=new java.util.Properties();

      config.put("compression.s2c", "zlib,none");

      config.put("compression.c2s", "zlib,none");

      session.setConfig(config);

      session.connect();



Current release has supported following properties,

* compression.s2c: zlib, none

  default: none

  Specifies whether to use compression for the data stream

  from sshd to jsch.  If "zlib,none" is given and the remote sshd does

  not allow the packet compression, compression will not be done.

* compression.c2s: zlib, none

  default: none

  Specifies whether to use compression for the data stream

  from jsch to sshd.

* StrictHostKeyChecking: ask | yes | no

  default: ask

  If this property is set to ``yes'', jsch will never automatically add

  host keys to the $HOME/.ssh/known_hosts file, and refuses to connect

  to hosts whose host key has changed.  This property forces the user

  to manually add all new hosts.  If this property is set to ``no'', 

  jsch will automatically add new host keys to the user known hosts

  files.  If this property is set to ``ask'', new  host keys will be

  added to the user known host files only after the user has confirmed 

  that is what they really want to do, and jsch will refuse to connect 

  to hosts whose host key has changed.



TODO

====

* re-implementation with java.nio.

* replacing cipher, hash by JCE with pure Java code.

* SSH File Transfer Protocol version 4.

* error handling.



Copyrights & Disclaimers

========================

JSch is copyrighted by ymnk, JCraft,Inc. and is licensed through BSD style license.

Read the LICENSE.txt file for the complete license.



Credits and Acknowledgments

============================

JSch has been developed by [email protected] and it can not be hacked

without several help.

* First of all, we want to thank JCE team at Sun Microsystems.

  For long time, we had planed to implement SSH2 in pure Java,

  but we had hesitated to do because tons of work must be done for

  implementing ciphers, hashes, etc., from the scratch.

  Thanks to newly added functionalities to J2SE 1.4.0, we could

  start this project.

* We appreciate the OpenSSH project.

  The options '-ddd' of sshd, '---vvv' of ssh and the compile options 

  '-DPACKET_DEBUG', '-DDEBUG_KEXDH' and  '-DDEBUG_KEX' were very

  useful in debugging JSch.

* We appreciate IETF sesch working group and SSH Communications Security Corp.

  Without the standardization of the protocol, we could not get the

  chance to implement JSch.

* We appreciate Seigo Haruyama(http://www.unixuser.org/~haruyama/),

  who are interpreting drafts of SSH2 protocol in Japanese.

  His works were very useful for us to understand the technical terms

  in our native language.

* We also appreciate SourceForge.net's awesome service to the 

  Open Source Community.



If you have any comments, suggestions and questions, write us 

at [email protected]



``SSH is a registered trademark and Secure Shell is a trademark of

SSH Communications Security Corp (www.ssh.com)''.