/*
* Copyright (C)2009 - SSHJ Contributors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package net.schmizz.sshj.transport;
import net.schmizz.sshj.Config;
import net.schmizz.sshj.Service;
import net.schmizz.sshj.common.DisconnectReason;
import net.schmizz.sshj.common.SSHPacket;
import net.schmizz.sshj.common.SSHPacketHandler;
import net.schmizz.sshj.transport.verification.AlgorithmsVerifier;
import net.schmizz.sshj.transport.verification.HostKeyVerifier;
import java.io.InputStream;
import java.io.OutputStream;
import java.util.concurrent.TimeUnit;
/** Transport layer of the SSH protocol. */
public interface Transport
extends SSHPacketHandler {
/**
* Sets the host information and the streams to be used by this transport. Identification information is exchanged
* with the server. A {@link TransportException} is thrown in case of SSH protocol version incompatibility.
*
* @param host server's hostname
* @param port server's port
* @param in input stream for the connection
* @param out output stream for the connection
*
* @throws TransportException if there is an error during exchange of identification information
*/
void init(String host, int port, InputStream in, OutputStream out)
throws TransportException;
/**
* Adds the specified verifier.
*
* @param hkv the host key verifier
*/
void addHostKeyVerifier(HostKeyVerifier hkv);
/**
* Adds the specified verifier.
*
* @param verifier The verifier to call with negotiated algorithms
*/
void addAlgorithmsVerifier(AlgorithmsVerifier verifier);
/**
* Do key exchange and algorithm negotiation. This can be the initial one or for algorithm renegotiation.
*
* @throws TransportException if there was an error during key exchange
*/
void doKex()
throws TransportException;
/** @return the version string used by this client to identify itself to an SSH server, e.g. "SSHJ_3_0" */
String getClientVersion();
/** @return the {@link Config} associated with this transport. */
Config getConfig();
/** @return the timeout that is currently set for blocking operations. */
int getTimeoutMs();
/**
* Set a timeout for methods that may block.
*
* @param timeout the timeout in milliseconds
*/
void setTimeoutMs(int timeout);
/**
* @return the interval in seconds at which a heartbeat message is sent to the server
* @deprecated Moved to {@link net.schmizz.keepalive.KeepAlive#getKeepAliveInterval()}. This is accessible through the {@link net.schmizz.sshj.connection.Connection}.
* Scheduled to be removed in 0.12.0
*/
@Deprecated
int getHeartbeatInterval();
/**
* @param interval the interval in seconds, {@code 0} means no hearbeat
* @deprecated Moved to {@link net.schmizz.keepalive.KeepAlive#getKeepAliveInterval()}. This is accessible through the {@link net.schmizz.sshj.connection.Connection}.
* Scheduled to be removed in 0.12.0
*/
@Deprecated
void setHeartbeatInterval(int interval);
/** @return the hostname to which this transport is connected. */
String getRemoteHost();
/** @return the port number on the remote host to which this transport is connected. */
int getRemotePort();
/**
* Returns the version string as sent by the SSH server for identification purposes, e.g. "OpenSSH_$version".
* <p/>
* If the transport has not yet been initialized via {@link #init}, it will be {@code null}.
*
* @return server's version string (may be {@code null})
*/
String getServerVersion();
/** @return the session identifier assigned by server */
byte[] getSessionID();
/** @return the currently active {@link Service} instance. */
Service getService();
/**
* Request a SSH service represented by a {@link Service} instance. A separate call to {@link #setService} is not
* needed.
*
* @param service the SSH service to be requested
*
* @throws TransportException if the request failed for any reason
*/
void reqService(Service service)
throws TransportException;
/**
* Sets the currently active {@link Service}. Handling of non-transport-layer packets is {@link Service#handle
* delegated} to that service.
* <p/>
* For this method to be successful, at least one service request via {@link #reqService} must have been successful
* (not necessarily for the service being set).
*
* @param service (null-ok) the {@link Service}
*/
void setService(Service service);
/** @return whether the transport thinks it is authenticated. */
boolean isAuthenticated();
/**
* Informs this transport that authentication has been completed. This method <strong>must</strong> be called after
* successful authentication, so that delayed compression may become effective if applicable.
*/
void setAuthenticated();
/**
* Sends SSH_MSG_UNIMPLEMENTED in response to the last packet received.
*
* @return the sequence number of the packet sent
*
* @throws TransportException if an error occured sending the packet
*/
long sendUnimplemented()
throws TransportException;
/**
* @return whether this transport is active.
* <p/>
* The transport is considered to be running if it has been initialized without error via {@link #init} and
* has not been disconnected.
*/
boolean isRunning();
/**
* Joins the thread calling this method to the transport's death.
*
* @throws TransportException if the transport dies of an exception
*/
void join()
throws TransportException;
/**
* Joins the thread calling this method to the transport's death.
*
* @throws TransportException if the transport dies of an exception
*/
void join(int timeout, TimeUnit unit)
throws TransportException;
/** Send a disconnection packet with reason as {@link DisconnectReason#BY_APPLICATION}, and closes this transport. */
void disconnect();
/**
* Send a disconnect packet with the given {@link DisconnectReason reason}, and closes this transport.
*
* @param reason reason for disconnecting
*/
void disconnect(DisconnectReason reason);
/**
* Send a disconnect packet with the given {@link DisconnectReason reason} and {@code message}, and closes this
* transport.
*
* @param reason the reason code for this disconnect
* @param message the text message
*/
void disconnect(DisconnectReason reason, String message);
/**
* Write a packet over this transport.
* <p/>
* The {@code payload} {@link SSHPacket} should have 5 bytes free at the beginning to avoid a performance penalty
* associated with making space for header bytes (packet length, padding length).
*
* @param payload the {@link SSHPacket} containing data to send
*
* @return sequence number of the sent packet
*
* @throws TransportException if an error occurred sending the packet
*/
long write(SSHPacket payload)
throws TransportException;
/**
* Specify a {@code listener} that will be notified upon disconnection.
*
* @param listener
*/
void setDisconnectListener(DisconnectListener listener);
/** @return the current disconnect listener. */
DisconnectListener getDisconnectListener();
/**
* Kill the transport in an exceptional way.
*
* @param e The exception that occurred.
*/
void die(Exception e);
}