org.eclipse.californium.scandium.dtls

Class Handshaker

java.lang.Object

org.eclipse.californium.scandium.dtls.Handshaker

All Implemented Interfaces:

Destroyable

Direct Known Subclasses:

ClientHandshaker, ServerHandshaker

public abstract class Handshaker
extends Object
implements Destroyable

A base class for the DTLS handshake protocol. Contains all functionality and fields needed by all types of handshakers.

Field Summary

Fields

Modifier and Type	Field and Description
protected AdvancedPskStore	advancedPskStore Used to retrieve identity/pre-shared-key for a given destination
protected List<X509Certificate>	certificateChain The chain of certificates asserting this handshaker's identity
protected boolean	certificateVerfied Indicates, that the certificate or public key verification has finished.
protected NewAdvancedCertificateVerifier	certificateVerifier The logic in charge of verifying the chain of certificates asserting this handshaker's identity
protected Random	clientRandom
protected ConnectionIdGenerator	connectionIdGenerator The configured connection id length.
protected int	flightNumber The current flight number.
protected List<HandshakeMessage>	handshakeMessages List of handshake messages
protected boolean	isClient Indicates whether this handshaker performs the client or server part of the protocol.
protected org.slf4j.Logger	LOGGER
protected SecretKey	masterSecret The master secret for this handshake.
protected CertPath	peerCertPath The certificate path of the other peer
protected PrivateKey	privateKey The handshaker's private key.
protected PublicKey	publicKey The handshaker's public key.
protected ReassemblingHandshakeMessage	reassembledMessage Current partial reassembled handshake message.
protected Integer	recordSizeLimit Record size limit.
protected Random	serverRandom
protected DTLSSession	session
protected boolean	sniEnabled Support Server Name Indication TLS extension.
protected HandshakeState[]	states
protected int	statesIndex
protected ProtocolVersion	usedProtocol
protected boolean	useKeyUsageVerification Use key usage verification for x509.
protected boolean	useStateValidation Use handshake state machine validation.
protected boolean	useTruncatedCertificatePathForVerification Truncate certificate path for validation.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	Handshaker(boolean isClient, int initialMessageSeq, DTLSSession session, RecordLayer recordLayer, ScheduledExecutorService timer, Connection connection, DtlsConnectorConfig config) Creates a new handshaker for negotiating a DTLS session with a given peer.

Method Summary

Methods

Modifier and Type	Method and Description
void	addApplicationDataForDeferredProcessing(org.eclipse.californium.elements.RawData outgoingMessage) Add outgoing application data for deferred processing.
void	addRecordsForDeferredProcessing(Record incomingMessage) Add incoming records for deferred processing.
void	addSessionListener(SessionListener listener) Adds a listener to the list of listeners to be notified about session life cycle events.
protected void	applyMasterSecret(SecretKey masterSecret) Applying the key expansion on the master secret generates a large key block to generate the encryption, MAC and IV keys.
protected void	calculateKeys(SecretKey masterSecret) Calculates the encryption key, MAC key and IV from a given master secret.
void	completePendingFlight() Registers an outbound flight that has not been acknowledged by the peer yet in order to be able to cancel its re-transmission later once it has been acknowledged.
DTLSFlight	createFlight() Create new flight with the current getSession() and the current flightNumber.
void	destroy()
protected abstract void	doProcessMessage(HandshakeMessage message) Does the specific processing of a message received from a peer in the course of an ongoing handshake.
protected void	ensureUndestroyed() Check, if this handshaker has been destroyed.
protected void	expectChangeCipherSpecMessage() Marks this handshaker to expect the peer's CHANGE_CIPHER_SPEC message next.
protected void	expectMessage(DTLSMessage message) Check, if message is expected.
protected byte[]	generateRandomSeed() Generate random seed for master secret.
Random	getClientRandom() Get client random.
Connection	getConnection() Gets related connection.
Throwable	getFailureCause() Get cause of failure.
protected MessageDigest	getHandshakeMessageDigest() Get message digest for FINISH message.
InetSocketAddress	getPeerAddress() Gets the IP address and port of the peer this handshaker is used to negotiate a session with.
ConnectionId	getReadConnectionId() Get read connection ID for inbound records
Random	getServerRandom() Get server random.
DTLSSession	getSession() Gets the session this handshaker is used to establish.
void	handshakeAborted(Throwable cause) Abort handshake.
void	handshakeCompleted() Forward handshake completed to registered listeners.
void	handshakeFailed(Throwable cause) Notifies all registered session listeners about a handshake failure.
void	handshakeFlightRetransmitted(int flight) Notifies all registered session listeners about a handshake retransmit of a flight.
protected void	handshakeStarted() Forward handshake start to registered listeners.
boolean	hasSessionEstablished() Checks, if the session is established.
boolean	isChangeCipherSpecMessageExpected() Checks whether the peer's CHANGE_CIPHER_SPEC message is the next message expected in the ongoing handshake.
boolean	isDestroyed()
boolean	isExpired() Test, if handshake is expired according nano realtime.
boolean	isInboundMessageProcessed() Check, if inbound messages are all processed.
boolean	isProbing() Test, if handshake was started in probing mode.
boolean	isPskRequestPending() Check, if psk request is pending.
boolean	isRemovingConnection() Check, if the connection must be removed.
void	processAsyncHandshakeResult(HandshakeResult handshakeResult) Process asynchronous handshake result.
void	processAsyncPskSecretResult(PskSecretResult pskSecretResult) Deprecated. use processAsyncHandshakeResult(HandshakeResult) instead.
protected void	processCertificateVerificationResult(CertificateVerificationResult certificateVerificationResult) Process certificate verification result.
protected abstract void	processCertificateVerified() Do the handshaker specific processing of successful verified certificates
protected abstract void	processMasterSecret(SecretKey masterSecret) Do the handshaker specific master secret processing
void	processMessage(Record record) Processes a handshake record received from a peer based on the handshake's current state.
protected void	processPskSecretResult(PskSecretResult pskSecretResult) Process PSK secret result.
protected GenericHandshakeMessage	reassembleFragment(FragmentedHandshakeMessage fragment) Process a received fragmented handshake message.
void	removeSessionListener(SessionListener listener) Removes a listener from the list of listeners to be notified about session life cycle events.
protected PskSecretResult	requestPskSecretResult(PskPublicInformation pskIdentity, SecretKey otherSecret) Request psk secret result for PSK cipher suites.
void	resetProbing() Reset probing mode, when data is received during.
void	sendFlight(DTLSFlight flight) Send flight.
void	sendLastFlight(DTLSFlight flight) Send last flight.
protected void	sessionEstablished() Forward session established to registered listeners.
protected void	setCurrentReadState()
protected void	setCurrentWriteState()
void	setFailureCause(Throwable cause) Set the failure cause.
void	setGenerateClusterMacKeys(boolean enable) Enable to generate keys for cluster MAC.
abstract void	startHandshake() Starts the handshake by sending the first flight to the peer.
List<org.eclipse.californium.elements.RawData>	takeDeferredApplicationData() Take deferred outgoing application data.
void	takeDeferredApplicationData(Handshaker replacedHandshaker) Take deferred outgoing application data from provided handshaker.
List<Record>	takeDeferredRecords() Take deferred incoming records.
void	verifyCertificate(CertificateMessage message) Start validating the X.509 certificate chain provided by the the peer as part of this message, or the raw public key of the message.
protected void	wrapMessage(DTLSFlight flight, DTLSMessage fragment) Wraps a DTLS message fragment into (potentially multiple) DTLS records and add them to the flight.

Methods inherited from class java.lang.Object

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

Field Detail

LOGGER

protected final org.slf4j.Logger LOGGER

isClient

protected final boolean isClient

Indicates whether this handshaker performs the client or server part of the protocol.

usedProtocol

protected ProtocolVersion usedProtocol

clientRandom

protected Random clientRandom

serverRandom

protected Random serverRandom

masterSecret

protected SecretKey masterSecret

The master secret for this handshake.

session

protected final DTLSSession session

certificateVerifier

protected final NewAdvancedCertificateVerifier certificateVerifier

The logic in charge of verifying the chain of certificates asserting this handshaker's identity

advancedPskStore

protected final AdvancedPskStore advancedPskStore

Used to retrieve identity/pre-shared-key for a given destination

connectionIdGenerator

protected final ConnectionIdGenerator connectionIdGenerator

The configured connection id length. null, not supported, 0 supported but not used.

flightNumber

protected int flightNumber

The current flight number.

recordSizeLimit

protected Integer recordSizeLimit

Record size limit. null, if not used.

Since:

2.4

handshakeMessages

protected final List<HandshakeMessage> handshakeMessages

List of handshake messages

reassembledMessage

protected ReassemblingHandshakeMessage reassembledMessage

Current partial reassembled handshake message.

privateKey

protected final PrivateKey privateKey

The handshaker's private key.

publicKey

protected final PublicKey publicKey

The handshaker's public key.

certificateChain

protected final List<X509Certificate> certificateChain

The chain of certificates asserting this handshaker's identity

peerCertPath

protected CertPath peerCertPath

The certificate path of the other peer

certificateVerfied

protected boolean certificateVerfied

Indicates, that the certificate or public key verification has finished.

Since:

2.5

sniEnabled

protected boolean sniEnabled

Support Server Name Indication TLS extension.

useStateValidation

protected boolean useStateValidation

Use handshake state machine validation.

useKeyUsageVerification

protected final boolean useKeyUsageVerification

Use key usage verification for x509.

useTruncatedCertificatePathForVerification

protected final boolean useTruncatedCertificatePathForVerification

Truncate certificate path for validation.

statesIndex

protected int statesIndex

states

protected HandshakeState[] states

Constructor Detail

Handshaker

protected Handshaker(boolean isClient,
          int initialMessageSeq,
          DTLSSession session,
          RecordLayer recordLayer,
          ScheduledExecutorService timer,
          Connection connection,
          DtlsConnectorConfig config)

Creates a new handshaker for negotiating a DTLS session with a given peer.

Parameters:

isClient - indicates whether this handshaker plays the client or server role.

initialMessageSeq - the initial message sequence number to use and expect in the exchange of handshake messages with the peer. This parameter can be used to initialize the message_seq and receive_next_seq counters to a value larger than 0, e.g. if one or more cookie exchange round-trips have been performed with the peer before the handshake starts.

session - the session this handshaker is negotiating.

recordLayer - the object to use for sending flights to the peer.

timer - scheduled executor for flight retransmission (since 2.4).

connection - the connection related to this handshaker.

config - the dtls configuration

Throws:

NullPointerException - if session, recordLayer, or config is null.

IllegalArgumentException - if the initial message sequence number is negative

Method Detail

isInboundMessageProcessed

public boolean isInboundMessageProcessed()

Check, if inbound messages are all processed.

Returns:

true, all inbound messages are processed, false, some inbound messages are pending.

Since:

2.1

processMessage

public final void processMessage(Record record)
                          throws HandshakeException

Processes a handshake record received from a peer based on the handshake's current state. This method passes the messages into the inboundMessageBuffer and delegates processing of the ordered messages to the doProcessMessage(HandshakeMessage) method. If ChangeCipherSpecMessage is processed, the deferredRecords are passed again to the RecordLayer to get decrypted and processed.

Parameters:

record - the handshake record

Throws:

HandshakeException - if the record's plaintext fragment cannot be parsed into a handshake message or cannot be processed properly

IllegalArgumentException - if the record's epoch differs from the session's read epoch

expectMessage

protected void expectMessage(DTLSMessage message)
                      throws HandshakeException

Check, if message is expected.

Parameters:

message - mesage to check

Throws:

HandshakeException - if the message is not expected

See Also:

useStateValidation, DtlsConnectorConfig.useHandshakeStateValidation()

doProcessMessage

protected abstract void doProcessMessage(HandshakeMessage message)
                                  throws HandshakeException,
                                         GeneralSecurityException

Does the specific processing of a message received from a peer in the course of an ongoing handshake. This method does not do anything. Concrete handshaker implementations should override this method in order to prepare the response to the received record.

Parameters:

message - the message received from the peer

Throws:

HandshakeException - if the record's plaintext fragment cannot be parsed into a handshake message or cannot be processed properly

GeneralSecurityException - if the record's ciphertext fragment cannot be decrypted

startHandshake

public abstract void startHandshake()
                             throws HandshakeException

Starts the handshake by sending the first flight to the peer.

The particular message to be sent depends on this peer's role in the handshake, i.e. if this end represents the client or server.

Throws:

HandshakeException - if the message to start the handshake cannot be created and sent using the session's current security parameters.

processAsyncHandshakeResult

public void processAsyncHandshakeResult(HandshakeResult handshakeResult)
                                 throws HandshakeException

Process asynchronous handshake result. MUST not be called from doProcessMessage(HandshakeMessage) implementations! If handshake expects the cipher change message, then process the messages from the inbound buffer.

Parameters:

handshakeResult - asynchronous handshake result

Throws:

HandshakeException - if an error occurs

IllegalStateException - if pskRequestPending or certificateVerificationPending is not pending, or the handshaker isDestroyed().

Since:

2.5

processAsyncPskSecretResult

@Deprecated
public void processAsyncPskSecretResult(PskSecretResult pskSecretResult)
                                 throws HandshakeException

Deprecated. use processAsyncHandshakeResult(HandshakeResult) instead.

Process asynchronous PSK secret result. MUST not be called from doProcessMessage(HandshakeMessage) implementations! If handshake expects the cipher change message, then process the messages from the inbound buffer.

Parameters:

pskSecretResult - PSK secret result.

Throws:

HandshakeException - if an error occurs

IllegalStateException - if pskRequestPending is not pending, or the handshaker isDestroyed().

Since:

2.3

processPskSecretResult

protected void processPskSecretResult(PskSecretResult pskSecretResult)
                               throws HandshakeException

Process PSK secret result.

Parameters:

pskSecretResult - PSK secret result.

Throws:

HandshakeException - if an error occurs

IllegalStateException - if pskRequestPending is not pending, or the handshaker isDestroyed().

Since:

2.3

processMasterSecret

protected abstract void processMasterSecret(SecretKey masterSecret)
                                     throws HandshakeException

Do the handshaker specific master secret processing

Parameters:

masterSecret - master secret

Throws:

HandshakeException - if an error occurs

Since:

2.3

processCertificateVerificationResult

protected void processCertificateVerificationResult(CertificateVerificationResult certificateVerificationResult)
                                             throws HandshakeException

Process certificate verification result.

Parameters:

certificateVerificationResult - certificate verification result

Throws:

HandshakeException - if an error occurred during processing

IllegalStateException - if certificateVerificationPending is not pending, or the handshaker isDestroyed().

Since:

2.5

processCertificateVerified

protected abstract void processCertificateVerified()
                                            throws HandshakeException

Do the handshaker specific processing of successful verified certificates

Throws:

HandshakeException - if an error occurs

Since:

2.5

getHandshakeMessageDigest

protected final MessageDigest getHandshakeMessageDigest()

Get message digest for FINISH message.

Returns:

message digest update with all handshake messages in handshakeMessages

applyMasterSecret

protected void applyMasterSecret(SecretKey masterSecret)

Applying the key expansion on the master secret generates a large key block to generate the encryption, MAC and IV keys. Also set the master secret to the session for resumption handshakes. See RFC5246 for further details about the keys.

Parameters:

masterSecret - the master secret.

Since:

2.3

See Also:

masterSecret

calculateKeys

protected void calculateKeys(SecretKey masterSecret)

Calculates the encryption key, MAC key and IV from a given master secret. First, applies the key expansion to the master secret.

Parameters:

masterSecret - the master secret.

generateRandomSeed

protected byte[] generateRandomSeed()

Generate random seed for master secret.

Returns:

random seed

Since:

2.3

requestPskSecretResult

protected PskSecretResult requestPskSecretResult(PskPublicInformation pskIdentity,
                                     SecretKey otherSecret)

Request psk secret result for PSK cipher suites. Sets pskRequestPending.

Parameters:

pskIdentity - PSK identity

otherSecret - others secret for ECHDE support. Maybe null.

Returns:

psk secret result. null, if result is returned asynchronous.

Since:

2.3

setCurrentReadState

protected final void setCurrentReadState()

setCurrentWriteState

protected final void setCurrentWriteState()

wrapMessage

protected final void wrapMessage(DTLSFlight flight,
               DTLSMessage fragment)
                          throws HandshakeException

Wraps a DTLS message fragment into (potentially multiple) DTLS records and add them to the flight. Sets the record's epoch, sequence number and handles fragmentation for handshake messages.

Parameters:

flight - the flight to add the wrapped messages

fragment - the message fragment

Throws:

HandshakeException - if the message could not be encrypted using the session's current security parameters

reassembleFragment

protected GenericHandshakeMessage reassembleFragment(FragmentedHandshakeMessage fragment)
                                              throws HandshakeException

Process a received fragmented handshake message. Checks, if all fragments are available and reassemble the handshake message, if so.

Parameters:

fragment - the fragmented handshake message.

Returns:

the reassembled generic handshake message (if all fragments are available), null, otherwise.

Throws:

HandshakeException - if the reassembling fails

Since:

2.4

getSession

public final DTLSSession getSession()

Gets the session this handshaker is used to establish.

Returns:

the session

getPeerAddress

public final InetSocketAddress getPeerAddress()

Gets the IP address and port of the peer this handshaker is used to negotiate a session with.

Returns:

the peer address

getConnection

public final Connection getConnection()

Gets related connection.

Returns:

connection

createFlight

public DTLSFlight createFlight()

Create new flight with the current getSession() and the current flightNumber.

Returns:

new flight

Since:

2.5

getReadConnectionId

public ConnectionId getReadConnectionId()

Get read connection ID for inbound records

Returns:

connection ID for inbound records. null, if connection ID is not supported, a empty connection ID, if connection ID is supported but not used for inbound records.

Since:

2.5

getClientRandom

public Random getClientRandom()

Get client random.

Returns:

client random, or null, if not available.

getServerRandom

public Random getServerRandom()

Get server random.

Returns:

server random, or null, if not available.

addApplicationDataForDeferredProcessing

public void addApplicationDataForDeferredProcessing(org.eclipse.californium.elements.RawData outgoingMessage)

Add outgoing application data for deferred processing.

Parameters:

outgoingMessage - outgoing application data

addRecordsForDeferredProcessing

public void addRecordsForDeferredProcessing(Record incomingMessage)

Add incoming records for deferred processing.

Parameters:

incomingMessage - incoming record.

takeDeferredApplicationData

public List<org.eclipse.californium.elements.RawData> takeDeferredApplicationData()

Take deferred outgoing application data.

Returns:

list of application data

takeDeferredRecords

public List<Record> takeDeferredRecords()

Take deferred incoming records.

Returns:

list if deferred incoming records

takeDeferredApplicationData

public void takeDeferredApplicationData(Handshaker replacedHandshaker)

Take deferred outgoing application data from provided handshaker.

Parameters:

replacedHandshaker - replaced handshaker to take deferred outgoing application data

completePendingFlight

public void completePendingFlight()

Registers an outbound flight that has not been acknowledged by the peer yet in order to be able to cancel its re-transmission later once it has been acknowledged. The retransmission of a different previous pending flight will be cancelled also.

sendLastFlight

public void sendLastFlight(DTLSFlight flight)

Send last flight. The last flight doesn't need retransmission.

Parameters:

flight - last flight to send

See Also:

sendFlight(DTLSFlight)

sendFlight

public void sendFlight(DTLSFlight flight)

Send flight.

Parameters:

flight - flight to send

See Also:

sendFlight(DTLSFlight)

addSessionListener

public final void addSessionListener(SessionListener listener)

Adds a listener to the list of listeners to be notified about session life cycle events.

Parameters:

listener - The listener to add.

removeSessionListener

public final void removeSessionListener(SessionListener listener)

Removes a listener from the list of listeners to be notified about session life cycle events.

Parameters:

listener - The listener to remove.

handshakeStarted

protected final void handshakeStarted()
                               throws HandshakeException

Forward handshake start to registered listeners.

Throws:

HandshakeException - if thrown by listener

sessionEstablished

protected final void sessionEstablished()
                                 throws HandshakeException

Forward session established to registered listeners. amendPeerPrincipal().

Throws:

HandshakeException - if thrown by listener

handshakeCompleted

public final void handshakeCompleted()

Forward handshake completed to registered listeners.

handshakeFailed

public final void handshakeFailed(Throwable cause)

Notifies all registered session listeners about a handshake failure. Listeners are intended to remove the connection, if no session is established. If setFailureCause(Throwable) was called before, only calls with the same cause will notify the listeners. If setFailureCause(Throwable) wasn't called before, sets the cause property to the given cause.

Parameters:

cause - The reason for the failure.

See Also:

isRemovingConnection(), handshakeAborted(Throwable)

handshakeAborted

public final void handshakeAborted(Throwable cause)

Abort handshake. Notifies all registered session listeners about a handshake failure. Listeners are intended to keep the connection. If setFailureCause(Throwable) was called before, only calls with the same cause will notify the listeners. If setFailureCause(Throwable) wasn't called before, sets the cause property to the given cause.

Parameters:

cause - The reason for the abort.

Since:

2.1

See Also:

handshakeFailed(Throwable), isRemovingConnection()

hasSessionEstablished

public boolean hasSessionEstablished()

Checks, if the session is established. Indicates, that the peer has send it's FINISH and is awaiting to receive data or alerts in epoch 1.

Returns:

true, if the session is established, false, otherwise.

Since:

2.3

isProbing

public boolean isProbing()

Test, if handshake was started in probing mode. Usually a resuming client handshake removes the session from the connection store with the start. Probing removes the session only with the first data received back.

Returns:

true, if handshake is in probing mode, false, otherwise.

Since:

2.1

See Also:

ResumingClientHandshaker

resetProbing

public void resetProbing()

Reset probing mode, when data is received during.

Since:

2.1

See Also:

ResumingClientHandshaker

isExpired

public boolean isExpired()

Test, if handshake is expired according nano realtime. Used to mitigate deep sleep during handshakes.

Returns:

true, if handshake is expired, mainly during deep sleep, false, if the handshake is still in time.

Since:

2.1

isPskRequestPending

public boolean isPskRequestPending()

Check, if psk request is pending.

Returns:

true, if psk request is pending, false, otherwise.

isRemovingConnection

public boolean isRemovingConnection()

Check, if the connection must be removed. The connection must be removed, if handshakeFailed(Throwable) was called, and the connection has no established session.

Returns:

true, remove the connection, false, keep it.

Since:

2.1

getFailureCause

public Throwable getFailureCause()

Get cause of failure.

Returns:

cause of failure, or null, if the cause is unknown and not set before

See Also:

setFailureCause(Throwable), handshakeFailed(Throwable)

setFailureCause

public void setFailureCause(Throwable cause)

Set the failure cause. In some cases the cleanup of the handshake may consider a different failure as cause. This prevents handshakeFailed(Throwable) to notify listener in that case.

Parameters:

cause - failure cause

See Also:

handshakeFailed(Throwable), getFailureCause()

setGenerateClusterMacKeys

public void setGenerateClusterMacKeys(boolean enable)

Enable to generate keys for cluster MAC.

Parameters:

enable - true, generate keys for cluster MAC, false, otherwise.

Since:

2.5

handshakeFlightRetransmitted

public final void handshakeFlightRetransmitted(int flight)

Notifies all registered session listeners about a handshake retransmit of a flight.

Parameters:

flight - number of retransmitted flight.

isChangeCipherSpecMessageExpected

public final boolean isChangeCipherSpecMessageExpected()

Checks whether the peer's CHANGE_CIPHER_SPEC message is the next message expected in the ongoing handshake.

Returns:

true if the message is expected next.

expectChangeCipherSpecMessage

protected final void expectChangeCipherSpecMessage()

Marks this handshaker to expect the peer's CHANGE_CIPHER_SPEC message next.

verifyCertificate

public void verifyCertificate(CertificateMessage message)
                       throws HandshakeException

Start validating the X.509 certificate chain provided by the the peer as part of this message, or the raw public key of the message. This method delegates both certificate validation to the NewAdvancedCertificateVerifier. If a asynchronous implementation of NewAdvancedCertificateVerifier is used, the result will be not available after this call, but will be available after the callback of the asynchronous implementation.

Parameters:

message - the certificate message

Throws:

HandshakeException - if any of the checks fails

destroy

public void destroy()
             throws DestroyFailedException

Specified by:

destroy in interface Destroyable

Throws:

DestroyFailedException

isDestroyed

public boolean isDestroyed()

Specified by:

isDestroyed in interface Destroyable

ensureUndestroyed

protected void ensureUndestroyed()

Check, if this handshaker has been destroyed.

Throws:

IllegalStateException - if the handshake has been destroyed.