com.entrust.toolkit.asn1.structures

Class AlgorithmID

java.lang.Object

com.entrust.toolkit.asn1.structures.AlgorithmID

All Implemented Interfaces:

ASN1Type, java.lang.Cloneable

public class AlgorithmID
extends java.lang.Object
implements ASN1Type, java.lang.Cloneable

This class implements the ASN.1 structure for AlgorithmIdentifier as defined in RFC 3280, the Certificate and CRL Profile specification.

 AlgorithmIdentifier ::= SEQUENCE {
     algorithm     OBJECT IDENTIFIER,
     parameters    ANY DEFINED BY algorithm OPTIONAL
 }
 

It represents an algorithm identifier that is used to identify a cryptographic algorithm. The OBJECT IDENTIFIER component identifies the algorithm (such as DSA with SHA-1). The contents of the optional parameters field will vary according to the algorithm identified.

In order to link algorithm identifiers with actual cryptographic algorithms and keys, this class maintains a mapping between algorithm identifiers and their corresponding JCA cryptographic algorithm and key names. It also contains several methods that allow JCA algorithm instances to be created directly from an algorithm identifier.

This class also maintains a mapping between algorithm identifiers and algorithm-parameter specifications. It contains a method that allows the algorithm parameters to be converted to a registered AlgorithmParameterSpec representation.

Since:

7.0

See Also:

AlgorithmParameterSpec

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	AlgorithmID.CipherAlgs Contains a set of pre-defined (known) cipher algorithm identifiers.
static class	AlgorithmID.MacAlgs Contains a set of pre-defined (known) message authentication code (MAC) algorithm identifiers.
static class	AlgorithmID.MessageDigestAlgs Contains a set of pre-defined (known) message digest algorithm identifiers.
static class	AlgorithmID.SignatureAlgs Contains a set of pre-defined (known) signature algorithm identifiers.

Constructor Summary

Constructors

Constructor and Description
AlgorithmID(AlgorithmID algId) The copy constructor; creates a deep copy of the provided algorithm identifier, including algorithm parameters.
AlgorithmID(ASN1Object obj) Creates a new AlgorithmIdentifier from an ASN1Object.
AlgorithmID(ObjectID algorithm) Creates a new AlgorithmIdentifier object with the specified algorithm and null parameters.
AlgorithmID(ObjectID algorithm, java.security.spec.AlgorithmParameterSpec params) Creates a new AlgorithmIdentifier object with the specified algorithm and parameters (in transparent format).
AlgorithmID(ObjectID algorithm, ASN1Object params) Creates a new AlgorithmIdentifier object with the specified algorithm and parameters.

Method Summary

Methods

Modifier and Type	Method and Description
java.lang.Object	clone() Creates and returns a copy of this algorithm identifier object.
void	decode(ASN1Object obj) Decodes an AlgorithmIdentifier from an ASN1Object.
boolean	equalOIDs(AlgorithmID algorithmID) Compares the object identifier(OID) of this algorithm identifier with the OID of the provided algorithm identifier.
boolean	equals(java.lang.Object obj) Determines whether this AlgorithmID instance is equal to another AlgorithmID instance.
ObjectID	getAlgorithm() Returns the identifier for the algorithm.
java.security.spec.AlgorithmParameterSpec	getAlgorithmParameterSpec() Converts the algorithm parameters from ASN1 encoded format to JCA algorithm-parameter specification format.
javax.crypto.Cipher	getCipherInstance() Attempts to create a Cipher instance for the algorithm that this algorithm identifier represents.
java.security.MessageDigest	getEntrustMessageDigestInstance() Attempts to create a MessageDigest instance for the algorithm that this algorithm identifier represents from the Entrust JCA/JCE cryptographic provider.
java.security.Signature	getEntrustSignatureInstance() Attempts to create a Signature instance for the algorithm that this algorithm identifier represents from the Entrust JCA/JCE cryptographic provider.
java.lang.String	getJCAAlgName() Returns the name of the Java Cryptography Architecture(JCA) cryptographic algorithm that this algorithm identifier represents.
java.lang.String	getJCAKeyName() Returns the name of the Java Cryptography Architecture(JCA) cryptographic key that this algorithm identifier represents.
javax.crypto.KeyAgreement	getKeyAgreementInstance() Attempts to create a KeyAgreement instance for the algorithm that this algorithm identifier represents.
java.security.KeyFactory	getKeyFactoryInstance() Attempts to create a KeyFactory instance for the algorithm that this algorithm identifier represents.
javax.crypto.KeyGenerator	getKeyGeneratorInstance() Attempts to create a KeyGenerator instance for the algorithm that this algorithm identifier represents.
java.security.KeyPairGenerator	getKeyPairGeneratorInstance() Attempts to create a KeyPairGenerator instance for the algorithm that this algorithm identifier represents.
javax.crypto.Mac	getMacInstance() Attempts to create a Mac instance for the algorithm that this algorithm identifier represents.
java.security.MessageDigest	getMessageDigestInstance() Attempts to create a MessageDigest instance for the algorithm that this algorithm identifier represents.
ASN1Object	getParameters() Returns the paramters associated with the algorithm if any have been set; otherwise null is returned.
java.security.AlgorithmParameters	getParametersAsAlgorithmParameters() Extracts the algorithm parameters from the algorithm identifier and returns them in JCA opaque algorithm parameters representation.
<T extends java.security.spec.AlgorithmParameterSpec> T	getParametersAsAlgorithmParameterSpec(java.lang.Class<T> paramSpec) Extracts the algorithm parameters from the algorithm identifier and returns them in JCA transparent algorithm parameters representation.
javax.crypto.SecretKeyFactory	getSecretKeyFactoryInstance() Attempts to create a SecretKeyFactory instance for the algorithm that this algorithm identifier represents.
java.security.SecureRandom	getSecureRandomInstance() Attempts to create a SecureRandom instance for the algorithm that this algorithm identifier represents.
java.security.Signature	getSignatureInstance() Attempts to create a Signature instance for the algorithm that this algorithm identifier represents.
int	getSymmetricKeySize() Returns the symmetric key size in bits specified by this algorithm identifier.
int	hashCode() Returns a hash code value for the object.
void	initSignatureSign(java.security.Signature signatureAlg, java.security.PrivateKey signingKey) Initializes a Signature algorithm instance for signing with the specified signing private key and algorithm parameters from the Algorithm Identifier.
void	initSignatureVerify(java.security.Signature signatureAlg, java.security.PublicKey verificationKey) Initializes a Signature algorithm instance for verification with the specified verification public key and algorithm parameters from the Algorithm Identifier.
boolean	registerJCANames(java.lang.String jcaAlgName, java.lang.String jcaKeyName) Registers the Java Cryptography Architecture(JCA) cryptographic algorithm and key names for a given algorithm identifier.
boolean	registerParameterSpec(java.lang.Class<?> parameterSpecClass) Registers a Java Cryptography Architecture(JCA) algorithm-parameter specification for a given algorithm identifier.
void	setParameters(java.security.spec.AlgorithmParameterSpec parameters) Sets the parameters associated with the algorithm by converting from transparent representation.
void	setParameters(ASN1Object parameters) Sets the parameters associated with the algorithm.
ASN1Object	toASN1Object() Encodes this AlgorithmIdentifier object as an ASN1Object.
AlgorithmID	toIAIKAlgorithmID() Converts an Entrust Algorithm Identifier to an IAIK Algorithm Identifier.
java.lang.String	toMessageString() Creates a message string that represents the contents of this AlgorithmIdentifier object, without the parameters.
java.lang.String	toString() Creates a text representation of the ASN.1 structure of this AlgorithmIdentifier object.

Methods inherited from class java.lang.Object

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

Constructor Detail

AlgorithmID

public AlgorithmID(ObjectID algorithm)

Creates a new AlgorithmIdentifier object with the specified algorithm and null parameters.

Parameters:

algorithm - identifier for the algorithm

AlgorithmID

public AlgorithmID(ObjectID algorithm,
           ASN1Object params)

Creates a new AlgorithmIdentifier object with the specified algorithm and parameters.

Parameters:

algorithm - identifier for the algorithm

parameters - algorithm parameters (can be null)

Since:

8.0

AlgorithmID

public AlgorithmID(ObjectID algorithm,
           java.security.spec.AlgorithmParameterSpec params)
            throws java.security.InvalidAlgorithmParameterException

Creates a new AlgorithmIdentifier object with the specified algorithm and parameters (in transparent format).

Parameters:

algorithm - identifier for the algorithm

parameters - algorithm parameters (can be null)

Throws:

java.security.InvalidAlgorithmParameterException - if the algorithm parameters are not appropriate for this algorithm identifier

Since:

8.0

AlgorithmID

public AlgorithmID(ASN1Object obj)
            throws CodingException

Creates a new AlgorithmIdentifier from an ASN1Object.

The ASN1Object must be an AlgorithmIdentifier structure.

Parameters:

obj - the ASN.1 representation of an AlgorithmIdentifier structure

Throws:

CodingException - thrown if an errors occurs while decoding the ANS1Object

AlgorithmID

public AlgorithmID(AlgorithmID algId)

The copy constructor; creates a deep copy of the provided algorithm identifier, including algorithm parameters.

Parameters:

algId - algorithm identifier to be copied

Since:

7.2

Method Detail

getAlgorithm

public ObjectID getAlgorithm()

Returns the identifier for the algorithm.

Returns:

the algorithm component

getParameters

public ASN1Object getParameters()

Returns the paramters associated with the algorithm if any have been set; otherwise null is returned.

Returns:

the applicationName component

setParameters

public void setParameters(ASN1Object parameters)

Sets the parameters associated with the algorithm.

Parameters:

parameters - the parameters component

Throws:

java.lang.RuntimeException - thrown if this method is called on a known algorithm identifier (any algorithm identifier available as a static field from this class)

setParameters

public void setParameters(java.security.spec.AlgorithmParameterSpec parameters)
                   throws java.security.InvalidAlgorithmParameterException

Sets the parameters associated with the algorithm by converting from transparent representation.

Parameters:

parameters - the parameters (in transparent representation)

Throws:

java.security.InvalidAlgorithmParameterException - if the algorithm parameters are not appropriate for this algorithm identifier

java.lang.RuntimeException - thrown if this method is called on a known algorithm identifier (any algorithm identifier available as a static field from this class)

Since:

8.0

decode

public void decode(ASN1Object obj)
            throws CodingException

Decodes an AlgorithmIdentifier from an ASN1Object.

The ASN1Object must be an AlgorithmIdentifier structure.

Specified by:

decode in interface ASN1Type

Parameters:

obj - an ASN.1 representation of an AlgorithmIdentifier structure

Throws:

CodingException - thrown if an errors occurs while decoding the ANS1Object

java.lang.RuntimeException - thrown if this method is called on a known algorithm identifier (any algorithm identifier available as a static field from this class)

toASN1Object

public ASN1Object toASN1Object()

Encodes this AlgorithmIdentifier object as an ASN1Object.

Specified by:

toASN1Object in interface ASN1Type

Returns:

an ASN.1 representation of the AlgorithmIdentifier structure

toString

public java.lang.String toString()

Creates a text representation of the ASN.1 structure of this AlgorithmIdentifier object.

Overrides:

toString in class java.lang.Object

Returns:

a text representation of the ASN.1 structure of this object

equals

public boolean equals(java.lang.Object obj)

Determines whether this AlgorithmID instance is equal to another AlgorithmID instance.

Performs the following check: a == b.

Overrides:

equals in class java.lang.Object

Parameters:

obj - another AlgorithmID instance

Returns:

true if a == b; false otherwise

hashCode

public int hashCode()

Returns a hash code value for the object.

Overrides:

hashCode in class java.lang.Object

Returns:

a hash code for this object

toMessageString

public java.lang.String toMessageString()

Creates a message string that represents the contents of this AlgorithmIdentifier object, without the parameters.

This method can be used to create messages that can be returned in exceptions.

Returns:

a message string that represents this object

toIAIKAlgorithmID

public AlgorithmID toIAIKAlgorithmID()

Converts an Entrust Algorithm Identifier to an IAIK Algorithm Identifier.

The Algorithm Identifier components (identifier and parameters) are passed by reference (a deep copy of the elements is not done).

Returns:

the IAIK Algorithm Identifier

Since:

8.1

equalOIDs

public boolean equalOIDs(AlgorithmID algorithmID)

Compares the object identifier(OID) of this algorithm identifier with the OID of the provided algorithm identifier.

It is simply a comparison of the 'algorithm' components of two algorithm identifiers. The 'parameters' components are not used in this comparison.

Parameters:

algorithmID - an algorithm identifier

Returns:

true if the algorithm object identifiers are equal; false otherwise

clone

public java.lang.Object clone()

Creates and returns a copy of this algorithm identifier object.

Both the algorithm identifier and algorithm parmaeters are copied. This is done using a shallows copy.

Overrides:

clone in class java.lang.Object

Returns:

a clone of this algorithm identifier instance

registerJCANames

public boolean registerJCANames(java.lang.String jcaAlgName,
                       java.lang.String jcaKeyName)

Registers the Java Cryptography Architecture(JCA) cryptographic algorithm and key names for a given algorithm identifier.

This class internally maintains two static look-up tables; one that associates algorithm object identifiers (OIDs) with JCA cryptographic algorithm names, and one that associates algorithm OIDs with JCA cryptographic key names. These tables are statically loaded with an entry for every known algorithm (all algorithms available as static fields from this class are considered known algorithms). This method can be used to load the look-up tables with entries for additional algorithm OIDs (not previously registered), but will not allow existing entries to be over-written.

Once an algorithm identifier has been registered, both the JCA cryptographic algorithm name and the JCA cryptographic key name can be accessed using the following get methods: getJCAAlgName() or getJCAKeyName().

Parameters:

jcaAlgName - the JCA cryptographic algorithm name being registered

jcaKeyName - the JCA cryptographic key name being registered

Returns:

boolean true if the registration was successful (the algorithm OID was not already registered); false otherwise

getJCAAlgName

public java.lang.String getJCAAlgName()

Returns the name of the Java Cryptography Architecture(JCA) cryptographic algorithm that this algorithm identifier represents.

This class internally maintains a static look-up table that associates algorithm object identifiers (OIDs) with JCA cryptographic algorithm names. This table is statically loaded with an entry for every known algorithm (all algorithms available as static fields from this class are considered known algorithms). When this method is called, the internal look-up table is checked for an entry that matches the algorithm identifier's OID. If an entry is not found, the algorithm identifier's OID name is returned.

Additional entries can be manually added to the JCA cryptographic algorithm name look-up table, by registering the JCA algorithm name. This can be done using: registerJCANames(String, String).

The algorithm name that this method returns can be used to create an instance of a JCA cryptographic algorithm. This can be done using any of the following:

• Cipher.getInstance()
• KeyAgreement.getInstance()
• Mac.getInstance()
• MessageDigest.getInstance()
• SecureRandom.getInstance()
• Signature.getInstance()

To simplify the process of creating cryptographic algorithm instances from algorithm identifiers, this class also provides several 'get cryptographic instance' methods (ex: getCipherInstance()) that take care of the cryptographic algorithm instantiation. They simply return the desired type of cryptographic algorithm, if it exists in the JCA.

Returns:

the JCA cryptographic algorithm name

See Also:

Cipher, KeyAgreement, Mac, MessageDigest, SecureRandom, Signature

getJCAKeyName

public java.lang.String getJCAKeyName()

Returns the name of the Java Cryptography Architecture(JCA) cryptographic key that this algorithm identifier represents.

This class internally maintains a static look-up table that associates algorithm object identifiers (OIDs) with JCA cryptographic key names. This table is statically loaded with an entry for every known algorithm (all algorithms available as static fields from this class are considered known algorithms). When this method is called, the internal look-up table is checked for an entry that matches the algorithm identifier's OID. If an entry is not found, the algorithm identifier's cryptographic algorithm name is returned.

Additional entries can be manually added to the JCA cryptographic key name look-up table, by registering the JCA key name. This can be done using: registerJCANames(String, String).

The key name that this method returns can be used to create an instance of a JCA key generator/factory representation. This can be done using any of the following:

• KeyFactory.getInstance()
• KeyGenerator.getInstance()
• KeyPairGenerator.getInstance()
• SecretKeyFactory.getInstance()

To simplify the process of creating cryptographic key generator/factory instances from algorithm identifiers, this class also provides several 'get cryptographic instance' methods (ex: getKeyGeneratorInstance()) that take care of the cryptographic algorithm instantiation. They simply return the desired type of cryptographic algorithm, if it exists in the JCA.

Returns:

the JCA cryptographic key name

See Also:

KeyFactory, KeyPairGenerator, KeyGenerator, SecretKeyFactory

getCipherInstance

public javax.crypto.Cipher getCipherInstance()
                                      throws java.security.NoSuchAlgorithmException

Attempts to create a Cipher instance for the algorithm that this algorithm identifier represents.

The registered 'JCA algorithm name' is used to request the algorithm instance from the cryptographic providers in the following order.

• Entrust
• IAIK
• default provider order

Returns:

a Cipher instance corresponding to the algorithm identifier

Throws:

java.security.NoSuchAlgorithmException - thrown if a Cipher instance for the algorithm identifier is not recognized by any of the installed cryptographic providers

See Also:

Cipher

getKeyAgreementInstance

public javax.crypto.KeyAgreement getKeyAgreementInstance()
                                                  throws java.security.NoSuchAlgorithmException

Attempts to create a KeyAgreement instance for the algorithm that this algorithm identifier represents.

The registered 'JCA algorithm name' is used to request the algorithm instance from the cryptographic providers in the following order.

• Entrust
• IAIK
• default provider order

Returns:

a KeyAgreement instance corresponding to the algorithm identifier

Throws:

java.security.NoSuchAlgorithmException - thrown if a KeyAgreement instance for the algorithm identifier is not recognized by any of the installed cryptographic providers

See Also:

KeyAgreement

getKeyFactoryInstance

public java.security.KeyFactory getKeyFactoryInstance()
                                               throws java.security.NoSuchAlgorithmException

Attempts to create a KeyFactory instance for the algorithm that this algorithm identifier represents.

The registered 'JCA key name' is used to request the algorithm instance from the cryptographic providers in the following order.

• Entrust
• IAIK
• default provider order

Returns:

a KeyFactory instance corresponding to the algorithm identifier

Throws:

java.security.NoSuchAlgorithmException - thrown if a KeyFactory instance for the algorithm identifier is not recognized by any of the installed cryptographic providers

See Also:

KeyFactory

getKeyGeneratorInstance

public javax.crypto.KeyGenerator getKeyGeneratorInstance()
                                                  throws java.security.NoSuchAlgorithmException

Attempts to create a KeyGenerator instance for the algorithm that this algorithm identifier represents.

The registered 'JCA key name' is used to request the algorithm instance from the cryptographic providers in the following order.

• Entrust
• IAIK
• default provider order

Returns:

a KeyGenerator instance corresponding to the algorithm identifier

Throws:

java.security.NoSuchAlgorithmException - thrown if a KeyGenerator instance for the algorithm identifier is not recognized by any of the installed cryptographic providers

See Also:

KeyGenerator

getKeyPairGeneratorInstance

public java.security.KeyPairGenerator getKeyPairGeneratorInstance()
                                                           throws java.security.NoSuchAlgorithmException

Attempts to create a KeyPairGenerator instance for the algorithm that this algorithm identifier represents.

The registered 'JCA key name' is used to request the algorithm instance from the cryptographic providers in the following order.

• Entrust
• IAIK
• default provider order

Returns:

a KeyPairGenerator instance corresponding to the algorithm identifier

Throws:

java.security.NoSuchAlgorithmException - thrown if a KeyPairGenerator instance for the algorithm identifier is not recognized by any of the installed cryptographic providers

See Also:

KeyPairGenerator

getMacInstance

public javax.crypto.Mac getMacInstance()
                                throws java.security.NoSuchAlgorithmException

Attempts to create a Mac instance for the algorithm that this algorithm identifier represents.

The registered 'JCA algorithm name' is used to request the algorithm instance from the cryptographic providers in the following order.

• Entrust
• IAIK
• default provider order

Returns:

a Mac instance corresponding to the algorithm identifier

Throws:

java.security.NoSuchAlgorithmException - thrown if a Mac instance for the algorithm identifier is not recognized by any of the installed cryptographic providers

See Also:

Mac

getMessageDigestInstance

public java.security.MessageDigest getMessageDigestInstance()
                                                     throws java.security.NoSuchAlgorithmException

Attempts to create a MessageDigest instance for the algorithm that this algorithm identifier represents.

The registered 'JCA algorithm name' is used to request the algorithm instance from the cryptographic providers in the following order.

• Entrust
• IAIK
• default provider order

Returns:

a MessageDigest instance corresponding to the algorithm identifier

Throws:

java.security.NoSuchAlgorithmException - thrown if a MessageDigest instance for the algorithm identifier is not recognized by any of the installed cryptographic providers

See Also:

MessageDigest

getEntrustMessageDigestInstance

public java.security.MessageDigest getEntrustMessageDigestInstance()
                                                            throws java.security.NoSuchAlgorithmException

Attempts to create a MessageDigest instance for the algorithm that this algorithm identifier represents from the Entrust JCA/JCE cryptographic provider.

Returns:

a MessageDigest instance corresponding to the algorithm identifier

Throws:

java.security.NoSuchAlgorithmException - if the Entrust provider does not support the message digest algorithm

java.lang.SecurityException - if the Entrust provider is not installed

Since:

7.2

See Also:

MessageDigest

getSecretKeyFactoryInstance

public javax.crypto.SecretKeyFactory getSecretKeyFactoryInstance()
                                                          throws java.security.NoSuchAlgorithmException

Attempts to create a SecretKeyFactory instance for the algorithm that this algorithm identifier represents.

The registered 'JCA key name' is used to request the algorithm instance from the cryptographic providers in the following order.

• Entrust
• IAIK
• default provider order

Returns:

a SecretKeyFactory instance corresponding to the algorithm identifier

Throws:

java.security.NoSuchAlgorithmException - thrown if a SecretKeyFactory instance for the algorithm identifier is not recognized by any of the installed cryptographic providers

See Also:

SecretKeyFactory

getSecureRandomInstance

public java.security.SecureRandom getSecureRandomInstance()
                                                   throws java.security.NoSuchAlgorithmException

Attempts to create a SecureRandom instance for the algorithm that this algorithm identifier represents.

The registered 'JCA algorithm name' is used to request the algorithm instance from the cryptographic providers in the following order.

• Entrust
• IAIK
• default provider order

Returns:

a SecureRandom instance corresponding to the algorithm identifier

Throws:

java.security.NoSuchAlgorithmException - thrown if a SecureRandom instance for the algorithm identifier is not recognized by any of the installed cryptographic providers

See Also:

SecureRandom

getSignatureInstance

public java.security.Signature getSignatureInstance()
                                             throws java.security.NoSuchAlgorithmException

Attempts to create a Signature instance for the algorithm that this algorithm identifier represents.

The registered 'JCA algorithm name' is used to request the algorithm instance from the cryptographic providers in the following order.

• Entrust
• IAIK
• default provider order

Returns:

a Signature instance corresponding to the algorithm identifier

Throws:

java.security.NoSuchAlgorithmException - thrown if a Signature instance for the algorithm identifier is not recognized by any of the installed cryptographic providers

See Also:

Signature

initSignatureVerify

public void initSignatureVerify(java.security.Signature signatureAlg,
                       java.security.PublicKey verificationKey)
                         throws java.security.InvalidAlgorithmParameterException,
                                java.security.InvalidKeyException

Initializes a Signature algorithm instance for verification with the specified verification public key and algorithm parameters from the Algorithm Identifier.

For an Algorithm Identifier that contains algorithms parameters, these parameters are extracted, decoded, and set in the Signature algorithm instance prior to initialization. This ensures that the algorithm parameters specified inside an Algorithm Identifier are actually used during signature verification; some signature algorithms require algorithm parameters (ex: RSA-PSS).

This API was introduced to provide better support for the RSA-PSS signature algorithm, which requires algorithm parameters. It is used throughout the Toolkit for signature verification purposes. It should be used in conjunction with the getSignatureInstance() API to instantiate and then initialize a Signature algorithm instance.

Important:

The JCA Signature class was not designed to allow algorithm parameters to be set in a provider independent manner; the Signature class only accepts algorithm parameters in AlgorithmParameterSpec format. This API extracts the algorithm parameters from the Algorithm Identifier in DER encoded ASN.1 format and then converts them to one of Entrust's AlgorithmParameterSpec implementations. (The actual AlgorithmParameterSpec used are registered in Entrust's AlgorithmID class, for more details refer to getAlgorithmParameterSpec()). These implementations will most likely only be compatible with Entrust's Signature algorithm implementations. For this reason, when using this API to instantiate and initialize a Signature algorithm instance from a non-Entrust JCA/JCE cryptographic service provider, and algorithm parameters are specified in the Algorithm Identifier, an InvalidAlgorithmParameterException may result.

Parameters:

signatureAlg - the Signature algorithm implementation to be initialized for verification

verificationKey - the public verification key

Throws:

java.security.InvalidKeyException - if the public verification key is not appropriate for the Signature algorithm implementation

java.security.InvalidAlgorithmParameterException - if the algorithm parameters are not supported by the Signature algorithm implementation or the algorithm parameters could not be converted from DER encoded ASN.1 format to AlgorithmParameterSpec format

Since:

7.2 patch

initSignatureSign

public void initSignatureSign(java.security.Signature signatureAlg,
                     java.security.PrivateKey signingKey)
                       throws java.security.InvalidAlgorithmParameterException,
                              java.security.InvalidKeyException

Initializes a Signature algorithm instance for signing with the specified signing private key and algorithm parameters from the Algorithm Identifier.

For an Algorithm Identifier that contains algorithms parameters, these parameters are extracted, decoded, and set in the Signature algorithm instance prior to initialization. This ensures that the algorithm parameters specified inside an Algorithm Identifier are actually used during signature generation (some signature algorithms require algorithm parameters).

After the Signature algorithm instance has been initialized, the algorithm parameters it is configured to use are extracted, encoded, and stored back in Algorithm Identifier. This ensures that the algorithm parameters that are actually used by the Signature algorithm implementation are not discarded. This is important for signature algorithms that automatically generate their own default parameters when none are provided (ex: RSA-PSS).

This API was introduced to provide better support for the RSA-PSS signature algorithm, which requires algorithm parameters. It is used throughout the Toolkit for signature generation purposes. It should be used in conjunction with the getSignatureInstance() API to instantiate and then initialize a Signature algorithm instance.

Important:

The JCA Signature class was not designed to allow algorithm parameters to be set in a provider independent manner; the Signature class only accepts algorithm parameters in AlgorithmParameterSpec format. This API extracts the algorithm parameters from the Algorithm Identifier in DER encoded ASN.1 format and then converts them to one of Entrust's AlgorithmParameterSpec implementations. (The actual AlgorithmParameterSpec used are registered in Entrust's AlgorithmID class, for more details refer to getAlgorithmParameterSpec()). These implementations will most likely only be compatible with Entrust's Signature algorithm implementations. For this reason, when using this API to instantiate and initialize a Signature algorithm instance from a non-Entrust JCA/JCE cryptographic service provider, and algorithm parameters are specified in the Algorithm Identifier, an InvalidAlgorithmParameterException may result.

Parameters:

signatureAlg - the Signature algorithm implementation to be initialized for signing

signingKey - the private signing key

Throws:

java.security.InvalidKeyException - if the private signing key is not appropriate for the Signature algorithm implementation

java.security.InvalidAlgorithmParameterException - if the algorithm parameters are not supported by the Signature algorithm implementation or the algorithm parameters could not be converted from DER encoded ASN.1 format to AlgorithmParameterSpec format

Since:

7.2 patch

getEntrustSignatureInstance

public java.security.Signature getEntrustSignatureInstance()
                                                    throws java.security.NoSuchAlgorithmException

Attempts to create a Signature instance for the algorithm that this algorithm identifier represents from the Entrust JCA/JCE cryptographic provider.

Returns:

a Signature instance corresponding to the algorithm identifier

Throws:

java.security.NoSuchAlgorithmException - if the Entrust provider does not support the digital signature algorithm

java.lang.SecurityException - if the Entrust provider is not installed

Since:

7.2

See Also:

Signature

registerParameterSpec

public boolean registerParameterSpec(java.lang.Class<?> parameterSpecClass)

Registers a Java Cryptography Architecture(JCA) algorithm-parameter specification for a given algorithm identifier.

This class internally maintains a static look-up table that associates algorithm identifiers with JCA algorithm-parameter specification classes. This table is statically loaded with entries for every known algorithm (all algorithms available as static fields from this class are considered known algorithms). Entries in this table indicate which algorithm-parameter specifications are "registered" to which algorithm identifiers.

This method can be used add additonal algorithm-parameter specification class registrations to the look-up table. There are a few requirements regarding the algorithm-parameter specification classes that can be registered:

• Must implement AlgorithmParameterSpec
• Must implement ASN1Type
• Must be able to create a new instance of the class using Class.newInstance()

Once an algorithm-parameter specification class has been registered, any instance of the algorithm identifier can have its parameters converted to an AlgorithmParameterSpec using getAlgorithmParameterSpec(). This is useful for initializing JCA cryptographic algorithm instances associated with the algorithm identifier. For example:

 // AlgorithmID cipherAlg is set by some previous peice of code
 Cipher cipher = cipherAlg.getCipherInstance();
 KeyGenerator keyGenerator = cipherAlg.getKeyGeneratorInstance();
 Key key = keyGenerator.generateKey();
 AlgorithmParameterSpec params = cipherAlg.getAlgorithmParameterSpec();
 cipher.init(Cipher.ENCRYPT_MODE, key, params);
 

Note:

An algorithm identifier can have multiple algorithm-parameter specification classes registered for it (ex: CipherAlgs.cast5CBC has both IvParameterSpec and CAST128ParameterSpec registered)

Parameters:

parameterSpecClass - the algorithm-parameter specification class being registered

Returns:

true if the registration was successful; false otherwise

Throws:

java.lang.IllegalArgumentException - thrown if the algorithm-parameter specification class does not implement AlgorithmParameterSpec or ASN1Type, or a new instance of the class could not be created using Class.getInstance()

See Also:

AlgorithmParameterSpec, ASN1Type

getAlgorithmParameterSpec

public java.security.spec.AlgorithmParameterSpec getAlgorithmParameterSpec()
                                                                    throws java.security.InvalidAlgorithmParameterException

Converts the algorithm parameters from ASN1 encoded format to JCA algorithm-parameter specification format.

This class internally maintains a static look-up table that associates algorithm identifiers with JCA algorithm-parameter specification classes. This table is statically loaded with entries for every known algorithm (all algorithms available as static fields from this class are considered known algorithms). Entries in this table indicate which algorithm-parameter specifications are "registered" to which algorithm identifiers.

When this method is called, an attempt is made to convert (using an ASN1 decode operation) the algorithm parameters to each of the algorithm specification classes registered for the algorithm identifier. An instance of the first algorithm-parameter specification class that is able to successfully ASN1 decode the parameters is returned.

The algorithm-parameter specification that this method returns can be used to initialize a JCA cryptographic algorithm instance (not a JCA key generator/factory instance) for this algorithm identifier. For example:

 // AlgorithmID cipherAlg is set by some previous peice of code
 Cipher cipher = cipherAlg.getCipherInstance();
 KeyGenerator keyGenerator = cipherAlg.getKeyGeneratorInstance();
 Key key = keyGenerator.generateKey();
 AlgorithmParameterSpec params = cipherAlg.getAlgorithmParameterSpec();
 cipher.init(Cipher.ENCRYPT_MODE, key, params);
 

Returns:

algorithm parameters in AlgorithmParameterSpec format

Throws:

java.security.InvalidAlgorithmParameterException - thrown if are no algorithm-parameter specifications registered for algorithm identifier, or the algorithm parameters could not be converted to any of the registered algorithm-parameter specifications

getParametersAsAlgorithmParameterSpec

public <T extends java.security.spec.AlgorithmParameterSpec> T getParametersAsAlgorithmParameterSpec(java.lang.Class<T> paramSpec)
                                                                                          throws java.security.InvalidAlgorithmParameterException

Extracts the algorithm parameters from the algorithm identifier and returns them in JCA transparent algorithm parameters representation.

The conversion from ASN.1 encoded representation to JCA transparent algorithm parameters representation is performed by first converting to JCA opaque algorithm parameters representation using the getParametersAsAlgorithmParameters() API. Then, the AlgorithmParameters instance return from the JCA is used to convert to JCA transparent algorithm parameters representation using the getParameterSpec(Class<T>) API.

Parameters:

paramSpec - the parameter specification class in which the algorithm parameters should be returned

Returns:

the algorithm parameters contained in this algorithm identifier in JCA transparent algorithm parameters representation

Throws:

java.security.InvalidAlgorithmParameterException - if the requested parameter specification is inappropriate for this algorithm identifier, or the algorithm identifier does not contain any parameters, or the parameters it does contain are invalid

Since:

8.0

getParametersAsAlgorithmParameters

public java.security.AlgorithmParameters getParametersAsAlgorithmParameters()
                                                                     throws java.security.InvalidAlgorithmParameterException

Extracts the algorithm parameters from the algorithm identifier and returns them in JCA opaque algorithm parameters representation.

The conversion from ASN.1 encoded representation to JCA opaque algorithm parameters representation is performed by requesting the registered AlgorithmParameters instance from the JCA, then using that instance to decode from ASN.1 encoded representation.

When requesting the AlgorithmParameters instance from the JCA, first an attempt is made using the algorithm identifier OID, then if that fails a second attempt is made using the algorithm identifier OID name. In each case the request is made using the following JCA cryptographic service provider (CSP) orders (precedence is given to the Entrust CSPs).

• Entrust
• IAIK
• default provider order

Returns:

the algorithm parameters contained in this algorithm identifier in JCA opaque algorithm parameters representation (null if algorithm parameters are not present in the algorithm identifier)

Throws:

java.security.InvalidAlgorithmParameterException - if an error occurred while extracting the algorithm parameters (algorithm identifier for which algorithm parameters are not registered in the JCA or bad algorithm parameters encoding)

Since:

8.0

getSymmetricKeySize

public int getSymmetricKeySize()
                        throws java.security.GeneralSecurityException

Returns the symmetric key size in bits specified by this algorithm identifier.

Algorithm identifiers for symmetric algorithms (symmetric cipher, symmetric key-wrap) indicate the symmetric key size either in the OID or the parameters. This API extracts the symmetric key size by examining the OID and parameters (if necessary). However, this only works with algorithm identifiers that represent symmetric algorithms. Currently, this API supports the following symmetric algorithm identifiers:

Algorithm name	Algorithm OID	Key size
id-aes128-ECB	2.16.840.1.101.3.4.1.1	128
id-aes128-CBC	2.16.840.1.101.3.4.1.2	128
id-aes128-OFB	2.16.840.1.101.3.4.1.3	128
id-aes128-CFB	2.16.840.1.101.3.4.1.4	128
id-aes128-wrap	2.16.840.1.101.3.4.1.5	128
id-aes192-ECB	2.16.840.1.101.3.4.1.21	192
id-aes192-CBC	2.16.840.1.101.3.4.1.22	192
id-aes192-OFB	2.16.840.1.101.3.4.1.23	192
id-aes192-CFB	2.16.840.1.101.3.4.1.24	192
id-aes192-wrap	2.16.840.1.101.3.4.1.25	192
id-aes256-ECB	2.16.840.1.101.3.4.1.41	256
id-aes256-CBC	2.16.840.1.101.3.4.1.42	256
id-aes256-OFB	2.16.840.1.101.3.4.1.43	256
id-aes256-CFB	2.16.840.1.101.3.4.1.44	256
id-aes256-wrap	2.16.840.1.101.3.4.1.45	256
cast3CBC	1.2.840.113533.7.66.3	Extracted from parameters
cast5CBC	1.2.840.113533.7.66.10	Extracted from parameters
desECB	1.3.14.3.2.6	64
desCBC	1.3.14.3.2.7	64
desOFB	1.3.14.3.2.8	64
desCFB	1.3.14.3.2.9	64
desEDE	1.3.14.3.2.17	192
des-EDE3-CBC	1.2.840.113549.3.7	192
ideaECB	1.3.6.1.4.1.188.7.1.1.1	128
ideaCBC	1.3.6.1.4.1.188.7.1.1.2	128
ideaOFB	1.3.6.1.4.1.188.7.1.1.3	128
ideaCFB	1.3.6.1.4.1.188.7.1.1.4	128

Returns:

the symmetric key size in bits

Throws:

java.security.GeneralSecurityException - if the algorithm identifier does not represent a symmetric algorithm or an error occurred while examining the algorithm parameters

Since:

8.0