Package javacard.security
Interface ECKey
-
- All Known Subinterfaces:
ECPrivateKey
,ECPublicKey
public interface ECKey
TheECKey
interface is the base interface for the EC algorithm's private and public key implementations. An EC private key implementation must also implement theECPrivateKey
interface methods. An EC public key implementation must also implement theECPublicKey
interface methods.The equation of the curves for keys of type
TYPE_EC_FP_PUBLIC
orTYPE_EC_FP_PRIVATE
is y^2 = x^3 + A * x + B. The equation of the curves for keys of typeTYPE_EC_F2M_PUBLIC
orTYPE_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].
-
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description void
copyDomainParametersFrom(ECKey ecKey)
Copies the domain parameters from the specifiedECKey
instance into the domain parameters ofthis
object instance.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 typeTYPE_EC_F2M_PUBLIC
orTYPE_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).void
setFieldF2M(short e1, short e2, short e3)
Sets the field specification parameter value for keys of typeTYPE_EC_F2M_PUBLIC
orTYPE_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).void
setFieldFP(byte[] buffer, short offset, short length)
Sets the field specification parameter value for keys of typeTYPE_EC_FP_PRIVATE
orTYPE_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 typeTYPE_EC_FP_PRIVATE
orTYPE_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 theCipher
object specified viasetKeyCipher()
is notnull
, the key value is decrypted using theCipher
object.
- Parameters:
buffer
- the input bufferoffset
- the offset into the input buffer at which the parameter value beginslength
- the byte length of the parameter value- Throws:
CryptoException
- with the following reason codes:CryptoException.ILLEGAL_VALUE
if the length parameter is 0 or invalid or 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 typeTYPE_EC_FP_PUBLIC
norTYPE_EC_FP_PRIVATE
.
- If the key object implements the
-
setFieldF2M
void setFieldF2M(short e) throws CryptoException
Sets the field specification parameter value for keys of typeTYPE_EC_F2M_PUBLIC
orTYPE_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 typeTYPE_EC_F2M_PUBLIC
norTYPE_EC_F2M_PRIVATE
.
-
setFieldF2M
void setFieldF2M(short e1, short e2, short e3) throws CryptoException
Sets the field specification parameter value for keys of typeTYPE_EC_F2M_PUBLIC
orTYPE_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 pentanomiale2
- the value of the second of the intermediate exponent of the pentanomiale3
- 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 typeTYPE_EC_F2M_PUBLIC
norTYPE_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 typeTYPE_EC_FP_PRIVATE
orTYPE_EC_FP_PUBLIC
, this is the value of A as an integer modulo the field specification parameter p, that is, an integer in the range0
to p-1. For keys of typeTYPE_EC_F2M_PRIVATE
orTYPE_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 theCipher
object specified viasetKeyCipher()
is notnull
, the key value is decrypted using theCipher
object.
- Parameters:
buffer
- the input bufferoffset
- the offset into the input buffer at which the coefficient value beginslength
- the byte length of the coefficient value- Throws:
CryptoException
- with the following reason codes:CryptoException.ILLEGAL_VALUE
if the length parameter is 0 or invalid or if the input parameter data is inconsistent with the key length or if input data decryption is required and fails.
- If the key object implements the
-
setB
void setB(byte[] buffer, short offset, short length) throws CryptoException
Sets the second coefficient of the curve of the key. For keys of typeTYPE_EC_FP_PRIVATE
orTYPE_EC_FP_PUBLIC
, this is the value of B as an integer modulo the field specification parameter p, that is, an integer in the range0
to p-1. For keys of typeTYPE_EC_F2M_PRIVATE
orTYPE_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 theCipher
object specified viasetKeyCipher()
is notnull
, the key value is decrypted using theCipher
object.
- Parameters:
buffer
- the input bufferoffset
- the offset into the input buffer at which the coefficient value beginslength
- the byte length of the coefficient value- Throws:
CryptoException
- with the following reason codes:CryptoException.ILLEGAL_VALUE
if the length parameter is 0 or invalid or if the input parameter data is inconsistent with the key length or if input data decryption is required and fails.
- If the key object implements the
-
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 theCipher
object specified viasetKeyCipher()
is notnull
, the key value is decrypted using theCipher
object.
- Parameters:
buffer
- the input bufferoffset
- the offset into the input buffer at which the point specification beginslength
- the byte length of the point specification- Throws:
CryptoException
- with the following reason codes:CryptoException.ILLEGAL_VALUE
if the length parameter is 0 or invalid or 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.
- If the key object implements the
-
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 bufferoffset
- the offset into the input buffer at which the order beginslength
- the byte length of the order- Throws:
CryptoException
- with the following reason codes:CryptoException.ILLEGAL_VALUE
if the length parameter is 0 or invalid or 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 theCipher
object specified viasetKeyCipher()
is notnull
, the key value is decrypted using theCipher
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, theKeyAgreement
algorithm typeALG_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 typeTYPE_EC_FP_PRIVATE
orTYPE_EC_FP_PUBLIC
, this is the value of the prime p corresponding to the field GF(p). For keys of typeTYPE_EC_F2M_PRIVATE
orTYPE_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 bufferoffset
- 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 typeTYPE_EC_FP_PRIVATE
orTYPE_EC_FP_PUBLIC
, this is the value of A as an integer modulo the field specification parameter p, that is, an integer in the range0
to p-1. For keys of typeTYPE_EC_F2M_PRIVATE
orTYPE_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 bufferoffset
- 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 typeTYPE_EC_FP_PRIVATE
orTYPE_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 typeTYPE_EC_F2M_PRIVATE
orTYPE_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 bufferoffset
- 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 bufferoffset
- 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 bufferoffset
- 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 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
-
copyDomainParametersFrom
void copyDomainParametersFrom(ECKey ecKey) throws CryptoException
Copies the domain parameters from the specifiedECKey
instance into the domain parameters ofthis
object instance.This method should only be used when a separate set of parameters is required. It is better to share the domain parameters using the
KeyBuilder.buildKeyWithSharedDomain(byte, byte, Key, boolean)
method when the value of the domain parameters remains constant in time.- Parameters:
ecKey
- a key or domain parameter object from which the domain parameters will be copied- Throws:
CryptoException
- with the following reason codes:CryptoException.ILLEGAL_VALUE
if the parameters could not be assigned because the given key is null, not of the correct size, or if some or all of the domain parameters are not validCryptoException.UNINITIALIZED_KEY
if the domain parameters are not all present
-
-