iaik.security.ssl
Class PSKCredential

java.lang.Object
  extended by 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:

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
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
 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

This Javadoc may contain text parts from text parts from IETF Internet Standard specifications (see copyright note).

iSaSiLk 5.104, (c) 2002 IAIK, (c) 2003 - 2015 SIC