EcPrivateKey ("Entrust Authority Security Toolkit for the Java Platform")

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, javax.security.auth.Destroyable
```
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

All Methods Instance Methods Concrete 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

Methods inherited from interface javax.security.auth.Destroyable
destroy, isDestroyed

- 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

Class EcPrivateKey

Field Summary

Fields inherited from class iaik.pkcs.pkcs8.PrivateKeyInfo

Fields inherited from interface java.security.interfaces.ECPrivateKey

Constructor Summary

Method Summary

Methods inherited from class iaik.pkcs.pkcs8.PrivateKeyInfo

Methods inherited from class java.lang.Object

Methods inherited from interface javax.security.auth.Destroyable

Field Detail

FORMAT_PKCS8

FORMAT_PKCS8_ENTRUST

Constructor Detail

EcPrivateKey

EcPrivateKey

EcPrivateKey

EcPrivateKey

Method Detail

getS

getAlgorithm

getParams

geEcPublicKey

getFormat

setFormat

decode

encode

getEncoded

getEncoded