org.eclipse.californium.scandium.dtls.pskstore

Interface AdvancedPskStore

All Known Implementing Classes:

AdvancedInMemoryPskStore, AdvancedMultiPskStore, AdvancedSinglePskStore, AsyncAdvancedPskStore, AsyncInMemoryPskStore, BridgePskStore

public interface AdvancedPskStore

Advanced PSK store with optional asynchronous API. It could also be used to delegate the master secret generation to a HSM. Returns psk secret result instead of PSK's secret key. The secret must either be a master secret (algorithm "MAC"), or a PSK secret key (algorithm "PSK"). If required, the psk secret result maybe returned asynchronously using a PskSecretResultHandler.

Synchronous example returning the PSK secret key:

 @Override
 public PskSecretResult generateMasterSecret(ConnectionId cid, ServerNames serverNames, PskPublicInformation identity,
                        String hmacAlgorithm, SecretKey otherSecret, byte[] seed) {
                SecretKey pskSecret = ... func ... identity ...; // identity maybe normalized!
                return new PskSecretResult(cid, identity, pskSecret);
 }
 

Asynchronous example returning the master secret:

 @Override
 public PskSecretResult generateMasterSecret(ConnectionId cid, ServerNames serverNames, PskPublicInformation identity,
                        String hmacAlgorithm, SecretKey otherSecret, byte[] seed) {
        
                start ... func ... cid, servernames, identity, otherSecret, seed 
                        // calls processResult with generate master secret asynchronous;
                return null; // returns null for asynchronous processing
 }
 
 @Override
 public void setResultHandler(PskSecretResultHandler resultHandler) {
                this.resultHandler = resultHandler;
 }
 
 private void processResult(PskPublicInformation identity, ConnectionId cid,
                        SecretKey masterSecret) {
                // executed by different thread!
                PskSecretResult result = new PskSecretResult(cid, identity, masterSecret);
                resultHandler.apply(result);
 }
 

Since:

2.3

Method Summary

Methods

Modifier and Type	Method and Description
PskPublicInformation	getIdentity(InetSocketAddress peerAddress, ServerNames virtualHost) Gets the identity to use for a PSK based handshake with a given peer.
boolean	hasEcdhePskSupported() Check, if ECDHE PSK cipher suites are supported.
PskSecretResult	requestPskSecretResult(ConnectionId cid, ServerNames serverName, PskPublicInformation identity, String hmacAlgorithm, SecretKey otherSecret, byte[] seed) Request psk secret result.
void	setResultHandler(PskSecretResultHandler resultHandler) Set the handler for asynchronous master secret results.

Method Detail

hasEcdhePskSupported

boolean hasEcdhePskSupported()

Check, if ECDHE PSK cipher suites are supported.

Returns:

true, if ECDHE PSK cipher suites are supported, false, if not.

requestPskSecretResult

PskSecretResult requestPskSecretResult(ConnectionId cid,
                                     ServerNames serverName,
                                     PskPublicInformation identity,
                                     String hmacAlgorithm,
                                     SecretKey otherSecret,
                                     byte[] seed)

Request psk secret result. Either return the result, or null and process the request asynchronously. The PskSecretResult must contain the CID, the normalized identity and master secret or PSK secret key, if available. If the result is not returned, it is passed asynchronously to the result handler, provided during DTLSConnector initialization by setResultHandler(PskSecretResultHandler).

Parameters:

cid - connection id for stateless asynchronous implementations.

serverName - server names. Maybe null, if SNI is not enabled or not used by the client.

identity - psk identity. Maybe normalized, if identity is available in the store.

hmacAlgorithm - HMAC algorithm name for PRF.

otherSecret - other secret from ECDHE, or null. Must be cloned for asynchronous use. See RFC 5489, other secret

seed - seed for PRF.

Returns:

psk secret result, or null, if result is provided asynchronous.

getIdentity

PskPublicInformation getIdentity(InetSocketAddress peerAddress,
                               ServerNames virtualHost)

Gets the identity to use for a PSK based handshake with a given peer.

A DTLS client uses this method to determine the identity to include in its CLIENT_KEY_EXCHANGE message during a PSK based DTLS handshake with the peer.

Parameters:

peerAddress - The IP address and port of the peer to perform the handshake with.

virtualHost - The virtual host at the peer to connect to. If null, the identity will be looked up in the global scope.

Returns:

The identity to use or null if no peer with the given address and virtual host is registered.

Throws:

NullPointerException - if address is null.

setResultHandler

void setResultHandler(PskSecretResultHandler resultHandler)

Set the handler for asynchronous master secret results. Called during initialization of the DTLSConnector. Synchronous implementations may just ignore this using an empty implementation. Note: the type of the handler will change to HandshakeResultHandler with 3.0.

Parameters:

resultHandler - handler for asynchronous master secret results. This handler MUST NOT be called from the thread calling requestPskSecretResult(ConnectionId, ServerNames, PskPublicInformation, String, SecretKey, byte[]), instead just return the result there.