javacard.security
Class KeyAgreement

java.lang.Object
  extended by 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:

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:

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:

    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.


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