org.globalplatform
Interface CVM

All Superinterfaces:
javacard.framework.Shareable

public interface CVM
extends javacard.framework.Shareable

This interface defines basic Cardholder Verification Method services (e.g. comparison of CVM value, CVM state query). It is typically exposed to on-card Applications by a Global Services Application implementing one or more Cardholder Verification Methods. Some services are restricted to Applications having the CVM Management Privilege.

To retrieve an instance of this interface, an Application shall invoke the GPSystem.getCVM(byte) method, or shall use a GlobalService instance of the GPSystem.FAMILY_CVM family. For backward compatibility, the CVM instances retrieved using the GPSystem.getCVM(byte) method are mapped onto those retrieved as Global Services of the GPSystem.FAMILY_CVM family.

The CVM instance maintains the following data (see Card Specification v2.2.1 section 8.2.2 for more details):

Operations performed by this interface shall be independent of, and not interfere with, any transaction in progress (e.g. if the verify(byte[], short, byte, byte) method is invoked from within a transaction and this transaction is aborted, then the try counter is not revert to its original value).

Since:

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()
          Sets the CVM state to BLOCKED.
 byte getTriesRemaining()
          Gets the CVM try counter, that is, the number of unsuccessful comparisons of the CVM value that may be performed before this CVM instance gets blocked.
 boolean isActive()
          Indicates whether this CVM instance is active, that is, whether it has been fully initialized (i.e. both value and try limit) and is ready for use.
 boolean isBlocked()
          Indicates whether this CVM instance is blocked, that is, whether the CVM state is BLOCKED.
 boolean isSubmitted()
          Indicates whether an attempt has been made to compare the CVM value, that is, whether the CVM state is INVALID_SUBMISSION or VALIDATED.
 boolean isVerified()
          Indicates whether a successful comparison of the CVM value has occurred, that is, whether the CVM state is VALIDATED.
 boolean resetAndUnblockState()
          Resets the CVM state to ACTIVE, even if it is currently BLOCKED.
 boolean resetState()
          Resets the CVM state to ACTIVE.
 boolean setTryLimit(byte bTryLimit)
          Sets the CVM try limit, that is, the maximum value of the CVM try counter.
 boolean update(byte[] baBuffer, short sOffset, byte bLength, byte bFormat)
          Updates the CVM value.
 short verify(byte[] baBuffer, short sOffset, byte bLength, byte bFormat)
          Compares a value with the stored CVM value.
 

Field Detail

CVM_SUCCESS

static final short CVM_SUCCESS
The CVM value comparison was successful.

See Also:
Constant Field Values

CVM_FAILURE

static final short CVM_FAILURE
The CVM value comparison failed.

See Also:
Constant Field Values

FORMAT_ASCII

static final byte FORMAT_ASCII
The CVM value is formatted as ASCII bytes.

Note:

See Also:
Constant Field Values

FORMAT_BCD

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

Note:

See Also:
Constant Field Values

FORMAT_HEX

static final byte FORMAT_HEX
The CVM value is formatted as hexadecimal (binary) data.

Note:

See Also:
Constant Field Values
Method Detail

isActive

boolean isActive()
Indicates whether this CVM instance is active, that is, whether it has been fully initialized (i.e. both value and try limit) and is ready for use. If yes, then the CVM state is deemed to be in one of the following states: ACTIVE, INVALID_SUBMISSION, VALIDATED or BLOCKED.

Returns:
true if the CVM has been fully initialized and is ready for use, false otherwise (i.e. the CVM state is NOT_READY).

isSubmitted

boolean isSubmitted()
Indicates whether an attempt has been made to compare the CVM value, that is, whether the CVM state is INVALID_SUBMISSION or VALIDATED.

Returns:
true if the CVM state is INVALID_SUBMISSION or VALIDATED, false otherwise.

isVerified

boolean isVerified()
Indicates whether a successful comparison of the CVM value has occurred, that is, whether the CVM state is VALIDATED.

Returns:
true if the CVM state is VALIDATED, false otherwise.

isBlocked

boolean isBlocked()
Indicates whether this CVM instance is blocked, that is, whether the CVM state is BLOCKED.

Returns:
true if the CVM state is BLOCKED, false otherwise.

getTriesRemaining

byte getTriesRemaining()
Gets the CVM try counter, that is, the number of unsuccessful comparisons of the CVM value that may be performed before this CVM instance gets blocked.

Returns:
current value of the CVM try counter.

update

boolean update(byte[] baBuffer,
               short sOffset,
               byte bLength,
               byte bFormat)
Updates the CVM value.

If the Application invoking this method does not have the CVM Management Privilege, or if the specified format (bFormat) is unknown (or not supported by this CVM instance), or if the new CVM value is not consistent with respect to the specified format, then the CVM value is not updated.

If the CVM value is successfully updated and the CVM try limit has already been successfully set previously, then this method also resets the CVM try counter to the CVM try limit, and (re)sets the CVM state to ACTIVE.

Notes:

Parameters:
baBuffer - byte array containing the new CVM value. Must be a global byte array.
sOffset - offset of the new CVM value within baBuffer.
bLength - length of the new CVM value.
bFormat - format of the new CVM value: FORMAT_ASCII, FORMAT_BCD or FORMAT_HEX.
Returns:
true if the CVM value was successfully updated, false otherwise.
Throws:
java.lang.SecurityException - if baBuffer is not a global byte array.
java.lang.NullPointerException - if baBuffer is null.
java.lang.ArrayIndexOutOfBoundsException - if reading the new CVM value would cause access of data outside array bounds.
See Also:
GPRegistryEntry.PRIVILEGE_CVM_MANAGEMENT

resetState

boolean resetState()
Resets the CVM state to ACTIVE.

The CVM state can only be reset to ACTIVE from the states ACTIVE, INVALID_SUBMISSION or VALIDATED. In particular, it cannot be reset to ACTIVE if it is in state BLOCKED or if the CVM instance never entered the state ACTIVE, that is, if the CVM instance is not fully initialized.

Returns:
true if the CVM state was reset, false otherwise.

blockState

boolean blockState()
Sets the CVM state to BLOCKED.

If the Application invoking this method does not have the CVM Management Privilege, then the CVM state is not updated.

The CVM state can only be set to BLOCKED if the CVM instance already entered the state ACTIVE once, that is, if the CVM instance is fully initialized. Notice that this method shall return true if the CVM state is already BLOCKED.

Notes:

Returns:
true if the CVM state was set to BLOCKED, false otherwise.
See Also:
GPRegistryEntry.PRIVILEGE_CVM_MANAGEMENT

resetAndUnblockState

boolean resetAndUnblockState()
Resets the CVM state to ACTIVE, even if it is currently BLOCKED.

If the Application invoking this method does not have the CVM Management Privilege, then the CVM state is not updated.

The CVM state can only be set to ACTIVE if the CVM instance already entered the state ACTIVE once, that is, if the CVM instance is fully initialized. If the CVM state is successfully reset, then this method also resets the CVM try counter to the CVM try limit.

Notes:

Returns:
true if the CVM state was reset to ACTIVE, false otherwise.
See Also:
GPRegistryEntry.PRIVILEGE_CVM_MANAGEMENT

setTryLimit

boolean setTryLimit(byte bTryLimit)
Sets the CVM try limit, that is, the maximum value of the CVM try counter.

If the Application invoking this method does not have the CVM Management Privilege, then the CVM try limit is not set.

If the CVM try limit is successfully set, then this method also resets the CVM try counter to the new CVM try limit. If the CVM value has already been successfully set previously, then this method also (re)sets the CVM state to ACTIVE.

Notes:

Parameters:
bTryLimit - the maximum number of tries for the CVM.
Returns:
true if the try limit was set, false otherwise.
See Also:
GPRegistryEntry.PRIVILEGE_CVM_MANAGEMENT

verify

short verify(byte[] baBuffer,
             short sOffset,
             byte bLength,
             byte bFormat)
Compares a value with the stored CVM value.

If the CVM state is BLOCKED, or if the submitted format (bFormat) is unknown (or not supported by this CVM instance), or if this method throws a NullPointerException or an ArrayIndexOutOfBoundsException, then the comparison is deemed unsuccessful.

If the submitted CVM value is not in the same format as the stored CVM value, then format conversion shall occur according to the following rules prior to comparing values:

If the comparison is unsuccessful and the CVM state is not BLOCKED, then the CVM try counter must be decremented (by 1). In this case, if the CVM try counter reaches a value of '0' then the CVM state shall be set to BLOCKED, otherwise the CVM state shall be set to INVALID_SUBMISSION.

If the comparison is successful, then the CVM try counter shall be reset to the CVM try limit and the CVM state shall be set to VALIDATED.

The CVM try counter and the CVM state shall not conform to a transaction in progress, i.e. they shall not revert to a previous value if a transaction in progress is aborted.

Parameters:
baBuffer - byte array containing the submitted CVM value. Must be a global byte array.
sOffset - offset of the submitted CVM value within baBuffer.
bLength - length of the submitted CVM value.
bFormat - format of the submitted CVM value: FORMAT_ASCII, FORMAT_BCD or FORMAT_HEX.
Returns:
CVM_SUCCESS if the comparison was successful, CVM_FAILURE otherwise.
Throws:
java.lang.SecurityException - if baBuffer is not a global byte array.
java.lang.NullPointerException - if baBuffer is null.
java.lang.ArrayIndexOutOfBoundsException - if reading the submitted CVM value would cause access of data outside array bounds.


Copyright © 2003-2014 GlobalPlatform, Inc. All rights reserved. The technology provided or described in this specification is subject to updates, revisions, and extensions by GlobalPlatform. Recipients of this document are invited to submit, with their comments, notification of any relevant patent rights or other intellectual property rights of which they may be aware which might be necessarily infringed by the implementation of the specification or other work product set forth in this document, and to provide supporting documentation.
THIS SPECIFICATION OR OTHER WORK PRODUCT IS BEING OFFERED WITHOUT ANY WARRANTY WHATSOEVER, AND IN PARTICULAR, ANY WARRANTY OF NON-INFRINGEMENT IS EXPRESSLY DISCLAIMED. ANY IMPLEMENTATION OF THIS SPECIFICATION OR OTHER WORK PRODUCT SHALL BE MADE ENTIRELY AT THE IMPLEMENTER'S OWN RISK, AND NEITHER THE COMPANY, NOR ANY OF ITS MEMBERS OR SUBMITTERS, SHALL HAVE ANY LIABILITY WHATSOEVER TO ANY IMPLEMENTER OR THIRD PARTY FOR ANY DAMAGES OF ANY NATURE WHATSOEVER DIRECTLY OR INDIRECTLY ARISING FROM THE IMPLEMENTATION OF THIS SPECIFICATION OR OTHER WORK PRODUCT.