org.eclipse.californium.scandium

Class DTLSConnector

java.lang.Object

org.eclipse.californium.scandium.DTLSConnector

All Implemented Interfaces:

org.eclipse.californium.elements.Connector, RecordLayer

Direct Known Subclasses:

DtlsClusterConnector

public class DTLSConnector
extends Object
implements org.eclipse.californium.elements.Connector, RecordLayer

A Connector using Datagram TLS (DTLS) as specified in RFC 6347 for securing data exchanged between networked clients and a server application. Note: using IPv6 interfaces with multiple addresses including permanent and temporary (with potentially several different prefixes) currently causes issues on the server side. The outgoing traffic in response to incoming may select a different source address than the incoming destination address. To overcome this, please ensure that the 'any address' is not used on the server side and a separate Connector is created for each address to receive incoming traffic.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
protected class	DTLSConnector.Worker A worker thread for continuously doing repetitive tasks.

Field Summary

Fields

Modifier and Type	Field and Description
protected DtlsConnectorConfig	config all the configuration options for the DTLS connector
protected ConnectionIdGenerator	connectionIdGenerator Configure connection id generator.
protected DtlsHealth	health
protected int	inboundDatagramBufferSize
static String	KEY_TLS_SERVER_HOST_NAME The EndpointContext key used to store the host name indicated by a client in an SNI hello extension.
protected ScheduledExecutorService	timer The timer daemon to schedule retransmissions.

Fields inherited from interface org.eclipse.californium.scandium.dtls.RecordLayer

DEFAULT_ETH_MTU, DEFAULT_IPV4_MTU, DEFAULT_IPV6_MTU, IPV4_HEADER_LENGTH, IPV6_HEADER_LENGTH, MAX_MTU

Constructor Summary

Constructors

Modifier	Constructor and Description
	DTLSConnector(DtlsConnectorConfig configuration) Creates a DTLS connector from a given configuration object using the standard in-memory ConnectionStore.
protected	DTLSConnector(DtlsConnectorConfig configuration, ResumptionSupportingConnectionStore connectionStore) Creates a DTLS connector for a given set of configuration options.
	DTLSConnector(DtlsConnectorConfig configuration, SessionCache sessionCache) Creates a DTLS connector for a given set of configuration options.

Method Summary

Methods

Modifier and Type	Method and Description
void	clearConnectionState() Clears all connection state this connector maintains for peers.
void	close(InetSocketAddress peerAddress) Closes a connection with a given peer.
protected static ResumptionSupportingConnectionStore	createConnectionStore(DtlsConnectorConfig configuration, SessionCache sessionCache) Create and initialize default connection store.
protected DtlsHealth	createDefaultHealthHandler(DtlsConnectorConfig configuration) Create default health handler.
void	destroy() Destroys the connector.
void	dropReceivedRecord(Record record) Report dropped record
void	forceResumeAllSessions() Marks all established sessions currently maintained by this connector to be resumed by means of an abbreviated handshake the next time a message is being sent to the corresponding peer using send(RawData).
void	forceResumeSessionFor(InetSocketAddress peer) Force connector to an abbreviated handshake.
InetSocketAddress	getAddress() Gets the address this connector is bound to.
int	getMaxDatagramSize(boolean ipv6) Gets the maximum size of a UDP datagram that can be sent to this session's peer without IP fragmentation.
int	getMaximumFragmentLength(InetSocketAddress peer) Gets the maximum amount of unencrypted payload data that can be sent to a given peer in a single DTLS record.
int	getMaximumTransmissionUnit() Deprecated. use getMaxDatagramSize(boolean) instead
String	getProtocol()
DTLSSession	getSessionByAddress(InetSocketAddress address) Returns the DTLSSession related to the given peer address.
protected void	init(InetSocketAddress bindAddress, DatagramSocket socket, Integer mtu) Initialize socket ad start connector.
boolean	isRunning() Checks if this connector is running.
protected void	onInitializeHandshaker(Handshaker handshaker) Called after initialization of new create handshaker.
protected void	processDatagram(DatagramPacket packet) Deprecated. use processDatagram(DatagramPacket, InetSocketAddress)
protected void	processDatagram(DatagramPacket packet, InetSocketAddress router) Process received datagram.
void	processRecord(Record record, Connection connection) Process received record.
protected void	receiveNextDatagramFromNetwork(DatagramPacket packet) Receive the next datagram from network.
void	send(org.eclipse.californium.elements.RawData message)
void	sendFlight(List<DatagramPacket> datagrams) Sends a set of UDP datagrams containing DTLS records with handshake messages to a peer.
protected void	sendNextDatagramOverNetwork(DatagramPacket datagramPacket)
protected void	sendRecord(Record record)
void	setAlertHandler(AlertHandler handler) Sets a handler to call back if an alert message is received from a peer.
void	setEndpointContextMatcher(org.eclipse.californium.elements.EndpointContextMatcher endpointContextMatcher)
void	setExecutor(ExecutorService executor) Sets the executor to be used for processing records.
void	setRawDataReceiver(org.eclipse.californium.elements.RawDataChannel messageHandler)
void	start()
protected void	start(InetSocketAddress bindAddress) Start connector.
Future<Void>	startDropConnectionsForPrincipal(Principal principal) Start to terminate connections related to the provided principals.
Future<Void>	startForEach(org.eclipse.californium.elements.util.LeastRecentlyUsedCache.Predicate<Connection> handler) Start applying provided handler to all connections.
Future<Void>	startTerminateConnectionsForPrincipal(org.eclipse.californium.elements.util.LeastRecentlyUsedCache.Predicate<Principal> principalHandler) Start to terminate connections applying the provided handler to the principals of all connections.
Future<Void>	startTerminateConnectionsForPrincipal(org.eclipse.californium.elements.util.LeastRecentlyUsedCache.Predicate<Principal> principalHandler, boolean removeFromSessionCache) Start to terminate connections applying the provided handler to the principals of all connections.
void	stop()
String	toString()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

KEY_TLS_SERVER_HOST_NAME

public static final String KEY_TLS_SERVER_HOST_NAME

The EndpointContext key used to store the host name indicated by a client in an SNI hello extension.

See Also:

Constant Field Values

config

protected final DtlsConnectorConfig config

all the configuration options for the DTLS connector

health

protected final DtlsHealth health

connectionIdGenerator

protected final ConnectionIdGenerator connectionIdGenerator

Configure connection id generator. May be null, if connection id should not be supported.

inboundDatagramBufferSize

protected int inboundDatagramBufferSize

timer

protected ScheduledExecutorService timer

The timer daemon to schedule retransmissions.

Constructor Detail

DTLSConnector

public DTLSConnector(DtlsConnectorConfig configuration)

Creates a DTLS connector from a given configuration object using the standard in-memory ConnectionStore.

Parameters:

configuration - the configuration options

Throws:

NullPointerException - if the configuration is null

DTLSConnector

public DTLSConnector(DtlsConnectorConfig configuration,
             SessionCache sessionCache)

Creates a DTLS connector for a given set of configuration options.

Parameters:

configuration - The configuration options.

sessionCache - An (optional) cache for DTLSSession objects that can be used for persisting and/or sharing of session state among multiple instances of DTLSConnector. Whenever a handshake with a client is finished the negotiated session is put to this cache. Similarly, whenever a client wants to perform an abbreviated handshake based on an existing session the connection store will try to retrieve the session from this cache if it is not available from the connection store's in-memory (first-level) cache.

Throws:

NullPointerException - if the configuration is null.

DTLSConnector

protected DTLSConnector(DtlsConnectorConfig configuration,
             ResumptionSupportingConnectionStore connectionStore)

Creates a DTLS connector for a given set of configuration options.

The connection store must use the same connection id generator as configured in the provided configuration. The current implementation synchronize on the connection store, therefore it is important not to use the connection store within a different synchronization scope.

Parameters:

configuration - The configuration options.

connectionStore - The registry to use for managing connections to peers.

Throws:

NullPointerException - if any of the parameters is null.

IllegalArgumentException - if the connection store uses a different cid generator than the configuration.

Method Detail

createConnectionStore

protected static ResumptionSupportingConnectionStore createConnectionStore(DtlsConnectorConfig configuration,
                                                        SessionCache sessionCache)

Create and initialize default connection store.

Parameters:

configuration - configuration for initialization

sessionCache - An (optional) cache for DTLSSession objects that can be used for persisting and/or sharing of session state among multiple instances of DTLSConnector. Whenever a handshake with a client is finished the negotiated session is put to this cache. Similarly, whenever a client wants to perform an abbreviated handshake based on an existing session the connection store will try to retrieve the session from this cache if it is not available from the connection store's in-memory (first-level) cache.

Returns:

connection store

Since:

2.5

createDefaultHealthHandler

protected DtlsHealth createDefaultHealthHandler(DtlsConnectorConfig configuration)

Create default health handler.

Parameters:

configuration - configuration

Returns:

default health handler.

Since:

2.5

onInitializeHandshaker

protected void onInitializeHandshaker(Handshaker handshaker)

Called after initialization of new create handshaker. Intended to be used for subclass specific handshaker initialization.

Parameters:

handshaker - new create handshaker

setExecutor

public final void setExecutor(ExecutorService executor)

Sets the executor to be used for processing records.

If this property is not set before invoking the start method, a new ExecutorService is created with a thread pool of size. This helps with performing multiple handshakes in parallel, in particular if the key exchange requires a look up of identities, e.g. in a database or using a web service.

If this method is used to set an executor, the executor will not be shut down by the stop method.

Parameters:

executor - The executor.

Throws:

IllegalStateException - if a new executor is set and this connector is already running.

close

public final void close(InetSocketAddress peerAddress)

Closes a connection with a given peer. The connection is gracefully shut down, i.e. a final CLOSE_NOTIFY alert message is sent to the peer prior to removing all session state.

Parameters:

peerAddress - the address of the peer to close the connection to

Throws:

IllegalStateException - if executor cache is exceeded.

start

public final void start()
                 throws IOException

Specified by:

start in interface org.eclipse.californium.elements.Connector

Throws:

IOException

start

protected void start(InetSocketAddress bindAddress)
              throws IOException

Start connector.

Parameters:

bindAddress - address to bind socket.

Throws:

IOException - I/O error

init

protected void init(InetSocketAddress bindAddress,
        DatagramSocket socket,
        Integer mtu)
             throws IOException

Initialize socket ad start connector.

Parameters:

bindAddress - address to bind socket

socket - socket

mtu - mtu of socket, or null, if socket implementation doesn't use a special mtu.

Throws:

IOException - I/O error

Since:

2.1

forceResumeSessionFor

public final void forceResumeSessionFor(InetSocketAddress peer)

Force connector to an abbreviated handshake. See RFC 5246. The abbreviated handshake will be done next time data will be sent with send(RawData).

Parameters:

peer - the peer for which we will force to do an abbreviated handshake

forceResumeAllSessions

public final void forceResumeAllSessions()

Marks all established sessions currently maintained by this connector to be resumed by means of an abbreviated handshake the next time a message is being sent to the corresponding peer using send(RawData).

This method's execution time is proportional to the number of connections this connector maintains.

clearConnectionState

public final void clearConnectionState()

Clears all connection state this connector maintains for peers.

After invoking this method a new connection needs to be established with a peer using a full handshake in order to exchange messages with it again.

stop

public void stop()

Specified by:

stop in interface org.eclipse.californium.elements.Connector

destroy

public void destroy()

Destroys the connector.

This method invokes stop() and clears the ConnectionStore used to manage connections to peers. Thus, contrary to the behavior specified for Connector.destroy(), this connector can be re-started using the start() method but subsequent invocations of the send(RawData) method will trigger the establishment of a new connection to the corresponding peer.

Specified by:

destroy in interface org.eclipse.californium.elements.Connector

startDropConnectionsForPrincipal

public Future<Void> startDropConnectionsForPrincipal(Principal principal)

Start to terminate connections related to the provided principals. Note: if SessionCache is used, it's not possible to remove a cache entry, if no related connection is in the connection store.

Parameters:

principal - principal, which connections are to terminate

Returns:

future to cancel or wait for completion

startTerminateConnectionsForPrincipal

public Future<Void> startTerminateConnectionsForPrincipal(org.eclipse.californium.elements.util.LeastRecentlyUsedCache.Predicate<Principal> principalHandler)

Start to terminate connections applying the provided handler to the principals of all connections. Note: if SessionCache is used, it's not possible to remove a cache entry, if no related connection is in the connection store. All available connections will be removed from that session cache as well.

Parameters:

principalHandler - handler to be called within the serial execution of the related connection. If true is returned, the related connection is terminated and the session is removed from the session cache.

Returns:

future to cancel or wait for completion

See Also:

startTerminateConnectionsForPrincipal(org.eclipse.californium.elements.util.LeastRecentlyUsedCache.Predicate, boolean)

startTerminateConnectionsForPrincipal

public Future<Void> startTerminateConnectionsForPrincipal(org.eclipse.californium.elements.util.LeastRecentlyUsedCache.Predicate<Principal> principalHandler,
                                                 boolean removeFromSessionCache)

Start to terminate connections applying the provided handler to the principals of all connections. Note: if SessionCache is used, it's not possible to remove a cache entry, if no related connection is in the connection store.

Parameters:

principalHandler - handler to be called within the serial execution of the related connection. If true is returned, the related connection is terminated

removeFromSessionCache - true if the session of the connection should be removed from the session cache, false, otherwise

Returns:

future to cancel or wait for completion

Since:

2.6

See Also:

startTerminateConnectionsForPrincipal(org.eclipse.californium.elements.util.LeastRecentlyUsedCache.Predicate)

startForEach

public Future<Void> startForEach(org.eclipse.californium.elements.util.LeastRecentlyUsedCache.Predicate<Connection> handler)

Start applying provided handler to all connections.

Parameters:

handler - handler to be called within the serial execution of the passed in connection. If true is returned, iterating is stopped.

Returns:

future to cancel or wait for completion

receiveNextDatagramFromNetwork

protected void receiveNextDatagramFromNetwork(DatagramPacket packet)
                                       throws IOException

Receive the next datagram from network. Potentially called by multiple threads.

Parameters:

packet - datagram the be read from network

Throws:

IOException - if anio- error occurred

See Also:

processDatagram(DatagramPacket)

processDatagram

@Deprecated
protected void processDatagram(DatagramPacket packet)

Deprecated. use processDatagram(DatagramPacket, InetSocketAddress)

Process received datagram. Potentially called by multiple threads.

Parameters:

packet - datagram filled with the received data and source address.

processDatagram

protected void processDatagram(DatagramPacket packet,
                   InetSocketAddress router)

Process received datagram. Potentially called by multiple threads.

Parameters:

packet - received message

router - router address, null, if no router is used.

Since:

2.5

processRecord

public void processRecord(Record record,
                 Connection connection)

Process received record.

Specified by:

processRecord in interface RecordLayer

Parameters:

record - received record.

connection - connection to process record.

send

public void send(org.eclipse.californium.elements.RawData message)

Specified by:

send in interface org.eclipse.californium.elements.Connector

getSessionByAddress

public final DTLSSession getSessionByAddress(InetSocketAddress address)

Returns the DTLSSession related to the given peer address.

Parameters:

address - the peer address

Returns:

the DTLSSession or null if no session found.

dropReceivedRecord

public void dropReceivedRecord(Record record)

Description copied from interface: RecordLayer

Report dropped record

Specified by:

dropReceivedRecord in interface RecordLayer

Parameters:

record - dropped record

getMaxDatagramSize

public int getMaxDatagramSize(boolean ipv6)

Description copied from interface: RecordLayer

Gets the maximum size of a UDP datagram that can be sent to this session's peer without IP fragmentation.

Specified by:

getMaxDatagramSize in interface RecordLayer

Parameters:

ipv6 - true, IPv6 destination, false, IPv4 destination

Returns:

the maximum datagram size in bytes

sendFlight

public void sendFlight(List<DatagramPacket> datagrams)
                throws IOException

Description copied from interface: RecordLayer

Sends a set of UDP datagrams containing DTLS records with handshake messages to a peer.

The set is sent as a whole. In particular this means that all datagrams will be re-transmitted in case of a missing acknowledgement from the peer.

Specified by:

sendFlight in interface RecordLayer

Parameters:

datagrams - list of UDP datagrams containing DTLS records to send.

Throws:

IOException - if an io error occurs

sendRecord

protected void sendRecord(Record record)
                   throws IOException

Throws:

IOException

sendNextDatagramOverNetwork

protected void sendNextDatagramOverNetwork(DatagramPacket datagramPacket)
                                    throws IOException

Throws:

IOException

getMaximumTransmissionUnit

@Deprecated
public final int getMaximumTransmissionUnit()

Deprecated. use getMaxDatagramSize(boolean) instead

Gets the MTU value of the network interface this connector is bound to.

Applications may use this property to determine the maximum length of application layer data that can be sent using this connector without requiring IP fragmentation.

The value returned will be 0 if this connector is not running or the network interface this connector is bound to does not provide an MTU value.

Returns:

the MTU provided by the network interface

getMaximumFragmentLength

public final int getMaximumFragmentLength(InetSocketAddress peer)

Gets the maximum amount of unencrypted payload data that can be sent to a given peer in a single DTLS record.

The value of this property serves as an upper boundary for the DTLSPlaintext.length field defined in DTLS 1.2 spec, Section 4.3.1. This means that an application can assume that any message containing at most as many bytes as indicated by this method, will be delivered to the peer in a single unfragmented datagram.

The value returned by this method considers the current write state of the connection to the peer and any potential ciphertext expansion introduced by this cipher suite used to secure the connection. However, if no connection exists to the peer, the value returned is determined as follows:

   maxFragmentLength = network interface's Maximum Transmission Unit
                     - IP header length (20 bytes IPv4, 120 IPv6)
                     - UDP header length (8 bytes)
                     - DTLS record header length (13 bytes)
                     - DTLS message header length (12 bytes)
 

Parameters:

peer - the address of the remote endpoint

Returns:

the maximum length in bytes

getAddress

public final InetSocketAddress getAddress()

Gets the address this connector is bound to.

Specified by:

getAddress in interface org.eclipse.californium.elements.Connector

Returns:

the IP address and port this connector is bound to or configured to bind to

isRunning

public final boolean isRunning()

Checks if this connector is running.

Specified by:

isRunning in interface RecordLayer

Returns:

true if running.

setRawDataReceiver

public void setRawDataReceiver(org.eclipse.californium.elements.RawDataChannel messageHandler)

Specified by:

setRawDataReceiver in interface org.eclipse.californium.elements.Connector

setEndpointContextMatcher

public void setEndpointContextMatcher(org.eclipse.californium.elements.EndpointContextMatcher endpointContextMatcher)

Specified by:

setEndpointContextMatcher in interface org.eclipse.californium.elements.Connector

setAlertHandler

public final void setAlertHandler(AlertHandler handler)

Sets a handler to call back if an alert message is received from a peer.

Setting a handler using this method is useful to be notified when a peer closes an existing connection, i.e. when the alert message has not been received during a handshake but after the connection has been established.

The handler can be set (and changed) at any time, either before the connector has been started or when the connector is already running.

Application code interested in being notified when a particular message cannot be sent, e.g. due to a failing DTLS handshake that has been triggered as part of sending the message, should instead register a org.eclipse.californium.core.coap.MessageObserver on the message and implement its onSendError method accordingly.

Parameters:

handler - The handler to notify.

getProtocol

public String getProtocol()

Specified by:

getProtocol in interface org.eclipse.californium.elements.Connector

toString

public String toString()

Overrides:

toString in class Object