org.apache.sshd.common.session

Interface Session

All Superinterfaces:

AttributeStore, AutoCloseable, Channel, ChannelListenerManager, Closeable, FactoryManagerHolder, KexFactoryManager, KeyPairProviderHolder, MutableUserHolder, PortForwardingEventListenerManager, PropertyResolver, ReservedSessionMessagesManager, SessionListenerManager, SignatureFactoriesManager, UsernameHolder

All Known Subinterfaces:

ClientSession, ServerSession

All Known Implementing Classes:

AbstractClientSession, AbstractServerSession, AbstractSession, ClientSessionImpl, ServerSessionImpl

public interface Session
extends KexFactoryManager, SessionListenerManager, ReservedSessionMessagesManager, ChannelListenerManager, PortForwardingEventListenerManager, FactoryManagerHolder, PropertyResolver, AttributeStore, Closeable, MutableUserHolder

Represents an SSH session. Note: the associated username for the session may be null/empty if the session is not yet authenticated

Author:

Apache MINA SSHD Project

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	Session.TimeoutStatus Timeout status.

Nested classes/interfaces inherited from interface org.apache.sshd.common.AttributeStore

AttributeStore.AttributeKey<T>

Field Summary

Fields

Modifier and Type	Field and Description
static String	DEFAULT_SSH_VERSION_PREFIX Default prefix expected for the client / server identification string
static String	FALLBACK_SSH_VERSION_PREFIX Backward compatible special prefix
static int	MAX_VERSION_LINE_LENGTH Maximum number of characters for any single line sent as part of the initial handshake - according to RFC 4253 - section 4.2: The maximum length of the string is 255 characters, including the Carriage Return and Line Feed.

Fields inherited from interface org.apache.sshd.common.PropertyResolver

EMPTY

Fields inherited from interface org.apache.sshd.common.Closeable

CLOSE_WAIT_TIMEOUT, DEFAULT_CLOSE_WAIT_TIMEOUT

Method Summary

Modifier and Type	Method and Description
Buffer	createBuffer(byte cmd) Create a new buffer for the specified SSH packet and reserve the needed space (5 bytes) for the packet header.
Buffer	createBuffer(byte cmd, int estimatedSize) Create a new buffer for the specified SSH packet and reserve the needed space (5 bytes) for the packet header.
void	disconnect(int reason, String msg) Send a disconnect packet with the given reason and message.
void	exceptionCaught(Throwable t) Handle any exceptions that occurred on this session.
long	getAuthTimeout()
CipherInformation	getCipherInformation(boolean incoming) Retrieves current cipher information - Note: may change if key re-exchange executed
String	getClientVersion() Retrieve the client version for this session.
CompressionInformation	getCompressionInformation(boolean incoming) Retrieves current compression information - Note: may change if key re-exchange executed
long	getIdleTimeout()
IoSession	getIoSession()
KeyExchange	getKex()
MacInformation	getMacInformation(boolean incoming) Retrieves current MAC information - Note: may change if key re-exchange executed
String	getNegotiatedKexParameter(KexProposalOption paramType) Retrieve one of the negotiated values during the KEX stage
String	getServerVersion() Retrieve the server version for this session.
<T extends Service> T	getService(Class<T> clazz) Get the service of the specified type.
byte[]	getSessionId()
Session.TimeoutStatus	getTimeoutStatus() Check if timeout has occurred.
boolean	isAuthenticated()
static boolean	isValidVersionPrefix(String version)
Buffer	prepareBuffer(byte cmd, Buffer buffer) Prepare a new "clean" buffer while reserving the needed space (5 bytes) for the packet header.
KeyExchangeFuture	reExchangeKeys() Initiate a new key exchange.
Buffer	request(String request, Buffer buffer, long timeout, TimeUnit unit) Send a global request and wait for the response.
void	resetIdleTimeout() Re-start idle timeout timer
IoWriteFuture	sendDebugMessage(boolean display, Object msg, String lang) Sends an SSH_MSG_DEBUG to the peer session
IoWriteFuture	sendIgnoreMessage(byte... data) Sends an SSH_MSG_IGNORE to the peer session
void	setAuthenticated()
void	startService(String name)
IoWriteFuture	writePacket(Buffer buffer) Encode and send the given buffer.
IoWriteFuture	writePacket(Buffer buffer, long timeout, TimeUnit unit) Encode and send the given buffer with the specified timeout.

Methods inherited from interface org.apache.sshd.common.kex.KexFactoryManager

getCipherFactories, getCipherFactoriesNameList, getCipherFactoriesNames, getCompressionFactories, getCompressionFactoriesNameList, getCompressionFactoriesNames, getKeyExchangeFactories, getMacFactories, getMacFactoriesNameList, getMacFactoriesNames, setCipherFactories, setCipherFactoriesNameList, setCipherFactoriesNames, setCipherFactoriesNames, setCompressionFactories, setCompressionFactoriesNameList, setCompressionFactoriesNames, setCompressionFactoriesNames, setKeyExchangeFactories, setMacFactories, setMacFactoriesNameList, setMacFactoriesNames, setMacFactoriesNames

Methods inherited from interface org.apache.sshd.common.keyprovider.KeyPairProviderHolder

getKeyPairProvider, setKeyPairProvider

Methods inherited from interface org.apache.sshd.common.signature.SignatureFactoriesManager

getSignatureFactories, getSignatureFactories, getSignatureFactoriesNameList, getSignatureFactoriesNames, resolveSignatureFactories, setSignatureFactories, setSignatureFactoriesNameList, setSignatureFactoriesNames, setSignatureFactoriesNames

Methods inherited from interface org.apache.sshd.common.session.SessionListenerManager

addSessionListener, getSessionListenerProxy, removeSessionListener

Methods inherited from interface org.apache.sshd.common.session.ReservedSessionMessagesManager

getReservedSessionMessagesHandler, setReservedSessionMessagesHandler

Methods inherited from interface org.apache.sshd.common.channel.ChannelListenerManager

addChannelListener, getChannelListenerProxy, removeChannelListener

Methods inherited from interface org.apache.sshd.common.forward.PortForwardingEventListenerManager

addPortForwardingEventListener, getPortForwardingEventListenerProxy, removePortForwardingEventListener

Methods inherited from interface org.apache.sshd.common.FactoryManagerHolder

getFactoryManager

Methods inherited from interface org.apache.sshd.common.PropertyResolver

getBoolean, getBooleanProperty, getInteger, getIntProperty, getLong, getLongProperty, getObject, getParentPropertyResolver, getProperties, getString, getStringProperty

Methods inherited from interface org.apache.sshd.common.AttributeStore

getAttribute, removeAttribute, resolveAttribute, resolveAttribute, resolveAttribute, resolveAttribute, setAttribute

Methods inherited from interface org.apache.sshd.common.Closeable

addCloseFutureListener, close, close, close, getMaxCloseWaitTime, isClosed, isClosing, isOpen, removeCloseFutureListener

Methods inherited from interface org.apache.sshd.common.auth.MutableUserHolder

setUsername

Methods inherited from interface org.apache.sshd.common.auth.UsernameHolder

getUsername

Field Detail

DEFAULT_SSH_VERSION_PREFIX

static final String DEFAULT_SSH_VERSION_PREFIX

Default prefix expected for the client / server identification string

See Also:

RFC 4253 - section 4.2, Constant Field Values

FALLBACK_SSH_VERSION_PREFIX

static final String FALLBACK_SSH_VERSION_PREFIX

Backward compatible special prefix

See Also:

RFC 4253 - section 5, Constant Field Values

MAX_VERSION_LINE_LENGTH

static final int MAX_VERSION_LINE_LENGTH

Maximum number of characters for any single line sent as part of the initial handshake - according to RFC 4253 - section 4.2:

The maximum length of the string is 255 characters, including the Carriage Return and Line Feed.

See Also:

Constant Field Values

Method Detail

getClientVersion

String getClientVersion()

Retrieve the client version for this session.

Returns:

the client version.

getServerVersion

String getServerVersion()

Retrieve the server version for this session.

Returns:

the server version.

getNegotiatedKexParameter

String getNegotiatedKexParameter(KexProposalOption paramType)

Retrieve one of the negotiated values during the KEX stage

Parameters:

paramType - The request KexProposalOption value - ignored if null

Returns:

The negotiated parameter value - null if invalid parameter or no negotiated value

getCipherInformation

CipherInformation getCipherInformation(boolean incoming)

Retrieves current cipher information - Note: may change if key re-exchange executed

Parameters:

incoming - If true then the cipher for the incoming data, otherwise for the outgoing data

Returns:

The CipherInformation - or null if not negotiated yet.

getCompressionInformation

CompressionInformation getCompressionInformation(boolean incoming)

Retrieves current compression information - Note: may change if key re-exchange executed

Parameters:

incoming - If true then the compression for the incoming data, otherwise for the outgoing data

Returns:

The CompressionInformation - or null if not negotiated yet.

getMacInformation

MacInformation getMacInformation(boolean incoming)

Retrieves current MAC information - Note: may change if key re-exchange executed

Parameters:

incoming - If true then the MAC for the incoming data, otherwise for the outgoing data

Returns:

The MacInformation - or null if not negotiated yet.

createBuffer

Buffer createBuffer(byte cmd)

Create a new buffer for the specified SSH packet and reserve the needed space (5 bytes) for the packet header.

Parameters:

cmd - the SSH command

Returns:

a new buffer ready for write

createBuffer

Buffer createBuffer(byte cmd,
                    int estimatedSize)

Create a new buffer for the specified SSH packet and reserve the needed space (5 bytes) for the packet header.

Parameters:

cmd - The SSH command to initialize the buffer with

estimatedSize - Estimated number of bytes the buffer will hold, 0 if unknown.

Returns:

a new buffer ready for write

See Also:

prepareBuffer(byte, Buffer)

prepareBuffer

Buffer prepareBuffer(byte cmd,
                     Buffer buffer)

Prepare a new "clean" buffer while reserving the needed space (5 bytes) for the packet header.

Parameters:

cmd - The SSH command to initialize the buffer with

buffer - The Buffer instance to initialize

Returns:

The initialized buffer

sendDebugMessage

IoWriteFuture sendDebugMessage(boolean display,
                               Object msg,
                               String lang)
                        throws IOException

Sends an SSH_MSG_DEBUG to the peer session

Parameters:

display - true if OK to display the message at the peer as-is

msg - The message object whose toString() value to be used - if null then the "null" string is sent

lang - The language - null/empty if some pre-agreed default is used

Returns:

An IoWriteFuture that can be used to check when the packet has actually been sent

Throws:

IOException - if an error occurred when encoding sending the packet

See Also:

RFC 4253 - section 11.3

sendIgnoreMessage

IoWriteFuture sendIgnoreMessage(byte... data)
                         throws IOException

Sends an SSH_MSG_IGNORE to the peer session

Parameters:

data - The message data

Returns:

An IoWriteFuture that can be used to check when the packet has actually been sent

Throws:

IOException - if an error occurred when encoding sending the packet

See Also:

RFC 4253 - section 11.2

writePacket

IoWriteFuture writePacket(Buffer buffer)
                   throws IOException

Encode and send the given buffer. The buffer has to have 5 bytes free at the beginning to allow the encoding to take place. Also, the write position of the buffer has to be set to the position of the last byte to write.

Parameters:

buffer - the buffer to encode and send

Returns:

An IoWriteFuture that can be used to check when the packet has actually been sent

Throws:

IOException - if an error occurred when encoding sending the packet

writePacket

IoWriteFuture writePacket(Buffer buffer,
                          long timeout,
                          TimeUnit unit)
                   throws IOException

Encode and send the given buffer with the specified timeout. If the buffer could not be written before the timeout elapses, the returned IoWriteFuture will be set with a TimeoutException exception to indicate a timeout.

Parameters:

buffer - the buffer to encode and spend

timeout - the timeout

unit - the time unit of the timeout parameter

Returns:

a future that can be used to check when the packet has actually been sent

Throws:

IOException - if an error occurred when encoding sending the packet

request

Buffer request(String request,
               Buffer buffer,
               long timeout,
               TimeUnit unit)
        throws IOException

Send a global request and wait for the response. This must only be used when sending a SSH_MSG_GLOBAL_REQUEST with a result expected, else it will time out

Parameters:

request - the request name - used mainly for logging and debugging

buffer - the buffer containing the global request

timeout - The number of time units to wait - must be positive

unit - The TimeUnit to wait for the response

Returns:

the return buffer if the request was successful, null otherwise.

Throws:

IOException - if an error occurred when encoding sending the packet

exceptionCaught

void exceptionCaught(Throwable t)

Handle any exceptions that occurred on this session. The session will be closed and a disconnect packet will be sent before if the given exception is an SshException with a positive error code

Parameters:

t - the exception to process

reExchangeKeys

KeyExchangeFuture reExchangeKeys()
                          throws IOException

Initiate a new key exchange.

Returns:

A KeyExchangeFuture for awaiting the completion of the exchange

Throws:

IOException - If failed to request keys re-negotiation

getService

<T extends Service> T getService(Class<T> clazz)

Get the service of the specified type. If the service is not of the specified class, an IllegalStateException will be thrown.

Type Parameters:

T - The generic Service type

Parameters:

clazz - The service class

Returns:

The service instance

Throws:

IllegalStateException - If failed to find a matching service

getIoSession

IoSession getIoSession()

Returns:

the IoSession associated to this session

resetIdleTimeout

void resetIdleTimeout()

Re-start idle timeout timer

getTimeoutStatus

Session.TimeoutStatus getTimeoutStatus()

Check if timeout has occurred.

Returns:

the timeout status, never null

getAuthTimeout

long getAuthTimeout()

Returns:

Timeout value in milliseconds for authentication stage

getIdleTimeout

long getIdleTimeout()

Returns:

Timeout value in milliseconds for communication

isAuthenticated

boolean isAuthenticated()

setAuthenticated

void setAuthenticated()
               throws IOException

Throws:

IOException

getSessionId

byte[] getSessionId()

Returns:

The established session identifier - null if not yet established

getKex

KeyExchange getKex()

disconnect

void disconnect(int reason,
                String msg)
         throws IOException

Send a disconnect packet with the given reason and message. Once the packet has been sent, the session will be closed asynchronously.

Parameters:

reason - the reason code for this disconnect

msg - the text message

Throws:

IOException - if an error occurred sending the packet

startService

void startService(String name)
           throws Exception

Parameters:

name - Service name

Throws:

Exception - If failed to start it

isValidVersionPrefix

static boolean isValidVersionPrefix(String version)

Parameters:

version - The reported client/server version

Returns:

true if version not empty and starts with either "SSH-2.0-" or "SSH-1.99-"