org.snmp4j.transport
Class TLSTM

java.lang.Object
  extended by org.snmp4j.transport.AbstractTransportMapping<TcpAddress>
      extended by org.snmp4j.transport.TcpTransportMapping
          extended by org.snmp4j.transport.TLSTM
All Implemented Interfaces:
ConnectionOrientedTransportMapping<TcpAddress>, TransportMapping<TcpAddress>

public class TLSTM
extends TcpTransportMapping

The TLSTM implements the Transport Layer Security Transport Mapping (TLS-TM) as defined by RFC 5953 with the new IO API and SSLEngine.

It uses a single thread for processing incoming and outgoing messages. The thread is started when the listen method is called, or when an outgoing request is sent using the sendMessage method.

Since:
2.0
Version:
2.0
Author:
Frank Fock

Nested Class Summary
protected  class TLSTM.DefaultSSLEngineConfiguration
           
protected  class TLSTM.TlsTrustManager
           
 
Field Summary
 
Fields inherited from class org.snmp4j.transport.TcpTransportMapping
tcpAddress
 
Fields inherited from class org.snmp4j.transport.AbstractTransportMapping
asyncMsgProcessingSupported, maxInboundMessageSize, transportListener
 
Constructor Summary
TLSTM()
          Creates a default TCP transport mapping with the server for incoming messages disabled.
TLSTM(TlsAddress address)
          Creates a TLS transport mapping with the server for incoming messages bind to the given address.
TLSTM(TlsTmSecurityCallback<java.security.cert.X509Certificate> securityCallback, TlsAddress serverAddress)
          Creates a TLS transport mapping that binds to the given address (interface) on the local host.
TLSTM(TlsTmSecurityCallback<java.security.cert.X509Certificate> securityCallback, TlsAddress serverAddress, CounterSupport counterSupport)
          Creates a TLS transport mapping that binds to the given address (interface) on the local host.
 
Method Summary
 void close()
          Closes all open sockets and stops the internal server thread that processes messages.
 boolean close(TcpAddress remoteAddress)
          Closes a connection to the supplied remote address, if it is open.
 long getConnectionTimeout()
          Gets the connection timeout.
 CounterSupport getCounterSupport()
           
static OctetString getFingerprint(java.security.cert.X509Certificate cert)
           
 java.lang.String getKeyStore()
           
 java.lang.String getKeyStorePassword()
           
 java.lang.String getLocalCertificateAlias()
           
 int getMaxInboundMessageSize()
          Gets the inbound buffer size for incoming requests.
 MessageLengthDecoder getMessageLengthDecoder()
          Returns the MessageLengthDecoder used by this transport mapping.
 TlsTmSecurityCallback<java.security.cert.X509Certificate> getSecurityCallback()
           
static java.lang.Object getSubjAltName(java.util.Collection<java.util.List<?>> subjAltNames, int type)
           
 java.lang.Class<? extends Address> getSupportedAddressClass()
          Gets the Address class that is supported by this transport mapping.
 java.lang.String getThreadName()
          Returns the name of the listen thread.
 boolean isListening()
          Returns true if the transport mapping is listening for incoming messages.
 boolean isServerEnabled()
          Checks whether a server for incoming requests is enabled.
 void listen()
          Listen for incoming and outgoing requests.
 void sendMessage(TcpAddress address, byte[] message, TransportStateReference tmStateReference)
          Sends a SNMP message to the supplied address.
 void setConnectionTimeout(long connectionTimeout)
          Sets the connection timeout.
 void setKeyStore(java.lang.String keyStore)
           
 void setKeyStorePassword(java.lang.String keyStorePassword)
           
 void setLocalCertificateAlias(java.lang.String localCertificateAlias)
          Sets the certificate alias used for client and server authentication by this TLSTM.
 void setMaxInboundMessageSize(int maxInboundMessageSize)
          Sets the maximum buffer size for incoming requests.
 void setMessageLengthDecoder(MessageLengthDecoder messageLengthDecoder)
          Sets the MessageLengthDecoder that decodes the total message length from the header of a message.
 void setSecurityCallback(TlsTmSecurityCallback<java.security.cert.X509Certificate> securityCallback)
           
 void setServerEnabled(boolean serverEnabled)
          Sets whether a server for incoming requests should be created when the transport is set into listen state.
protected  void setSocketOptions(java.net.ServerSocket serverSocket)
          Sets optional server socket options.
 void setThreadName(java.lang.String name)
          Sets the name of the listen thread for this UDP transport mapping.
 
Methods inherited from class org.snmp4j.transport.TcpTransportMapping
addTransportStateListener, fireConnectionStateChanged, getAddress, getListenAddress, removeTransportStateListener
 
Methods inherited from class org.snmp4j.transport.AbstractTransportMapping
addTransportListener, fireProcessMessage, isAsyncMsgProcessingSupported, removeTransportListener, setAsyncMsgProcessingSupported
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface org.snmp4j.TransportMapping
addTransportListener, removeTransportListener
 

Constructor Detail

TLSTM

public TLSTM()
      throws java.net.UnknownHostException
Creates a default TCP transport mapping with the server for incoming messages disabled.

Throws:
java.net.UnknownHostException - if the local host cannot be determined.

TLSTM

public TLSTM(TlsAddress address)
      throws java.io.IOException
Creates a TLS transport mapping with the server for incoming messages bind to the given address. The securityCallback needs to be specified before listen() is called.

Throws:
java.io.IOException - on failure of binding a local port.

TLSTM

public TLSTM(TlsTmSecurityCallback<java.security.cert.X509Certificate> securityCallback,
             TlsAddress serverAddress)
      throws java.io.IOException
Creates a TLS transport mapping that binds to the given address (interface) on the local host.

Parameters:
securityCallback - a security name callback to resolve X509 certificates to tmSecurityNames.
serverAddress - the TcpAddress instance that describes the server address to listen on incoming connection requests.
Throws:
java.io.IOException - if the given address cannot be bound.

TLSTM

public TLSTM(TlsTmSecurityCallback<java.security.cert.X509Certificate> securityCallback,
             TlsAddress serverAddress,
             CounterSupport counterSupport)
      throws java.io.IOException
Creates a TLS transport mapping that binds to the given address (interface) on the local host.

Parameters:
securityCallback - a security name callback to resolve X509 certificates to tmSecurityNames.
serverAddress - the TcpAddress instance that describes the server address to listen on incoming connection requests.
counterSupport - The CounterSupport instance to be used to count events created by this TLSTM instance. To get a default instance, use CounterSupport.getInstance().
Throws:
java.io.IOException - if the given address cannot be bound.
Method Detail

getLocalCertificateAlias

public java.lang.String getLocalCertificateAlias()

getKeyStore

public java.lang.String getKeyStore()

setKeyStore

public void setKeyStore(java.lang.String keyStore)

getKeyStorePassword

public java.lang.String getKeyStorePassword()

setKeyStorePassword

public void setKeyStorePassword(java.lang.String keyStorePassword)

setLocalCertificateAlias

public void setLocalCertificateAlias(java.lang.String localCertificateAlias)
Sets the certificate alias used for client and server authentication by this TLSTM. Setting this property to a value other than null filters out any certificates which are not in the chain of the given alias.

Parameters:
localCertificateAlias - a certificate alias which filters a single certification chain from the javax.net.ssl.keyStore key store to be used to authenticate this TLS transport mapping. If null no filtering appears, which could lead to more than a single chain available for authentication by the peer, which would violate the TLSTM standard requirements.

getCounterSupport

public CounterSupport getCounterSupport()

getSupportedAddressClass

public java.lang.Class<? extends Address> getSupportedAddressClass()
Description copied from interface: TransportMapping
Gets the Address class that is supported by this transport mapping.

Specified by:
getSupportedAddressClass in interface TransportMapping<TcpAddress>
Overrides:
getSupportedAddressClass in class TcpTransportMapping
Returns:
a subclass of Address.

getSecurityCallback

public TlsTmSecurityCallback<java.security.cert.X509Certificate> getSecurityCallback()

setSecurityCallback

public void setSecurityCallback(TlsTmSecurityCallback<java.security.cert.X509Certificate> securityCallback)

listen

public void listen()
            throws java.io.IOException
Listen for incoming and outgoing requests. If the serverEnabled member is false the server for incoming requests is not started. This starts the internal server thread that processes messages.

Specified by:
listen in interface TransportMapping<TcpAddress>
Specified by:
listen in class TcpTransportMapping
Throws:
java.net.SocketException - when the transport is already listening for incoming/outgoing messages.
java.io.IOException

setThreadName

public void setThreadName(java.lang.String name)
Sets the name of the listen thread for this UDP transport mapping. This method has no effect, if called before listen() has been called for this transport mapping.

Parameters:
name - the new thread name.
Since:
1.6

getThreadName

public java.lang.String getThreadName()
Returns the name of the listen thread.

Returns:
the thread name if in listening mode, otherwise null.
Since:
1.6

close

public void close()
Closes all open sockets and stops the internal server thread that processes messages.

Specified by:
close in interface TransportMapping<TcpAddress>
Specified by:
close in class TcpTransportMapping

close

public boolean close(TcpAddress remoteAddress)
              throws java.io.IOException
Closes a connection to the supplied remote address, if it is open. This method is particularly useful when not using a timeout for remote connections.

Parameters:
remoteAddress - the address of the peer socket.
Returns:
true if the connection has been closed and false if there was nothing to close.
Throws:
java.io.IOException - if the remote address cannot be closed due to an IO exception.
Since:
1.7.1

sendMessage

public void sendMessage(TcpAddress address,
                        byte[] message,
                        TransportStateReference tmStateReference)
                 throws java.io.IOException
Sends a SNMP message to the supplied address.

Specified by:
sendMessage in interface TransportMapping<TcpAddress>
Specified by:
sendMessage in class TcpTransportMapping
Parameters:
address - an TcpAddress. A ClassCastException is thrown if address is not a TcpAddress instance.
message - byte[] the message to sent.
tmStateReference - the (optional) transport model state reference as defined by RFC 5590 section 6.1.
Throws:
java.io.IOException

getConnectionTimeout

public long getConnectionTimeout()
Gets the connection timeout. This timeout specifies the time a connection may be idle before it is closed.

Returns:
long the idle timeout in milliseconds.

setConnectionTimeout

public void setConnectionTimeout(long connectionTimeout)
Sets the connection timeout. This timeout specifies the time a connection may be idle before it is closed.

Specified by:
setConnectionTimeout in interface ConnectionOrientedTransportMapping<TcpAddress>
Specified by:
setConnectionTimeout in class TcpTransportMapping
Parameters:
connectionTimeout - the idle timeout in milliseconds. A zero or negative value will disable any timeout and connections opened by this transport mapping will stay opened until they are explicitly closed.

isServerEnabled

public boolean isServerEnabled()
Checks whether a server for incoming requests is enabled.

Returns:
boolean

getMessageLengthDecoder

public MessageLengthDecoder getMessageLengthDecoder()
Description copied from class: TcpTransportMapping
Returns the MessageLengthDecoder used by this transport mapping.

Specified by:
getMessageLengthDecoder in interface ConnectionOrientedTransportMapping<TcpAddress>
Specified by:
getMessageLengthDecoder in class TcpTransportMapping
Returns:
a MessageLengthDecoder instance.

setServerEnabled

public void setServerEnabled(boolean serverEnabled)
Sets whether a server for incoming requests should be created when the transport is set into listen state. Setting this value has no effect until the listen() method is called (if the transport is already listening, close() has to be called before).

Parameters:
serverEnabled - if true if the transport will listens for incoming requests after listen() has been called.

setMessageLengthDecoder

public void setMessageLengthDecoder(MessageLengthDecoder messageLengthDecoder)
Description copied from class: TcpTransportMapping
Sets the MessageLengthDecoder that decodes the total message length from the header of a message.

Specified by:
setMessageLengthDecoder in interface ConnectionOrientedTransportMapping<TcpAddress>
Specified by:
setMessageLengthDecoder in class TcpTransportMapping
Parameters:
messageLengthDecoder - a MessageLengthDecoder instance.

getMaxInboundMessageSize

public int getMaxInboundMessageSize()
Gets the inbound buffer size for incoming requests. When SNMP packets are received that are longer than this maximum size, the messages will be silently dropped and the connection will be closed.

Specified by:
getMaxInboundMessageSize in interface TransportMapping<TcpAddress>
Overrides:
getMaxInboundMessageSize in class AbstractTransportMapping<TcpAddress>
Returns:
the maximum inbound buffer size in bytes.

setMaxInboundMessageSize

public void setMaxInboundMessageSize(int maxInboundMessageSize)
Sets the maximum buffer size for incoming requests. When SNMP packets are received that are longer than this maximum size, the messages will be silently dropped and the connection will be closed.

Parameters:
maxInboundMessageSize - the length of the inbound buffer in bytes.

isListening

public boolean isListening()
Description copied from interface: TransportMapping
Returns true if the transport mapping is listening for incoming messages. For connection oriented transport mappings this is a prerequisite to be able to send SNMP messages. For connectionless transport mappings it is a prerequisite to be able to receive responses.

Returns:
true if this transport mapping is listening for messages.

getFingerprint

public static OctetString getFingerprint(java.security.cert.X509Certificate cert)

getSubjAltName

public static java.lang.Object getSubjAltName(java.util.Collection<java.util.List<?>> subjAltNames,
                                              int type)

setSocketOptions

protected void setSocketOptions(java.net.ServerSocket serverSocket)
Sets optional server socket options. The default implementation does nothing.

Parameters:
serverSocket - the ServerSocket to apply additional non-default options.

Copyright 2005-2011 Frank Fock (SNMP4J.org)

Copyright © 2011 SNMP4J.org. All Rights Reserved.