SSH Tunneling Library

Sonatype helps open source projects to set up Maven repositories on https://oss.sonatype.org/

License

License

GroupId

GroupId

com.hotels
ArtifactId

ArtifactId

hcommon-ssh
Last Version

Last Version

1.0.2
Release Date

Release Date

Type

Type

jar
Description

Description

SSH Tunneling Library
Sonatype helps open source projects to set up Maven repositories on https://oss.sonatype.org/
Project Organization

Project Organization

Hotels.com (Data Platform Team)
Source Code Management

Source Code Management

https://github.com/HotelsDotCom/hcommon-ssh

Download hcommon-ssh

How to add to project

<!-- https://jarcasting.com/artifacts/com.hotels/hcommon-ssh/ -->
<dependency>
    <groupId>com.hotels</groupId>
    <artifactId>hcommon-ssh</artifactId>
    <version>1.0.2</version>
</dependency>
// https://jarcasting.com/artifacts/com.hotels/hcommon-ssh/
implementation 'com.hotels:hcommon-ssh:1.0.2'
// https://jarcasting.com/artifacts/com.hotels/hcommon-ssh/
implementation ("com.hotels:hcommon-ssh:1.0.2")
'com.hotels:hcommon-ssh:jar:1.0.2'
<dependency org="com.hotels" name="hcommon-ssh" rev="1.0.2">
  <artifact name="hcommon-ssh" type="jar" />
</dependency>
@Grapes(
@Grab(group='com.hotels', module='hcommon-ssh', version='1.0.2')
)
libraryDependencies += "com.hotels" % "hcommon-ssh" % "1.0.2"
[com.hotels/hcommon-ssh "1.0.2"]

Dependencies

compile (4)

Group / Artifact Type Version
net.java.dev.jna : jna jar 3.4.0
net.java.dev.jna : platform jar 3.4.0
javax.validation : validation-api jar 1.1.0.Final
org.slf4j : slf4j-api jar 1.7.5

Project Modules

There are no modules declared in this project.

Hcommon-ssh

This library provides common functionality which allows network-connected components to route traffic through SSH tunnels.

Start using

You can obtain this library from Maven Central:

Maven Central Build Status Coverage Status GitHub license

Overview

Components can be proxied to use a SSH tunnel. A SshSettings object provides the basic configuration required to establish the SSH connection and the SSH tunnel.

This library uses Java Proxies to handle the SSH tunneling logic so components must implement the marker interface Tunnelable.

An out-of-the-box factory is provided to handle the component wrapping: TunnelableFactory. The factory uses a MethodChecker to verify whether the method being invoked must ensure the SSH tunnel is open or whether the method must close the SSH tunnel. In order to proxy a component the wrap method of this factory class must be invoked passing the component to wrap, an instance of MethodChecker and the remote host and port to which the component will be connecting.

Example:

// Mark the client as tunnelable
public class MyClient implements Tunnelable, ... {
  ...
}
...
public class MyClientSupplier implements TunnelableSupplier<MyClient> {
  ...
}
...
MyClientSupplier myClientSupplier = new MyClientSupplier();
...
SshSettings sshSettings = SshSettings
  .builder()
  .withRoute("hop1 -> hop2")
  .withKnownHosts("/home/user/.ssh/known_hosts")
  .withPrivateKeys("/home/user/.ssh/id_rsa_common")
  .build();
TunnelableFactory factory = new TunnelableFactory(sshSettings);
Tunnelable wrapped = factory.wrap(myClientSupplier, MethodCheck.DEFAULT, "my-remote-service", 8080);

SSH tunnel syntax

The tunnel route expression is described with the following EBNF:

path = path part, {"->", path part}
path part = {user, "@"}, hostname
user = ? user name ?
hostname = ? hostname ?

For example, if the remote service runs on the host remote-server-box:1024 which can only be reached first via bastion-host and then jump-box then the SSH tunnel route expression in SshSettings will be bastion-host -> jump-box and host remote-server-box and port 1024 will be provided as method parameters in the factory. If bastion-host is only accessible by user ec2-user and jump-box by user user-a then the expression above becomes ec2-user@bastion-host -> user-a@jump-box.

Once the tunnel is established the library will set up port forwarding from the local machine specified to the remote machine. The last node in the tunnel expression doesn't need to be the target server, the only requirement is that this last node must be able to communicate with the remote-server-box. Sometimes this is not possible due to firewall restrictions so in these cases they must be the same.

All the machines in the tunnel expression can be included in the known___hosts file and in this case the keys required to access each box should be set in the SshSettings privateKkeys property. For example, if bastion-host is authenticated with bastion.pem and both jump-box and remote-server-box are authenticated with emr.pem then the property must be set as"<path-to-ssh-keys>/bastion.pem, <path-to-ssh-keys>/emr.pem".

If all machines in the tunnel expression are not included in the known___hosts file then the SshSettings property strictHostKeyChecking should be set to no.

To add the fingerprint of remote-box in to the known___hosts file the following command can be used:

ssh-keyscan -t rsa remote-box >> .ssh/known_hosts

Legal

This project is available under the Apache 2.0 License.

Copyright 2019 Expedia, Inc.

com.hotels

Hotels.com

Hotels.com open source contributions

Versions

Version
1.0.2
1.0.1
1.0.0