org.openuat.authentication
Class SimpleKeyAgreement

java.lang.Object
  org.openuat.authentication.SimpleKeyAgreement

public class SimpleKeyAgreement
extends java.lang.Object

This class implements a simple key agreement protocol. Simple refers to the interface of this class, not its security. For a complete key agreement, the caller is expected to initialize the object, transmit the public key to the remote host, receive the remote public key and add it to this agreements and then get the shared authentication and session keys. Each caller is expected to handle the transmitted public keys and especially the private keys with care and not leak it to an outside class. The steps must be done in exactly this order or a KeyAgreementProtocolException will be thrown.

Version:

1.1, changes to 1.0: Now supports re-using the local key pair for subsequent key agreement runs. The instance needs to be constructed for this, though (by setting the flag to true).

Author:

Rene Mayrhofer

Field Summary

static java.math.BigInteger	skip1024Base The base used with the SKIP 1024 bit modulus
static java.math.BigInteger	skip1024Modulus The SKIP 1024 bit modulus.

Constructor Summary

SimpleKeyAgreement(boolean useJSSE)
Initialized a fresh key agreement, simply by calling init().

SimpleKeyAgreement(boolean useJSSE, boolean permanentLocalKeyPair)
Initialized a fresh key agreement, simply by calling init().

SimpleKeyAgreement(byte[] localKeyPair)

Method Summary

void	addRemotePublicKey(byte[] key) Add the remote public key.
byte[]	getAuthenticationKey() This method can only be called in state completed.
byte[]	getPublicKey() Get the public key for the key agreement protocol.
byte[]	getSessionKey() This method can only be called in state completed.
void	init(boolean useJSSE) Initializes the random nonce of this side for generating the shared session key.
void	resetRemotePart() This resets the remote parts (if they have already been added) so that another round can be started with the same local key pair.
byte[]	storeLocalKeyPair()
void	wipe() This method performs a secure wipe of the cryptographic key material held by this class by overwriting the memory regions with zero before freeing them (i.e. handing them over to the garbage collector, which might free them at an unpredictable time later, marking them for overwrite at an even later time).

Methods inherited from class java.lang.Object

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

Field Detail

skip1024Modulus

public static final java.math.BigInteger skip1024Modulus

The SKIP 1024 bit modulus. This is only a BigInterger representation of skip1024ModulusBytes, but kept for performance reasons.

skip1024Base

public static final java.math.BigInteger skip1024Base

The base used with the SKIP 1024 bit modulus

Constructor Detail

SimpleKeyAgreement

public SimpleKeyAgreement(boolean useJSSE,
                          boolean permanentLocalKeyPair)
                   throws InternalApplicationException

Initialized a fresh key agreement, simply by calling init().

Parameters:

useJSSE - If set to true, the JSSE API with the default JCE provider of the JVM will be used for cryptographic operations. If set to false, an internal copy of the Bouncycastle Lightweight API classes will be used.

permanentLocalKeyPair - Is set to true, then a few checks are relaxed and the same key agreement instance may be used for multiple Diffie-Hellman rounds with different remote public keys. Before a second key agreement round can be started, resetRemotePart() must be called. This option should be used only in special circumstances when ephemeral keys can not be supported!

Throws:

InternalApplicationException

See Also:

init(boolean)

SimpleKeyAgreement

public SimpleKeyAgreement(boolean useJSSE)
                   throws InternalApplicationException

Initialized a fresh key agreement, simply by calling init().

Parameters:

useJSSE - If set to true, the JSSE API with the default JCE provider of the JVM will be used for cryptographic operations. If set to false, an internal copy of the Bouncycastle Lightweight API classes will be used.

Throws:

InternalApplicationException

See Also:

init(boolean)

SimpleKeyAgreement

public SimpleKeyAgreement(byte[] localKeyPair)

Method Detail

storeLocalKeyPair

public byte[] storeLocalKeyPair()

init

public void init(boolean useJSSE)
          throws InternalApplicationException

Initializes the random nonce of this side for generating the shared session key. This method can be called in any state and wipes all old values (by calling wipe()).

Parameters:

useJSSE - If set to true, the JSSE API with the default JCE provider of the JVM will be used for cryptographic operations. If set to false, an internal copy of the Bouncycastle Lightweight API classes will be used.

Throws:

InternalApplicationException

See Also:

wipe()

wipe

public void wipe()

This method performs a secure wipe of the cryptographic key material held by this class by overwriting the memory regions with zero before freeing them (i.e. handing them over to the garbage collector, which might free them at an unpredictable time later, marking them for overwrite at an even later time). More specifically, it wipes sharedKey, myKeypair and dh. TODO: This method is not yet secure! It can't access the internal data structures of myKeypair and dh, which do not offer wipe methods themselves.

See Also:

sharedKey, myKeypair, dh

resetRemotePart

public void resetRemotePart()
                     throws KeyAgreementProtocolException,
                            InternalApplicationException

This resets the remote parts (if they have already been added) so that another round can be started with the same local key pair. Calling this method is only supported when this instance has been constructed with permanentLocalKeyPair=true.

Throws:

KeyAgreementProtocolException

InternalApplicationException

getPublicKey

public byte[] getPublicKey()
                    throws KeyAgreementProtocolException

Get the public key for the key agreement protocol. This byte array should be transmitted to the remote side. This method can only be called in state initialized and changes it to inTransit.

Throws:

KeyAgreementProtocolException

addRemotePublicKey

public void addRemotePublicKey(byte[] key)
                        throws KeyAgreementProtocolException,
                               InternalApplicationException

Add the remote public key. This method can only be called in state inTransmit and changes it to completed.

Throws:

KeyAgreementProtocolException

InternalApplicationException

getSessionKey

public byte[] getSessionKey()
                     throws KeyAgreementProtocolException,
                            InternalApplicationException

This method can only be called in state completed. The returned session key must only be used for deriving authentication and encryption keys, e.g. as a PSK for IPSec. It must _not_ be used directly for authentication, since this could leak the encryption key to any attacker if the authentication function is not strong enough.

Throws:

KeyAgreementProtocolException

InternalApplicationException

getAuthenticationKey

public byte[] getAuthenticationKey()
                            throws KeyAgreementProtocolException,
                                   InternalApplicationException

This method can only be called in state completed. The returned key should be used for the initial authentication phase, but must _not_ be used for deriving other channel authentication and encryption keys. It is derived from the same base as the key returned by getSessionKey, and one can thus assume that if this key is equal on both sides, then both sides also share the same session key.

Throws:

KeyAgreementProtocolException

InternalApplicationException