com.entrust.toolkit.security.crypto.cipher

Class GcmParameters

java.lang.Object

java.security.AlgorithmParametersSpi

com.entrust.toolkit.security.crypto.cipher.GcmParameters

public class GcmParameters
extends java.security.AlgorithmParametersSpi

An opaque representation of GCM algorithm parameters intended for use with Entrust's symmetric cipher implementations when operating in the GCM block mode.

For details on the individual GCM algorithm parameter values, refer to the transparent representation GCMParameterSpec.

This class provides the capability to convert GCM algorithm parameters to/from transparent representation. Currently, the following transparent algorithm parameter representations are supported:

• GCMParameterSpec

This class also provides the capability to convert GCM algorithm parameters to/from encoded format. Currently, the following encoding/decoding formats are supported:

• ASN.1 - DER-encoded ASN.1 representation

RFC 5084 defines the ASN.1 definition for GCM parameters which is provided below. This encoding is designed for use with an AlgorithmID. RFC 5084 also defines algorithm OIDs that support this GCM parameter encoding:

     GCMParameters ::= SEQUENCE {
       aes-nonce        OCTET STRING, -- recommended size is 12 octets
       aes-ICVlen       AES-GCM-ICVlen DEFAULT 12 }
       
     AES-GCM-ICVlen ::= INTEGER (12 | 13 | 14 | 15 | 16)
     
     aes OBJECT IDENTIFIER ::= { joint-iso-itu-t(2) country(16) us(840)
         organization(1) gov(101) csor(3) nistAlgorithm(4) 1 }
         
     id-aes128-GCM OBJECT IDENTIFIER ::= { aes 6 }
     id-aes192-GCM OBJECT IDENTIFIER ::= { aes 26 }
     id-aes256-GCM OBJECT IDENTIFIER ::= { aes 46 }
 

Note: RFC 5084 defines the parameter encoding for GCM parameters used with the AES symmetric cipher, which is currently the only supported symmetric cipher that also supports the GCM block mode. However, there is nothing in this encoding that is specific to the AES cipher. Thus, it is anticipated that this encoding may be used with other symmetric cipher implementations in the future.

An important purpose of this class is to provide access the parameters that were used during an authenticated encryption or authenticated decryption operation. In the case of authenticated encryption, this is the only way to access the parameter values that are generated by the operation (i.e. initialization vector and authentication tag length). But, in order to access the individual parameter values, the opaque representation must first be converted to transparent representation (i.e. GCMParameterSpec).

To convert to GCMParameterSpec transparent representation from DER-encoded ASN.1 representation, perform the following steps:

1. Request an opaque representation of GCM algorithm parameters from Entrust's cryptographic service provider by calling AlgorithmParameters.getInstance("GCM", "Entrust").
2. Initialize the opaque representation by converting from DER-encoded ASN.1 representation by calling AlgorithmParameters.init(byte[]).
3. Convert to transparent representation by calling AlgorithmParameters.getParameterSpec(GCMParameterSpec.class)

To convert from GCMParameterSpec transparent representation to DER-encoded ASN.1 representation, perform the following steps:

1. Request an opaque representation of GCM algorithm parameters from Entrust's cryptographic service provider by calling AlgorithmParameters.getInstance("GCM", "Entrust").
2. Initialize the opaque representation by converting from transparent representation by calling AlgorithmParameters.init(AlgorithmParameterSpec), where AlgorithmParameterSpec is an instance of GCMParameterSpec.
3. Convert to DER-encoded ASN.1 representation by calling AlgorithmParameters.getEncoded().

Note: GCM parameters in opaque representation can only be used with the Cipher.init() API to initialize for authenticated decryption; they cannot be used to initialize for authenticated encryption. Refer to GCMParameterSpec for a transparent representation of GCM parameters that can be used to initialize for authenticated encryption.

Since:

8.0

See Also:

GcmBlockMechanism

Constructor Summary

Constructors

Constructor and Description
GcmParameters() The constructor; creates a new instance of GCM algorithm parameters.

Method Summary

Methods

Modifier and Type	Method and Description
protected byte[]	engineGetEncoded() Returns the parameters in their primary encoding format.
protected byte[]	engineGetEncoded(java.lang.String format) Returns the parameters encoded in the specified format.
protected <T extends java.security.spec.AlgorithmParameterSpec> T	engineGetParameterSpec(java.lang.Class<T> paramSpec) Returns a (transparent) specification of this parameters object.
protected void	engineInit(java.security.spec.AlgorithmParameterSpec paramSpec) Initializes this parameters object using the parameters specified in paramSpec.
protected void	engineInit(byte[] params) Imports the specified parameters and decodes them according to the primary decoding format for the parameters.
protected void	engineInit(byte[] params, java.lang.String format) Imports the parameters from params and decodes them according to the specified decoding format.
protected java.lang.String	engineToString() Returns a formatted string describing the parameters.

Methods inherited from class java.lang.Object

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

Constructor Detail

GcmParameters

public GcmParameters()

The constructor; creates a new instance of GCM algorithm parameters.

Applications should never use this constructor, instead the algorithm parameters instance should be requested from the appropriate JCA/JCE cryptographic service provider as follows: AlgorithmParameters.getInstance("GCM", "Entrust").

Method Detail

engineInit

protected void engineInit(java.security.spec.AlgorithmParameterSpec paramSpec)
                   throws java.security.spec.InvalidParameterSpecException

Initializes this parameters object using the parameters specified in paramSpec.

Specified by:

engineInit in class java.security.AlgorithmParametersSpi

Parameters:

paramSpec - the parameter specification

Throws:

java.security.spec.InvalidParameterSpecException - if the given parameter specification is inappropriate for the initialization of this parameter object

engineInit

protected void engineInit(byte[] params)
                   throws java.io.IOException

Imports the specified parameters and decodes them according to the primary decoding format for the parameters.

The primary decoding format for GCM parameters is ASN.1; details on this format are provided in the class documentation (see GcmParameters ).

Specified by:

engineInit in class java.security.AlgorithmParametersSpi

Parameters:

params - the encoded parameters.

Throws:

java.io.IOException - on decoding errors

engineInit

protected void engineInit(byte[] params,
              java.lang.String format)
                   throws java.io.IOException

Imports the parameters from params and decodes them according to the specified decoding format.

If format is null, the primary decoding format for parameters is used. The primary decoding format for GCM parameters is ASN.1; details on this format are provided in the class documentation (see GcmParameters). Currently, the following decoding formats are supported: 'ASN.1'.

Specified by:

engineInit in class java.security.AlgorithmParametersSpi

Parameters:

params - the encoded parameters

format - the name of the decoding format

Throws:

java.io.IOException - if the decoding format is unsupported or a decoding error occurs

engineGetEncoded

protected byte[] engineGetEncoded()
                           throws java.io.IOException

Returns the parameters in their primary encoding format.

The primary encoding format for GCM parameters is ASN.1; details on this format are provided in the class documentation (see GcmParameters ).

Specified by:

engineGetEncoded in class java.security.AlgorithmParametersSpi

Returns:

the parameters encoded using the specified encoding scheme

Throws:

java.io.IOException

engineGetEncoded

protected byte[] engineGetEncoded(java.lang.String format)
                           throws java.io.IOException

Returns the parameters encoded in the specified format.

If format is null, the primary encoding format for parameters is used. The primary encoding format for GCM parameters is ASN.1; details on this format are provided in the class documentation (see GcmParameters). Currently, the following encoding formats are supported: 'ASN.1'.

Specified by:

engineGetEncoded in class java.security.AlgorithmParametersSpi

Parameters:

format - the name of the encoding format

Returns:

the parameters encoded using the specified encoding scheme

Throws:

java.io.IOException - if the encoding format is unsupported

engineGetParameterSpec

protected <T extends java.security.spec.AlgorithmParameterSpec> T engineGetParameterSpec(java.lang.Class<T> paramSpec)
                                                                              throws java.security.spec.InvalidParameterSpecException

Returns a (transparent) specification of this parameters object.

Specified by:

engineGetParameterSpec in class java.security.AlgorithmParametersSpi

Parameters:

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

Returns:

the parameter specification

Throws:

java.security.spec.InvalidParameterSpecException - if the requested parameter specification is inappropriate for this parameter object

engineToString

protected java.lang.String engineToString()

Returns a formatted string describing the parameters.

Specified by:

engineToString in class java.security.AlgorithmParametersSpi

Returns:

a formatted string describing the parameters