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