iaik.security.ssl

Class PSKCredential

java.lang.Object

iaik.security.ssl.PSKCredential

All Implemented Interfaces:

java.lang.Cloneable

public class PSKCredential
extends java.lang.Object
implements java.lang.Cloneable

This class represents a PSKCredential for use with PSK (pre-shared key) based cipher suites ( RFC 4279).

A PSK Credential associates a pre-shared key with identity, identity hint and remote peer id:

• The psk identity is used to uniquely identify the pre-shared key. If client and server have agreed on using a psk cipher suite, the client sends the psk identity within the ClientKeyExchange message to server to tell the server which pre-shared key shall be used for authenticating the TLS session. The handshake can proceed if the server has a has a pre-shared key for the received identity, otherwise the handshake will fail.

  When creating a PSKCredential the psk identity has to be specified as String or as byte array. If given as byte array, it has to represent the UTF-8 encoding of the identity String name. For instance, client "pskclient.iaik.at" and server "pskserver.iaik.tugraz.at" may have agreed on a pre-shared key that shall be identified by the name of the client. Both client and server can create the required PSKCredential in the same way by using "pskclient.iaik.tugraz.at" as identity String:

          // psk identity
          String identity = "pskclient.iaik.tugraz.at";
          // the pre-shared key
          PreSharedKey psk = ...;
          // create PSKCredential
          PSKCredential pskCredential = new PSKCredential(identity, psk);
          

• A psk identity hint maybe sent in the ServerKeyExchange message from the server to the client to help the client in selecting a pre-shared key for authenticating the TLS session. When setting a psk identity hint for a PSKCedential it has to be specified as String or as byte array. If given as byte array, it has to represent the UTF-8 encoding of the identity String name. However, please note that 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).
• A remote peer id maybe required to tell the PSKCredential the peer to which to authenticate with the pre-shared key of the credential. For instance, if we are on the client side and want to use the PSKCredential from above for a TLS communication with server "pskserver.iaik.tugraz.at", we may have to specify "pskserver.iaik.tugraz.at" as remote peer id for the psk credential:

          pskCredential.setRemotePeerId("pskserver.iaik.tugraz.at");
          

  Specifying a remote peer id for a PSKCredential is required by the PSKManager who is responsible for pre-shared key management (see below).

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 the client can use it for authenticating the TLS session with this server. Note, that you can disable the PSKManager at all by using method setPSKCredential for specifying an exclusive PSKCredential to be used only with some specific SSLContext. This may be suitable on the client side: since you already know the server when creating the SSLClientContext you also will know the pre-shared key to be used for establishing a TLS-PSK session with this server. Thus you may not neet a PSKManager and may explicitly set the corresponding PSKCredential to be used with this specific SSLClientContext. However, be careful to use setPSKCredential on the server side. In this case your server will only have one single pre-shared key to be used with any client that requests a PSK based TLS communication.

On the server side a remote peer id for a PSKCredential is only required when the server wants to send a psk identity hint to the client. However, usage of psk identity hints is not recommended by the TLS-PSK specification.

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:

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

Constructor Summary

Constructors

Constructor and Description
PSKCredential(byte[] identity, javax.crypto.SecretKey psk) Creates a PSKCredential with the given identity and pre-shared key.
PSKCredential(java.lang.String identity, javax.crypto.SecretKey psk) Creates a PSKCredential with given identity and pre-shared key.

Method Summary

Modifier and Type	Method and Description
java.lang.Object	clone() Returns a clone of this PSKCredential.
boolean	equals(java.lang.Object obj) Compares this PSKCredential with the given object.
byte[]	getIdentity() Gets the PSK identity of this PSKCredential.
byte[]	getIdentityHint() Gets the PSK identity hint of this PSKCredential.
java.lang.String	getIdentityHintString() Gets the PSK identity hint as String.
java.lang.String	getIdentityString() Gets the PSK identity as String.
javax.crypto.SecretKey	getPSK() Gets the pre-shared key.
java.lang.Object	getRemotePeerId() Gets the remote peer id associated with this PSKCredential.
int	hashCode() Returns a hashcode for this object.
void	setIdentityHint(byte[] identityHint) Sets the identity hint for this PSKCredential.
void	setIdentityHint(java.lang.String identityHint) Sets the identity hint for this PSKCredential.
void	setRemotePeerId(java.lang.Object peerId) Associates this PSKCredential with the given remote peer id.
java.lang.String	toString() Gets a String representation of this PSKCredential.

Methods inherited from class java.lang.Object

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

Constructor Detail

PSKCredential

public PSKCredential(byte[] identity,
                     javax.crypto.SecretKey psk)
              throws java.lang.IllegalArgumentException,
                     java.io.UnsupportedEncodingException

Creates a PSKCredential with the given identity and pre-shared key.
The given identity shall be the UTF-8 encoded PSK Identity String. The pre-shared key is not cloned.

Parameters:

identity - the (UTF-8 encoded) PSK idendity (the identity byte array is not cloned or copied by this method)

psk - the pre-shared key

Throws:

java.lang.IllegalArgumentException - if the given identity is null or the given identity is too long (> 2^16-1)

java.io.UnsupportedEncodingException - if the given identity cannot be UTF-8 decoded

PSKCredential

public PSKCredential(java.lang.String identity,
                     javax.crypto.SecretKey psk)
              throws java.lang.IllegalArgumentException,
                     java.io.UnsupportedEncodingException

Creates a PSKCredential with given identity and pre-shared key. The pre-shared key is not cloned.

Parameters:

identity - the PSK idendity

psk - the pre-shared key

Throws:

java.lang.IllegalArgumentException - if the given identity is null or the given identity is to long (> 2^16-1)

java.io.UnsupportedEncodingException - if the given identity cannot be UTF-8 encoded

Method Detail

setIdentityHint

public void setIdentityHint(byte[] identityHint)
                     throws java.lang.IllegalArgumentException,
                            java.io.UnsupportedEncodingException

Sets the identity hint for this PSKCredential.

An identity hint may be sent by the server to help the client in selecting the pre-shared key to be used. Note that the TLS-PSK specification (RFC 4279) does NOT recommend to use a psk identity hint. Unless not explicitly required by the application environment, the server SHOULD NOT send a psk identity hint, and the client MUST ignore a psk identity hint if sent by the server.
The given identity hint shall be the UTF-8 encoded PSK Identity Hint String.

Parameters:

identityHint - the (UTF-8 encoded) PSK idendity hint (the identityHint array is not cloned or copied by this method)

Throws:

java.lang.IllegalArgumentException - if the given identity hint is to long (> 2^16-1)

java.io.UnsupportedEncodingException - if the given identity hint cannot be UTF-8 decoded

setIdentityHint

public void setIdentityHint(java.lang.String identityHint)
                     throws java.lang.IllegalArgumentException,
                            java.io.UnsupportedEncodingException

Sets the identity hint for this PSKCredential.

An identity hint may be sent by the server to help the client in selecting the pre-shared key to be used. Note that the TLS-PSK specification (RFC 4279) does NOT recommend to use a psk identity hint. Unless not explicitly required by the application environment, the server SHOULD NOT send a psk identity hint, and the client MUST ignore a psk identity hint if sent by the server.

Parameters:

identityHint - the PSK idendity hint (as String)

Throws:

java.lang.IllegalArgumentException - if the given identity hint is to long (> 2^16-1)

java.io.UnsupportedEncodingException - if the given identity hint cannot be UTF-8 encoded

setRemotePeerId

public void setRemotePeerId(java.lang.Object peerId)

Associates this PSKCredential with the given remote peer id. The given peerId (if not null) identifies the peer for which the pre-shared key(s) of this PSKCredential shall be used to authenticate a psk cipher suite based TLS session.

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 set "pskserver.iaik.tugraz.at" as remote peer id:

 // 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();
 ...
 

Parameters:

peerId - the id of the peer for which the pre-shared key(s) of this PSKCredential shall be used

getPSK

public javax.crypto.SecretKey getPSK()

Gets the pre-shared key.

Returns:

the pre-shared key of this PSKCredential

getIdentity

public byte[] getIdentity()

Gets the PSK identity of this PSKCredential.

The psk identity is used to uniquely identify the pre-shared key. If client and server have agreed on using a psk cipher suite, the client sends the psk identity within the ClientKeyExchange message to server to tell the server which pre-shared key shall be used for authenticating the TLS session. The handshake can proceed if the server has a has a pre-shared key for the received identity, otherwise the handshake will fail.

When creating a PSKCredential the psk identity has to be specified as String or as byte array. If given as byte array, it has to represent the UTF-8 encoding of the identity String name. For instance, client "pskclient.iaik.at" and server "pskserver.iaik.tugraz.at" may have agreed on a pre-shared key that shall be identified by the name of the client. Both client and server can create the required PSKCredential in the same way by using "pskclient.iaik.tugraz.at" as identity String:

 // psk identity
 String identity = "pskclient.iaik.tugraz.at";
 // create PSKCredential
 PSKCredential pskCredential = new PSKCredential(identity);
 

Returns:

the PSK identity

getIdentityString

public java.lang.String getIdentityString()

Gets the PSK identity as String.

Returns:

the PSK identity as String

See Also:

getIdentity()

getIdentityHint

public byte[] getIdentityHint()

Gets the PSK identity hint of this PSKCredential.

Returns:

the PSK identity hint or null if no psk identity hint has been set

See Also:

setIdentityHint(byte[])

getIdentityHintString

public java.lang.String getIdentityHintString()

Gets the PSK identity hint as String.

Returns:

the PSK identity hint as String or null if no psk identity hint has been set

See Also:

setIdentityHint(String)

getRemotePeerId

public java.lang.Object getRemotePeerId()

Gets the remote peer id associated with this PSKCredential. The peer id (if set identifies the peer for which the pre-shared key(s) of this PSKCredential shall be used to authenticate a psk cipher suite based TLS session.

Returns:

the id of the peer for which the pre-shared key(s) of this PSKCredential shall be used; or null if no peer id is set for this PSKCredential

See Also:

setRemotePeerId(java.lang.Object)

equals

public boolean equals(java.lang.Object obj)

Compares this PSKCredential with the given object.

Overrides:

equals in class java.lang.Object

Parameters:

obj - an object to be compared with this PSKCredential

Returns:

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

hashCode

public int hashCode()

Returns a hashcode for this object.

Overrides:

hashCode in class java.lang.Object

Returns:

the hashcode

clone

public java.lang.Object clone()

Returns a clone of this PSKCredential.

Overrides:

clone in class java.lang.Object

Returns:

a clone

toString

public java.lang.String toString()

Gets a String representation of this PSKCredential.

Overrides:

toString in class java.lang.Object

Returns:

a String giving some information about this PSKCredential