iaik.security.ssl

Class TLS13PostHandshakeConfig.TLS13KeyUpdateConfig

java.lang.Object

iaik.security.ssl.TLS13PostHandshakeConfig

iaik.security.ssl.TLS13PostHandshakeConfig.TLS13KeyUpdateConfig

All Implemented Interfaces:

java.lang.Cloneable

Enclosing class:

TLS13PostHandshakeConfig

public static final class TLS13PostHandshakeConfig.TLS13KeyUpdateConfig
extends TLS13PostHandshakeConfig
implements java.lang.Cloneable

Configuration for post handshake type KEY_UPDATE.

At any time after having sent its Finished message a TLS 1.3 client or server may send a KeyUpdate post handshake message to notify the peer that it is updating its write keys (see RFC 8446):

 enum {
     update_not_requested(0), update_requested(1), (255)
 } KeyUpdateRequest;

 struct {
      KeyUpdateRequest request_update;
 } KeyUpdate;
 

The KeyUpdate message itself is encrypted with the old keys. When receiving a KeyUpdate message the local TLS application has to update its read keys. When the request_update field of the received KeyUpdate message is set to update_requested the local application shall also update its write keys and send back a KeyUpdate message with the request_update field set to update_not_requested. Doing so both sides of the connection have updated their whole keying material.

Per default iSaSiLk does not request any key update but follows key update requests received from the peer. This class allows to configure the key update behavior by specifying the following parameters:

• The responseDataLimit parameter specifies the amount of data that may be read until the peer has to respond to a KeyUpdate message with a KeyUpdate message notifying that it has updated its write keys (default: -1; accept that the peer may not send a key update message).
• The ignorePeerKeyUpdateRequests parameter specifies whether to ignore write key update requests from the peer (do ensure to only update write keys by locally triggering a key update). (default: false; write key update requests from the peer are not ignored)
• The requestPeerWriteKeyUpdate parameter specifies whether to request a write key update from the peer when sending a KeyUpdate message (default: true).
• The readPeerResponseImmediately parameter specifies whether to try to read the peer KeyUpdate post handshake message immediately after having sent the post handshake KeyUpdate message (default: false; the peer KeyUpdate message is not read before the next read() call).
  Only meaningful if requesting a write key update from the peer.
• The updateWriteKeysImmediately parameter specifies whether to update the write keys immediately after having received a KeyUpdate request from the peer. By default iSaSiLk does not update the write keys immediately after having received a KeyUpdate request, rather it waits with the write key update until the next regular (data) write operation
• The checkKeyUpdateMessagesBasedOnAvailibility parameter specifies whether to call available() on the underlying stream before trying to read a further message after a KeyUpdate message has been received.

For telling iSaSiLk the key update configuration method postHandshake has to be called on the SSLSocket/SSLTransport in use. When calling postHandshake to explicitly trigger a KeyUpdate care has to be taken that the regular handshake has been already finished (and some data has been exchanged) and a protocol version >=1.3 has been negotiated, e.g.:

 SSLSocket sslSocket = ...;
 ...
 sslSocket.startHandshake();
 ...
 // do some data reading/writing
 ...
 boolean triggerKeyUpdate = true;
 TLS13KeyUpdateConfig keyUpdateConfig = new TLS13KeyUpdateConfig(triggerKeyUpdate);
 sslSocket.postHandshake(keyUpdateConfig);
 

When triggering key updates special care has to be taken because of interoperability and performance issues. Key updates may not performed too frequently. When triggering a key update by explicitly calling method postHandshake on the SSLSocket/SSLTransport object in use, and knowing that the peer will immediately send back its KeyUpdate message the TLS13KeyUpdateConfig may be directed to immediately try to read the KeyUpdate response from the peer.

Nested Class Summary

Nested classes/interfaces inherited from class iaik.security.ssl.TLS13PostHandshakeConfig

TLS13PostHandshakeConfig.TLS13KeyUpdateConfig, TLS13PostHandshakeConfig.TLS13NewSessionTicketConfig, TLS13PostHandshakeConfig.TLS13PostHandshakeAuthConfig

Field Summary

Fields inherited from class iaik.security.ssl.TLS13PostHandshakeConfig

KEY_UPDATE, NEW_SESSION_TICKET, POST_HANDSHAKE_AUTH

Constructor Summary

Constructors

Constructor and Description
TLS13KeyUpdateConfig() Default constructor.

Method Summary

Modifier and Type	Method and Description
java.lang.Object	clone() Returns a clone of this TLS13KeyUpdateConfig.
void	setCheckKeyUpdateMessagesBasedOnAvailibility(boolean checkAvailable) Sets whether to call available() on the underlying stream before trying to read a further message after a KeyUpdate message has been received.
void	setIgnorePeerKeyUpdateRequests(boolean ignore) Sets whether to ignore write key update requests from the peer.
void	setReadPeerResponseImmediately(boolean read) Sets whether to try to read the peer KeyUpdate post handshake message immediately after having sent the post handshake KeyUpdate message.
void	setRequestPeerWriteKeyUpdate(boolean requestUpdate) Sets whether to request a write key update from the peer when sending a KeyUpdate message.
void	setResponseDataLimit(long responseDataLimit) Sets the amount of data that may be read until the peer has to respond to a KeyUpdate message with a KeyUpdate message notifying that it has updated its write keys.
void	setUpdateWriteKeysImmediately(boolean update) Sets whether to update the write keys immediately after having received a KeyUpdate request from the peer.
java.lang.String	toString() Gets a string representation of this configuration.

Methods inherited from class iaik.security.ssl.TLS13PostHandshakeConfig

setMaxNumberOfPostHandshakeMessages, setMaxNumberOfSubsequentPostHandshakeMessages

Methods inherited from class java.lang.Object

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

Constructor Detail

TLS13KeyUpdateConfig

public TLS13KeyUpdateConfig()

Default constructor.

Method Detail

setResponseDataLimit

public void setResponseDataLimit(long responseDataLimit)

Sets the amount of data that may be read until the peer has to respond to a KeyUpdate message with a KeyUpdate message notifying that it has updated its write keys. (Default: -1; accept that the peer may not send a key update message).

Note that a short responseDataLimt value may cause to abort the connection before all data has been transmitted/received.

Parameters:

responseDataLimit - the amount of data that may be read until the peer has to respond to a KeyUpdate message with a KeyUpdate message notifying that it has updated its write keys. (Default: -1; no key update message from the peer may be sent)

Throws:

java.lang.IllegalArgumentException - of no dataLimit has been set

setIgnorePeerKeyUpdateRequests

public void setIgnorePeerKeyUpdateRequests(boolean ignore)

Sets whether to ignore write key update requests from the peer.

When having configured a key update interval it may be considerable to ignore any write key update requests from the peer (to limit the number of key updates) by setting ignorePeerKeyUpdateRequests to true. In this case, when receiving a KeyUpdate post handshake request message from the peer, the read keys will updated as required but the write keys will not be updated until the local update interval has beem exhausted.

Parameters:

ignore - whether to ignore write key update requests from the peer (do ensure to only update write keys in the locally configured intervals). (Default: false; write key update requests from the peer are not ignored)

setRequestPeerWriteKeyUpdate

public void setRequestPeerWriteKeyUpdate(boolean requestUpdate)

Sets whether to request a write key update from the peer when sending a KeyUpdate message.
When set to true (default) not only the local write keys will be updated but also the peer will be requested to update its write keys (and thus doing a full read/write key update). When set to false only the local write keys will be updated and the peer will not be requested to update its write keys (and thus only updating its read keys).

Parameters:

requestUpdate - whether to also request a write key update from the peer or only cause the peer to update its read keys

setReadPeerResponseImmediately

public void setReadPeerResponseImmediately(boolean read)

Sets whether to try to read the peer KeyUpdate post handshake message immediately after having sent the post handshake KeyUpdate message.
Only meaningful if requesting a write key update from the peer.

When set to true iSaSiLk tries to read the peer KeyUpdate message (if requesting a peer write key update) immediately after having sent the KeyUpdate message. Any application data that the client sends in front of the the client authentication messages is internally buffered to be pushed back after the peer key update messages has arrived. However, this may cause an exception if too much application data is sent to can be internally buffered. For that reason you may call setReadPeerResponseImmediately(true); only if you are sure that the peer will send the key update message immediately (or at least reasonable) soon after having received the key update request. Alternatively you may make some explicitly read() call -- or span up some listener thread -- after having triggered the post handshake KeyUpdate request to explicitly handle any blocking condition or receiving of application data before receiving the KeyUpdate messages.

Parameters:

read - true if trying to read the peer KeyUpdate response (if requested) immediately after having sent the KeyUpdate request, false if not trying to read the response (default)

setUpdateWriteKeysImmediately

public void setUpdateWriteKeysImmediately(boolean update)

Sets whether to update the write keys immediately after having received a KeyUpdate request from the peer.

By default iSaSiLk does not immediately update the write keys if having received a KeyUpdate request from the peer. Since a write key update is only required when actually writing some data iSaSiLk by default waits with the write key update until (application) data is actually written.

Parameters:

update - whether to update the write keys immediately after having received a KeyUpdate request from the peer, false (default) if waiting with the write key update until the next regular (data) write operation

setCheckKeyUpdateMessagesBasedOnAvailibility

public void setCheckKeyUpdateMessagesBasedOnAvailibility(boolean checkAvailable)

Sets whether to call available() on the underlying stream before trying to read a further message after a KeyUpdate message has been received.
Calling available() may only work properly if the SSLInputInputStream.available mode is set to "decrypted". By default iSaSiLk decides whether trying to read further messages after a KeyUpdate based on the number of pending KeyUpdate requests, except when SSLInputInputStream.available mode is set to "decrypted". In this case available() is called on the underlying stream before trying to read a further message. With this method you can configure iSaSiLk to call available() in any (or no) case, respectively.

Parameters:

checkAvailable - true to call ir.messageAvailable(); before trying to read a further message, false if deciding whether to read a further message based on the number of pending key update requests

clone

public java.lang.Object clone()

Returns a clone of this TLS13KeyUpdateConfig.

Overrides:

clone in class TLS13PostHandshakeConfig

Returns:

a clone of this TLS13KeyUpdateConfig

toString

public java.lang.String toString()

Gets a string representation of this configuration.

Overrides:

toString in class java.lang.Object

Returns:

a string representation