Class SensitiveArrays

java.lang.Object

javacard.framework.SensitiveArrays

public class SensitiveArrays
extends Object

The SensitiveArrays class provides methods for creating and handling integrity-sensitive array objects.

The makeIntegritySensitiveArray method can be used to create integrity-sensitive array objects. Integrity-sensitive array objects include an integrity control element that is automatically and transparently updated by the platform whenever the array content is legally modified. The integrity control element is automatically checked by the platform before any array update operation. If an inconsistency is detected during an array integrity check a SecurityException is thrown. The integrity control element is not automatically checked by the platform before a read operation: it is up to the applet to trigger such a check by calling the assertIntegrity method.

Since:

3.0.5

Method Summary

Modifier and Type	Method	Description
static void	assertIntegrity(Object obj)	Checks the integrity of the specified integrity-sensitive array object.
static short	clearArray(Object obj)	Clears the specified array object.
static boolean	isIntegritySensitive(Object obj)	Returns whether the provided object is an integrity-sensitive array.
static boolean	isIntegritySensitiveArraysSupported()	Returns whether the implementation for the Java Card platform supports integrity-sensitive arrays.
static Object	makeIntegritySensitiveArray(byte type, byte memory, short length)	Creates an integrity-sensitive array of the specified array and memory type, with the specified array length.

Methods inherited from class Object

equals

Modifier and Type	Method	Description
boolean	equals(Object obj)	Compares two Objects for equality.

Method Details

assertIntegrity

public static void assertIntegrity(Object obj)

Checks the integrity of the specified integrity-sensitive array object.

Parameters:

obj - the integrity-sensitive array object being queried

Throws:

NullPointerException - if obj is null.

SecurityException - if the integrity of obj has been compromised.

SystemException - with the following reason codes:

• ILLEGAL_VALUE if the specified object is not an integrity-sensitive array object.

See Also:

• makeIntegritySensitiveArray(byte, byte, short)

isIntegritySensitive

public static boolean isIntegritySensitive(Object obj)

Returns whether the provided object is an integrity-sensitive array.

In addition to returning a boolean result, this method sets the result in an internal state which can be rechecked using assertion methods of the SensitiveResult class.

Parameters:

obj - the object being queried.

Returns:

true if the provided object is an integrity-sensitive array or a view on an integrity-sensitive array; false otherwise.

Throws:

NullPointerException - if obj is null.

See Also:

• makeIntegritySensitiveArray(byte, byte, short)

isIntegritySensitiveArraysSupported

public static boolean isIntegritySensitiveArraysSupported()

Returns whether the implementation for the Java Card platform supports integrity-sensitive arrays.

In addition to returning a boolean result, this method sets the result in an internal state which can be rechecked using assertion methods of the SensitiveResult class.

Returns:

true if integrity-sensitive arrays are supported; false otherwise.

See Also:

• makeIntegritySensitiveArray(byte, byte, short)

makeIntegritySensitiveArray

public static Object makeIntegritySensitiveArray(byte type,
 byte memory,
 short length)

Creates an integrity-sensitive array of the specified array and memory type, with the specified array length.

Note: only the content of the array is sensitive, in particular in the case of an array of object references, only the references stored in the array are sensitive, not the objects themselves.

Parameters:

type - the array type - must be one of: ARRAY_TYPE_BOOLEAN, ARRAY_TYPE_BYTE, ARRAY_TYPE_SHORT, ARRAY_TYPE_INT or ARRAY_TYPE_OBJECT.

memory - the memory type - must be one of: MEMORY_TYPE_PERSISTENT, MEMORY_TYPE_TRANSIENT_RESET or MEMORY_TYPE_TRANSIENT_DESELECT.

length - the length of the sensitive array.

Returns:

the new integrity-sensitive array.

Throws:

NegativeArraySizeException - if the length parameter is negative

SystemException - with the following reason codes:

• ILLEGAL_USE if integrity-sensitive arrays are not supported.
• ILLEGAL_VALUE if type or memory is not a valid type code. An implementation which does not support integrity-sensitive array objects of int array type may throw this exception.
• NO_TRANSIENT_SPACE if no sufficient transient space is available.
• NO_RESOURCE if no sufficient persistent space is available.

clearArray

public static short clearArray(Object obj)
                        throws TransactionException

Clears the specified array object. This method sets all the values in the array to null for ARRAY_TYPE_OBJECT arrays and to zero for all other array types. The integrity of the array object is not checked by this method before the clearing and the reinitialization of the integrity-control information.

In addition to returning a short result, this method sets the result in an internal state which can be rechecked using assertion methods of the SensitiveResult class.

Note:

• The clearing operation is atomic.
• When a transaction is in progress, the clearing of a persistent integrity-sensitive array participates to the transaction and is therefore subject to atomic commit capacity limitations. If the commit capacity is exceeded, no clearing is performed and a TransactionException exception is thrown.
• The clearing cannot be performed on a view, even if it is a view on a sensitive array, because it operates on the entire array whereas a view gives only access to a subset of the elements.

Parameters:

obj - the array being cleared.

Returns:

the length of the specified array object.

Throws:

SystemException - with the following reason codes:

• ILLEGAL_VALUE if the specified object is not an integrity-sensitive array object or is an array view.

NullPointerException - if obj is null.

TransactionException - if clearing would cause the commit capacity to be exceeded.

See Also:

• JCSystem.getUnusedCommitCapacity()