1 2 JSch 3 4 Java Secure Channel 5 by ymnk@jcraft.com, JCraft,Inc. 6 7 http://www.jcraft.com/jsch/ 8 9Last modified: Thu Mar 18 13:58:16 UTC 2015 10 11 12Description 13=========== 14JSch is a pure Java implementation of SSH2. JSch allows you to 15connect to an sshd server and use port forwarding, X11 forwarding, 16file transfer, etc., and you can integrate its functionality 17into your own Java programs. JSch is licensed under BSD style license. 18 19 20Documentation 21============= 22* README files all over the source tree have info related to the stuff 23 in the directories. 24* ChangeLog: what changed from the previous version? 25 26 27Directories & Files in the Source Tree 28====================================== 29* src/com/ has source trees of JSch 30* example/ has some samples, which demonstrate the usages. 31* tools/ has scripts for Ant. 32 33 34Why JSch? 35========== 36Our intension in developing this stuff is to enable users of our pure 37java X servers, WiredX(http://wiredx.net/) and WeirdX, to enjoy secure X 38sessions. Our efforts have mostly targeted the SSH2 protocol in relation 39to X Window System and X11 forwarding. Of course, we are also interested in 40adding other functionality - port forward, file transfer, terminal emulation, etc. 41 42 43Features 44======== 45* JSch is in pure Java, but it depends on JavaTM Cryptography 46 Extension (JCE). JSch is know to work with: 47 o J2SE 1.4.0 or later (no additional libraries required). 48 o J2SE 1.3 and Sun's JCE reference implementation that can be 49 obtained at http://java.sun.com/products/jce/ 50 o J2SE 1.2.2 and later and Bouncycastle's JCE implementation that 51 can be obtained at http://www.bouncycastle.org/ 52* SSH2 protocol support. 53* Key exchange: diffie-hellman-group-exchange-sha1, 54 diffie-hellman-group1-sha1, 55 diffie-hellman-group14-sha1, 56 diffie-hellman-group-exchange-sha256, 57 ecdh-sha2-nistp256, 58 ecdh-sha2-nistp384, 59 ecdh-sha2-nistp521 60* Cipher: blowfish-cbc,3des-cbc,aes128-cbc,aes192-cbc,aes256-cbc 61 3des-ctr,aes128-ctr,aes192-ctr,aes256-ctc, 62 arcfour,arcfour128,arcfour256 63* MAC: hmac-md5,hmac-md5-96,hmac-sha1,hmac-sha1-96 64* Host key type: ssh-dss,ssh-rsa, 65 ecdsa-sha2-nistp256,ecdsa-sha2-nistp384,ecdsa-sha2-nistp521 66* Userauth: password 67* Userauth: publickey(DSA,RSA,ECDSA) 68* Userauth: keyboard-interactive 69* Userauth: gssapi-with-mic 70* X11 forwarding. 71* xauth spoofing. 72* connection through HTTP proxy. 73* connection through SOCKS5, SOCKS4 proxy. 74* port forwarding. 75* stream forwarding. 76* signal sending. 77 The unofficial patch for sshd of openssh will be find in the thread 78 http://marc.theaimsgroup.com/?l=openssh-unix-dev&m=104295745607575&w=2 79* envrironment variable passing. 80* remote exec. 81* generating DSA and RSA key pairs. 82* supporting private keys in OpenSSL(traditional SSLeay) and PKCS#8 format. 83* SSH File Transfer Protocol(version 0, 1, 2, 3) 84* partial authentication 85* packet compression: zlib, zlib@openssh.com 86 JZlib(http://www.jcraft.com/jzlib/) has been used. 87* hashed known_hosts file. 88* NONE Cipher switching. 89 http://www.psc.edu/networking/projects/hpn-ssh/none.php 90* JSch is licensed under BSD style license(refer to LICENSE.txt). 91 92 93How To Try 94========== 95This archive does not include java byte code, so please compile 96the source code by your self. 97 $ cd jsch-?.?.?/src 98 $ javac com/jcraft/jsch/*java com/jcraft/jsch/jce/*java com/jcraft/jzlib/*.java 99'/examples/' directory has included some samples to demonstrate what 100JSch can do. Please refer to '/examples/README' file. 101 102 103AES cipher 104========== 105JSch supports aes128-cbc,aes192-cbc,aes256-cbc,aes128-ctr,aes192-ctr, 106aes256-ctr but you require AES support in your J2SE to choose some of them. 107If you are using Sun's J2SE, J2SE 1.4.2 or later is required. 108And then, J2SE 1.4.2(or later) does not support aes256 by the default, 109because of 'import control restrictions of some countries'. 110We have confirmed that by applying 111 "Java Cryptography Extension (JCE) 112 Unlimited Strength Jurisdiction Policy Files 1.4.2" 113on 114 http://java.sun.com/j2se/1.4.2/download.html#docs 115we can enjoy 'aes256-cbc,aes256-ctr'. 116 117 118Stream Forwarding 119================= 120JSch has a unique functionality, Stream Forwarding. 121Stream Forwarding allows you to plug Java I/O streams directly into a remote TCP 122port without assigning and opening a local TCP port. 123In port forwarding, as with the -L option of ssh command, you have to assign 124and open a local TCP port and that port is also accessible by crackers 125on localhost. In some case, that local TCP port may be plugged to a 126secret port via SSH session. 127A sample program, /example/StreamForwarding.java , demonstrates 128this functionality. 129 130 131Generating Authentication Keys 132============================== 133JSch allows you to generate DSA and RSA key pairs, which are in OpenSSH format. 134Please refer to 'examples/KeyGen.java'. 135 136 137Packet Compression 138================== 139According to the draft from IETF sesch working group, the packet 140compression can be applied to each data stream directions; from sshd 141server to ssh client and from ssh client to sshd server. So, jsch 142allows you to choose which data stream direction will be compressed or not. 143For example, in X11 forwarding session, the packet compression for data 144stream from sshd to ssh client will save the network traffic, but 145usually the traffic from ssh client to sshd is light, so by omitting 146the compression for this direction, you may be able to save some CPU time. 147Please refer to a sample program 'examples/Compression.java'. 148 149 150Property 151======== 152By setting properties, you can control the behavior of jsch. 153Here is an example of enabling the packet compression, 154 155 Session session=jsch.getSession(user, host, 22); 156 java.util.Properties config=new java.util.Properties(); 157 config.put("compression.s2c", "zlib,none"); 158 config.put("compression.c2s", "zlib,none"); 159 session.setConfig(config); 160 session.connect(); 161 162Current release has supported following properties, 163* compression.s2c: zlib, none 164 default: none 165 Specifies whether to use compression for the data stream 166 from sshd to jsch. If "zlib,none" is given and the remote sshd does 167 not allow the packet compression, compression will not be done. 168* compression.c2s: zlib, none 169 default: none 170 Specifies whether to use compression for the data stream 171 from jsch to sshd. 172* StrictHostKeyChecking: ask | yes | no 173 default: ask 174 If this property is set to ``yes'', jsch will never automatically add 175 host keys to the $HOME/.ssh/known_hosts file, and refuses to connect 176 to hosts whose host key has changed. This property forces the user 177 to manually add all new hosts. If this property is set to ``no'', 178 jsch will automatically add new host keys to the user known hosts 179 files. If this property is set to ``ask'', new host keys will be 180 added to the user known host files only after the user has confirmed 181 that is what they really want to do, and jsch will refuse to connect 182 to hosts whose host key has changed. 183 184 185TODO 186==== 187* re-implementation with java.nio. 188* replacing cipher, hash by JCE with pure Java code. 189* SSH File Transfer Protocol version 4. 190* error handling. 191 192 193Copyrights & Disclaimers 194======================== 195JSch is copyrighted by ymnk, JCraft,Inc. and is licensed through BSD style license. 196Read the LICENSE.txt file for the complete license. 197 198 199Credits and Acknowledgments 200============================ 201JSch has been developed by ymnk@jcraft.com and it can not be hacked 202without several help. 203* First of all, we want to thank JCE team at Sun Microsystems. 204 For long time, we had planed to implement SSH2 in pure Java, 205 but we had hesitated to do because tons of work must be done for 206 implementing ciphers, hashes, etc., from the scratch. 207 Thanks to newly added functionalities to J2SE 1.4.0, we could 208 start this project. 209* We appreciate the OpenSSH project. 210 The options '-ddd' of sshd, '---vvv' of ssh and the compile options 211 '-DPACKET_DEBUG', '-DDEBUG_KEXDH' and '-DDEBUG_KEX' were very 212 useful in debugging JSch. 213* We appreciate IETF sesch working group and SSH Communications Security Corp. 214 Without the standardization of the protocol, we could not get the 215 chance to implement JSch. 216* We appreciate Seigo Haruyama(http://www.unixuser.org/~haruyama/), 217 who are interpreting drafts of SSH2 protocol in Japanese. 218 His works were very useful for us to understand the technical terms 219 in our native language. 220* We also appreciate SourceForge.net's awesome service to the 221 Open Source Community. 222 223 224If you have any comments, suggestions and questions, write us 225at jsch@jcraft.com 226 227 228``SSH is a registered trademark and Secure Shell is a trademark of 229SSH Communications Security Corp (www.ssh.com)''. 230