sshj - SSHv2 library for Java

Warning

SSHJ versions up to and including 0.37.0 are vulnerable to CVE-2023-48795 - Terrapin. Please upgrade to 0.38.0 or higher.

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:

1. Add a dependency to SSHJ to your project.

2. 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 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:

<dependency>
  <groupId>com.hierynomus</groupId>
  <artifactId>sshj</artifactId>
  <version>0.38.0</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

1. Clone the SSHJ repository.

2. Ensure you have Java6 installed with the Unlimited strength Java Cryptography Extensions (JCE).

3. 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:

1. Install Maven 2.2.1 or up.

2. Clone the SSHJ repository.

3. Go into the examples directory and run the command mvn eclipse:eclipse.

4. Import the examples project into Eclipse.

5. 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}, aes{128,256}-gcm@openssh.com, blowfish-{cbc,ctr}, chacha20-poly1305@openssh.com, 3des-{cbc,ctr}, twofish{128,192,256}-{cbc,ctr}, twofish-cbc, serpent{128,192,256}-{cbc,ctr}, idea-{cbc,ctr}, cast128-{cbc,ctr}, arcfour, arcfour{128,256} SSHJ also supports the following extended (non official) ciphers: camellia{128,192,256}-{cbc,ctr}, camellia{128,192,256}-{cbc,ctr}@openssh.org

key exchange

diffie-hellman-group1-sha1, diffie-hellman-group14-sha1, diffie-hellman-group14-sha256, diffie-hellman-group15-sha512, diffie-hellman-group16-sha512, diffie-hellman-group17-sha512, diffie-hellman-group18-sha512 diffie-hellman-group-exchange-sha1, diffie-hellman-group-exchange-sha256, ecdh-sha2-nistp256, ecdh-sha2-nistp384, ecdh-sha2-nistp521, curve25519-sha256@libssh.org

SSHJ also supports the following extended (non official) key exchange algorithms:
`diffie-hellman-group14-sha256@ssh.com`, `diffie-hellman-group15-sha256`, `diffie-hellman-group15-sha256@ssh.com`, `diffie-hellman-group15-sha384@ssh.com`,
`diffie-hellman-group16-sha256`, `diffie-hellman-group16-sha384@ssh.com`, `diffie-hellman-group16-sha512@ssh.com`, `diffie-hellman-group18-sha512@ssh.com`

signatures

ssh-rsa, ssh-dss, ecdsa-sha2-nistp256, ecdsa-sha2-nistp384, ecdsa-sha2-nistp521, ssh-ed25519, ssh-rsa2-256, ssh-rsa2-512

mac

hmac-md5, hmac-md5-96, hmac-sha1, hmac-sha1-96, hmac-sha2-256, hmac-sha2-512, hmac-ripemd160, hmac-ripemd160@openssh.com hmac-md5-etm@openssh.com, hmac-md5-96-etm@openssh.com, hmac-sha1-etm@openssh.com, hmac-sha1-96-etm@openssh.com, hmac-sha2-256-etm@openssh.com, hmac-sha2-512-etm@openssh.com, hmac-ripemd160-etm@openssh.com

compression

zlib and zlib@openssh.com (delayed zlib)

private key files

pkcs5, pkcs8, openssh-key-v1, ssh-rsa-cert-v01@openssh.com, ssh-dsa-cert-v01@openssh.com

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

Comparing to other implementations

SSH Implementation Comparison

Dependencies

• Java 8 or higher

• SLF4J 2.0.0

• Bouncy Castle

Reporting bugs

Issue tracker: https://github.com/hierynomus/sshj/issues

Contributing

Fork away!

Release history

SSHJ 0.38.0 (2024-01-02)

• Mitigated CVE-2023-48795 - Terrapin

• Merged #917: Implement OpenSSH strict key exchange extension

• Merged #903: Fix for writing known hosts key string

• Merged #913: Prevent remote port forwarding buffers to grow without bounds

• Moved tests to JUnit5

• Merged #827: Fallback to posix-rename@openssh.com extension if available

• Merged #904: Add ChaCha20-Poly1305 support for OpenSSH keys

SSHJ 0.37.0 (2023-10-11)

• Merged #899: Add support for AES-GCM OpenSSH private keys

• Merged #901: Fix ZLib compression bug

• Merged #898: Improved malformed file handling for OpenSSH private keys

SSHJ 0.36.0 (2023-09-04)

• Rewrote Integration tests to JUnit5

• Merged #851: Fix race condition in key exchange causing intermittent SSH_MSG_UNIMPLEMENTED

• Merged #861: Add DefaultSecurityProviderConfig with has BouncyCastle disabled

• Merged #881: Rewrote test classes to JUnit Jupiter engine

• Merged #880: Removed Java 7 backport Socket utilities

• Merged #879: Replaced custom Base64 with java.util.Base64

• Merged #852: Removed unused bcrypt password hashing methods

• Merged #874: Java 8 minimum version + dependency upgrades

• Merged #876: Change newStatefulSFTPClient to return StatefulSFTPClient

• Merged #860: Upgrade to Gradle 7.6.1

• Merged #838: Replaced Curve25519 class with X25519 Key agreement

• Merged #772: Remove dependency on jzlib

SSHJ 0.35.0 (2023-01-30)

• Merged #835: TimeoutException message improved

• Merged #815: Support authPassword on FreeBSD

• Merged #813: Prevent CHANNEL_CLOSE between isOpen and write call.

• Merged #811: Add Transport.isKeyExchangeREquired to prevent unnecessary KEXINIT

SSHJ 0.34.0 (2022-08-10)

• Merged #743: Use default client credentials for AuthGssApiWithMic

• Merged #801: Restore thread interrupt status after catching InterruptedException

• Merged #793: Merge PKCS5 and PKCS8 classes

• Upgraded dependencies SLF4J (1.7.36) and Logback (1.2.11)

• Merged #791: Update KeepAlive examples

• Merged #775: Add SFTP resume support

SSHJ 0.33.0 (2022-04-22)

• Upgraded dependencies BouncyCastle (1.70)

• Merged #687: Correctly close connection when remote closes connection.

• Merged #741: Add support for testcontainers in test setup to test more scenarios

• Merged #733: Send correct key proposal if client knows CA key

• Merged #746: Fix bug in reading Putty private key file with passphrase

• Merged #742: Use Config.keyAlgorithms to determine rsa-sha2 support

• Merged #754: Use SFTP protocol version to set FXP rename flags conditionally

• Merged #752: Correctly start and terminate KeepAlive thread

• Merged #753: Provide better thread names

• Merged #724: Add parameter to limit read ahead length

• Merged #763: Try all public key algorithms for a specific key type

• Merged #756: Remove deprecated proxy connect methods

• Merged #770: Add support for ed25519 aes-128-cbc keys

• Merged #773: Fix NPE when reading empty OpenSSHKeyV1KeyFile

• Merged #777: Don’t request too many read-ahead packets

SSHJ 0.32.0 (2021-10-12)

• Send EOF on channel close (Fixes #143, #496, #553, #554)

• Merged #726: Parse OpenSSH v1 keys with full CRT information present

• Merged #721: Prefer known host key algorithm for host key verification

• Merged #716, #729 and #730: Add full support for PuTTY v3 key files.

• Merged #708 and #71: Add support for PKCS#8 private keys

• Merged #703: Support host certificate keys

• Upgraded dependencies BouncyCastle (1.69), SLF4j (1.7.32), Logback (1.2.6), asn-one (0.6.0)

• Merged #702: Support Public key authentication using certificates

• Merged #691: Fix for writing negative unsigned integers to Buffer

• Merged #682: Support for chacha20-poly1305@openssh.com cipher

• Merged #680: Configurable preserve mtimes for SCP transfers

SSHJ 0.31.0 (2021-02-08)

• Bump dependencies (asn-one 0.5.0, BouncyCastle 1.68, slf4j-api 1.7.30)

• Merged #660: Support ED25519 and ECDSA keys in PuTTY format

• Merged #655: Bump BouncyCastle due to CVE

• Merged #653: Make Parameters class useable as HashMap key

• Merged #647: Reduce log level for identification parser

• Merged #630: Add support for aes128-gcm@openssh.com and aes256-gcm@openssh.com ciphers

• Merged #636: Improved Android compatibility

• Merged #627: Prevent key leakage

SSHJ 0.30.0 (2020-08-17)

• BREAKING CHANGE: Removed setSignatureFactories and getSignatureFactories from the Config and switched them for getKeyAlgorithms and setKeyAlgorithms

• Fixed #588: Add support for ssh-rsa2-256 and ssh-rsa2-512 signatures

• Merged #579: Fix NPE in OpenSSHKnownHosts

• Merged #587: Add passwordfinder retry for OpenSSHKeyV1KeyFile

• Merged #586: Make KeyType compatible with Android Store

• Merged #593: Change UserAuth.getAllowedMethods() to Collection return type

• Merged #595: Allow reading arbitrary length keys

• Merged #591: Allow to query SFTP extensions

• Merged #603: Add method to create Stateful SFTP client

• Merged #605: Use Daemon threads to avoid blocking JVM shutdown

• Merged #606: Always use the JCERandom RNG by default

• Merged #609: Clear passphrase after use to prevent security issues

• Merged #618: Fix localport of DirectConnection for use with OpenSSH > 8.0

• Merged #619: Upgraded BouncyCastle to 1.66

• Merged #622: Send 'ext-info-c' with KEX algorithms

• Merged #623: Fix transport encoding of nistp521 signatures

• Merged #607: Fix mathing pubkeys to key algorithms

• Merged #602: Fix RSA certificate key determination

SSHJ 0.27.0 (2019-01-24)

• Fixed #415: Fixed wrongly prefixed '/' to path in SFTPClient.mkdirs

• Added support for ETM (Encrypt-then-Mac) MAC algorithms.

• Fixed #454: Added missing capacity check for Buffer.putUint64

• Fixed #466: Added lock timeout for remote action to prevent hanging

• Fixed #470: Made EdDSA the default (first) signature factory

• Fixed #467: Added AES256-CBC as cipher mode in openssh-key-v1 support

• Fixed #464: Enabled curve25519-sha256@openssh.org in DefaultConfig

• Fixed #472: Handle server initiated global requests

• Fixed #485: Added support for all keytypes to openssh-key-v1 keyfiles.

SSHJ 0.26.0 (2018-07-24)

• Fixed #413: Use UTF-8 for PrivateKeyFileResource

• Fixed #427: Support encrypted ed25519 openssh-key-v1 files

• Upgraded BouncyCastle to 1.60

• Added support for hmac-ripemd160@openssh.com MAC

SSHJ 0.24.0 (2018-04-04)

• Added support for hmac-ripemd160

• Fixed #382: Fixed escaping in WildcardHostmatcher

• Added integration testsuite using Docker against OpenSSH

• Fixed #187: Fixed length bug in Buffer.putString

• Fixed #405: Continue host verification if first hostkey does not match.

SSHJ 0.23.0 (2017-10-13)

• Merged #372: Upgrade to 'net.i2p.crypto:eddsa:0.2.0'

• Fixed #355 and #354: Correctly decode signature bytes

• Fixed #365: Added support for new-style OpenSSH fingerprints of server keys

• Fixed #356: Fixed key type detection for ECDSA public keys

• Made SSHJ Java9 compatible

SSHJ 0.22.0 (2017-08-24)

• Fixed #341: Fixed path walking during recursive copy

• Merged #338: Added ConsolePasswordFinder to read password from stdin

• Merged #336: Added support for ecdsa-sha2-nistp384 and ecdsa-sha2-nistp521 signatures

• Fixed #331: Added support for wildcards in known_hosts file

SSHJ 0.21.1 (2017-04-25)

• Merged #322: Fix regression from 40f956b (invalid length parameter on outputstream)

SSHJ 0.21.0 (2017-04-14)

• Merged #319: Added support for ssh-rsa-cert-v01@openssh.com and ssh-dsa-cert-v01@openssh.com certificate key files

• Upgraded Gradle to 3.4.1

• Merged #305: Added support for custom string encoding

• Fixed #312: Upgraded BouncyCastle to 1.56

SSHJ 0.20.0 (2017-02-09)

• Merged #294: Reference ED25519 by constant instead of name

• Merged #293, #295 and #301: Fixed OSGi packaging

• Added new Diffie Hellman groups 15-18 for stronger KeyExchange algorithms

SSHJ 0.19.1 (2016-12-30)

• Enabled PKCS5 Key files in DefaultConfig

• Merged #291: Fixed sshj.properties loading and chained exception messages

• Merged #284: Correctly catch interrupt in keepalive thread

• Fixed #292: Pass the configured RandomFactory to Diffie Hellman KEX

• Fixed #256: SSHJ now builds if no git repository present

• LocalPortForwarder now correctly interrupts its own thread on close()

SSHJ 0.19.0 (2016-11-25)

• Fixed #276: Add support for ed-25519 and new OpenSSH key format

• Fixed #280: Read version from a generated sshj.properties file to correctly output version during negotiation

SSHJ 0.18.0 (2016-09-30)

• Fixed Android compatibility

• Upgrade to Gradle 3.0

• Merged #271: Load known_hosts without requiring BouncyCastle

• Merged #269: Brought back Java6 support by popular demand

• Merged #267: Added support for per connection logging (Fixes #264)

• Merged #262, #265 and #266: Added PKCS5 key file support

• Fixed toString of sftp FileAttributes (Fixes #258)

• Fixed #255: No longer depending on 'privately marked' classes in net.i2p.crypto.eddsa.math package, fixes OSGI dependencies

SSHJ 0.17.2 (2016-07-07)

• Treating SSH Server identification line ending in '\n' instead of '\r\n' leniently.

SSHJ 0.17.1 (2016-07-06)

• Improved parsing of the SSH Server identification. Too long header lines now no longer break the protocol.

SSHJ 0.17.0 (2016-07-05)

• Introduced breaking change in SFTP copy behaviour: Previously an SFTP copy operation would behave differently if both source and target were folders with different names. In this case instead of copying the contents of the source into the target directory, the directory itself was copied as a sub directory of the target directory. This behaviour has been removed in favour of the default behaviour which is to copy the contents of the source into the target. Bringing the behaviour in line with how SCP works.

• Fixed #252 (via: #253): Same name subdirs are no longer merged by accident

SSHJ 0.16.0 (2016-04-11)

• Fixed #239: Remote port forwards did not work if you used the empty string as address, or a catch-all address.

• Fixed #242: Added OSGI headers to sources jar manifest

• Fixed #236: Remote Port forwarding with dynamic port allocation fails with BufferUnderflowException

• Upgraded gradle distribution to 2.12

• Closed #234: Dropped Java6 support (0.15.0 was already Java6 incompatible due to Java7 dependency)

• Fixed #118: Added configuration switch for waiting on a server ident before sending the client ident.

• Fixed #114: Added javadoc that you always need to call close() on a Command before inspecting the exit codes.

• Fixed #237: Fixed race condition if a hostkeys-00@openssh.com global request is received directly after a successful auth.

SSHJ 0.15.0 (2015-11-20)

• Fixed #220: Added support for ssh-ed25519 host keys

• Fixed #225: Fixed bug in ECDSA fingerprint calculation that sometimes produced an incorrect fingerprint

• Added arcfour Stream Ciphers from RFC4253 and RFC4345

• Added all Block Ciphers from RFC4344 and RFC4253

SSHJ 0.14.0 (2015-11-04)

• Fixed #171: Added support for curve25519-sha256@libssh.org key exchange algorithm

• Added support for ecdh-sha2-nistp256, ecdh-sha2-nistp384 and ecdh-sha2-nistp521 key exchange algorithms

• Fixed #167: Added support for diffie-hellman-group-exchange-sha1 and diffie-hellman-group-exchange-sha256 key exchange methods

• Fixed #212: Configure path escaping to enable shell expansion to work correctly

• Merged #210: RemoteFileInputStream.skip returns wrong value (Fixes #209)

• Merged #208: Added SCP bandwidth limitation support

• Merged #211: Made keyfile format detection more robust

SSHJ 0.13.0 (2015-08-18)

• Merged #199: Fix for IndexOutOfBoundsException in ReadAheadRemoteFileInputStream, fixes #183

• Merged #195: New authentication supported: gssapi-with-mic

• Merged #201: New option to verify negotiated key exchange algorithms

• Merged #196: Fix for looking up complete hostname in known hosts file

SSHJ 0.12.0 (2015-04-14)

• Added support for HTTP proxies when running JDK6 or JDK7, fixes: #170

• Merged #186: Fix for detecting end-of-stream

• Compiling to JDK6, fixes #179 and #185

• Correctly close socket and channel when LocalPortForwarder fails to open and start the channel (Fixes #175 and #176)

• Merged #181: Invalid write packet length when reading with offset (Fixes #180)

SSHJ 0.11.0 (2015-01-23)

• New maven coordinates com.hierynomus:sshj:0.11.0 as @hierynomus took over as maintainer of SSHJ

• Migrated build system to Gradle 2.2.1

• Merged #150: Fix for incorrect file handle on some SSH servers, fixes: #54, #119, #168, #169

• Made jzlib optional in OSGi bundling, fixes: #162

• Improved some log levels, fixes: #161

• Merged #156, #164, #165: Fixed block sizes for hmac-sha2-256 and hmac-sha2-512

• Merged #141: Add proxy support

• Merged #157, #163: Doc and build fixes

• Upgraded BouncyCastle to 1.51, fixes: #142

• Implemented keep-alive with connection drop detection, fixes #166