sshj/README.adoc

= sshj - SSHv2 library for Java
Jeroen van Erp
:sshj_groupid: com.hierynomus
:sshj_version: 0.11.0
:source-highlighter: pygments

image::https://travis-ci.org/hierynomus/sshj.svg?branch=master[]

To get started, have a look at one of the examples. Hopefully you will find the API pleasant to work with :)

== Getting SSHJ

To get SSHJ, you have two options:

. Add a dependency to SSHJ to your project.
. Build SSHJ yourself.

And, if you want, you can also run the SSHJ examples.

Binary releases of SSHJ are not provided here, but you can download it http://search.maven.org/#artifactdetails%7C{sshj_groupid}%7Csshj%7C{sshj_version}%7Cjar[straight from the Maven Central repository] if you want to.

== Depending on SSHJ
If you're building your project using Maven, you can add the following dependency to the `pom.xml`:

[source,xml,subs="verbatim,attributes"]
----
<dependency>
  <groupId>{sshj_groupid}</groupId>
  <artifactId>sshj</artifactId>
  <version>{sshj_version}</version>
</dependency>
----

If your project is built using another build tool that uses the Maven Central repository, translate this dependency into the format used by your build tool.

== Building SSHJ
. Clone the Overthere repository.
. Ensure you have Java6 installed with the http://www.oracle.com/technetwork/java/javase/downloads/jce-6-download-429243.html[Unlimited strength Java Cryptography Extensions (JCE)].
. Run the command `./gradlew clean build`.

== Running the examples
In the `examples` directory, there is a separate Maven project that shows how the library can be used in some sample cases. If you want to run them, follow these guidelines:

. Install http://maven.apache.org/[Maven 2.2.1] or up.
. Clone the Overthere repository.
. Go into the `examples` directory and run the command `mvn eclipse:eclipse`.
. Import the `examples` project into Eclipse.
. Change the login details in the example classes (address, username and password) and run them!

== Features of the library include:

* reading known_hosts files for host key verification
* publickey, password and keyboard-interactive authentication
* command, subsystem and shell channels
* local and remote port forwarding
* scp + complete sftp version 0-3 implementation

== Supported algorithms
Implementations / adapters for the following algorithms are included:

ciphers::
  `aes{128,192,256}-{cbc,ctr}`, `blowfish-cbc`, `3des-cbc`

key exchange::
  `diffie-hellman-group1-sha1`, `diffie-hellman-group14-sha1`

signatures::
  `ssh-rsa`, `ssh-dss`

mac::
  `hmac-md5`, `hmac-md5-96`, `hmac-sha1`, `hmac-sha1-96`, `hmac-sha2-256`, `hmac-sha2-512`

compression::
  `zlib` and `zlib@openssh.com` (delayed zlib)

private key files::
   `pkcs8` encoded (what openssh uses)

If you need something that is not included, it shouldn't be too hard to add (do contribute it!)


== Dependencies
Java 6+. http://www.slf4j.org/download.html[slf4j] is required. http://www.bouncycastle.org/java.html[bouncycastle] is highly recommended and required for using some of the crypto algorithms. http://www.jcraft.com/jzlib/[jzlib] is required for using zlib compression.

== Reporting bugs
Issue tracker: https://github.com/hierynomus/sshj/issues

== Discussion
Google Group: http://groups.google.com/group/sshj-users

== Contributing
Fork away!

== Release history

SSHJ 0.12.0 (not released yet)::
* Added support for HTTP proxies when running JDK6 or JDK7, fixes: https://github.com/hierynomus/sshj/issues/170[#170]
* Merged https://github.com/hierynomus/sshj/issues/186[#186]: Fix for detecting end-of-stream
* Compiling to JDK6, fixes https://github.com/hierynomus/sshj/issues/179[#179] and https://github.com/hierynomus/sshj/issues/185[#185]
* Correctly close socket and channel when LocalPortForwarder fails to open and start the channel (Fixes https://github.com/hierynomus/sshj/issues/175[#175] and https://github.com/hierynomus/sshj/issues/176[#176])
SSHJ 0.11.0 (2015-01-23)::
* New maven coordinates `com.hierynomus:sshj:0.11.0` as https://github.com/hierynomus[@hierynomus] took over as maintainer of SSHJ
* Migrated build system to Gradle 2.2.1
* Merged https://github.com/hierynomus/sshj/issues/150[#150]: Fix for incorrect file handle on some SSH servers, fixes: https://github.com/hierynomus/sshj/issues/54[#54], https://github.com/hierynomus/sshj/issues/119[#119], https://github.com/hierynomus/sshj/issues/168[#168], https://github.com/hierynomus/sshj/issues/169[#169]
* Made `jzlib` optional in OSGi bundling, fixes: https://github.com/hierynomus/sshj/issues/162[#162]
* Improved some log levels, fixes: https://github.com/hierynomus/sshj/issues/161[#161]
* Merged https://github.com/hierynomus/sshj/issues/156[#156], https://github.com/hierynomus/sshj/issues/164[#164], https://github.com/hierynomus/sshj/issues/165[#165]: Fixed block sizes for `hmac-sha2-256` and `hmac-sha2-512`
* Merged https://github.com/hierynomus/sshj/issues/141[#141]: Add proxy support
* Merged https://github.com/hierynomus/sshj/issues/157[#157], https://github.com/hierynomus/sshj/issues/163[#163]: Doc and build fixes
* Upgraded BouncyCastle to 1.51, fixes: https://github.com/hierynomus/sshj/issues/142[#142]
* Implemented keep-alive with connection drop detection, fixes https://github.com/hierynomus/sshj/issues/166[#166]