KeyPair (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 KeyPair

    java.lang.Object
      javacard.security.KeyPair

    @TransactionType(value=SUPPORTS)
    public final class KeyPair

extends Object

This class is a container for a key pair (a public key and a private key). It does not enforce any security, and, when initialized, should be treated like a PrivateKey.

In addition, this class features a key generation method.

Since:
  Java Card 2.x, Java Card 3.0
See Also:
  `PublicKey`, `PrivateKey`

Field Summary
`static byte` | `ALG_DSA` `KeyPair` object containing a DSA key pair.
`static byte` | `ALG_EC_F2M` `KeyPair` object containing an EC key pair for EC operations over fields of characteristic 2 with polynomial basis.
`static byte` | `ALG_EC_FP` `KeyPair` object containing an EC key pair for EC operations over large prime fields
`static byte` | `ALG_RSA` `KeyPair` object containing a RSA key pair.
`static byte` | `ALG_RSA_CRT` `KeyPair` object containing a RSA key pair with private key in its Chinese Remainder Theorem form.
`static String` | `SERVICE_NAME` This cryptographic service name, as used to lookup implemented algorithms.

Constructor Summary
`KeyPair(byte algorithm, short keyLength)` Constructs a `KeyPair` instance for the specified algorithm and keylength; the encapsulated keys are uninitialized.
`KeyPair(PublicKey publicKey, PrivateKey privateKey)` Constructs a new `KeyPair` object containing the specified public key and private key.
`KeyPair(String algorithm, short keyLength)` Constructs a `KeyPair` instance for the specified algorithm and keylength; the encapsulated keys are uninitialized.
`KeyPair(String algorithm, String provider, short keyLength)` Constructs a `KeyPair` instance for the specified algorithm and keylength; the encapsulated keys are uninitialized.

Method Summary
`void` | `genKeyPair()` (Re)Initializes the key objects encapsulated in this `KeyPair` instance with new key values.
`PrivateKey` | `getPrivate()` Returns a reference to the private key component of this `KeyPair` object.
`PublicKey` | `getPublic()` Returns a reference to the public key component of this `KeyPair` object.

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_RSA

    public static final byte ALG_RSA

  `KeyPair` object containing a RSA key pair.

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

  See Also:
    Constant Field Values

### ALG_RSA_CRT

    public static final byte ALG_RSA_CRT

  `KeyPair` object containing a RSA key pair with private key in its Chinese Remainder Theorem form.

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

  See Also:
    Constant Field Values

### ALG_DSA

    public static final byte ALG_DSA

  `KeyPair` object containing a DSA key pair.

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

  See Also:
    Constant Field Values

### ALG_EC_F2M

    public static final byte ALG_EC_F2M

  `KeyPair` object containing an EC key pair for EC operations over fields of characteristic 2 with polynomial basis.

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

  See Also:
    Constant Field Values

### ALG_EC_FP

    public static final byte ALG_EC_FP

  `KeyPair` object containing an EC key pair for EC operations over large prime fields

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

  See Also:
    Constant Field Values

Constructor Detail

### KeyPair

    public KeyPair(byte algorithm,
                   short keyLength)
            throws CryptoException

  Constructs a `KeyPair` instance for the specified algorithm and keylength; the encapsulated keys are uninitialized. To initialize the `KeyPair` instance use the `genKeyPair()` method.

  The encapsulated key objects are of the specified `keyLength` size and implement the appropriate `Key` interface associated with the specified algorithm (example - `RSAPublicKey` interface for the public key and `RSAPrivateKey` interface for the private key within an `ALG_RSA` key pair).

  This method creates 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 `KeyPair(java.lang.String, short)` with the `algorithm` parameter set to the equivalent `String` algorithm name - as listed in the `ALG_*` constants above.

  Notes:

  - The key objects encapsulated in the generated `KeyPair` object need not support the `KeyEncryption` interface.

  Parameters:
    `algorithm` - the type of algorithm whose key pair needs to be generated. Valid codes listed in `ALG_*` constants above. See `ALG_RSA`.
    `keyLength` - the key size in bits. The valid key bit lengths are key type dependent. See the `KeyBuilder` class.
  Throws:
    `CryptoException` - with the following reason codes:
    - `CryptoException.NO_SUCH_ALGORITHM` if the requested algorithm associated with the specified type, size of key is not supported.
    `SecurityException` - if creating an instance of this cryptographic service is not granted.
  See Also:
    `KeyBuilder`, `Signature`, `javacardx.crypto.Cipher`, `javacardx.crypto.KeyEncryption`

### KeyPair

    public KeyPair(String algorithm,
                   short keyLength)
            throws CryptoException

  Constructs a `KeyPair` instance for the specified algorithm and keylength; the encapsulated keys are uninitialized. To initialize the `KeyPair` instance use the `genKeyPair()` method.

  The encapsulated key objects are of the specified `keyLength` size and implement the appropriate `Key` interface associated with the specified algorithm (example - `RSAPublicKey` interface for the public key and `RSAPrivateKey` interface for the private key within an `ALG_RSA` key pair).

  This method creates 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.

  Notes:

  - The key objects encapsulated in the generated `KeyPair` object need not support the `KeyEncryption` interface.

  Parameters:
    `algorithm` - the type of algorithm whose key pair needs to be generated. Valid names listed in `ALG_*` constants above. See `ALG_RSA`.
    `keyLength` - the key size in bits. The valid key bit lengths are key type dependent. See the `KeyBuilder` class.
  Throws:
    `CryptoException` - with the following reason codes:
    - `CryptoException.NO_SUCH_ALGORITHM` if the requested algorithm associated with the specified type, size of key 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
  See Also:
    `KeyBuilder`, `Signature`, `javacardx.crypto.Cipher`, `javacardx.crypto.KeyEncryption`

### KeyPair

    public KeyPair(String algorithm,
                   String provider,
                   short keyLength)
            throws CryptoException

  Constructs a `KeyPair` instance for the specified algorithm and keylength; the encapsulated keys are uninitialized. To initialize the `KeyPair` instance use the `genKeyPair()` method.

  The encapsulated key objects are of the specified `keyLength` size and implement the appropriate `Key` interface associated with the specified algorithm (example - `RSAPublicKey` interface for the public key and `RSAPrivateKey` interface for the private key within an `ALG_RSA` key pair).

  Notes:

  - The key objects encapsulated in the generated `KeyPair` object need not support the `KeyEncryption` interface.

  Parameters:
    `algorithm` - the type of algorithm whose key pair needs to be generated. Valid names listed in `ALG_*` constants above. See `ALG_RSA`.
    `provider` - the desired key pair algorithm provider.
    `keyLength` - the key size in bits. The valid key bit lengths are key type dependent. See the `KeyBuilder` class.
  Throws:
    `CryptoException` - with the following reason codes:
    - `CryptoException.NO_SUCH_ALGORITHM` if the requested algorithm associated with the specified type, size of key 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
  See Also:
    `KeyBuilder`, `Signature`, `javacardx.crypto.Cipher`, `javacardx.crypto.KeyEncryption`

### KeyPair

    public KeyPair(PublicKey publicKey,
                   PrivateKey privateKey)
            throws CryptoException

  Constructs a new `KeyPair` object containing the specified public key and private key.

  Note that this constructor only stores references to the public and private key components in the generated `KeyPair` object. It does not throw an exception if the key parameter objects are uninitialized.

  Parameters:
    `publicKey` - the public key.
    `privateKey` - the private key.
  Throws:
    `CryptoException` - with the following reason codes:
    - `CryptoException.ILLEGAL_VALUE` if the input parameter key objects are mismatched - different algorithms or different key sizes. Parameter values are not checked.
    - `CryptoException.NO_SUCH_ALGORITHM` if the algorithm associated with the specified type, size of key is not supported.
    `SecurityException` - if creating an instance of this cryptographic service is not granted.

Method Detail

### genKeyPair

    public final void genKeyPair()
                          throws CryptoException

  (Re)Initializes the key objects encapsulated in this `KeyPair` instance with new key values. The initialized public and private key objects encapsulated in this instance will then be suitable for use with the `Signature`, `Cipher` and `KeyAgreement` objects. An internal secure random number generator is used during new key pair generation.

  Notes:

  - For the RSA algorithm, if the exponent value in the public key object is pre-initialized, it will be retained. Otherwise, a default value of 65537 will be used.
  - For the DSA algorithm, if the p, q and g parameters of the public key object are pre-initialized, they will be retained. Otherwise, default precomputed parameter sets will be used. The required default precomputed values are listed in Appendix B of Java Cryptography Architecture API Specification & Reference document.
  - For the EC case, if the Field, A, B, G and R parameters of the public key object are pre-initialized, then they will be retained. Otherwise default pre-specified values MAY be used (e.g., WAP predefined curves), since computation of random generic EC keys is infeasible on the smart card platform.
  - If the time taken to generate the key values is excessive, the implementation may automatically request additional APDU processing time from the CAD.

  Throws:
    `CryptoException` - with the following reason codes:
    - `CryptoException.ILLEGAL_VALUE` if the pre-initialized exponent value parameter in the RSA public key or the pre-initialized p, q, g parameter set in the DSA public key or the pre-initialized Field, A, B, G and R parameter set in public EC key is invalid.
  See Also:
    `javacard.framework.APDU`, `Signature`, `javacardx.crypto.Cipher`, `RSAPublicKey`, `ECKey`, `DSAKey`

### getPublic

    public PublicKey getPublic()

  Returns a reference to the public key component of this `KeyPair` object.

  Returns:
    a reference to the public key.

### getPrivate

    public PrivateKey getPrivate()

  Returns a reference to the private key component of this `KeyPair` object.

  Returns:
    a reference to the private key.

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.