iaik.security.ssl

Class PreSharedKey

java.lang.Object

javax.crypto.spec.SecretKeySpec

iaik.security.ssl.PreSharedKey

All Implemented Interfaces:

java.io.Serializable, java.security.Key, java.security.spec.KeySpec, javax.crypto.SecretKey, javax.security.auth.Destroyable

public class PreSharedKey
extends javax.crypto.spec.SecretKeySpec

Pre-shared key to be used by PSK cipher suites according to RFC 4279.

A pre-shared key is a symmetric key shared between client and server in advance. It is used for authentication when a PSK cipher suite is selected.
Although this class is implemented as JCE SecretKey a PreSharedKey object typically will not be used with JCE Cipher or Mac engines. Pre shared keys are required by PSK cipher suites to build the premaster secret. An application that wants to run a PSK cipher suite has to tell iSaSiLk which pre-shared key have to be used for peer authentication. Using SecretKey instance for pre-shared keys allows an application to use Java KeyStores for securely storing a pre-shared key. However, it may be appropriate to limit the exposure of pre-shared keys over times (see security considerations of the TLS-PSK specification).

When client and server agree on a psk cipher suite, the client has to tell the server which pre-shared key (psk) shall be used by sending the psk identity within the ClientKeyExchange message. If the server has a pre-shared key for the received identity the handshake can continue, otherwise the handshake will fail. Before receiving the psk identity in the ClientKeyExchange message, the server may use the ServerKeyExchange message to send a psk identity hint to help the client to select a proper pre-shared key. However, the TLS-PSK specification recommends that an identity hint should not be sent by the server and that it must be ignored by the client (except for a special profile makes some other recommendation).

iSaSiLk wraps pre-shared keys into PSKCredentials. Each PSKCredential binds a pre-shared key to a psk identity. Optionally a PSKCredential may also contain a psk identity hint for the pre-shared key and identification information of the peer to which to authenticate with the pre-shared key of the credential.
PSKCredentials are maintained by the PSKManager who is responsible for providing the right pre-shared key when going into a TLS connection with some particular peer. On the server side, the PSKManager searches for the psk by means of the psk identity received from the client. On the client side, the PSKManager needs to know the remote peer id to search for the right pre-shared key. You may write and plug-in your own PSKManager; however, in general you may not take care about PSKManager details at all and only use the SSLContext addPSKCredential, setPSKCredential methods to add/set PSKCredentials for being used for psk cipher suite based TLS authentication. To, for instance, tell iSaSiLk to use a pre-shared key with identity "pskclient.iaik.tugraz.at" for communicating with a server named "pskserver.iaik.tugraz.at" you may create and add a PSKCredential in the following way:

 // psk identity
 String identity = "pskclient.iaik.tugraz.at";
 // server name (remote peer id)
 String serverName = "pskserver.iaik.tugraz.at";
 // the pre-shared key
 PreSharedKey psk = ...;
 // create PSKCredential
 PSKCredential pskCredential = new PSKCredential(identity, psk);
 // set remote peer id
 pskCredential.setRemotePeerId(serverName);
 // create client context
 SSLClientContext context = new SSLClientContext();
 // add PSKCredential
 context.addPSKCredential(pskCredential);
 // enable PSK cipher suites
 CipherSuiteList suites = new CipherSuiteList();
 suites.add(CipherSuite.CS_ALL_PSK);
 context.setEnabledCipherSuiteList(suites);
 context.updateCipherSuites();
 ...
 

When calling method addPSKCredential iSaSiLk forwards the given PSKCredential to the internal PSKManager. When then connecting to the server with the remote peer id specified in the credential just added, the PSKManager returns this credential and iSaSiLk can use it for authenticating the TLS session with this server.

In the sample above we have enabled all psk based cipher suites by calling suites.add(CipherSuite.CS_ALL_PSK);. However, you also can enable one specific cipher suite only (e.g. CipherSuite.TLS_PSK_WITH_3DES_EDE_CBC_SHA) or any of the three defined sets of psk based cipher suites:

1. Cipher suites that use symmetric key operations for authentication only:

           TLS_PSK_WITH_RC4_128_SHA,
           TLS_PSK_WITH_3DES_EDE_CBC_SHA,
           TLS_PSK_WITH_AES_128_CBC_SHA,
           TLS_PSK_WITH_AES_256_CBC_SHA
           

2. Cipher suites that use a Diffie-Hellman key exchange authenticated with a pre-shared key:

           TLS_DHE_PSK_WITH_RC4_128_SHA,
           TLS_DHE_PSK_WITH_3DES_EDE_CBC_SHA,
           TLS_DHE_PSK_WITH_AES_128_CBC_SHA,
           TLS_DHE_PSK_WITH_AES_256_CBC_SHA  
           

3. Cipher suites Cipher suites that use a RSA public key authentication of the server and pre-shared key authentication of the client:

           TLS_RSA_PSK_WITH_RC4_128_SHA,
           TLS_RSA_PSK_WITH_3DES_EDE_CBC_SHA,
           TLS_RSA_PSK_WITH_AES_128_CBC_SHA,
           TLS_RSA_PSK_WITH_AES_256_CBC_SHA
           

See Also:

PSKCredential, PSKManager, SSLContext.addPSKCredential(PSKCredential), SSLContext.setPSKCredential(PSKCredential), SSLContext.getPSKCredential(byte[], SSLTransport), Serialized Form

Constructor Summary

Constructors

Constructor and Description
PreSharedKey(byte[] psk) Creates a PreSharedKey object from given key material.

Method Summary

Modifier and Type	Method and Description
void	destroyCriticalData() Destroys the critical data of this object.
boolean	equals(java.lang.Object obj) Compares two pre shared keys.
java.lang.String	getAlgorithm() Returns the name ("PSK") of the key algorithm for this key.
byte[]	getEncoded() Returns a copy of the key material as byte array.
java.lang.String	getFormat() Returns the format name ("RAW").
int	hashCode() Returns a hash code value for this object.
java.lang.String	toString() Returns a string representation of this PreSharedKey.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface javax.security.auth.Destroyable

destroy, isDestroyed

Constructor Detail

PreSharedKey

public PreSharedKey(byte[] psk)

Creates a PreSharedKey object from given key material.

Parameters:

psk - the key material as byte array

Method Detail

getEncoded

public byte[] getEncoded()

Returns a copy of the key material as byte array.

Specified by:

getEncoded in interface java.security.Key

Overrides:

getEncoded in class javax.crypto.spec.SecretKeySpec

Returns:

a copy of the key material as byte array

getAlgorithm

public java.lang.String getAlgorithm()

Returns the name ("PSK") of the key algorithm for this key.

Specified by:

getAlgorithm in interface java.security.Key

Overrides:

getAlgorithm in class javax.crypto.spec.SecretKeySpec

Returns:

"PSK"

getFormat

public java.lang.String getFormat()

Returns the format name ("RAW").

Specified by:

getFormat in interface java.security.Key

Overrides:

getFormat in class javax.crypto.spec.SecretKeySpec

Returns:

"RAW"

destroyCriticalData

public void destroyCriticalData()

Destroys the critical data of this object.

equals

public boolean equals(java.lang.Object obj)

Compares two pre shared keys.

Overrides:

equals in class javax.crypto.spec.SecretKeySpec

Parameters:

obj - an object to be compared with this key

Returns:

true if the object to be compared has the same value; false otherwise

hashCode

public int hashCode()

Returns a hash code value for this object.

Overrides:

hashCode in class javax.crypto.spec.SecretKeySpec

Returns:

a hash code value for this object

toString

public java.lang.String toString()

Returns a string representation of this PreSharedKey.

Overrides:

toString in class java.lang.Object

Returns:

a string giving some information about this secret key