iaik.security.cipher

Class OCBParameterSpec

java.lang.Object

javax.crypto.spec.IvParameterSpec

iaik.security.cipher.OCBParameterSpec

All Implemented Interfaces:

java.security.spec.AlgorithmParameterSpec

Direct Known Subclasses:

OCBCMSParameterSpec

public class OCBParameterSpec
extends javax.crypto.spec.IvParameterSpec

OCB parameter specification.

This class provides the necessary inputs (additional data, nonce, TAG length) when the OCB Authenticated-Encryption mode (RFC 7253) is used for encryption/decryption.

In OCB mode (RFC 7253) the payload data is both encrypted and authenticated. There is also the possibility to specify associated data, that is only authenticated.

The OCB mode needs some parameters that have to be specified as OCBParameterSpec. These parameters are the length of the TAG (between 1 and 16 bytes; default 16) and a nonce (between 1 and 15 bytes; default 12) that should be unique. If these parameters are not specified the default TAG length of 16 bytes is used and a nonce (12 bytes) is generated. Furthermore, any additional (to be authenticated only, but not encrypted) data can be specified as parameter (or by Cipher.updateAAD() calls). When calling the Cipher-method doFinal() the TAG calculation is finished and (by default) the tag is appended to the cipher text:

 byte[] aad = ...;
 byte[] nonce = ...;
 int tagLength = ...;
 OCBParameterSpec ocbParmaterSpec = new OCBParameterSpec(aad, nonce, tagLength);
 Cipher c = Cipher.getInstance("AES/OCB/NoPadding", "IAIK");
 c.init(Cipher.ENCRYPT_MODE, key, ocbParmaterSpec);
 byte[] ciphertext = c.doFinal(data);
 

When decrypting the cipher text the appended tag is compared with the tag calculated during decryption and an exception is thrown if the two tags do not match:

 Cipher c = Cipher.getInstance("AES/OCB/NoPadding", "IAIK");
 c.init(Cipher.DECRYPT_MODE, key, ocbParmaterSpec);
 byte[] ciphertext = c.doFinal(data);
 

However, if you do not want to append the tag to the cipher text you may initialize the OCB Cipher with an OCBCMSParameterSpec (instead of OCBParameterSpec). In this case the tag is not appended to the cipher text, but saved to the OCBCMSParameterSpec, which can be read out by calling the Cipher method getParameters():

 OCBCMSParameterSpec paramSpec = new OCBCMSParameterSpec(aad, nonce, tagLength);
 Cipher c = Cipher.getInstance("AES/OCB/NoPadding");
 c.init(Cipher.ENCRYPT_MODE, key, ocbCMSParmaterSpec);
 byte[] encr = c.doFinal(data);
 AlgorithmParameters params = c.getParameters();
 OCPCMSParameterSpec paramSpec = (OCBParameterSpec)params.getParameterSpec(OCBCMSParameterSpec.class);
 byte[] tag = paramSpec.getTag();
 

For decryption the tag has to be be specified by the parameters (because not appended to the cipher text)SS in order to be able to check the authenticity of the data:

 Cipher c = Cipher.getInstance("AES/OCB/NoPadding", "IAIK");
 c.init(Cipher.DECRYPT_MODE, key, params);
 byte[] ciphertext = c.doFinal(data);
 

Version:

File Revision 2

See Also:

OCBParameterSpec, OCBCMSParameterSpec, OCBParameters, AlgorithmParameterSpec

Constructor Summary

Constructors

Constructor and Description
OCBParameterSpec() Creates an OCB Parameter specification with default values.
OCBParameterSpec(byte[] aaData, byte[] nonce) Creates an OCB Parameter specification with the given additional data and nonce.
OCBParameterSpec(byte[] aaData, byte[] nonce, int tagLen) Creates an OCB Parameter specification with the given additional data, nonce and TAG length.

Method Summary

Modifier and Type	Method and Description
byte[]	getAAD() Returns the associated data used for authentication.
byte[]	getNonce() Returns the nonce value.
int	getTagLength() Returns the number of bytes used for the tag block.
void	setTagLength(int tagLength) Set number of bytes that should be used as TAG.
java.lang.String	toString() Returns a string describing the OCB Parameters.

Methods inherited from class javax.crypto.spec.IvParameterSpec

getIV

Methods inherited from class java.lang.Object

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

Constructor Detail

OCBParameterSpec

public OCBParameterSpec(byte[] aaData,
                        byte[] nonce,
                        int tagLen)
                 throws java.security.InvalidAlgorithmParameterException

Creates an OCB Parameter specification with the given additional data, nonce and TAG length.

Parameters:

aaData - the additional data that is authenticated

nonce - the nonce/iv

tagLen - number of bytes used as TAG

Throws:

java.security.InvalidAlgorithmParameterException - if the specified tag (between 1 and 16 bytes) or nonce length (between 1 and 15 bytes) are not valid

OCBParameterSpec

public OCBParameterSpec(byte[] aaData,
                        byte[] nonce)
                 throws java.security.InvalidAlgorithmParameterException

Creates an OCB Parameter specification with the given additional data and nonce. TAG length will be set to 16 bytes.

Parameters:

aaData - the additional data that is authenticated

nonce - the nonce/iv

Throws:

java.security.InvalidAlgorithmParameterException - if the length of the specified nonce is not valid (not between 1 and 15 bytes)

OCBParameterSpec

public OCBParameterSpec()
                 throws java.security.InvalidAlgorithmParameterException

Creates an OCB Parameter specification with default values. A 12 byte nonce will be generated and the TAG length will be set to 16 bytes.

Throws:

java.security.InvalidAlgorithmParameterException

Method Detail

setTagLength

public void setTagLength(int tagLength)
                  throws java.security.InvalidAlgorithmParameterException

Set number of bytes that should be used as TAG.

Throws:

java.security.InvalidAlgorithmParameterException - if the specified TAG length is not valid (not between 1 and 16 bytes long)

getAAD

public byte[] getAAD()

Returns the associated data used for authentication.

Returns:

associated data

getTagLength

public int getTagLength()

Returns the number of bytes used for the tag block.

Returns:

number of bytes of the authentication block

getNonce

public byte[] getNonce()

Returns the nonce value.

Returns:

the nonce

toString

public java.lang.String toString()

Returns a string describing the OCB Parameters.

Overrides:

toString in class java.lang.Object

Returns:

a string describing the OCB Parameters.