com.entrust.toolkit.security.crypto.ec

Class EcPrivateKey

java.lang.Object

iaik.pkcs.pkcs8.PrivateKeyInfo

com.entrust.toolkit.security.crypto.ec.EcPrivateKey

All Implemented Interfaces:

ASN1Type, java.io.Serializable, java.security.interfaces.ECKey, java.security.interfaces.ECPrivateKey, java.security.Key, java.security.PrivateKey

public final class EcPrivateKey
extends PrivateKeyInfo
implements java.security.interfaces.ECPrivateKey

An Elliptic Curve (EC) private key.

An EC private key contains an EC private value and a set of EC domain parameters. The ASN.1 representation of an EC private key is defined in the PKCS, ANSI and SEC standards as follows:

 PrivateKeyInfo ::= SEQUENCE {
     version                 INTEGER,
     privateKeyAlgorithm     ecPublicKeyType,
     privateKey              PrivateKey
     attributes              [0] IMPLICIT SET OF Attribute OPTIONAL
 }
 
 ecPublicKeyType ALGORITHM ::= {
     OID id-ecPublicKey PARAMS ECDomainParameters
 }
 
 id-publicKeyType OBJECT IDENTIFIER ::= { 1 2 840 10045 2 1 }
 
 -- Defined in SEC 1: Elliptic Curve Cryptography
 ECPrivateKey ::= SEQUENCE {
      version       INTEGER { ecPrivkeyVer1(1) } (ecPrivkeyVer1),
      privateKey    OCTET STRING,
      parameters    [0] ECDomainParameters {{ SECGCurveNames }} OPTIONAL,
      publicKey     [1] BIT STRING OPTIONAL
 }
 

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 private keys containing these algorithm identifiers without failure). The Toolkit will recognize them during decoding as valid EC private 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 private 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 }
 

In the standard private key format, there are two different fields that can be used to store the EC domain parameters: PrivateKeyInfo.privateKeyAlgorithm.PARAMS and PrivateKeyInfo.privateKey.parameters. The SEC1 standard recommends that EC domain parameters be placed in the in the PrivateKeyInfo.privateKeyAlgorithm.PARAMS field and that the PrivateKeyInfo.privateKey.parameters field be omitted. This implementation follows that recommendation when encoding an EC private key. When decoding an EC private key, EC domain parameters are permitted in either or both fields; however, when both fields are present, the EC domain parameters contained in each field must be identical. Additionally, the standard private key format contains a field to represent the public key. This implementation partially supports this field; it is permitted during decoding, but always omitted during encoding.

In addition to the standard private key format, Entrust has also defined its own EC private key format; in the Entrust format, the ECPrivateKey definition is different:

 ECPrivateKey ::= INTEGER
 

The Entrust private key format was defined before the SEC 1 standard was released. The Entrust private key format is used by Entrust products only. It is not interoperable outside an Entrust environment. The Entrust private key format is used during secure key transfer between an Entrust client and an Entrust PKI. It is also used during the secure storage of EC private keys in an Entrust Profile (EPF).

The following constants have been defined that allow a caller to specify the format that should be used during encoding (both formats are supported during decoding):

• FORMAT_PKCS8
• FORMAT_PKCS8_ENTRUST

By default, the standard PKCS#8 format (FORMAT_PKCS8) is used during encoding. However, if the encoding format was set by the caller via the setFormat(String) API, this encoding format is used instead. Note that when a private key is decoded, the encoding format is automatically set to reflect the format that was encountered during decoding (this ensures that the same format is used if the key is re-encoded).

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').

Since:

7.2 SP2

See Also:

EcPublicKey, EcKeyPairGenerator, EcKeyFactory, Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	FORMAT_PKCS8 Standard PKCS#8 format for an EC private key (interoperable outside an Entrust environment).
static java.lang.String	FORMAT_PKCS8_ENTRUST Entrust specific PKCS#8 format for an EC private key (non-interoperable outside an Entrust environment).

Fields inherited from class iaik.pkcs.pkcs8.PrivateKeyInfo

private_key_algorithm, private_key_info

Fields inherited from interface java.security.interfaces.ECPrivateKey

serialVersionUID

Constructor Summary

Constructors

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

Method Summary

Methods

Modifier and Type	Method and Description
protected void	decode(byte[] encodedPrivateKey) Decodes a DER encoded ASN.1 ECPrivateKey structure.
protected byte[]	encode() Encodes a DER encoded ASN.1 ECPrivateKey structure.
byte[]	geEcPublicKey()
java.lang.String	getAlgorithm() Returns the algorithm of this private key, which is 'EC'.
byte[]	getEncoded() Returns this DER encoding of this private key.
byte[]	getEncoded(boolean forceSpecifiedEcDomainParams) Encodes the private key using the force 'specified' indicator.
java.lang.String	getFormat() Returns the format that will be used during encoding.
java.security.spec.ECParameterSpec	getParams() Returns the EC domain parameters associated with is EC private key.
java.math.BigInteger	getS() Returns the EC private value s (also referred to as d).
void	setFormat(java.lang.String format) Sets the format that will be used during encoding (both formats are supported during decoding).

Methods inherited from class iaik.pkcs.pkcs8.PrivateKeyInfo

createPrivateKeyInfo, decode, equals, getPrivateKey, getPrivateKey, toASN1Object, toString, writeTo

Methods inherited from class java.lang.Object

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

Field Detail

FORMAT_PKCS8

public static final java.lang.String FORMAT_PKCS8

Standard PKCS#8 format for an EC private key (interoperable outside an Entrust environment). Uses a DER encoding of the following ASN.1 structure when encoding and decoding the private key:

 PrivateKeyInfo ::= SEQUENCE {
     version                 INTEGER,
     privateKeyAlgorithm     ecPublicKeyType,
     privateKey              PrivateKey
     attributes              [0] IMPLICIT SET OF Attribute OPTIONAL
 }
 
 ecPublicKeyType ALGORITHM ::= {
     OID id-ecPublicKey PARAMS ECDomainParameters
 }
 
 id-publicKeyType OBJECT IDENTIFIER ::= { 1 2 840 10045 2 1 }
 
 -- Defined in SEC 1: Elliptic Curve Cryptography
 ECPrivateKey ::= SEQUENCE {
      version       INTEGER { ecPrivkeyVer1(1) } (ecPrivkeyVer1),
      privateKey    OCTET STRING,
      parameters    [0] ECDomainParameters {{ SECGCurveNames }} OPTIONAL,
      publicKey     [1] BIT STRING OPTIONAL
 }
 

See Also:

Constant Field Values

FORMAT_PKCS8_ENTRUST

public static final java.lang.String FORMAT_PKCS8_ENTRUST

Entrust specific PKCS#8 format for an EC private key (non-interoperable outside an Entrust environment). Uses a DER encoding of the following ASN.1 structure when encoding and decoding the private key:

 PrivateKeyInfo ::= SEQUENCE {
     version                 INTEGER,
     privateKeyAlgorithm     ecPublicKeyType,
     privateKey              PrivateKey
     attributes              [0] IMPLICIT SET OF Attribute OPTIONAL
 }
 
 ecPublicKeyType ALGORITHM ::= {
     OID id-ecPublicKey PARAMS ECDomainParameters
 }
 
 id-publicKeyType OBJECT IDENTIFIER ::= { 1 2 840 10045 2 1 }
 
 -- Defined by Entrust
 ECPrivateKey ::= INTEGER
 

See Also:

Constant Field Values

Constructor Detail

EcPrivateKey

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

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

Both FORMAT_PKCS8 and FORMAT_PKCS8_ENTRUST formats are supported during decoding.

An EC private key contains EC domain parameters in addition to the private key value itself. Multiple EC domain parameter formats are supported including 'specified', 'named', and 'implicitCA'. During decoding of an EC private 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 EcPrivateKey(byte[], ECParameterSpec).

Parameters:

ba - a DER encoded ASN.1 PrivateKeyInfo structure

Throws:

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

EcPrivateKey

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

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

An EC private key contains EC domain parameters in addition to the private key value itself. Multiple EC domain parameter formats are supported including 'specified', 'named', and 'implicitCA'. During decoding of an EC private 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 PrivateKeyInfo 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 PrivateKeyInfo structure that contains an EC private key

Since:

8.0

EcPrivateKey

public EcPrivateKey(java.math.BigInteger s,
            java.security.spec.ECParameterSpec params)

A constructor; creates a new EcPrivateKey object from the provided private value and EC domain parameters.

Parameters:

s - the EC private value (also referred to as d)

params - the EC domain parameters

EcPrivateKey

public EcPrivateKey(java.math.BigInteger s,
            java.security.spec.ECParameterSpec params,
            boolean forceSpecifiedEcDomainParams)

A constructor; creates a new EcPrivateKey object from the provided private value, 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 private key.

Parameters:

s - the EC private value (also referred to as d)

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

Since:

8.0

Method Detail

getS

public java.math.BigInteger getS()

Returns the EC private value s (also referred to as d).

Specified by:

getS in interface java.security.interfaces.ECPrivateKey

Returns:

the private value

getAlgorithm

public java.lang.String getAlgorithm()

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

Specified by:

getAlgorithm in interface java.security.Key

Specified by:

getAlgorithm in class PrivateKeyInfo

Returns:

the algorithm of the private key

getParams

public java.security.spec.ECParameterSpec getParams()

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

Specified by:

getParams in interface java.security.interfaces.ECKey

Returns:

the EC domain parameters

geEcPublicKey

public byte[] geEcPublicKey()

Returns:

a byte[] representation of the public key if it was stored as part of the private key. Otherwise return null. The private key represents a SubjectPublicKey from RFC 5480 section 2.2.

getFormat

public java.lang.String getFormat()

Returns the format that will be used during encoding.

Specified by:

getFormat in interface java.security.Key

Overrides:

getFormat in class PrivateKeyInfo

Returns:

the encoding format

See Also:

setFormat(String)

setFormat

public void setFormat(java.lang.String format)

Sets the format that will be used during encoding (both formats are supported during decoding).

The following formats are supported:

• FORMAT_PKCS8
• FORMAT_PKCS8_ENTRUST

Parameters:

format - the encoding format

decode

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

Decodes a DER encoded ASN.1 ECPrivateKey structure.

The DER encoded ECPrivateKey ASN.1 structure is decoded and parsed and the EC private key value it contains is stored internally.

Specified by:

decode in class PrivateKeyInfo

Parameters:

encodedPrivateKey - a DER encoded ASN.1 ECPrivateKey structure

Throws:

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

encode

protected byte[] encode()

Encodes a DER encoded ASN.1 ECPrivateKey structure.

The DER encoded ECPrivateKey ASN.1 structure is returned. The ECPrivateKey is encoded using the encoding/decoding format that was specified (or the default encoding/decoding format if none has been manually selected).

Specified by:

encode in class PrivateKeyInfo

Returns:

the DER encoded ECPrivateKey ASN.1 structure

getEncoded

public byte[] getEncoded()

Returns this DER encoding of this private 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 PrivateKeyInfo

Returns:

DER encoding of the private key

getEncoded

public byte[] getEncoded(boolean forceSpecifiedEcDomainParams)

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

One component of the DER encoded private 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.EcPrivateKey.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 private key

Since:

8.0