com.entrust.toolkit.security.crypto.ec

Class EcPublicKey

java.lang.Object

iaik.x509.PublicKeyInfo

com.entrust.toolkit.security.crypto.ec.EcPublicKey

All Implemented Interfaces:

ASN1Type, java.io.Serializable, java.security.interfaces.ECKey, java.security.interfaces.ECPublicKey, java.security.Key, java.security.PublicKey

public final class EcPublicKey
extends PublicKeyInfo
implements java.security.interfaces.ECPublicKey

An Elliptic Curve (EC) public key.

An EC public key contains an EC public point and a set of EC domain parameters. The ASN.1 representation of an EC public key is defined in the X.509, ANSI and SEC standards as follows:

 -- Defined in SEC 1: Elliptic Curve Cryptography
 SubjectPublicKeyInfo ::= SEQUENCE {
     algorithm           AlgorithmIdentifier,
     subjectPublicKey    BIT STRING
     -- Contains the encoded EC public point
 }
 
 ecPublicKeyType ALGORITHM ::= {
     OID id-ecPublicKey PARAMS ECDomainParameters
 }
 
 id-ecPublicKey OBJECT IDENTIFIER ::= { 1 2 840 10045 2 1 }
 

The following additional EC key algorithm identifiers have also been defined. This release offers partial support for these additional EC key algorithm identifiers (enough for interoperability - the ability to consume public keys containing these algorithm identifiers without failure). The Toolkit will recognize them during decoding as valid EC public key algorithm identifiers, however, none of the algorithm restriction they imply are enforced. Additionally, the Toolkit does not yet offer any way to create or generate an EC public key containing one of these algorithm identifiers.

 id-ecPublicKeyTypeRestricted OBJECT IDENTIFIER ::= { 1 2 840 10045 2 2 }
 id-ecDH OBJECT IDENTIFIER ::= { 1 3 132 1 12 }
 id-ecMQV OBJECT IDENTIFIER ::= { 1 3 132 1 13 }
 

Refer to EcParameterFactory for details on the EC domain parameters, including a table of supported named EC domains as well as their ASN.1 specification. All three EC domain parameter formats are supported ('specified', 'named', and 'implicitCA'). Point compression is not supported.

Before the result of a cryptographic operation involving an EC public key is returned, a check must be performed to ensure that the public key is valid; this is called EC public key validation. All EC-based cryptographic algorithms provided by the Toolkit automatically perform EC public key validation prior to returning the result of any cryptographic operation that uses a public key.

The Toolkit's EC public key validation routine performs a set of checks on the EC public point and if any of these checks fail the public key is considered invalid and cannot be used. It employs an optimized version of the full public key validation routine described in NIST Special Publication 800-56A (March, 2007) Section 5.6.2.5.

Note: A prerequisite to the public key validation is having a valid set of EC domain parameters. All EC-based cryptographic algorithms provided by the Toolkit automatically validate the EC domain parameters associated with an EC public key prior to performing EC public key validation. For additional details on the EC domain parameter validation routine, refer to EcParameterFactory

Since:

7.2 SP2

See Also:

EcPrivateKey, EcKeyPairGenerator, EcKeyFactory, Serialized Form

Field Summary

Fields inherited from class iaik.x509.PublicKeyInfo

public_key_algorithm

Fields inherited from interface java.security.interfaces.ECPublicKey

serialVersionUID

Constructor Summary

Constructors

Constructor and Description
EcPublicKey(byte[] ba) A constructor; creates a new EcPublicKey object by decoding and parsing the passed in DER encoded ASN.1 SubjectPublicKeyInfo structure.
EcPublicKey(byte[] ba, java.security.spec.ECParameterSpec configuredImplicitCaParams) A constructor; creates a new EcPublicKey object by decoding and parsing the passed in DER encoded ASN.1 SubjectPublicKeyInfo structure with support for providing 'implicitCA' EC domain parameter values.
EcPublicKey(java.security.spec.ECPoint w, java.security.spec.ECParameterSpec params) A constructor; creates a new EcPublicKey object from the provided public point and EC domain parameters.
EcPublicKey(java.security.spec.ECPoint w, java.security.spec.ECParameterSpec params, boolean forceSpecifiedEcDomainParams) A constructor; creates a new EcPublicKey object from the provided public point, EC domain parameters, and an indicator for whether or not the domain parameters must be encoded in 'specified' format .

Method Summary

Methods

Modifier and Type	Method and Description
protected void	decode(byte[] subjectPublicKey) Decodes a DER encoded ASN.1 representation of an EC public key value (a BIT STRING).
static java.security.spec.ECPoint	decodePoint(byte[] encodedEcPoint, java.security.spec.EllipticCurve ellipticCurve) Converts an EC point in binary encoded format to Sun JCA format.
protected byte[]	encode() Encodes a DER encoded ASN.1 representation of an EC public key value (a BIT STRING).
static byte[]	encodePoint(java.security.spec.ECPoint ecPoint, java.security.spec.EllipticCurve ellipticCurve) Converts an EC point in Sun JCA format to binary encoded format.
java.lang.String	getAlgorithm() Returns the algorithm of this public key, which is 'EC'.
byte[]	getEncoded() Returns this DER encoding of this public key.
byte[]	getEncoded(boolean forceSpecifiedEcDomainParams) Encodes the public key using the force 'specified' indicator.
static byte[]	getEncoded(java.security.interfaces.ECPublicKey publicKey, EcParameterFormat format) Encodes an EC public key using the requested EC domain parameter format.
byte[]	getEncodedPoint() Returns the encoded EC public point (the byte value of SubjectPublicKey.subjectPublicKey).
java.security.spec.ECParameterSpec	getParams() Returns the EC domain parameters associated with is EC public key.
java.security.spec.ECPoint	getW() Returns the EC public point w (also referred to as Q).

Methods inherited from class iaik.x509.PublicKeyInfo

createPublicKeyInfo, decode, equals, getFingerprint, getFormat, getPublicKey, getPublicKey, toASN1Object, toString, writeTo

Methods inherited from class java.lang.Object

clone, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.security.Key

getFormat

Constructor Detail

EcPublicKey

public EcPublicKey(byte[] ba)
            throws java.security.InvalidKeyException

A constructor; creates a new EcPublicKey object by decoding and parsing the passed in DER encoded ASN.1 SubjectPublicKeyInfo structure.

An EC public key contains EC domain parameters in addition to the public key value itself. Multiple EC domain parameter formats are supported including 'specified', 'named', and 'implicitCA'. During decoding of an EC public key, when EC domain parameters in 'implicitCA' format are encountered, this must be interpreted to mean a specific set of EC domain parameter values. For details on how 'implicitCA' EC domain parameters are interpreted, refer to EcPublicKey(byte[], ECParameterSpec).

Parameters:

ba - a DER encoded ASN.1 SubjectPublicKeyInfo structure

Throws:

java.security.InvalidKeyException - if the DER encoded data passed in does not represent a DER encoded ASN.1 SubjectPublicKeyInfo structure that contains an EC public key

EcPublicKey

public EcPublicKey(byte[] ba,
           java.security.spec.ECParameterSpec configuredImplicitCaParams)
            throws java.security.InvalidKeyException

A constructor; creates a new EcPublicKey object by decoding and parsing the passed in DER encoded ASN.1 SubjectPublicKeyInfo structure with support for providing 'implicitCA' EC domain parameter values.

An EC public key contains EC domain parameters in addition to the public key value itself. Multiple EC domain parameter formats are supported including 'specified', 'named', and 'implicitCA'. During decoding of an EC public key, when EC domain parameters in 'implicitCA' format are encountered, this must be interpreted to mean a specific set of EC domain parameter values. There are multiple ways of indicating the set of EC domain parameter values for 'implicitCA'; this constructor provides one way of doing so.

The following logic is used during a decode operation when 'implicitCA' domain parameters are encountered to determine the actual EC domain parameter values that should be used:

1. If locally configured 'implictCA' EC domain parameter values have been provided, these values are used. In this case the 'implicitCA' EC domain parameters are provided by the caller of this constructor.
2. If globally configured 'implictCA' EC domain parameter values have been set programmatically, these values are used. In this case the 'implicitCA' EC domain parameters are configured prior to the decode operation using the EcParameterFactory.setConfiguredImplicitCaParams(ECParameterSpec) API.
3. If a valid globally configured 'implictCA' named EC domain has been set through Java system properties, domain parameter values for this EC domain are used. In this case the 'implictCA' EC domain parameters are configured by setting the com.entrust.toolkit.security.crypto.ec.EcParameterFactory.configuredImplicitCaParamsDomainName Java system property to a valid EC domain name.
4. Otherwise the default set of 'implicitCA' EC domain parameters values are used; these parameters represent the P-256 EC domain.

Parameters:

ba - a DER encoded ASN.1 SubjectPublicKeyInfo structure

configuredImplicitCaParams - the locally configured 'implicitCA' EC domain parameter values (OPTIONAL)

Throws:

java.security.InvalidKeyException - if the DER encoded data passed in does not represent a DER encoded ASN.1 SubjectPublicKeyInfo structure that contains an EC public key

Since:

8.0

EcPublicKey

public EcPublicKey(java.security.spec.ECPoint w,
           java.security.spec.ECParameterSpec params)

A constructor; creates a new EcPublicKey object from the provided public point and EC domain parameters.

Parameters:

w - the EC public point (also referred to as Q)

params - the EC domain parameters

EcPublicKey

public EcPublicKey(java.security.spec.ECPoint w,
           java.security.spec.ECParameterSpec params,
           boolean forceSpecifiedEcDomainParams)

A constructor; creates a new EcPublicKey object from the provided public point, EC domain parameters, and an indicator for whether or not the domain parameters must be encoded in 'specified' format .

EC domain parameters can be represented in ASN.1 with 'specified', 'named' or 'implicitCA' format. Refer to getEncoded() for details on the EC domain parameter format that is used when encoding the public key.

Parameters:

w - the EC public point (also referred to as Q)

params - the EC domain parameters

forceSpecifiedEcDomainParams - a force 'specified' indicator; true if the EC domain parameters contained in this EC key must be encoded in 'specified' format; false otherwise

Method Detail

encodePoint

public static byte[] encodePoint(java.security.spec.ECPoint ecPoint,
                 java.security.spec.EllipticCurve ellipticCurve)

Converts an EC point in Sun JCA format to binary encoded format.

The EC point encoding routine is taken from ANSI X9.62-2005 Section A.5.7, however, currently only uncompressed form is supported.

ANSI X9.62-2005 A.5.7
Point to Octet String

The octet string representation of the point at infinity O shall be a single zero octet PC = 00.

An elliptic curve point P = (xP, yP) which is not the point at infinity shall be represented as an octet string in one of the following three forms:

1. compressed form,
2. uncompressed form, or
3. hybrid form

Input:

An elliptic curve point P = (xP, yP) which is not the point at infinity.

Actions

The following sequence of steps or its equivalent:

1. Convert the field element xP to an octet string XP. (see A.5)
2. If the compressed form is used, then do the following:
   1. Compute the bit zP. (See A.3.1.3)
   2. Assign the value 02 to the single octet PC if zP is 0, or the value 03 if zP is 1.
   3. The result is the octet string PO = PC || XP.
3. If the uncompressed form is used, then do the following:
   1. Convert the field element yP to an octet string YP. (See A.5)
   2. Assign the value 04 to the single octet PC.
   3. The result is octet string PO = PC || XP || YP.
4. if the hybrid form is used, then do the following:
   1. Convert the field element yP to an octet string YP. (See A.5)
   2. Compute the bit zP. (See A.3.1.3)
   3. Assign the value 06 to the single octet PC if zP is 0, or the value 07 if zP is 1.
   4. The result is octet string PO = PC || XP || YP.

Output:

An octet string PO of length l + 1 octets if the compressed form is used, or of length 2l + 1 if the uncompressed or hybrid form is used.

Parameters:

ecPoint - an EC point in Sun JCA format

ellipticCurve - the elliptic curve that the EC point exists on

Returns:

the EC point in binary encoded format

decodePoint

public static java.security.spec.ECPoint decodePoint(byte[] encodedEcPoint,
                                     java.security.spec.EllipticCurve ellipticCurve)

Converts an EC point in binary encoded format to Sun JCA format.

The EC point decoding routine is taken from ANSI X9.62-2005 Section A.5.8, however, currently only uncompressed form is supported and step 6 is not performed.

ANSI X9.62-2005 A.5.8
Octet String to Point

Input:

An octet string PO of length l + 1 octets if the compressed for is used, or of length 2l + 1 if the uncompressed or hybrid form is used, and field elements a, b which define the elliptic curve over Fq.

Actions:

The following sequence of steps or its equivalent:

1. If the compressed form is used, then parse PO as follows: PO = PC || XP, where PC is a single octet and XP is an octet string of length l octets. If the uncompressed or hybrid form is used, then parse PO as follows: PO = PC || XP || YP, where PC is a single octet, and XP and YP are octet strings each of length l octets.
2. Convert XP to a field element xP. (See A.5)
3. If the compressed form is used, then do the following:
   1. Verify that PC is either 02 or 03. (It is an error if this is not the case.)
   2. Set the bit zP to be equal to 0 if PC = 02, or 1 if PC = 03.
   3. Convert (xP, zP) to an elliptic curve point (xP, yP). (See A.3.1.3)
4. If the uncompressed form is used, then do the following:
   1. Verify that PC is 04. (It is an error if this is not the case.)
   2. Convert YP to a field element yP. (See A.5).
5. If the hybrid form is used, then do the following:
   1. Verify that PC is either 06 or 07. (It is an error if this is not the case.)
   2. Convert YP to a field element yP (See A.5)
   3. Set the bit zP to be equal to 0 if PC = 06, or 1 if PC = 07
   4. Perform one or both of the following:
      1. Compute a compressed point (xP, zP') from (xP, yP). (See A.3.1.3). Verify that (xP, zP) = (xP, zP'). (It is an error if this is not the case).
      2. Compute the uncompressed elliptic curve point (xP, yP') from the compressed point (xP, zP). (see A.3.1.3). Check that (xP, yP) = (xP, yP'). (It is an error if this is not the case).
6. If q is a prime, verify that yP^2 = xP^3 + axP + b. (It is an error if this is not the case). If q = 2^m, verify that yP^2 + xPyP = Xp^3 + aXp^2 + b. (It is an error if this is not the case).
7. The result is P = (xP, yP).

Output

An elliptic curve point P = (xP, yP), not the point at infinity.

Parameters:

encodedEcPoint - an EC point in binary encoded format

ellipticCurve - the elliptic curve that the EC point exists on

Returns:

the EC point in Sun JCA format

Throws:

java.lang.IllegalArgumentException - if an error occurs during point decoding (the binary encoded EC point is invalid)

getEncoded

public static byte[] getEncoded(java.security.interfaces.ECPublicKey publicKey,
                EcParameterFormat format)
                         throws java.lang.IllegalArgumentException,
                                UnsupportedECDomainException

Encodes an EC public key using the requested EC domain parameter format.

One component of a DER encoded EC public key are the EC domain parameters and these parameters can be represented in ASN.1 using different formats. This API allows the caller to control the EC domain parameter format that is used when encoding the EC domain parameters contained in the EC public key. Refer to EcParameterFactory.getInstance(ECParameterSpec, EcParameterFormat) for details on the supported EC domain parameters formats.

Parameters:

publicKey - an EC public key

format - requested EC domain parameter format

Returns:

the DER encoding of the public key

Throws:

java.lang.IllegalArgumentException - if the EC public key or the parameter format are not provided (missing)

UnsupportedECDomainException - if the 'named' format is requested and the EC domain parameter contained in the provided EC public key do not match one of the supported 'named' EC domains

Since:

8.0

getW

public java.security.spec.ECPoint getW()

Returns the EC public point w (also referred to as Q).

Specified by:

getW in interface java.security.interfaces.ECPublicKey

Returns:

the public point

getAlgorithm

public java.lang.String getAlgorithm()

Returns the algorithm of this public key, which is 'EC'.

Specified by:

getAlgorithm in interface java.security.Key

Specified by:

getAlgorithm in class PublicKeyInfo

Returns:

the algorithm of the public key

getParams

public java.security.spec.ECParameterSpec getParams()

Returns the EC domain parameters associated with is EC public key.

Specified by:

getParams in interface java.security.interfaces.ECKey

Returns:

the EC domain parameters

decode

protected void decode(byte[] subjectPublicKey)
               throws java.security.InvalidKeyException

Decodes a DER encoded ASN.1 representation of an EC public key value (a BIT STRING).

The DER encoded EC public key value is decoded and parsed and the EC public point it contains is stored internally.

Specified by:

decode in class PublicKeyInfo

Parameters:

subjectPublicKey - a DER encoded ASN.1 representation of an EC public key value

Throws:

java.security.InvalidKeyException - if the DER encoded data passed in does not represent a DER encoded ASN.1 BIT STRING structure that contains an EC public key

encode

protected byte[] encode()

Encodes a DER encoded ASN.1 representation of an EC public key value (a BIT STRING).

Specified by:

encode in class PublicKeyInfo

Returns:

the DER encoded ASN.1 representation of an EC public key value

getEncodedPoint

public byte[] getEncodedPoint()

Returns the encoded EC public point (the byte value of SubjectPublicKey.subjectPublicKey).

Returns:

the encoded EC public point

getEncoded

public byte[] getEncoded()

Returns this DER encoding of this public key.

Refer to getEncoded(boolean) for details on the EC domain parameter format that is used during encoding. This API has the same effect as calling getEncoded(false).

Specified by:

getEncoded in interface java.security.Key

Overrides:

getEncoded in class PublicKeyInfo

Returns:

DER encoding of the public key

getEncoded

public byte[] getEncoded(boolean forceSpecifiedEcDomainParams)

Encodes the public key using the force 'specified' indicator.

One component of the DER encoded public key is the EC domain parameters. EC domain parameters can be represented in ASN.1 using 'specified', 'named' or 'implicitCA' format. Because the most widely supported EC domain parameter format is 'specified', for interoperability reasons it can be desirable to force a 'specified' encoding. This implementation allows the EC domain parameter format used during encoding to be configured; the following logic is used during an encode operation to decide the format in which the EC domain parameters that the key contains should be encoded:

1. If the force 'specified' indicator has been set to true, then the 'specified' format is used.
2. If a force 'specified' indicator of true was provided through the constructor, then the 'specified' format is used.
3. If the either of the com.entrust.toolkit.security.crypto.ec.EcKey.forceSpecifiedEcDomainParams=true or com.entrust.toolkit.security.crypto.ec.EcPublicKey.forceSpecifiedEcDomainParams=true Java system properties are set as indicated, then the 'specified' format is used.
4. Otherwise, the EC domain parameter format indicated by the EC domain parameters themselves is used. For example, EcParameterSpecWithName supports 'specified', 'named', and 'implicitCA' formats, while EcParameterSpec only supports 'specified' format.

Parameters:

forceSpecifiedEcDomainParams - a force 'specified' indicator; true if the EC domain parameters contained in this EC key must be encoded in 'specified' format; false otherwise

Returns:

the DER encoding of this public key

Since:

8.0