public interface CVM
extends javacard.framework.Shareable
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):
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).Modifier and Type | Field and Description |
---|---|
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.
|
Modifier and Type | Method and Description |
---|---|
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.
|
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.
|
static final short CVM_SUCCESS
static final short CVM_FAILURE
static final byte FORMAT_ASCII
Note:
static final byte FORMAT_BCD
Note:
static final byte FORMAT_HEX
Note:
boolean isActive()
true
if the CVM has been fully initialized and is
ready for use, false
otherwise (i.e. the CVM state is NOT_READY).boolean isSubmitted()
true
if the CVM state is INVALID_SUBMISSION or
VALIDATED, false
otherwise.boolean isVerified()
true
if the CVM state is VALIDATED,
false
otherwise.boolean isBlocked()
true
if the CVM state is BLOCKED, false
otherwise.byte getTriesRemaining()
boolean update(byte[] baBuffer, short sOffset, byte bLength, byte bFormat)
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:
GPRegistryEntry
interface;
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
.true
if the CVM value was successfully updated,
false
otherwise.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.GPRegistryEntry.PRIVILEGE_CVM_MANAGEMENT
boolean resetState()
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.
true
if the CVM state was reset, false
otherwise.boolean blockState()
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:
GPRegistryEntry
interface;
true
if the CVM state was set to BLOCKED,
false
otherwise.GPRegistryEntry.PRIVILEGE_CVM_MANAGEMENT
boolean resetAndUnblockState()
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:
GPRegistryEntry
interface;
true
if the CVM state was reset to ACTIVE,
false
otherwise.GPRegistryEntry.PRIVILEGE_CVM_MANAGEMENT
boolean setTryLimit(byte bTryLimit)
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:
GPRegistryEntry
interface;
bTryLimit
- the maximum number of tries for the CVM.true
if the try limit was set, false
otherwise.GPRegistryEntry.PRIVILEGE_CVM_MANAGEMENT
short verify(byte[] baBuffer, short sOffset, byte bLength, byte bFormat)
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 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.
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
.CVM_SUCCESS
if the comparison was successful, CVM_FAILURE
otherwise.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-2018 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.