KeyAgreement (Java Card API, Connected Edition)
Date: 2009-12-11

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## javacard.security
Class KeyAgreement

    java.lang.Object
      javacard.security.KeyAgreement

    @TransactionType(value=SUPPORTS)
    public abstract class KeyAgreement

extends Object

The `KeyAgreement` class is the base class for key agreement algorithms such as Diffie-Hellman and EC Diffie-Hellman [IEEE P1363]. Implementations of `KeyAgreement` algorithms must extend this class and implement all the abstract methods. A tear or card reset event resets an initialized `KeyAgreement` object to the state it was in when previously initialized via a call to `init()`.

Since:
  Java Card 2.x, Java Card 3.0

Field Summary
`static byte` | `ALG_EC_SVDP_DH` Elliptic curve secret value derivation primitive, Diffie-Hellman version, as per [IEEE P1363].
`static byte` | `ALG_EC_SVDP_DH_KDF` Elliptic curve secret value derivation primitive, Diffie-Hellman version, as per [IEEE P1363].
`static byte` | `ALG_EC_SVDP_DH_PLAIN` Elliptic curve secret value derivation primitive, Diffie-Hellman version, as per [IEEE P1363].
`static byte` | `ALG_EC_SVDP_DHC` Elliptic curve secret value derivation primitive, Diffie-Hellman version, with cofactor multiplication, as per [IEEE P1363].
`static byte` | `ALG_EC_SVDP_DHC_KDF` Elliptic curve secret value derivation primitive, Diffie-Hellman version, with cofactor multiplication, as per [IEEE P1363].
`static byte` | `ALG_EC_SVDP_DHC_PLAIN` Elliptic curve secret value derivation primitive, Diffie-Hellman version, with cofactor multiplication, as per [IEEE P1363].
`static String` | `SERVICE_NAME` This cryptographic service name, as used to lookup implemented algorithms.

Constructor Summary
`protected` | `KeyAgreement()` Protected constructor.

Method Summary
`abstract short` | `generateSecret(byte[] publicData, short publicOffset, short publicLength, byte[] secret, short secretOffset)` Generates the secret data as per the requested algorithm using the `PrivateKey` specified during initialization and the public key data provided.
`abstract byte` | `getAlgorithm()` Gets the KeyAgreement algorithm.
`abstract String` | `getAlgorithmName()` Gets the KeyAgreement algorithm name.
`static KeyAgreement` | `getInstance(byte algorithm, boolean externalAccess)` Creates a `KeyAgreement` object instance of the selected algorithm.
`static KeyAgreement` | `getInstance(String algorithm, boolean externalAccess)` Creates a `KeyAgreement` object instance of the selected algorithm.
`static KeyAgreement` | `getInstance(String algorithm, String provider, boolean externalAccess)` Creates a `KeyAgreement` object instance of the selected algorithm.
`abstract void` | `init(PrivateKey privKey)` Initializes the object with the given private key.

Methods inherited from class java.lang.Object
`equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### SERVICE_NAME

    public static final String SERVICE_NAME

  This cryptographic service name, as used to lookup implemented algorithms.

  Since:
    Java Card 3.0
  See Also:
    Constant Field Values

### ALG_EC_SVDP_DH

    public static final byte ALG_EC_SVDP_DH

  Elliptic curve secret value derivation primitive, Diffie-Hellman version, as per [IEEE P1363].

  Note:

  - This algorithm computes the SHA-1 message digest of the output of the derivation primitive to yeild a 20 byte result.
  - A call to the getAlgorithm() method of an instance implementing this algorithm returns "EC_SVDP_DH_KDF".

  The `String` name equivalent to this algorithm type to use as parameter to the `getInstance(String algorithm, ...)` method is `"EC_SVDP_DH_KDF"`

  See Also:
    Constant Field Values

### ALG_EC_SVDP_DH_KDF

    public static final byte ALG_EC_SVDP_DH_KDF

  Elliptic curve secret value derivation primitive, Diffie-Hellman version, as per [IEEE P1363].

  Note:

  - This algorithm computes the SHA-1 message digest of the output of the derivation primitive to yeild a 20 byte result.

  The `String` name equivalent to this algorithm type to use as parameter to the `getInstance(String algorithm, ...)` method is `"EC_SVDP_DH_KDF"`

  See Also:
    Constant Field Values

### ALG_EC_SVDP_DHC

    public static final byte ALG_EC_SVDP_DHC

  Elliptic curve secret value derivation primitive, Diffie-Hellman version, with cofactor multiplication, as per [IEEE P1363]. (output value is to be equal to that from `ALG_EC_SVDP_DH`)

  Note:

  - This algorithm computes the SHA-1 message digest of the output of the derivation primitive to yeild a 20 byte result.
  - A call to the getAlgorithm() method of an instance implementing this algorithm returns "EC_SVDP_DHC_KDF".

    The `String` name equivalent to this algorithm type to use as parameter to the `getInstance(String algorithm, ...)` method is `"EC_SVDP_DHC_KDF"`

    See Also:
      Constant Field Values

### ALG_EC_SVDP_DHC_KDF

    public static final byte ALG_EC_SVDP_DHC_KDF

  Elliptic curve secret value derivation primitive, Diffie-Hellman version, with cofactor multiplication, as per [IEEE P1363]. (output value is to be equal to that from `ALG_EC_SVDP_DH`)

  Note:

  - This algorithm computes the SHA-1 message digest of the output of the derivation primitive to yeild a 20 byte result.

    The `String` name equivalent to this algorithm type to use as parameter to the `getInstance(String algorithm, ...)` method is `"EC_SVDP_DHC_KDF"`

    See Also:
      Constant Field Values

### ALG_EC_SVDP_DH_PLAIN

    public static final byte ALG_EC_SVDP_DH_PLAIN

  Elliptic curve secret value derivation primitive, Diffie-Hellman version, as per [IEEE P1363].

  Note:

  - This algorithm returns the raw output of the derivation primitive.

  The `String` name equivalent to this algorithm type to use as parameter to the `getInstance(String algorithm, ...)` method is `"EC_SVDP_DH_PLAIN"`

  See Also:
    Constant Field Values

### ALG_EC_SVDP_DHC_PLAIN

    public static final byte ALG_EC_SVDP_DHC_PLAIN

  Elliptic curve secret value derivation primitive, Diffie-Hellman version, with cofactor multiplication, as per [IEEE P1363]. (output value is to be equal to that from `ALG_EC_SVDP_DH`)

  Note:

  - This algorithm returns the raw output of the derivation primitive.

    The `String` name equivalent to this algorithm type to use as parameter to the `getInstance(String algorithm, ...)` method is `"EC_SVDP_DHC_PLAIN"`

    See Also:
      Constant Field Values

Constructor Detail

### KeyAgreement

    protected KeyAgreement()

  Protected constructor.

Method Detail

### getInstance

    public static final KeyAgreement getInstance(byte algorithm,
                                                 boolean externalAccess)
                                          throws CryptoException

  Creates a `KeyAgreement` object instance of the selected algorithm.

  This method returns an instance of the specified algorithm supported by the most preferred provider of this cryptographic service. Note that the list of installed providers may be retrieved via the `CryptoServices.getProviders()` method.

  A call to this method is equivalent to a call to `getInstance(java.lang.String, boolean)` with the `algorithm` parameter set to the equivalent `String` algorithm name - as listed in the `ALG_*` constants above.

  Parameters:
    `algorithm` - the desired key agreement algorithm Valid codes listed in `ALG_*` constants above, for example, `ALG_EC_SVDP_DH`.
    `externalAccess` - if `true` indicates that the instance will be shared among multiple applet instances and that the `KeyAgreement` instance will also be accessed (via a `Shareable` interface) when the owner of the `KeyAgreement` instance is not the currently selected applet. If `true` or if called from a web application the implementation must not allocate `CLEAR_ON_DESELECT` transient space for internal data.
  Returns:
    the KeyAgreement object instance of the requested algorithm
  Throws:
    `CryptoException` - with the following reason codes:
    - `CryptoException.NO_SUCH_ALGORITHM` if the requested algorithm or shared access mode is not supported.
    `SecurityException` - if creating an instance of this cryptographic service is not granted.

### getInstance

    public static final KeyAgreement getInstance(String algorithm,
                                                 boolean externalAccess)
                                          throws CryptoException

  Creates a `KeyAgreement` object instance of the selected algorithm.

  This method returns an instance of the specified algorithm supported by the most preferred provider of this cryptographic service. Note that the list of installed providers may be retrieved via the `CryptoServices.getProviders()` method.

  Parameters:
    `algorithm` - the desired key agreement algorithm name. Valid names listed in `ALG_*` constants above, for example, `ALG_EC_SVDP_DH`.
    `externalAccess` - if `true` indicates that the instance will be shared among multiple applet instances and that the `KeyAgreement` instance will also be accessed (via a `Shareable` interface) when the owner of the `KeyAgreement` instance is not the currently selected applet. If `true` or if called from a web application the implementation must not allocate `CLEAR_ON_DESELECT` transient space for internal data.
  Returns:
    the KeyAgreement object instance of the requested algorithm
  Throws:
    `CryptoException` - with the following reason codes:
    - `CryptoException.NO_SUCH_ALGORITHM` if the requested algorithm or shared access mode is not supported.
    `NullPointerException` - if `algorithm` is null.
    `SecurityException` - if creating an instance of this cryptographic service is not granted.
  Since:
    Java Card 3.0

### getInstance

    public static final KeyAgreement getInstance(String algorithm,
                                                 String provider,
                                                 boolean externalAccess)
                                          throws CryptoException

  Creates a `KeyAgreement` object instance of the selected algorithm.

  Parameters:
    `algorithm` - the desired key agreement algorithm name. Valid names listed in `ALG_*` constants above, for example, `ALG_EC_SVDP_DH`.
    `provider` - the desired key agreement algorithm provider.
    `externalAccess` - if `true` indicates that the instance will be shared among multiple applet instances and that the `KeyAgreement` instance will also be accessed (via a `Shareable` interface) when the owner of the `KeyAgreement` instance is not the currently selected applet. If `true` or if called from a web application the implementation must not allocate `CLEAR_ON_DESELECT` transient space for internal data.
  Returns:
    the KeyAgreement object instance of the requested algorithm
  Throws:
    `CryptoException` - with the following reason codes:
    - `CryptoException.NO_SUCH_ALGORITHM` if the requested algorithm or shared access mode is not supported.
    `NullPointerException` - if `algorithm` or `provider` is null.
    `SecurityException` - if creating an instance of this cryptographic service is not granted.
  Since:
    Java Card 3.0

### init

    public abstract void init(PrivateKey privKey)
                       throws CryptoException

  Initializes the object with the given private key.

  Parameters:
    `privKey` - the private key
  Throws:
    `CryptoException` - with the following reason codes:
    - `CryptoException.ILLEGAL_VALUE` if the input key type is inconsistent with the `KeyAgreement` algorithm, for example, if the `KeyAgreement` algorithm is `ALG_EC_SVDP_DH` and the key type is `TYPE_RSA_PRIVATE`, or if `privKey` is inconsistent with the implementation.
    - `CryptoException.UNINITIALIZED_KEY` if `privKey` is uninitialized, or if the `KeyAgreement` algorithm is set to `ALG_EC_SVDP_DHC` and the cofactor, K, has not been successfully initialized since the time the initialized state of the key was set to false.

### getAlgorithm

    public abstract byte getAlgorithm()

  Gets the KeyAgreement algorithm. Pre-defined codes listed in `ALG_*` constants above, for example, `ALG_EC_SVDP_DH_PLAIN`.

  Returns:
    the algorithm code defined above; if the algorithm is not one of the pre-defined algorithms, `0` is returned.

### getAlgorithmName

    public abstract String getAlgorithmName()

  Gets the KeyAgreement algorithm name. Pre-defined codes listed for each of the `ALG_*` constants above, for example, `ALG_EC_SVDP_DH_PLAIN`.

  New algorithms may be defined through the Extensible Cryptography Framework.

  Returns:
    the algorithm name.
  Since:
    Java Card 3.0

### generateSecret

    public abstract short generateSecret(byte[] publicData,
                                         short publicOffset,
                                         short publicLength,
                                         byte[] secret,
                                         short secretOffset)
                                  throws CryptoException

  Generates the secret data as per the requested algorithm using the `PrivateKey` specified during initialization and the public key data provided. Note that in the case of the algorithms `ALG_EC_SVDP_DH` and `ALG_EC_SVDP_DHC` the public key data provided should be the public elliptic curve point of the second party in the protocol, specified as per ANSI X9.62. A specific implementation need not support the compressed form, but must support the uncompressed form of the point.

  Parameters:
    `publicData` - buffer holding the public data of the second party
    `publicOffset` - offset into the publicData buffer at which the data begins
    `publicLength` - byte length of the public data
    `secret` - buffer to hold the secret output
    `secretOffset` - offset into the secret array at which to start writing the secret
  Returns:
    byte length of the secret
  Throws:
    `CryptoException` - with the following reason codes:
    - `CryptoException.ILLEGAL_VALUE` if the `publicData` data format is incorrect, or if the `publicData` data is inconsistent with the `PrivateKey` specified during initialization.
    - `CryptoException.INVALID_INIT` if this `KeyAgreement` object is not initialized.

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright (c) 2009 Sun Microsystems, Inc. All rights reserved.