Class SensitiveResult

java.lang.Object

javacardx.security.SensitiveResult

public final class SensitiveResult
extends Object

The SensitiveResult class provides methods for asserting results of sensitive functions. Sensitive methods of the Java Card API (refer to the See Also section below) store their results so that callers of these methods can assert their return values. If such a method returns abnormally with an exception then the stored result is tagged as Unassigned and any subsequent assertion of the result will fail.

The stored result is unaffected by context switches; especially, the stored result from an API method called by the method of a Shareable Interface Object is not automatically reset upon switching back to the context of the caller; it is the responsibility of the Shareable Interface Object implementation to reset the stored result if necessary using the reset method.

Upon entering any of the Applet entry point methods the stored result is tagged as Unassigned.

The sample code below illustrates the use of the SensitiveResult class:

try {
    boolean res = signature.verify(...);
    if (res) {
        SensitiveResult.assertTrue();
        // Grant service
    } else {
        SensitiveResult.assertFalse();
        // Deny service
    }
} finally {
    SensitiveResult.reset();
}

Note that results from Java Card API methods yielding a byte result are stored as short after conversion (with sign-extension).

Since:

3.0.5

See Also:

• SensitiveArrays.isIntegritySensitive(Object)
• SensitiveArrays.isIntegritySensitiveArraysSupported()
• SensitiveArrays.clearArray(Object)
• AID.equals(Object)
• AID.equals(byte[], short, byte)
• AID.partialEquals(byte[], short, byte)
• AID.RIDEquals(AID)
• JCSystem.getAID()
• JCSystem.lookupAID(byte[], short, byte)
• JCSystem.getPreviousContextAID()
• JCSystem.getAppletShareableInterfaceObject(AID, byte)
• OwnerPINx.getTryLimit()
• OwnerPINxWithPredecrement.decrementTriesRemaining()
• OwnerPINxWithPredecrement.check(byte[], short, byte)
• OwnerPIN.getTriesRemaining()
• OwnerPIN.check(byte[], short, byte)
• OwnerPIN.isValidated()
• OwnerPIN.getValidatedFlag()
• PIN.getTriesRemaining()
• PIN.check(byte[], short, byte)
• PIN.isValidated()
• Util.arrayCopy(byte[], short, byte[], short, short)
• Util.arrayCopyNonAtomic(byte[], short, byte[], short, short)
• Util.arrayFill(byte[], short, short, byte)
• Util.arrayFillNonAtomic(byte[], short, short, byte)
• Util.arrayCompare(byte[], short, byte[], short, short)
• BioTemplate.isValidated()
• BioTemplate.getTriesRemaining()
• BioTemplate.initMatch(byte[], short, short)
• BioTemplate.match(byte[], short, short)
• BioMatcher.isValidated()
• BioMatcher.getTriesRemaining()
• BioMatcher.initMatch(byte[], short, short)
• BioMatcher.match(byte[], short, short)
• BigNumber.compareTo(javacardx.framework.math.BigNumber)
• BigNumber.compareTo(byte[], short, short, byte)
• Checksum.doFinal(byte[], short, short, byte[], short)
• MessageDigest.doFinal(byte[], short, short, byte[], short)
• MessageDigest.OneShot.doFinal(byte[], short, short, byte[], short)
• RandomData.getAlgorithm()
• RandomData.nextBytes(byte[], short, short)
• RandomData.OneShot.getAlgorithm()
• RandomData.OneShot.nextBytes(byte[], short, short)
• Signature.sign(byte[], short, short, byte[], short)
• Signature.OneShot.sign(byte[], short, short, byte[], short)
• Signature.signPreComputedHash(byte[], short, short, byte[], short)
• Signature.OneShot.signPreComputedHash(byte[], short, short, byte[], short)
• Signature.verify(byte[], short, short, byte[], short, short)
• Signature.OneShot.verify(byte[], short, short, byte[], short, short)
• Signature.verifyPreComputedHash(byte[], short, short, byte[], short, short)
• Signature.OneShot.verifyPreComputedHash(byte[], short, short, byte[], short, short)
• Cipher.doFinal(byte[], short, short, byte[], short)
• Cipher.OneShot.doFinal(byte[], short, short, byte[], short)
• Cipher.update(byte[], short, short, byte[], short)
• AEADCipher.doFinal(byte[], short, short, byte[], short)
• AEADCipher.update(byte[], short, short, byte[], short)
• AEADCipher.retrieveTag(byte[], short, short)
• AEADCipher.verifyTag(byte[], short, short, short)
• DerivationFunction.nextBytes(byte[], short, short)
• DerivationFunction.nextBytes(javacard.security.SecretKey)
• MonotonicCounter.setValue(byte[], short, short)
• MonotonicCounter.incrementBy(short)
• MonotonicCounter.compareTo(javacardx.security.util.MonotonicCounter)
• MonotonicCounter.compareTo(byte[], short, short)
• MonotonicCounter.equalsMax()
• CertificateParser.parseCert(byte[], short, short, javacardx.security.cert.CertificateParser.ParserHandler, javacard.security.PublicKey)
• Certificate.verify(javacard.security.PublicKey)
• TimeDuration.compareTo(javacardx.framework.time.TimeDuration)
• TimeDuration.compareTo(short, short)

Method Summary

Modifier and Type	Method	Description
static void	assertEquals(short val)	Asserts the stored result to be a short value equal to the provided short value.
static void	assertEquals(Object obj)	Asserts the stored result to be an object reference equal to the provided object reference.
static void	assertFalse()	Asserts the stored result to be a boolean value equal to false.
static void	assertGreaterThan(short val)	Asserts the stored result to be a short value strictly greater than the provided short value.
static void	assertLessThan(short val)	Asserts the stored result to be a short value strictly less than the provided short value.
static void	assertNegative()	Asserts the stored result to be a short value strictly negative.
static void	assertPositive()	Asserts the stored result to be a short value strictly positive.
static void	assertTrue()	Asserts the stored result to be a boolean value equal to true.
static void	assertZero()	Asserts the stored result to be a short value equal to zero.
static void	reset()	Resets the stored result.

Methods inherited from class Object

equals

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

Method Details

assertEquals

public static void assertEquals(Object obj)
                         throws SecurityException

Asserts the stored result to be an object reference equal to the provided object reference. This method throws an exception if and only if the stored result reference res and the provided object reference obj do not refer to the same object or are not both null; in other words (res == obj) evaluates to false.

Parameters:

obj - The object reference to compare with the stored result.

Throws:

SecurityException - if the provided object reference is not equal to that of the stored result.

assertTrue

public static void assertTrue()
                       throws SecurityException

Asserts the stored result to be a boolean value equal to true.

Throws:

SecurityException - if the stored result is not set to true.

assertFalse

public static void assertFalse()
                        throws SecurityException

Asserts the stored result to be a boolean value equal to false.

Throws:

SecurityException - if the stored result is not set to false.

assertNegative

public static void assertNegative()
                           throws SecurityException

Asserts the stored result to be a short value strictly negative. A call to this method is semantically equivalent to a call to assertLessThan(short) with parameter 0.

Throws:

SecurityException - if the stored result is not negative.

assertPositive

public static void assertPositive()
                           throws SecurityException

Asserts the stored result to be a short value strictly positive. A call to this method is semantically equivalent to a call to assertGreaterThan(short) with parameter 0.

Throws:

SecurityException - if the stored result is not positive.

assertZero

public static void assertZero()
                       throws SecurityException

Asserts the stored result to be a short value equal to zero. A call to this method is semantically equivalent to a call to assertEquals(short) with parameter 0.

Throws:

SecurityException - if the stored result is not zero.

assertEquals

public static void assertEquals(short val)
                         throws SecurityException

Asserts the stored result to be a short value equal to the provided short value.

Parameters:

val - The short value to compare with the stored result.

Throws:

SecurityException - if the provided value is not equal to that of the stored result.

assertGreaterThan

public static void assertGreaterThan(short val)
                              throws SecurityException

Asserts the stored result to be a short value strictly greater than the provided short value.

Parameters:

val - The short value to compare with the stored result.

Throws:

SecurityException - if the provided value is not greater than that of the stored result.

assertLessThan

public static void assertLessThan(short val)
                           throws SecurityException

Asserts the stored result to be a short value strictly less than the provided short value.

Parameters:

val - The short value to compare with the stored result.

Throws:

SecurityException - if the provided value is not less than that of the stored result.

reset

public static void reset()

Resets the stored result. The stored result is tagged as Unassigned and any subsequent assertion of the result will fail.