ESDHPublicKey ("Entrust Authority Security Toolkit for the Java Platform")

java.lang.Object
- iaik.x509.PublicKeyInfo
- - iaik.security.dh.ESDHPublicKey

All Implemented Interfaces:

ASN1Type, java.io.Serializable, java.security.Key, java.security.PublicKey, javax.crypto.interfaces.DHKey, javax.crypto.interfaces.DHPublicKey
```
public class ESDHPublicKey
extends PublicKeyInfo
implements javax.crypto.interfaces.DHPublicKey, java.io.Serializable
```
This class implements a Diffie Hellman public key and supports ASN.1 encoding. This class extends iaik.x509.PublicKeyInfo for supporting ESDH 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 ESDH 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:
- The first phase is performed independently by the two entities involved in the key agreement and uses the Diffie Hellman parameters derived from the central authority to randomly generate a private integer value x satisfying 0 < x < p-1. If the central authority has prescribed the length l of the private value x, it has to fulfill 2^(l-1) <= x < 2^l. From the private value, the public value y is created by doing y = (g^x)(mod p) with 0 < y < p. Subsequently each entity sends the public value just created to the other entity involved in the key agreement.
- The second phase again is performed independently by the two entities involved in the key agreement and uses the Diffie Hellman parameters derived from the central authority and the public value y' received from the other entity to finally create the shared secret z from the own private value x: z = (y'^x)(mod p) with 0 < z < p.
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 ESDHPrivateKey for bringing in the required private information. A ESDH Hellman private key maybe generated using a proper key pair generator, e.g.:
```
 KeyPairGnerator dh_key_gen = KeyPairGenerator.getInstance("ESDH");
 dh_key_gen.initialize(1024);
 KeyPair dh_key_pair = dh_key_gen.generateKeyPair();
 ESDHPrivateKey dh_priv_key = (ESDHPrivateKey)dh_key_pair.getPrivate();
 KeyAgreement dh_key_agreement = KeyAgreement.getInstance("ESDH");
 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();
 
```
See Also:

PublicKeyInfo, DHPublicKey, KeyAgreement, ESDHParameterSpec, ESDHPrivateKeySpec, ESDHPublicKeySpec, KeyPairGenerator, KeyPair, ESDHPrivateKey, ESDHKeyPairGenerator, ESDHKeyFactory, ESDHParameters, ESDHParameterGenerator, ESDHKeyAgreement, Serialized Form

Field Summary
- Fields inherited from class iaik.x509.PublicKeyInfo
  public_key_algorithm
- Fields inherited from interface javax.crypto.interfaces.DHPublicKey
  serialVersionUID

Constructor Summary

Constructors
Constructor and Description
`ESDHPublicKey(ASN1Object obj)` Creates a new ESDHPublicKey from the given ASN.1 object.
`ESDHPublicKey(java.math.BigInteger y, ESDHParameterSpec parameters)` Creates a new ESDHPublicKey from public key value and ESDH parameter specification
`ESDHPublicKey(byte[] pk)` Creates a new ESDHPublicKey from the given DER encoded byte array.
`ESDHPublicKey(ESDHPublicKeySpec keySpec)` Creates a new ESDHPublicKey from the given ESDHPublicKeySpec representing the ESDH public key value y, and the values p, g, q, j (if available) and seed and pgenCounter (if available).
`ESDHPublicKey(java.io.InputStream is)` Creates a new ESDHPublicKey from an InputStream.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`protected void`	`decode(byte[] publicKey)` Decodes an ESDHPublicKey, encoded in DER format.
`protected byte[]`	`encode()` Returns this ESDH public key as DER encoded ASN.1 object.
`java.lang.String`	`getAlgorithm()` Returns the name of the appertaining algorithm.
`byte[]`	`getFingerprint()` Returns the fingerprint of this ESDH public key.
`javax.crypto.spec.DHParameterSpec`	`getParams()` Returns the key parameters.
`java.math.BigInteger`	`getY()` Returns the public value `y` as BigInteger.
`int`	`hashCode()` Returns a hash code for this object.
`java.lang.String`	`toString()` Returns a string that represents the contents of this public key.

Methods inherited from class iaik.x509.PublicKeyInfo
createPublicKeyInfo, decode, equals, getEncoded, getFormat, getPublicKey, getPublicKey, toASN1Object, writeTo

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.security.Key
getEncoded, getFormat

- Constructor Detail
  - ESDHPublicKey
```
public ESDHPublicKey(java.math.BigInteger y,
                     ESDHParameterSpec parameters)
```
    Creates a new ESDHPublicKey from public key value and ESDH parameter specification
    
    Parameters:
    
    y - the BigInteger value representing the ESDH public key value y
    
    parameters - the ESDH parameters p (prime modulus), g (base generator), prime factor q, the subgroup factor j (if available) and the seed seed and pgenCounter pgenCounter (if available) as ESDHParameterSpec
    
    See Also:
    
    ESDHParameterSpec
  - ESDHPublicKey
```
public ESDHPublicKey(ESDHPublicKeySpec keySpec)
```
    Creates a new ESDHPublicKey from the given ESDHPublicKeySpec representing the ESDH public key value y, and the values p, g, q, j (if available) and seed and pgenCounter (if available).
    
    Parameters:
    
    keySpec - the ESDHPublicKeySpec representing the public key value y, the prime modulus p, the base generator g, the subgroup factor j (if available) and the seed seed and pgenCounter pgenCounter (if available)
    
    See Also:
    
    ESDHPublicKeySpec
  - ESDHPublicKey
```
public ESDHPublicKey(byte[] pk)
              throws java.security.InvalidKeyException
```
    Creates a new ESDHPublicKey from the given DER encoded byte array.
    This constructor may be used for parsing an already exisiting ESDH public key, wrapped into a X.509 PublicKeyInfo that is supplied as DER encoded byte array.
    
    Parameters:
    
    pk - the byte array holding the DER encoded public key info
    
    Throws:
    
    java.security.InvalidKeyException - if something is wrong with the key encoding
  - ESDHPublicKey
```
public ESDHPublicKey(ASN1Object obj)
              throws java.security.InvalidKeyException
```
    Creates a new ESDHPublicKey from the given ASN.1 object. The supplied ASN1Object represents a X.509 PublicKeyInfo holding the ESDH public key.
    
    Parameters:
    
    obj - the public key ASN.1 data structure
    
    Throws:
    
    java.security.InvalidKeyException - if something is wrong with the key encoding
  - ESDHPublicKey
```
public ESDHPublicKey(java.io.InputStream is)
              throws java.io.IOException,
                     java.security.InvalidKeyException
```
    Creates a new ESDHPublicKey from an InputStream.
    This constructor may be used for parsing an already exisiting ESDH 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:
    
    java.io.IOException - if an I/O error occurs
    
    java.security.InvalidKeyException - if something is wrong with the key encoding
- Method Detail
  - decode
```
protected void decode(byte[] publicKey)
               throws java.security.InvalidKeyException
```
    Decodes an ESDHPublicKey, 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 ESDH parameters prime p and base g, prime factor q, the subgroup factor j (if available) and the seed seed and pgenCounter pgenCounter (if available).
    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 ESDH public key.
    
    Specified by:
    
    decode in class PublicKeyInfo
    
    Parameters:
    
    publicKey - the public key as DER encoded ASN.1 object
    
    Throws:
    
    java.security.InvalidKeyException - if the given key is not a ESDH public key
  - encode
```
protected byte[] encode()
```
    Returns this ESDH 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 ESDH public key.
    
    Specified by:
    
    encode in class PublicKeyInfo
    
    Returns:
    
    a byte array holding the ESDH public key as a DER encoded ASN.1 data structure
  - getAlgorithm
```
public java.lang.String getAlgorithm()
```
    Returns the name of the appertaining algorithm.
    
    Specified by:
    
    getAlgorithm in interface java.security.Key
    
    Specified by:
    
    getAlgorithm in class PublicKeyInfo
    
    Returns:
    
    the string "ESDH"
  - getY
```
public java.math.BigInteger getY()
```
    Returns the public value y as BigInteger.
    
    Specified by:
    
    getY in interface javax.crypto.interfaces.DHPublicKey
    
    Returns:
    
    the public value y as BigInteger
  - getParams
```
public javax.crypto.spec.DHParameterSpec getParams()
```
    Returns the key parameters.
    
    Specified by:
    
    getParams in interface javax.crypto.interfaces.DHKey
    
    Returns:
    
    the key parameters as ESDHParameterSpec
  - getFingerprint
```
public byte[] getFingerprint()
```
    Returns the fingerprint of this ESDH public key. This is a MD5 hash of the DER encoded SubjectPublicKey.
    
    Overrides:
    
    getFingerprint in class PublicKeyInfo
    
    Returns:
    
    the fingerprint of this ESDH public key
  - hashCode
```
public int hashCode()
```
    Returns a hash code for this object.
    
    Overrides:
    
    hashCode in class java.lang.Object
    
    Returns:
    
    the hash code
  - toString
```
public java.lang.String toString()
```
    Returns a string that represents the contents of this public key.
    
    Overrides:
    
    toString in class PublicKeyInfo
    
    Returns:
    
    the string representation

Class ESDHPublicKey

Field Summary

Fields inherited from class iaik.x509.PublicKeyInfo

Fields inherited from interface javax.crypto.interfaces.DHPublicKey

Constructor Summary

Method Summary

Methods inherited from class iaik.x509.PublicKeyInfo

Methods inherited from class java.lang.Object

Methods inherited from interface java.security.Key

Constructor Detail

ESDHPublicKey

ESDHPublicKey

ESDHPublicKey

ESDHPublicKey

ESDHPublicKey

Method Detail

decode

encode

getAlgorithm

getY

getParams

getFingerprint

hashCode

toString