Security Top

I just announced the new Learn Spring Security course, including the full material focused on the new OAuth2 stack in Spring Security 5:

>> CHECK OUT THE COURSE
Java Top

I just announced the new Learn Spring course, focused on the fundamentals of Spring 5 and Spring Boot 2:

>> CHECK OUT THE COURSE

1. Introduction

SSH, also known as Secure Shell or Secure Socket Shell, is a network protocol that allows one computer to securely connect to another computer over an unsecured network. In this tutorial, we'll show how to establish a connection to a remote SSH server with Java using the JSch and Apache MINA SSHD libraries.

In our examples, we'll first open the SSH connection, then execute one command, read the output and write it to the console, and, finally, close the SSH connection. We'll keep the sample code as simple as possible.

2. JSch

JSch is the Java implementation of SSH2 that allows us to connect to an SSH server and use port forwarding, X11 forwarding, and file transfer. Also, it is licensed under the BSD style license and provides us with an easy way to establish an SSH connection with Java.

First, let's add the JSch Maven dependency to our pom.xml file:

<dependency>
    <groupId>com.jcraft</groupId>
    <artifactId>jsch</artifactId>
    <version>0.1.55</version>
</dependency>

2.1. Implementation

To establish an SSH connection using JSch, we need a username, password, host URL, and SSH port. The default SSH port is 22, but it could happen that we'll configure the server to use other port for SSH connections:

public static void listFolderStructure(String username, String password, 
  String host, int port, String command) throws Exception {
    
    Session session = null;
    ChannelExec channel = null;
    
    try {
        session = new JSch().getSession(username, host, port);
        session.setPassword(password);
        session.setConfig("StrictHostKeyChecking", "no");
        session.connect();
        
        channel = (ChannelExec) session.openChannel("exec");
        channel.setCommand(command);
        ByteArrayOutputStream responseStream = new ByteArrayOutputStream();
        channel.setOutputStream(responseStream);
        channel.connect();
        
        while (channel.isConnected()) {
            Thread.sleep(100);
        }
        
        String responseString = new String(responseStream.toByteArray());
        System.out.println(responseString);
    } finally {
        if (session != null) {
            session.disconnect();
        }
        if (channel != null) {
            channel.disconnect();
        }
    }
}

As we can see in the code, we first create a client session and configure it for connection to our SSH server. Then, we create a client channel used to communicate with the SSH server where we provide a channel type – in this case, exec, which means that we'll be passing shell commands to the server.

Also, we should set the output stream for our channel where the server response will be written. After we establish the connection using the channel.connect() method, the command is passed, and the received response is written on the console.

Let's see how to use different configuration parameters that JSch offers:

  • StrictHostKeyChecking – it indicates whether the application will check if the host public key could be found among known hosts. Also, available parameter values are ask, yes, and no, where ask is the default. If we set this property to yes, JSch will never automatically add the host key to the known_hosts file, and it'll refuse to connect to hosts whose host key has changed. This forces the user to manually add all new hosts. If we set it to no, JSch will automatically add a new host key to the list of known hosts
  • compression.s2c – specifies whether to use compression for the data stream from the server to our client application. Available values are zlib and none where the second is the default
  • compression.c2s – specifies whether to use compression for the data stream in the client-server direction. Available values are zlib and none where the second is the default

It's important to close the session and the SFTP channel after the communication with the server is over to avoid memory leaks.

3. Apache MINA SSHD

Apache MINA SSHD provides SSH support for Java-based applications. This library is based on Apache MINA, a scalable and high-performance asynchronous IO library.

Let's add the Apache Mina SSHD Maven dependency:

<dependency>
    <groupId>org.apache.sshd</groupId>
    <artifactId>sshd-core</artifactId>
    <version>2.5.1</version>
</dependency>

3.1. Implementation

Let's see the code sample of connecting to the SSH server using Apache MINA SSHD:

public static void listFolderStructure(String username, String password, 
  String host, int port, long defaultTimeoutSeconds, String command) throws IOException {
    
    SshClient client = SshClient.setUpDefaultClient();
    client.start();
    
    try (ClientSession session = client.connect(username, host, port)
      .verify(defaultTimeoutSeconds, TimeUnit.SECONDS).getSession()) {
        session.addPasswordIdentity(password);
        session.auth().verify(defaultTimeoutSeconds, TimeUnit.SECONDS);
        
        try (ByteArrayOutputStream responseStream = new ByteArrayOutputStream(); 
          ClientChannel channel = session.createChannel(Channel.CHANNEL_SHELL)) {
            channel.setOut(responseStream);
            try {
                channel.open().verify(defaultTimeoutSeconds, TimeUnit.SECONDS);
                try (OutputStream pipedIn = channel.getInvertedIn()) {
                    pipedIn.write(command.getBytes());
                    pipedIn.flush();
                }
            
                channel.waitFor(EnumSet.of(ClientChannelEvent.CLOSED), 
                TimeUnit.SECONDS.toMillis(defaultTimeoutSeconds));
                String responseString = new String(responseStream.toByteArray());
                System.out.println(responseString);
            } finally {
                channel.close(false);
            }
        }
    } finally {
        client.stop();
    }
}

When working with the Apache MINA SSHD, we have a pretty similar sequence of events as with JSch. First, we establish a connection to an SSH server using the SshClient class instance. If we initialize it with SshClient.setupDefaultClient(), we'll be able to work with the instance that has a default configuration suitable for most use cases. This includes ciphers, compression, MACs, key exchanges, and signatures.

After that, we'll create ClientChannel and attach the ByteArrayOutputStream to it, so that we'll use it as a response stream. As we can see, SSHD requires defined timeouts for every operation. It also allows us to define how long it will wait for server response after the command is passed by using Channel.waitFor() method.

It's important to notice that SSHD will write complete console output into the response stream. JSch will do it only with the command execution result.

Complete documentation on Apache Mina SSHD is available on the project's official GitHub repository.

4. Conclusion

This article illustrated how to establish an SSH connection with Java using two of the available Java libraries – JSch and Apache Mina SSHD. We also showed how to pass the command to the remote server and get the execution result. Also, complete code samples are available over on GitHub.

Security bottom

I just announced the new Learn Spring Security course, including the full material focused on the new OAuth2 stack in Spring Security 5:

>> CHECK OUT THE COURSE
Java bottom

I just announced the new Learn Spring course, focused on the fundamentals of Spring 5 and Spring Boot 2:

>> CHECK OUT THE COURSE
Comments are closed on this article!