com.entrust.toolkit.x509.policies

Class EntrustAsymKeyType

java.lang.Object

com.entrust.toolkit.x509.policies.EntrustAsymKeyType

public class EntrustAsymKeyType
extends java.lang.Object

An asymmetric key type.

Asymmetric key types (in string representation) are used in various Entrust policy settings to convey information about a particular key pair. Specifically, the information necessary to generate a key pair of this type. This includes the following:

• Name: A unique string identifier for this type (e.g. "EC-P-256").
• Key algorithm: A string identifier for the algorithm for keys of this type (e.g. 'EC')
• Key size: The length in bits for keys of this type (i.e. 192-bits)
• Key parameters: The algorithm parameters required when generating a key pair of this type (e.g. EC domain parameters). Algorithm parameters are optional and only present for certain key types.

The class provides the ability to convert to/from an asymmetric key type in string representation. An asymmetric key type in string representation is simply the asymmetric key type name, which the following format:

<algorithm>-<parameters>

The algorithm component determines the format of the parameters component. This class supports the following key algorithms and enforces the indicated parameter format in each case:

Algorithm	Parameters Format
'RSA'	An integer key size in bits
'EC'	An EC domain name (see EcParameterFactory for a details on supported EC named domains)
'DSA'	An integer key size in bits
'ECDSA'	An integer key size in bits (this indicates the default EC domain parameters at this key size; see EcParameterFactory for details on the default EC domain parameters at a given key size)

This class also provides the ability to extract an asymmetric key type from an existing key. This functionality is supported for keys of the following type:

• RSA keys (implementations of java.security.interfaces.RSAKey
• DSA keys (implementations of java.security.interfaces.DSAKey
• EC keys (implementations of java.security.interfaces.ECKey, and instances of com.entrust.toolkit.security.provider.ECDSAPrivateKey and com.entrust.toolkit.security.provider.ECDSAPublicKey)

Since:

8.0

Method Summary

Methods

Modifier and Type	Method and Description
boolean	equals(java.lang.Object obj) Indicates whether or not another asymmetric key type is equal to this asymmetric key type.
static java.lang.String	getAsymKeyTypeString(java.security.Key key) Returns a string representation of the asymmetric key type for the provided key.
int	getBitsOfSecurity() Returns the bits of security that keys generated using this asymmetric key type provide.
static EntrustAsymKeyType	getEcInstance(java.security.spec.AlgorithmParameterSpec ecKeyParams) Determines the asymmetric key type of an EC key by examining the EC domain parameters associated with the key.
static EntrustAsymKeyType	getInstance(java.security.Key key) Determines the asymmetric key type of the specific key.
static EntrustAsymKeyType	getInstance(java.lang.String name) Parses an asymmetric key type from string name representation.
java.lang.String	getKeyAlgorithm() Gets the key algorithm component of this asymmetric key type.
java.security.spec.AlgorithmParameterSpec	getKeyParams() Gets the key parameters component of this asymmetric key type.
int	getKeySizeBits() Gets the key size component of this asymmetric key type.
java.lang.String	getName() Gets the name of this asymmetric key type.
int	hashCode() Returns a hash code value for this object.
boolean	isDsaKeyType() Indicates whether keys generated using this asymmetric key type are DSA keys.
boolean	isEcKeyType() Indicates whether keys generated using this key type are EC keys.
boolean	isRsaKeyType() Indicates whether keys generated using this asymmetric key type are RSA keys.
boolean	isStrongerThan(EntrustAsymKeyType keyType) Determines whether or not this asymmetric key type is stronger than another asymmetric key type.
boolean	supportsKeyEstablishment() Indicates whether keys generated using this asymmetric key type can be used for key establishment.
java.lang.String	toString() Returns the string representation of this object which is the name of this asymmetric key type.

Methods inherited from class java.lang.Object

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

Method Detail

getEcInstance

public static EntrustAsymKeyType getEcInstance(java.security.spec.AlgorithmParameterSpec ecKeyParams)

Determines the asymmetric key type of an EC key by examining the EC domain parameters associated with the key.

Currently, the following EC domain parameter representations are supported:

• java.security.spec.ECParameterSpec
• java.security.spec.ECGenParameterSpec
• com.entrust.toolkit.security.provider.ECParameters

Returns:

the asymmetric key type

Throws:

java.lang.IllegalArgumentException - if the provided EC domain parameters are invalid (unsupported parameter representation)

getInstance

public static EntrustAsymKeyType getInstance(java.lang.String name)
                                      throws java.lang.IllegalArgumentException

Parses an asymmetric key type from string name representation.

All key types listed in the class documentation of EntrustAsymKeyType are supported by this API.

Parameters:

name - name of the asymmetric key type

Returns:

the asymmetric key type (parsed from string representation)

Throws:

java.lang.IllegalArgumentException - if the provided name is invalid (invalid string name for an asymmetric key type)

getInstance

public static EntrustAsymKeyType getInstance(java.security.Key key)
                                      throws java.lang.IllegalArgumentException

Determines the asymmetric key type of the specific key.

Refer to the class documentation of EntrustAsymKeyType for details on the keys that are supported.

Parameters:

key - a key

Returns:

the asymmetric key type of the provided key

Throws:

java.lang.IllegalArgumentException - if type of key is not supported

getAsymKeyTypeString

public static java.lang.String getAsymKeyTypeString(java.security.Key key)

Returns a string representation of the asymmetric key type for the provided key.

The string representation is the asymmetric key type name for supported asymmetric key types (see getName()) or the string 'UNSUPPORTED (key algorithm)' for unsupported key types (where 'key algorithm' is the algorithm of the key).

All asymmetric key types supported by the getInstance(Key) are also supported by this API. This API was designed for use in exception messages and log messages.

Parameters:

key - a key

Returns:

string representation of the asymmetric key type

getName

public java.lang.String getName()

Gets the name of this asymmetric key type.

Returns:

the asymmetrickey type name (e.g. 'EC-P-256')

getKeyAlgorithm

public java.lang.String getKeyAlgorithm()

Gets the key algorithm component of this asymmetric key type.

Returns:

the key algorithm (e.g. 'EC')

getKeySizeBits

public int getKeySizeBits()

Gets the key size component of this asymmetric key type.

Returns:

the key size in bits (e.g. 256-bits)

getKeyParams

public java.security.spec.AlgorithmParameterSpec getKeyParams()

Gets the key parameters component of this asymmetric key type.

Note: Only certain asymmetric key types support key parameters; for example RSA-based and DSA-based key types do not contain key parameters, but EC-based key types do contain key parameters

Returns:

the key parameters (e.g. EC domain parameters); null for asymmetric key types that do not contain key parameters

toString

public java.lang.String toString()

Returns the string representation of this object which is the name of this asymmetric key type.

Overrides:

toString in class java.lang.Object

Returns:

the string representation of this object

isEcKeyType

public boolean isEcKeyType()

Indicates whether keys generated using this key type are EC keys.

An asymmetric key type is EC-based if the algorithm component is "EC" or "ECDSA".

Returns:

true if the asymmetric key type is EC-based; false otherwise

isRsaKeyType

public boolean isRsaKeyType()

Indicates whether keys generated using this asymmetric key type are RSA keys.

An asymmetric key type is RSA-based if the algorithm component is "RSA".

Returns:

true if the asymmetric key type is RSA-based; false otherwise

isDsaKeyType

public boolean isDsaKeyType()

Indicates whether keys generated using this asymmetric key type are DSA keys.

An asymmetric key type is DSA-based if the algorithm component is "DSA".

Returns:

true if the asymmetric key type is DSA-based; false otherwise

supportsKeyEstablishment

public boolean supportsKeyEstablishment()

Indicates whether keys generated using this asymmetric key type can be used for key establishment.

Note: EC and RSA keys can be used for key establishment; DSA keys cannot.

Returns:

true if the asymmetric key type support key establishment; false otherwise

isStrongerThan

public boolean isStrongerThan(EntrustAsymKeyType keyType)

Determines whether or not this asymmetric key type is stronger than another asymmetric key type.

For asymmetric key types with the same algorithm component, or for two EC-based key types, the key size is compared; if this asymmetric key type has a larger key size, then it is stronger. Otherwise, the bits of security provided by the key (see getBitsOfSecurity() is compared; if this asymmetric key type has more bits of security, then it is stronger.

Parameters:

keyType - the other asymmetric key type

Returns:

true if this asymmetric key type is stronger; false otherwise

getBitsOfSecurity

public int getBitsOfSecurity()

Returns the bits of security that keys generated using this asymmetric key type provide.

Bits of security for a particular asymmetric key type are determined based on the "Comparable strengths" table from NIST SP 800-57 Part 1, which indicates the following:

Bits of Security	Key size in bits
	RSA	DSA	ECDSA
80	1024	1024	160..223
112	2048	2048	224..255
128	3072	1024	256..383
192	7680	7680	384..511
256	15360	15360	512+

Note: For key sizes not listed here, the bits of security is considered to be the same as the next smaller key size that is listed here (i.e. RSA-1024, RSA-1280, and RSA-1536 all offer 80-bits of security).
Note: For key sizes smaller than the smallest key size listed here, these keys are treated as offering 0-bits of security (they are weak and should not be used).

Returns:

the bits of security (strength) of this asymmetric key type

equals

public boolean equals(java.lang.Object obj)

Indicates whether or not another asymmetric key type is equal to this asymmetric key type.

Overrides:

equals in class java.lang.Object

Returns:

true if the two objects are equal; false otherwise

hashCode

public int hashCode()

Returns a hash code value for this object.

Overrides:

hashCode in class java.lang.Object

Returns:

a hash code value for this object.