org.globalplatform
Interface CVM

public interface CVM

This defines the interface of a privileged system class that represents a Card Holder Verification Method. This class offers basic Cardholder Verification Method services (e.g. CVM verification, CVM state interrogation) to any of the applications present on the card, while some of the services (e.g. unblock CVM, change CVM value) are restricted to applications with the privilege to change the CVM values. Prior to using this interface, an application is required to obtain a handle to the CVM services by invoking the GPSystem.getCVM() method.

Field Summary

static short	CVM_FAILURE The CVM value comparison failed.
static short	CVM_SUCCESS The CVM value comparison was successful.
static byte	FORMAT_ASCII The CVM value is formatted as ASCII bytes.
static byte	FORMAT_BCD The CVM value is formatted as numerical digits, coded on a nibble (4 bits) and left justified.
static byte	FORMAT_HEX The CVM value is formatted as hexadecimal (binary) data.

Method Summary

boolean	blockState() This method sets the CVM state to BLOCKED.
byte	getTriesRemaining() This method returns the number of tries remaining for the CVM.
boolean	isActive() This method indicates whether the CVM is present and activated.
boolean	isBlocked() This method indicates whether the CVM is currently BLOCKED.
boolean	isSubmitted() This method indicates whether an attempt has been made to compare the CVM value.
boolean	isVerified() This method indicates whether a successful comparison of the CVM value has occurred (CVM state of VALIDATED).
boolean	resetAndUnblockState() This method resets the CVM state from BLOCKED to ACTIVE.
boolean	resetState() This method resets the CVM state to ACTIVE.
boolean	setTryLimit(byte bTryLimit) This method sets the maximum number of tries for the CVM.
boolean	update(byte[] babuffer, short sOffset, byte bLength, byte bFormat) This method changes the CVM value.
short	verify(byte[] baBuffer, short sOffset, byte bLength, byte bFormat) This method compares the stored CVM value with the one passed as parameter.

Field Detail

CVM_SUCCESS

public static final short CVM_SUCCESS

The CVM value comparison was successful.

See Also:

Constant Field Values

CVM_FAILURE

public static final short CVM_FAILURE

The CVM value comparison failed.

See Also:

Constant Field Values

FORMAT_ASCII

public static final byte FORMAT_ASCII

The CVM value is formatted as ASCII bytes.

Note:

• If the CVM value is stored in a format other than ASCII, it is the responsibility of the interface to convert to the expected format.

See Also:

Constant Field Values

FORMAT_BCD

public static final byte FORMAT_BCD

The CVM value is formatted as numerical digits, coded on a nibble (4 bits) and left justified.

Note:

• If the CVM value is stored in a format other than BCD, it is the responsibility of the interface to convert to the expected format.
• If the length of the CVM value is odd, the right most nibble of the CVM value shall be high values ('F').

See Also:

Constant Field Values

FORMAT_HEX

public static final byte FORMAT_HEX

The CVM value is formatted as hexadecimal (binary) data.

Note:

• If the CVM value is stored in a format other than HEX, it is the responsibility of the interface to convert to the expected format.

See Also:

Constant Field Values

Method Detail

isActive

public boolean isActive()

This method indicates whether the CVM is present and activated. If active the CVM could be in any one of the following states: ACTIVE, INVALID_SUBMISSION, VALIDATED or BLOCKED.

Returns:

true if the CVM state is (at least) ACTIVE, false otherwise.

isSubmitted

public boolean isSubmitted()

This method indicates whether an attempt has been made to compare the CVM value.

Note:

• This method does not differentiate whether the CVM value has been successfully verified or not, i.e. CVM states of VALIDATED or INVALID_SUBMISSION.

Returns:

true if the CVM state is (at least) SUBMITTED, false otherwise.

isVerified

public boolean isVerified()

This method indicates whether a successful comparison of the CVM value has occurred (CVM state of VALIDATED).

Returns:

true if the CVM state is VALIDATED, false otherwise.

isBlocked

public boolean isBlocked()

This method indicates whether the CVM is currently BLOCKED.

Returns:

true if the CVM state is BLOCKED, false otherwise.

getTriesRemaining

public byte getTriesRemaining()

This method returns the number of tries remaining for the CVM. This indicates the number of times the CVM value can be incorrectly presented prior to the CVM reaching the state of BLOCKED.

Returns:

Tries remaining.

update

public boolean update(byte[] babuffer,
                      short sOffset,
                      byte bLength,
                      byte bFormat)

This method changes the CVM value.

Notes:

• The OPEN locates the entry of the current applet context in the Open Platform Registry and verifies that the application has the CVM change privilege.
• The applet is responsible for identifying the format of the CVM value.
• The CVM try counter is reset when changing the CVM value.

Returns:

true if the CVM value was changed, false otherwise.

resetState

public boolean resetState()

This method resets the CVM state to ACTIVE.

Notes:

• The state of the CVM can only be set to ACTIVE from the states INVALID_SUBMISSION or VALIDATED.
• The state of the CVM cannot be set to ACTIVE from BLOCKED.

Returns:

true if the CVM state was reset, false otherwise.

blockState

public boolean blockState()

This method sets the CVM state to BLOCKED.

Returns:

true if the CVM state was set to BLOCKED, false otherwise.

resetAndUnblockState

public boolean resetAndUnblockState()

This method resets the CVM state from BLOCKED to ACTIVE.

Notes:

• The OPEN locates the entry of the current applet context in the Open Platform Registry and verifies that the application has the CVM change privilege.
• The CVM try counter is reset when unblocking the CVM.

Returns:

true if the CVM state was reset to ACTIVE, false otherwise.

setTryLimit

public boolean setTryLimit(byte bTryLimit)

This method sets the maximum number of tries for the CVM.

Notes:

• The OPEN locates the entry of the current applet context in the Open Platform Registry and verifies that the application has the CVM change privilege.
• The CVM try counter is reset when setting the maximum number of tries.

Returns:

true if the maximum number of tries was set, false otherwise.

verify

public short verify(byte[] baBuffer,
                    short sOffset,
                    byte bLength,
                    byte bFormat)

This method compares the stored CVM value with the one passed as parameter.

Notes:

• If the value passed as parameter is not in the same format as the CVM value, the value passed as parameter must be converted prior to comparing.
• If the comparison is successful, the try counter must be reset and the CVM state must be set to VALIDATED.
• If the comparison is unsuccessful, the try counter must be updated and the CVM state must be set to INVALID_SUBMISSION.
• If the maximum number of tries has been reached, the CVM state must be set to BLOCKED.

Returns:

value indicating whether the comparison was successful or not. Values other than CVM_SUCCESS (0) or CVM_FAILURE (-1) are Reserved for Future Use.