iaik.security.dh
Class DHPublicKey

java.lang.Object
  |
  +--iaik.x509.PublicKeyInfo
        |
        +--iaik.security.dh.DHPublicKey
All Implemented Interfaces:
ASN1Type, Cloneable, DHKey, DHPublicKey, Key, PublicKey, Serializable

public class DHPublicKey
extends PublicKeyInfo
implements DHPublicKey, Serializable

This class implements a Diffie Hellman public key and supports ASN.1 encoding. This class extends iaik.x509.PublicKeyInfo for supporting DH public keys to be used within X.509 certificates . This class implements the javax.crypto.interfaces.DHPublicKey interface for providing the functionality of a public key as used within DH key agreement.

The Diffie Hellman algorithm constitutes a key-exchange (or key-agreement) algorithm where some entities communicate according to a predescribed protocol for generating a shared secret only known by them.

The Diffie Hellman algorithm has been the first public-key algorithm. It only can be used for key-agreement, but not for data encrypting and decrypting.

PKCS#3 describes a method for implementing the Diffie Hellman key agreement where two entities use general Diffie Hellman parameters (an odd prime p, an integer base g satisfying 0 < g < p, and optionally an integer l prescribing the length of the private value), generated from some central authority (which may be an entity itself), to perform two phases of the key agreement protocol:

There may be more than only two entities involved into a Diffie Hellman key agreement.

Any application wishing to be participated into a Diffie Hellman key agreement has to instantiate the javax.crypto.KeyAgreement class and initialize it with its DHPrivateKey for bringing in the required private information. A DH Hellman private key maybe generated using a proper key pair generator, e.g.:

 KeyPairGnerator dh_key_gen = KeyPairGenerator.getInstance("DH");
 dh_key_gen.initialize(1024);
 KeyPair dh_key_pair = dh_key_gen.generateKeyPair();
 DHPrivateKey dh_priv_key = (DHPrivateKey)dh_key_pair.getPrivate();
 KeyAgreement dh_key_agreement = KeyAgreement.getInstance("DH");
 dh_key_agreement.init(dh_priv_key);
 

Each phase of a key agreement is performed by a call to the doPhase method, supplied with some other entity´s public key or some intermediate key resulting from the last phase. When calling doPhase, it has to be specified whether to perform already the last phase of the key agreement or not by setting the lastPhase parameter to true or false:

 dh_key_agreement.doPhase(dhPubKey_from_other_entity, true);
 
Actually generating the shared secret is done by calling the generateSecret method:

 byte[] shared_secret = dh_key_agreemant.generateSecret();
 

Version:
File Revision 21
See Also:
PublicKeyInfo, DHPublicKey, KeyAgreement, DHGenParameterSpec, DHParameterSpec, DHPrivateKeySpec, DHPublicKeySpec, KeyPairGenerator, KeyPair, DHPrivateKey, DHKeyPairGenerator, DHKeyFactory, DHParameters, DHParameterGenerator, DHKeyAgreement, Serialized Form

Fields inherited from class iaik.x509.PublicKeyInfo
public_key_algorithm
 
Fields inherited from interface java.security.PublicKey
serialVersionUID
 
Constructor Summary
DHPublicKey(ASN1Object obj)
          Creates a new DHPublicKey from the given ASN.1 object.
DHPublicKey(BigInteger y, DHParameterSpec parameters)
          Creates a new DHPublicKey from public key value and DH parameter specification
DHPublicKey(byte[] pk)
          Creates a new DHPublicKey from the given DER encoded byte array.
DHPublicKey(DHPublicKeySpec keySpec)
          Creates a new DHPublicKey from the given DHPublicKeySpec representing the DH public key value y, and the public values p, g and l.
DHPublicKey(InputStream is)
          Creates a new DHPublicKey from an InputStream.
 
Method Summary
protected  void decode(byte[] publicKey)
          Decodes a DHPublicKey, encoded in DER format.
protected  byte[] encode()
          Returns this DH public key as DER encoded ASN.1 object.
 String getAlgorithm()
          Returns the name of the appertaining algorithm.
 byte[] getFingerprint()
          Returns the fingerprint of this DH public key.
 DHParameterSpec getParams()
          Returns the key parameters.
 BigInteger getY()
          Returns the public value y as BigInteger.
 int hashCode()
          Returns a hash code for this object.
 String toString()
          Returns a string that represents the contents of this public key.
 
Methods inherited from class iaik.x509.PublicKeyInfo
clone, createPublicKeyInfo, decode, equals, getEncoded, getFormat, getPublicKey, getPublicKey, toASN1Object, writeTo
 
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface java.security.Key
getEncoded, getFormat
 

Constructor Detail

DHPublicKey

public DHPublicKey(BigInteger y,
                   DHParameterSpec parameters)
Creates a new DHPublicKey from public key value and DH parameter specification

Parameters:
y - the BigInteger value representing the DH public key value y
parameters - the DH parameters p (prime modulus), g (base generator) and l (length of the private value x) as DHParameterSpec
See Also:
DHParameterSpec

DHPublicKey

public DHPublicKey(DHPublicKeySpec keySpec)
Creates a new DHPublicKey from the given DHPublicKeySpec representing the DH public key value y, and the public values p, g and l.

Parameters:
keySpec - the DHPublicKeySpec representing the public key value y, the prime modulus p, the base generator g, and the length l of the private value
See Also:
DHPublicKeySpec

DHPublicKey

public DHPublicKey(byte[] pk)
            throws InvalidKeyException
Creates a new DHPublicKey from the given DER encoded byte array.

This constructor may be used for parsing an already exisiting DH public key, wrapped into a X.509 PublicKeyInfo that is supplied as DER encoded byte array.

Parameters:
the - byte array holding the DER encoded public key info
Throws:
InvalidKeyException - if something is wrong with the key encoding

DHPublicKey

public DHPublicKey(ASN1Object obj)
            throws InvalidKeyException
Creates a new DHPublicKey from the given ASN.1 object. The supplied ASN1Object represents a X.509 PublicKeyInfo holding the DH public key.

Parameters:
obj - the public key ASN.1 data structure
Throws:
InvalidKeyException - if something is wrong with the key encoding

DHPublicKey

public DHPublicKey(InputStream is)
            throws IOException,
                   InvalidKeyException
Creates a new DHPublicKey from an InputStream.

This constructor may be used for parsing an already exisiting DH public key, wrapped into a X.509 PublicKeyInfo that is supplied as DER encoded byte array.

Parameters:
is - the input stream with the data to be read to initialize the public key
Throws:
IOException - if an I/O error occurs
InvalidKeyException - if something is wrong with the key encoding
Method Detail

decode

protected void decode(byte[] publicKey)
               throws InvalidKeyException
Decodes a DHPublicKey, encoded in DER format.

From the given DER encoded byte array an ASN.1 object is created and parsed for the public key value y and the DH parameters prime p and base g, and - if included - the length l of the private value x.

This method is protected and typically will not be used by an application. Rather it is used by the parent X.509 PublicKeyInfo class for decoding the inherent DH public key.

Overrides:
decode in class PublicKeyInfo
Parameters:
publicKey - the public key as DER encoded ASN.1 object
Throws:
InvalidKeyException - if the given key is not a DH public key

encode

protected byte[] encode()
Returns this DH public key as DER encoded ASN.1 object.

This method is protected and typically will not be used by an application. Rather it is used by the parent X.509 PublicKeyInfo class for encoding the inherent DH public key.

Overrides:
encode in class PublicKeyInfo
Returns:
a byte array holding the DH public key as a DER encoded ASN.1 data structure

getAlgorithm

public String getAlgorithm()
Returns the name of the appertaining algorithm.

Specified by:
getAlgorithm in interface Key
Overrides:
getAlgorithm in class PublicKeyInfo
Returns:
the string "DH"

getY

public BigInteger getY()
Returns the public value y as BigInteger.

Specified by:
getY in interface DHPublicKey
Returns:
the public value y as BigInteger

getParams

public DHParameterSpec getParams()
Returns the key parameters.

Specified by:
getParams in interface DHKey
Returns:
the key parameters as DHParameterSpec

getFingerprint

public byte[] getFingerprint()
Returns the fingerprint of this DH public key. This is a MD5 hash of the DER encoded SubjectPublicKey.

Overrides:
getFingerprint in class PublicKeyInfo
Returns:
the fingerprint of this DH public key

hashCode

public int hashCode()
Returns a hash code for this object.
Overrides:
hashCode in class PublicKeyInfo
Returns:
the hash code

toString

public String toString()
Returns a string that represents the contents of this public key.

Overrides:
toString in class PublicKeyInfo
Returns:
the string representation

This Javadoc may contain text parts from Internet Standard specifications (RFC 2459, 3280, 3039, 2560, 1521, 821, 822, 2253, 1319, 1321, ,2630, 2631, 2268, 3058, 2984, 2104, 2144, 2040, 2311, 2279, see copyright note) and RSA Data Security Public-Key Cryptography Standards (PKCS#1,3,5,7,8,9,10,12, see copyright note).

IAIK-JCE 3.1 with IAIK-JCE CC Core 3.1, (c) 1997-2004 IAIK