Package javacardx.security.util

Class MonotonicCounter

java.lang.Object

javacardx.security.util.MonotonicCounter

public final class MonotonicCounter
extends Object

A MonotonicCounter represents a number that can only be increased, never decreased. It is typically used in security protocols to prevent replay attacks.

It is possible to create counters with a value in different memory spaces:

• A MonotonicCounter instance with a persistent value can typically be used to protect the update of persistent data against replay attack. It can only be increased until it reaches its maximum value and cannot be reused afterwards. The application shall take into account that updating the counter value may imply updating non-volatile memory.
  
  
• A MonotonicCounter instance with a transient value is cleared and reset when the corresponding clear event occurs (deselect or reset). It should only be used during a session to protect data with the exact same lifecycle. The application has the guarantee that updating the counter is not updating non-volatile memory.

Properties:

• The input or output format in byte arrays is unsigned hexadecimal with Big-Endian byte order.
• The update of the counter value is atomic for all operations.
• Even if a transaction is in progress, the update of the counter value shall not participate in transaction and cannot be rolled back.

Every implementation of this class is required to support counters with a value size from 1 byte up to a maximum of 8-bytes (8 bytes being the maximum possible counter length value).

Since:

3.1

Method Summary

Modifier and Type	Method	Description
short	compareTo(byte[] value, short offset, short length)	Compares the counter value with the specified value stored in an array formated as an unsigned hexadecimal with Big-Endian byte order which may contain leading zeroes.
short	compareTo(MonotonicCounter other)	Compares the counter value with the specified other counter.
boolean	equalsMax()	Returns true if the counter value is equal to the maximum value, false otherwise.
short	get(byte[] counterData, short offset)	Gets the counter in the specified output buffer.
static MonotonicCounter	getInstance(short size, byte memoryType)	Creates a MonotonicCounter instance with a value of the specified size, initialized to zero.
byte	getMemoryType()	Returns the memory type specified at object creation and used to store the value.
short	getSize()	This method returns the size in bytes of the counter.
short	incrementBy(short increment)	Increments the counter value by the specified positive value.
short	setValue(byte[] newValue, short offset, short length)	Sets the counter value to a greater new value.

Methods inherited from class java.lang.Object

equals

Method Detail

getInstance

public static final MonotonicCounter getInstance(short size,
                                                 byte memoryType)
                                          throws SystemException

Creates a MonotonicCounter instance with a value of the specified size, initialized to zero.

Parameters:

size - the byte size of the monotonic counter value

memoryType - the memory type of the monotonic counter value. Valid types are the following:

• JCSystem.MEMORY_TYPE_PERSISTENT
• JCSystem.MEMORY_TYPE_TRANSIENT_DESELECT
• JCSystem.MEMORY_TYPE_TRANSIENT_RESET

Returns:

The MonotonicCounter object instance of the requested byte length and memory type.

Throws:

SystemException - with the following reason codes:

• SystemException.ILLEGAL_VALUE if type is not a valid type code or if size is negative, equal to zero, or beyond the max size supported
• SystemException.NO_TRANSIENT_SPACE if sufficient transient space is not available.
• SystemException.NO_RESOURCE if not enough resources to allocate the instance

getMemoryType

public byte getMemoryType()

Returns the memory type specified at object creation and used to store the value.

The method returns one of the following constants:

• JCSystem.MEMORY_TYPE_PERSISTENT if the internal value is persistent,
• JCSystem.MEMORY_TYPE_TRANSIENT_DESELECT if the internal value is transient and cleared on CLEAR_ON_DESELECT event,
• JCSystem.MEMORY_TYPE_TRANSIENT_RESET if the internal value is transient and cleared on CLEAR_ON_RESET event.

Returns:

the memory type used to store the value

getSize

public short getSize()

This method returns the size in bytes of the counter.

Note: this is the total size of this counter when allocated (see getInstance(short, byte)), not the size required to encode the actual value

Returns:

size of the counter

setValue

public short setValue(byte[] newValue,
                      short offset,
                      short length)
               throws ArithmeticException,
                      ArrayIndexOutOfBoundsException

Sets the counter value to a greater new value.

The new value must be encoded in the input byte array as an unsigned hexadecimal number with big-endian byte order and may have some leading zeros.

The buffer containing the new value may be smaller that the counter size i.e the value returned by getSize(). In this case, additional leading zeroes are added to the counter value.

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, if supported by the platform.

Parameters:

newValue - input buffer containing the new counter value

offset - offset of the value within the input buffer

length - the value length

Returns:

offset + length

Throws:

ArithmeticException - if the new value is equal or lower than the actual value

ArrayIndexOutOfBoundsException - if the length parameter is larger than the counter size

get

public short get(byte[] counterData,
                 short offset)
          throws ArrayIndexOutOfBoundsException

Gets the counter in the specified output buffer. It includes potential leading zeroes.

Parameters:

counterData - the destination buffer to be filled out with the counter

offset - the offset within the destination buffer where to output the counter

Returns:

offset + getSize()

Throws:

ArrayIndexOutOfBoundsException

incrementBy

public short incrementBy(short increment)
                  throws ArithmeticException

Increments the counter value by the specified positive value.

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, if supported by the platform.

Parameters:

increment - value to increment - must be a positive value, strictly greater than zero.

Returns:

the increment value

Throws:

ArithmeticException - if the increment generates an invalid operation:

• if the increment causes a counter overflow
• if the increment is lower or equal to zero.

In any case, the counter value remains unchanged when an exception occurs.

compareTo

public short compareTo(byte[] value,
                       short offset,
                       short length)

Compares the counter value with the specified value stored in an array formated as an unsigned hexadecimal with Big-Endian byte order which may contain leading zeroes.

The specified value length may be smaller or greater than the counter size i.e the value returned by getSize().

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, if supported by the platform.

Parameters:

value - buffer containing the value to compare with.

offset - offset within the source byte array containing the most significant byte.

length - length of the value to compare with.

Returns:

the result of the comparison as follows:

• 0 if the counter is equal to the specified value
• -1 if the counter is smaller than the specified value
• 1 if the counter is greater than the specified value

Throws:

NullPointerException - if the value parameter is null

compareTo

public short compareTo(MonotonicCounter other)
                throws NullPointerException

Compares the counter value with the specified other counter. The size of the two counters may be different.

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, if supported by the platform.

Parameters:

other - the other counter to compare with.

Returns:

the result of the comparison as follows:

• 0 if the counter is equal to the other
• -1 if the counter is smaller than the other
• 1 if the counter is greater than the other

Throws:

NullPointerException - if the parameter is null

equalsMax

public boolean equalsMax()

Returns true if the counter value is equal to the maximum value, false otherwise.

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, if supported by the platform.

Returns:

true if the counter value is equal to its maximum value