org.aha.u4jsp.dh
Class TwoPartyDhKeyAgreement

java.lang.Object
  org.aha.u4jsp.dh.TwoPartyDhKeyAgreement

All Implemented Interfaces:

java.io.Serializable

public final class TwoPartyDhKeyAgreement
extends java.lang.Object
implements java.io.Serializable

Object that represents data needed to set up secure communication between two parties using Diffie-Hellman secret key agreement.

This does not replace but uses the Java cryptography API class DHParameterSpec:

• Is serializable: may be of use (persistent storage) to the unit that is the centralized owner of the parameters (i.e. a server).
• Possibility to store attributes associated with the secret key agreement needed to be communicated over the net to participant (i.e. a client): server's public key and symmetric cipher parameters (the later using attributes). An example on this is the DhSecureServerProtocol that store a SymmetricCipherSpec object as an attribute that is picked up by client side DhSecureClientProtocol.

Example of use in a client / server system:

1. Server restore an object of this type from persistent storage as a serialized object (from disk, RDBMS BLOB or other) or from Java Properties using TwoPartyDhKeyAgreement(Properties). Alternatively if parameters has not been stored (i.e. the very first launch of a service or data lost) the server can create parameters using the constructors TwoPartyDhKeyAgreement() and TwoPartyDhKeyAgreement(int). The main(String[]) of this class can be used to create parameters stored in a Properties file that can be read by TwoPartyDhKeyAgreement(Properties). Since computing these parameters may take some time (in the order of a minute) it may be an advantage to prepare such a property file not on server startup time. An alternative is to use TwoPartyDhKeyAgreement(Properties) but not define any these parameters with properties, then the ones of the SKIP protocol will be used.
2. After the server has an instance of this (item 1) but before accepting any requests (part of startup) invokes generateKeyPair() to generate it's key pair.
3. A client initiate a session by first requesting the parameters of the protocol. A convenient way to serve this information is to send this serialized to the clients. Note that the server's private key property of this is not transmitted over open air since it is transient data.
4. Assuming the client receives a serialized object of this type it restores it, uses getPublicKey() to fetch the server's public key and then invokes generateKeyPair() to compute it's key pair.
5. Client uses generateSecretKey(PublicKey, String) to compute the secret key to use for encryption and decryption.
6. This class does not dictate how the client communicates it's public key to the server, but convenient way may be to include it in as plain data up front of encrypted data for each request. This implies that the server generate the secret key for each request from a given client which is convenient since the server then do not need to keep a table of secret keys mapped to live sessions which is the alternative if this is considered a to much overhead.

Resources on Diffie-Hellman key agreement:

• Examples of using the underlying Java API classes from the The Java Developers Almanac 1.4: e470. Generating a Parameter Set for the Diffie-Hellman Key Agreement Algorithm and e471. Generating a Secret Key Using the Diffie-Hellman Key Agreement Algorithm.
• The mathematical method behind the protocol on Wikipedia: Diffie-Hellman (D-H) key exchange and on MathWorld: Diffie-Hellman Protocol

Instantiating from java properties

When created from a Properties where the following properties may be defined:

Property	Description	Mandatory
u4jsp.crypto.dh-g	The base generator g used.	Only if u4jsp.crypto.dh-p is given: if none of the Diffie-Hellman key agreement parameters are given those of the SKIP protocol are used.
u4jsp.crypto.dh-p	The prime modulus p used.	Only if u4jsp.crypto.dh-g is given: if none of the Diffie-Hellman key agreement parameters are given those of the SKIP protocol are used.

This class' main program can be used to generate the Diffie-Hellman parameters in a property file as described above, this may be a convenient way to start making a properties file for server side protocol persistence.

Author:

Arne Halvorsen (AHA) arne.halvorsen@gmail.com

See Also:

DHParameterSpec, KeyAgreement, KeyPairGenerator, PrivateKey, PublicKey, Serialized Form

Constructor Summary

TwoPartyDhKeyAgreement()
Creates parameters using a bit size of 1024.

TwoPartyDhKeyAgreement(java.math.BigInteger p, java.math.BigInteger g)
Constructor.

TwoPartyDhKeyAgreement(javax.crypto.spec.DHParameterSpec s)
Constructor.

TwoPartyDhKeyAgreement(int size)
Constructor.

TwoPartyDhKeyAgreement(java.util.Properties props)
Constructor.

TwoPartyDhKeyAgreement(java.lang.String p, java.lang.String g)
Constructor.

Method Summary

void	generateKeyPair() Generates a public key / private key pair using this set of parameters.
javax.crypto.SecretKey	generateSecretKey(java.security.PublicKey otherPk, java.lang.String cipher) Generates secret key given other party's public key and name on symmetric cipher to be used for data encryption/decryption.
java.util.Properties	getAsProperties() Return as properties getP(), getG().
java.util.Properties	getAsProperties(java.util.Properties props) Return as properties getP(), getG().
java.lang.Object	getAttribute(java.lang.String name) Gets attribute value.
java.math.BigInteger	getG() Gets the base generator g.
java.math.BigInteger	getP() Gets the prime modulus p.
java.security.PrivateKey	getPrivateKey() Gets the private key generated by generateKeyPair().
java.security.PublicKey	getPublicKey() Gets the public key generated by generateKeyPair().
javax.crypto.spec.DHParameterSpec	getSpec() Gets the DHParameterSpec representing the parameters needed as input to Java cryptographic methods.
static void	main(java.lang.String[] args) Program that can be used to create a property file with newly generated Diffie-Helmann key agreement parameters that TwoPartyDhKeyAgreement(Properties) accepts.
void	removeAttribute(java.lang.String name) Removes attribute.
void	setAttribute(java.lang.String name, java.lang.Object value) Sets attribute value.
java.lang.String	toString()

Methods inherited from class java.lang.Object

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

Constructor Detail

TwoPartyDhKeyAgreement

public TwoPartyDhKeyAgreement(javax.crypto.spec.DHParameterSpec s)

Constructor.

Parameters:

s - Specification to get parameters from.

TwoPartyDhKeyAgreement

public TwoPartyDhKeyAgreement(java.lang.String p,
                              java.lang.String g)

Constructor.

Parameters:

p - getP()'s String representation.

g - getG()'s String representation.

TwoPartyDhKeyAgreement

public TwoPartyDhKeyAgreement(java.math.BigInteger p,
                              java.math.BigInteger g)

Constructor.

Parameters:

p - getP().

g - getG().

TwoPartyDhKeyAgreement

public TwoPartyDhKeyAgreement()

Creates parameters using a bit size of 1024.

TwoPartyDhKeyAgreement

public TwoPartyDhKeyAgreement(int size)

Constructor.

Parameters:

size - The number of bits.

Throws:

java.lang.IllegalArgumentException - If size<1.

TwoPartyDhKeyAgreement

public TwoPartyDhKeyAgreement(java.util.Properties props)

Constructor.

See here for the properties that may be defined that are specific for the Diffie-Hellman key agreement protocol.

Parameters:

props - Properties to construct from as produced by getAsProperties().

Throws:

java.lang.IllegalArgumentException - If does not accept props.

See Also:

getAsProperties()

Method Detail

getP

public java.math.BigInteger getP()

Gets the prime modulus p.

Returns:

Prime modulus p.

getG

public java.math.BigInteger getG()

Gets the base generator g.

Returns:

Base generator g.

getSpec

public javax.crypto.spec.DHParameterSpec getSpec()

Gets the DHParameterSpec representing the parameters needed as input to Java cryptographic methods.

Returns:

DHParameterSpec.

generateKeyPair

public void generateKeyPair()

Generates a public key / private key pair using this set of parameters.

If pair has been generated this method does nothing.

See Also:

getPublicKey(), getPrivateKey()

getPublicKey

public java.security.PublicKey getPublicKey()

Gets the public key generated by generateKeyPair().

Returns:

PublicKey or null if generateKeyPair() has never been invoked.

See Also:

generateKeyPair(), getPrivateKey()

getPrivateKey

public java.security.PrivateKey getPrivateKey()

Gets the private key generated by generateKeyPair().

Note that this property is transient: It will not be serialized since this information is not to be send over insecure line and the main use of the serializable feature is to send this over a insecure line.

Returns:

PrivateKey or null if generateKeyPair() has never been invoked.

See Also:

generateKeyPair(), getPublicKey()

setAttribute

public void setAttribute(java.lang.String name,
                         java.lang.Object value)

Sets attribute value.

Parameters:

name - Attribute name.

value - Attribute value. May not be null, use removeAttribute(String) to remove.

Throws:

java.lang.IllegalArgumentException - If value is not serializable.

getAttribute

public java.lang.Object getAttribute(java.lang.String name)

Gets attribute value.

Parameters:

name - Attribute name.

Returns:

Value or null if not found.

removeAttribute

public void removeAttribute(java.lang.String name)

Removes attribute.

Parameters:

name - Attribute name.

getAsProperties

public java.util.Properties getAsProperties()

Return as properties getP(), getG().

Returns:

Properties.

See Also:

TwoPartyDhKeyAgreement(Properties)

getAsProperties

public java.util.Properties getAsProperties(java.util.Properties props)

Return as properties getP(), getG().

Parameters:

props - Optional Properties to store in, if null allocates.

Returns:

Properties.

See Also:

TwoPartyDhKeyAgreement(Properties)

generateSecretKey

public javax.crypto.SecretKey generateSecretKey(java.security.PublicKey otherPk,
                                                java.lang.String cipher)

Generates secret key given other party's public key and name on symmetric cipher to be used for data encryption/decryption.

In the case that this party's private key has not been generated this method does so by invoking generateKeyPair().

Parameters:

otherPk - Other party's public key.

cipher - Cipher algorithm name.

Returns:

Generated.

Throws:

java.lang.IllegalArgumentException - If cipher does not identify an symmetric cipher algorithm through KeyAgreement.generateSecret().

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

main

public static void main(java.lang.String[] args)

Program that can be used to create a property file with newly generated Diffie-Helmann key agreement parameters that TwoPartyDhKeyAgreement(Properties) accepts.

Accepts command line options:

Option	Description	Mandatory
-verbose	Prints to standard out generated Diffie-Hellman key agreement parameters.	No
-size <size>	The number of bits.	No, default value is 1024.
-file <path>	File to write to. If file exists properties will be loaded first and written again. Note that any existing properties named U4jspNames.DH_P, U4jspNames.DH_G will get new values since these are the Diffie-Hellman key agreement parameters.	No, if missing a file named security.properties is produced in current directory.

Parameters:

args - Command line arguments, see above table.