Site Tools


Sidebar

Smart Card Solution

User Manual

JavaCard API Samples

Java Card Specification

Knowledge Sharing

javacard:java-card-api:eckey

javacard.security

Interface ECKey

All Known Subinterfaces: ECPrivateKey , ECPublicKey


The ECKey interface is the base interface for the EC algorithm's private and public key implementations. An EC private key implementation must also implement the ECPrivateKey interface methods. An EC public key implementation must also implement the ECPublicKey interface methods.

The equation of the curves for keys of type TYPE_EC_FP_PUBLIC or TYPE_EC_FP_PRIVATE is y^2 = x^3 + A * x + B. The equation of the curves for keys of type TYPE_EC_F2M_PUBLIC or TYPE_EC_F2M_PRIVATE is y^2 + x * y = x^3 + A * x^2 + B.

The notation used to describe parameters specific to the EC algorithm is based on the naming conventions established in [IEEE P1363].

Version:

1.0 

See Also:ECPublicKey , ECPrivateKey , KeyBuilder , Signature , javacardx.crypto.KeyEncryption , KeyAgreement


Method Summary
 short getA (byte[] buffer,short offset)          Returns the first coefficient of the curve of the key.
 short getB (byte[] buffer,short offset)          Returns the second coefficient of the curve of the key.
 short getField (byte[] buffer,short offset)          Returns the field specification parameter value of the key.
 short getG (byte[] buffer,short offset)          Returns the fixed point of the curve.
 short getK ()          Returns the cofactor of the order of the fixed point G of the curve.
 short getR (byte[] buffer,short offset)          Returns the order of the fixed point G of the curve.
 void setA (byte[] buffer,short offset,short length)          Sets the first coefficient of the curve of the key.
 void setB (byte[] buffer,short offset,short length)          Sets the second coefficient of the curve of the key.
 void setFieldF2M (short e)          Sets the field specification parameter value for keys of type TYPE_EC_F2M_PUBLIC or TYPE_EC_F2M_PRIVATE in the case where the polynomial is a trinomial, of the form xn + xe + 1 (where n is the bit length of the key).
 void setFieldF2M (short e1,short e2,short e3)          Sets the field specification parameter value for keys of type TYPE_EC_F2M_PUBLIC or TYPE_EC_F2M_PRIVATE in the case where the polynomial is a pentanomial, of the form xn + xe1 + xe2 + xe3 + 1 (where n is the bit length of the key).
 void setFieldFP (byte[] buffer,short offset,short length)          Sets the field specification parameter value for keys of type TYPE_EC_FP_PRIVATE or TYPE_EC_FP_PUBLIC.
 void setG (byte[] buffer,short offset,short length)          Sets the fixed point of the curve.
 void setK (short K)          Sets the cofactor of the order of the fixed point G of the curve.
 void setR (byte[] buffer,short offset,short length)          Sets the order of the fixed point G of the curve.

 

Method Detail

setFieldFP

void setFieldFP(byte[] buffer, short offset, short length) throws CryptoException

Sets the field specification parameter value for keys of type TYPE_EC_FP_PRIVATE or TYPE_EC_FP_PUBLIC. The specified value is the prime p corresponding to the field GF(p).

The plain text data format is big-endian and right-aligned (the least significant bit is the least significant bit of last byte). Input parameter data is copied into the internal representation.

Note:

  • If the key object implements the javacardx.crypto.KeyEncryption interface and the Cipher object specified via setKeyCipher() is not null, the key value is decrypted using the Cipher object.


Parameters:buffer - the input buffer

offset - the offset into the input buffer at which the parameter value begins

length - the byte length of the parameter value

Throws: CryptoException - with the following reason codes:

  • CryptoException.ILLEGAL_VALUE if the input parameter data is inconsistent with the key length or if input data decryption is required and fails.


  • CryptoException.NO_SUCH_ALGORITHM if the key is neither of type TYPE_EC_FP_PUBLIC nor TYPE_EC_FP_PRIVATE.



setFieldF2M

void setFieldF2M(short e) throws CryptoException

Sets the field specification parameter value for keys of type TYPE_EC_F2M_PUBLIC or TYPE_EC_F2M_PRIVATE in the case where the polynomial is a trinomial, of the form x^n + x^e + 1 (where n is the bit length of the key). It is required that n > e > 0.

Parameters:e - the value of the intermediate exponent of the trinomial

Throws: CryptoException - with the following reason codes:

  • CryptoException.ILLEGAL_VALUE if the input parameter e is not such that 0 < e < n.


  • CryptoException.NO_SUCH_ALGORITHM if the key is neither of type TYPE_EC_F2M_PUBLIC nor TYPE_EC_F2M_PRIVATE.



setFieldF2M

void setFieldF2M(short e1, short e2, short e3) throws CryptoException

Sets the field specification parameter value for keys of type TYPE_EC_F2M_PUBLIC or TYPE_EC_F2M_PRIVATE in the case where the polynomial is a pentanomial, of the form x^n + x^e1 + x^e2 + x^e3 + 1 (where n is the bit length of the key). It is required for all ei where ei = {e1, e2, e3} that n > ei > 0.

Parameters:e1 - the value of the first of the intermediate exponents of the pentanomial

e2 - the value of the second of the intermediate exponent of the pentanomial

e3 - the value of the third of the intermediate exponents

Throws: CryptoException - with the following reason codes:

  • CryptoException.ILLEGAL_VALUE if the input parameters ei where ei = {e1, e2, e3}are not such that for all ei, n > ei > 0.


  • CryptoException.NO_SUCH_ALGORITHM if the key is neither of type TYPE_EC_F2M_PUBLIC nor TYPE_EC_F2M_PRIVATE.



setA

void setA(byte[] buffer, short offset, short length) throws CryptoException

Sets the first coefficient of the curve of the key.

For keys of type TYPE_EC_FP_PRIVATE or TYPE_EC_FP_PUBLIC, this is the value of A as an integer modulo the field specification parameter p, that is, an integer in the range 0 to p-1. For keys of type TYPE_EC_F2M_PRIVATE or TYPE_EC_F2M_PUBLIC, the bit representation of this value specifies a polynomial with binary coefficients which represents the value of A in the field.

The plain text data format is big-endian and right-aligned (the least significant bit is the least significant bit of last byte). Input parameter data is copied into the internal representation.

Note:

  • If the key object implements the javacardx.crypto.KeyEncryption interface and the Cipher object specified via setKeyCipher() is not null, the key value is decrypted using the Cipher object.


Parameters:buffer - the input buffer

offset - the offset into the input buffer at which the coefficient value begins

length - the byte length of the coefficient value

Throws: CryptoException - with the following reason codes:

  • CryptoException.ILLEGAL_VALUE if the input parameter data is inconsistent with the key length or if input data decryption is required and fails.



setB

void setB(byte[] buffer, short offset, short length) throws CryptoException

Sets the second coefficient of the curve of the key.

For keys of type TYPE_EC_FP_PRIVATE or TYPE_EC_FP_PUBLIC, this is the value of B as an integer modulo the field specification parameter p, that is, an integer in the range 0 to p-1. For keys of type TYPE_EC_F2M_PRIVATE or TYPE_EC_F2M_PUBLIC, the bit representation of this value specifies a polynomial with binary coefficients which represents the value of B in the field.

The plain text data format is big-endian and right-aligned (the least significant bit is the least significant bit of last byte). Input parameter data is copied into the internal representation.

Note:

  • If the key object implements the javacardx.crypto.KeyEncryption interface and the Cipher object specified via setKeyCipher() is not null, the key value is decrypted using the Cipher object.


Parameters:buffer - the input buffer

offset - the offset into the input buffer at which the coefficient value begins

length - the byte length of the coefficient value

Throws: CryptoException - with the following reason codes:

  • CryptoException.ILLEGAL_VALUE if the input parameter data is inconsistent with the key length or if input data decryption is required and fails.



setG

void setG(byte[] buffer, short offset, short length) throws CryptoException

Sets the fixed point of the curve. The point should be specified as an octet string as per ANSI X9.62. A specific implementation need not support the compressed form, but must support the uncompressed form of the point.

The plain text data format is big-endian and right-aligned (the least significant bit is the least significant bit of last byte). Input parameter data is copied into the internal representation.

Note:

  • If the key object implements the javacardx.crypto.KeyEncryption interface and the Cipher object specified via setKeyCipher() is not null, the key value is decrypted using the Cipher object.


Parameters:buffer - the input buffer

offset - the offset into the input buffer at which the point specification begins

length - the byte length of the point specification

Throws: CryptoException - with the following reason codes:

  • CryptoException.ILLEGAL_VALUE if the input parameter data format is incorrect, or if the input parameter data is inconsistent with the key length, or if input data decryption is required and fails.



setR

void setR(byte[] buffer, short offset, short length) throws CryptoException

Sets the order of the fixed point G of the curve.

The plain text data format is big-endian and right-aligned (the least significant bit is the least significant bit of last byte). Input parameter data is copied into the internal representation.

Parameters:buffer - the input buffer

offset - the offset into the input buffer at which the order begins

length - the byte length of the order

Throws: CryptoException - with the following reason codes:

  • CryptoException.ILLEGAL_VALUE if the input parameter data is inconsistent with the key length, or if input data decryption is required and fails.


Note:

  • If the key object implements the javacardx.crypto.KeyEncryption interface and the Cipher object specified via setKeyCipher() is not null, the key value is decrypted using the Cipher object.



setK

void setK(short K)

Sets the cofactor of the order of the fixed point G of the curve.

The cofactor need not be specified for the key to be initialized. However, the KeyAgreement algorithm type ALG_EC_SVDP_DHC requires that the cofactor, K, be initialized.

Parameters:K - the value of the cofactor


getField

short getField(byte[] buffer, short offset) throws CryptoException

Returns the field specification parameter value of the key.

For keys of type TYPE_EC_FP_PRIVATE or TYPE_EC_FP_PUBLIC, this is the value of the prime p corresponding to the field GF(p). For keys of type TYPE_EC_F2M_PRIVATE or TYPE_EC_F2M_PUBLIC, it is the value whose bit representation specifies the polynomial with binary coefficients used to define the arithmetic operations in the field GF(2^n)

The plain text data format is big-endian and right-aligned (the least significant bit is the least significant bit of last byte).

Parameters:buffer - the output buffer

offset - the offset into the output buffer at which the parameter value is to begin

Returns:the byte length of the parameter

Throws: CryptoException - with the following reason code:

  • CryptoException.UNINITIALIZED_KEY if the field specification parameter value of the key has not been successfully initialized since the time the initialized state of the key was set to false.


See Also:Key


getA

short getA(byte[] buffer, short offset) throws CryptoException

Returns the first coefficient of the curve of the key.

For keys of type TYPE_EC_FP_PRIVATE or TYPE_EC_FP_PUBLIC, this is the value of A as an integer modulo the field specification parameter p, that is, an integer in the range 0 to p-1. For keys of type TYPE_EC_F2M_PRIVATE or TYPE_EC_F2M_PUBLIC, the bit representation of this value specifies a polynomial with binary coefficients which represents the value of A in the field.

The plain text data format is big-endian and right-aligned (the least significant bit is the least significant bit of last byte).

Parameters:buffer - the output buffer

offset - the offset into the output buffer at which the coefficient value is to begin

Returns:the byte length of the coefficient

Throws: CryptoException - with the following reason code:

  • CryptoException.UNINITIALIZED_KEY if the coefficient of the curve of the key has not been successfully initialized since the time the initialized state of the key was set to false.


See Also:Key


getB

short getB(byte[] buffer, short offset) throws CryptoException

Returns the second coefficient of the curve of the key.

For keys of type TYPE_EC_FP_PRIVATE or TYPE_EC_FP_PUBLIC, this is the value of B as an integer modulo the field specification parameter p, that is, an integer in the range 0 to p-1. For keys of type TYPE_EC_F2M_PRIVATE or TYPE_EC_F2M_PUBLIC, the bit representation of this value specifies a polynomial with binary coefficients which represents the value of B in the field.

The plain text data format is big-endian and right-aligned (the least significant bit is the least significant bit of last byte).

Parameters:buffer - the output buffer

offset - the offset into the output buffer at which the coefficient value is to begin

Returns:the byte length of the coefficient

Throws: CryptoException - with the following reason code:

  • CryptoException.UNINITIALIZED_KEY if the second coefficient of the curve of the key has not been successfully initialized since the time the initialized state of the key was set to false.


See Also:Key


getG

short getG(byte[] buffer, short offset) throws CryptoException

Returns the fixed point of the curve. The point is represented as an octet string in compressed or uncompressed forms as per ANSI X9.62.

The plain text data format is big-endian and right-aligned (the least significant bit is the least significant bit of last byte).

Parameters:buffer - the output buffer

offset - the offset into the output buffer at which the point specification data is to begin

Returns:the byte length of the point specification

Throws: CryptoException - with the following reason code:

  • CryptoException.UNINITIALIZED_KEY if the fixed point of the curve of the key has not been successfully initialized since the time the initialized state of the key was set to false.


See Also:Key


getR

short getR(byte[] buffer, short offset) throws CryptoException

Returns the order of the fixed point G of the curve.

The plain text data format is big-endian and right-aligned (the least significant bit is the least significant bit of last byte).

Parameters:buffer - the output buffer

offset - the offset into the input buffer at which the order begins

Returns:the byte length of the order

Throws: CryptoException - with the following reason code:

  • CryptoException.UNINITIALIZED_KEY if the order of the fixed point G of the curve of the key has not been successfully initialized since the time the initialized state of the key was set to false.


See Also:Key


getK

short getK() throws CryptoException

Returns the cofactor of the order of the fixed point G of the curve.

Returns:the value of the cofactor

Throws: CryptoException - with the following reason codes:

  • CryptoException.UNINITIALIZED_KEY if the cofactor of theorder of the fixed point G of the curve of the key has not been successfully initialized since the time the initialized state of the key was set to false.


See Also:Key

javacard/java-card-api/eckey.txt · Last modified: 2017/05/13 04:04 (external edit)