iaik.pkcs.pkcs11.provider.ciphers

Class PKCS11GCMParameters

java.lang.Object

java.security.AlgorithmParametersSpi

iaik.pkcs.pkcs11.provider.ciphers.PKCS11GCMParameters

public class PKCS11GCMParameters
extends java.security.AlgorithmParametersSpi

This class represents GCM parameters. The parameters specified for the GCM algorithm in RFC 5084 consist of the nonce and the length of the tag (ICVlen):

 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)
 

The aes-ICVLen specifies the length of the message authentication code value.

As stated in the NIST Special Publication 800-38D also the tag length of 4 and 8 bytes are possible.

GCMParameters can be generated by calling one of the AlgorithmParameters.getInstance methods. Subsequently, the new AlgorithmParameters object must be initialized with a proper parameter specification (class PKCS11GCMParameterSpec is recommended) or a DER encoded byte array, e.g.

 IAIKPkcs11 iaikPcks11Provider = ...;
 PKCS11GCMParameterSpec gcmParamSpec = ...;
 AlgorithmParameters params = AlgorithmParameters.getInstance("GCM", iaikPcks11Provider);
 params.init(gcmParamsSpec);
 

See Also:

PKCS11GCMParameterSpec, AlgorithmParametersSpi

Constructor Summary

Constructors

Constructor and Description
PKCS11GCMParameters() The default constructor.
PKCS11GCMParameters(PKCS11GCMParameterSpec paramSpec) Creates GCM Parameters with the given PCKS11GCMParameterSpec.

Method Summary

Modifier and Type	Method and Description
protected byte[]	engineGetEncoded() Returns the parameters as DER byte array.
protected byte[]	engineGetEncoded(java.lang.String format) Returns the parameters as a DER byte array.
protected java.security.spec.AlgorithmParameterSpec	engineGetParameterSpec(java.lang.Class paramSpec) Returns a GCM Parameter Specification of this GCM 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) Initializes this GCMParameters object from the given DER encoded byte array.
protected void	engineInit(byte[] params, java.lang.String format) Inits the parameters from an DER encoded byte array.
protected java.lang.String	engineToString() Returns a formatted string describing the GCM Parameters.
static void	setIncludeDefaultTagLengthInEncding(boolean include) Decides whether the aes-ICVlen (tagLength) component should be included when encoding GCM parameters if it has the default value (12 bytes).

Methods inherited from class java.lang.Object

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

Constructor Detail

PKCS11GCMParameters

public PKCS11GCMParameters()

The default constructor. No values are set for the parameters. Use AlgorithmParameters.getInstance for obtaining a GCMParameters object.

PKCS11GCMParameters

public PKCS11GCMParameters(PKCS11GCMParameterSpec paramSpec)

Creates GCM Parameters with the given PCKS11GCMParameterSpec.

Parameters:

paramSpec - the PKCS11GCMParameterSpec

Method Detail

setIncludeDefaultTagLengthInEncding

public static void setIncludeDefaultTagLengthInEncding(boolean include)

Decides whether the aes-ICVlen (tagLength) component should be included when encoding GCM parameters if it has the default value (12 bytes). Although default values should be not included (if DER is used) it might be required to include the default value for compatibility reasons (when BER is used).

Parameters:

include - whether to include a default tagLength value (12 bytes) when encoding GCM parameters or not (by default the default value is not included)

engineGetEncoded

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

Returns the parameters as DER byte array.

Specified by:

engineGetEncoded in class java.security.AlgorithmParametersSpi

Returns:

the GCM parameters as DER byte array

Throws:

java.io.IOException - if an encoding error occurs

engineGetEncoded

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

Returns the parameters as a DER byte array.

Format is ignored. Only DER encoding is supported at this time. This method only calls engineGetEncoded(), regardless of what is specified in the format string.

Specified by:

engineGetEncoded in class java.security.AlgorithmParametersSpi

Parameters:

format - the encoding format; ignored

Returns:

the GCM parameters as DER byte array

Throws:

java.io.IOException - if an encoding error occurs

engineGetParameterSpec

protected java.security.spec.AlgorithmParameterSpec engineGetParameterSpec(java.lang.Class paramSpec)
                                                                    throws java.security.spec.InvalidParameterSpecException

Returns a GCM Parameter Specification of this GCM Parameters object. paramSpec identifies the specification class in which the parameters should be returned, which might be iaik.pkcs.pkcs11.provider.ciphers.PKCS11GCMParameterSpec (preferred choice), iaik.security.cipher.GCMParameterSpec or javax.crypto.spec.GCMParameterSpec. Since GCM support has not been been introduced before Java7 javax.crypto.spec.GCMParameterSpec can only be used with Java 7 or later.

Specified by:

engineGetParameterSpec in class java.security.AlgorithmParametersSpi

Parameters:

paramSpec - the specification class in which the parameters should be returned - has to be class iaik.pkcs.pkcs11.provider.ciphers.PKCS11GCMParameterSpec (preferred choice), iaik.security.cipher.GCMParameterSpec or (Java7 or later) class javax.crypto.spec.GCMParameterSpec

Returns:

the parameter specification.

Throws:

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

engineInit

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

Initializes this parameters object using the parameters specified in paramSpec. paramSpec might specify class iaik.pkcs.pkcs11.provider.ciphers.PKCS11GCMParameterSpec (preferred choice), iaik.security.cipher.GCMParameterSpec or class javax.crypto.spec.GCMParameterSpec. Since GCM support has not been been introduced before Java7 javax.crypto.spec.GCMParameterSpec can only be used with Java 7 or later.

Specified by:

engineInit in class java.security.AlgorithmParametersSpi

Parameters:

paramSpec - the parameter specification - iaik.pkcs.pkcs11.provider.ciphers.PKCS11GCMParameterSpec (preferred choice), iaik.security.cipher.GCMParameterSpec or javax.crypto.spec.GCMParameterSpec

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

Initializes this GCMParameters object from the given DER encoded byte array.

Specified by:

engineInit in class java.security.AlgorithmParametersSpi

Parameters:

params - the DER encoded byte array

Throws:

java.io.IOException - if an error occurs when decoding the given byte array or the derived parameter values are invalid

engineInit

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

Inits the parameters from an DER encoded byte array. Format is ignored. Only calls {engineInit(params) for initializing this GCMParameters object from the given DER encoded byte array, regardless of what is specified in the format string.

Specified by:

engineInit in class java.security.AlgorithmParametersSpi

Parameters:

params - the DER encoded byte array

format - the encoding format; ignored

Throws:

java.io.IOException - if an error occurs when decoding the given byte array

engineToString

protected java.lang.String engineToString()

Returns a formatted string describing the GCM Parameters.

Specified by:

engineToString in class java.security.AlgorithmParametersSpi

Returns:

a formatted string describing the GCM Parameters.