public interface CounterService extends ResourceService
Provides services for secure counters.
getValue(..)
method returns the current counter value, e.g., of a usage counter or manual counter.getLimit(..)
method returns the maximum limit configured for a counter.isExhaustedisExhausted(..)
method checks if the counter is over its limit.increment(..)
method increments a manual counter.Counter and limits must be configured by the CSP Admin and cannot be selected via the CSP-API. For details on admin commands, see Chapter 7 of GlobalPlatform Amendment N [GPC_SPE_230].
Below are pseudo admin command examples using CSP-Protocol ASN.1 types.
// Activate a built-in usage counter for a signature key. { // Import signature key. CSPCreateResource(SIG_KEY_ID, KEY_ECC_PUBLIC, CURVE_BRAINPOOL_P256_R1) CSPSetValue(SIG_KEY_ID, data) // Configure usage and access control. CSPConfigureResource(SIG_KEY_ID, ACR_USE) CSPConfigureResource(SIG_KEY_ID, USAGE_SIGNATURE, SIG_ECDSA, PAD_NULL, ALG_SHA_256) // Configure counter. CSPConfigureResource(SIG_KEY_ID, usageCounter(capacity=MEDIUM, limit=5000)) CSPSetup(counterMode = STRICT) }
TimeService
Modifier and Type | Field and Description |
---|---|
static byte |
COUNT_AUTH_USAGE
Authentication counter for passwords used as timeout.
|
static byte |
COUNT_MANUAL
Manual counter with optional limit.
|
static byte |
COUNT_TRANSPORT_USAGE
Transport counter for passwords marked as "in transport".
|
static byte |
COUNT_USAGE
Count resource usage with optional limit.
|
static byte |
COUNT_USAGE_FAILURE_ONLY
Counts failed resource usage with an optional limit.
|
static byte |
COUNT_USAGE_PER_BLOCK
Count detailed resource usage per cryptographic block operation with optional limit.
|
static byte |
COUNT_USAGE_SUCCESS_ONLY
Counts successful resource usage with an optional limit.
|
RESOURCE_CERTIFICATE, RESOURCE_COUNTER, RESOURCE_KEY, RESOURCE_PASSWORD, RESOURCE_TIMER, STATE_BLOCKED, STATE_EXHAUSTED, STATE_EXPIRED, STATE_OPERATIONAL, STATE_UNINITIALIZED
RESULT_FALSE, RESULT_TRUE
Modifier and Type | Method and Description |
---|---|
short |
getLimit(short resourceId,
byte counterType,
byte[] outBuffer,
short outOffset)
Retrieve the maximum limit configuration of a counter.
|
short |
getRemaining(short resourceId,
byte counterType,
byte[] outBuffer,
short outOffset)
Retrieve the remaining counter value before the counter reaches its limit.
|
short |
getValue(short resourceId,
byte counterType,
byte[] outBuffer,
short outOffset)
Retrieve the current value of a counter.
|
short |
getValueAsShort(short resourceId,
byte counterType)
Retrieve the current value of a counter as short.
|
short |
hasCounter(short resourceId,
byte counterType)
Retrieve whether a specific counter type is activated for the resource.
|
short |
hasLimit(short resourceId,
byte counterType)
Check if a limit is configured for a counter.
|
void |
increment(short counterResourceId,
short delta)
Manually increment a counter resource.
|
short |
isExhausted(short resourceId,
byte counterType)
Check if the counter is over its configured limit.
|
void |
reset(byte counterResourceId)
Reset a counter of type
COUNT_MANUAL . |
clear, clearTransient, getResourceType, getState
assertSensitiveResult
static final byte COUNT_MANUAL
The counter is incremented upon increment (..)
.
When over the limit, the counter resource changes to EXHAUSTED
.
static final byte COUNT_USAGE
The counter is incremented upon:
CipherService.doFinal(..)
SignatureService.sign(..)
TransformService.doFinal(..)
SecureChannelService.processSecurity(..)
ConfidentialDataTransferService.confidentialWrap(..)
ConfidentialDataTransferService.confidentialUnwrap(..)
AttestationService.computeAttestation(..)
PasswordService.check(..)
OffloadingService.manage(..)
The counter is reset to zero when a new resource value is imported or generated.
When over the limit, the counter resource changes to EXHAUSTED
.
static final byte COUNT_USAGE_PER_BLOCK
The counter is incremented upon:
CipherService.doFinal(..)
SignatureService.sign(..)
TransformService.doFinal(..)
SecureChannelService.processSecurity(..)
ConfidentialDataTransferService.confidentialWrap(..)
ConfidentialDataTransferService.confidentialUnwrap(..)
AttestationService.computeAttestation(..)
PasswordService.check(..)
OffloadingService.manage(..)
CipherService.update(..)
SignatureService.update(..)
TransformService.update(..)
ConfidentialDataTransferService.updateConfidentialWrap(..)
ConfidentialDataTransferService.updateConfidentialWrap(..)
AttestationService.update(..)
OffloadingService.updateManage(..)
The counter is reset to zero when a new resource value is imported or generated.
When over the limit, the counter resource changes to EXHAUSTED
.
static final byte COUNT_USAGE_SUCCESS_ONLY
This counter increments for the same method invocations as COUNT_USAGE
,
but only when the method completes successfully without errors.
The counter resets to zero when a new resource value is imported or generated.
If the limit is exceeded, the resource state changes to EXHAUSTED
.
static final byte COUNT_USAGE_FAILURE_ONLY
This counter increments for the same method invocations as COUNT_USAGE
,
but only when the method returned FALSE
or an exception.
The counter resets to zero when a new resource value is imported or generated.
If the limit is exceeded, the resource state changes to EXHAUSTED
.
static final byte COUNT_AUTH_USAGE
The CSP increments this counter for cryptographic operations requiring an authenticated password.
If the limit is exceeded, the authenticated flag of the password is reset.
static final byte COUNT_TRANSPORT_USAGE
The CSP increments this counter for successfully password verifications and deactivates the password after it is changed.
If the limit is exceeded, the resource state changes to EXHAUSTED
.
short hasCounter(short resourceId, byte counterType)
Usage Guidelines:
assertSensitiveResult(..)
.resourceId
- Resource to check.counterType
- Counter type; one of the COUNTER constant values.TRUE
if the timer is activated, FALSE
otherwise.CSPException
- with reason:
ILLEGAL_VALUE
: Resource ID does not exist [2001] or illegal counter type [20A1].ILLEGAL_CONFIG
: CSP not activated [3001].NOT_ALLOWED
: Client not authenticated [5006] or resource missing ACCESS_USE
[5007].NOT_SUPPORTED
: Counter type [80A2] or capacity [80A3] not supported.getValue(..)
,
getLimit(..)
,
getRemaining(..)
short getValue(short resourceId, byte counterType, byte[] outBuffer, short outOffset)
Usage Guidelines:
CSPSensitiveArrays
for the output value and invoke assertIntegrity(..)
after processing it.assertSensitiveResult(..)
.resourceId
- Resource owning the counter.counterType
- Counter type; one of the COUNTER constant values.outBuffer
- Output buffer for storing the counter value.outOffset
- Offset in the output buffer where the result should be written.CSPException
- with reason:
ILLEGAL_BUFFER
: Illegal input or output buffer [1001], [1004], [1005], [1006], [1007].ILLEGAL_VALUE
: Resource ID does not exist [2001] or illegal counter type [20A0].ILLEGAL_CONFIG
: CSP not activated [3001] or resource not initialized [3003].NOT_ALLOWED
: Client not authenticated [5006] or resource missing ACCESS_USE
[5007] or exhausted [50A0].NOT_SUPPORTED
: Counter type [80A2] or capacity [80A3] not supported.hasCounter(..)
,
getLimit(..)
,
getRemaining(..)
short getValueAsShort(short resourceId, byte counterType)
Usage Guidelines:
assertSensitiveResult(..)
.resourceId
- Resource owning the counter.counterType
- Counter type; one of the COUNTER constant values.CSPException
- with reason:
ILLEGAL_VALUE
: Resource ID does not exist [2001] or illegal counter type [20A0].ILLEGAL_CONFIG
: CSP not activated [3001] or resource not initialized [3003].ILLEGAL_USE
: Capacity exceeds short [60A0].NOT_ALLOWED
: Client not authenticated [5006] or resource missing ACCESS_USE
[5007] or exhausted [50A0].NOT_SUPPORTED
: Counter type [80A2] or capacity [80A3] not supported.hasCounter(..)
,
getLimit(..)
,
getRemaining(..)
short getRemaining(short resourceId, byte counterType, byte[] outBuffer, short outOffset)
Method Behavior:
Calculates the difference between the maximum counter limit and the current counter value.
Usage Guidelines:
CSPSensitiveArrays
for the output value and invoke assertIntegrity(..)
after processing it.assertSensitiveResult(..)
.resourceId
- Resource owning the counter.counterType
- Counter type; one of the COUNTER constant values.outBuffer
- Output buffer for storing the remaining counter value.outOffset
- Offset in the output buffer where the result should be written.CSPException
- with reason:
ILLEGAL_BUFFER
: Illegal input or output buffer [1001], [1004], [1005], [1006], [1007].ILLEGAL_VALUE
: Resource ID does not exist [2001] or illegal counter type [20A0].ILLEGAL_CONFIG
: CSP not activated [3001] or resource not initialized [3003].NOT_ALLOWED
: Client not authenticated [5006] or resource missing ACCESS_USE
[5007] or exhausted [50A0].ILLEGAL_USE
: No limit configured [60A1].NOT_SUPPORTED
: Counter type [80A2] or capacity [80A3] not supported.getLimit(..)
,
getValue(..)
short hasLimit(short resourceId, byte counterType)
Usage Guidelines:
assertSensitiveResult(..)
.resourceId
- Resource to check.counterType
- Counter type; one of the COUNTER constant values.TRUE
if the timer is activated, FALSE
otherwise.CSPException
- with reason:
ILLEGAL_VALUE
: Resource ID does not exist [2001] or illegal counter type [20A0].ILLEGAL_CONFIG
: CSP not activated [3001].NOT_ALLOWED
: Client not authenticated [5006].NOT_SUPPORTED
: Counter type [80A2] or capacity [80A3] not supported.getLimit(..)
,
hasCounter(..)
,
getValue(..)
short getLimit(short resourceId, byte counterType, byte[] outBuffer, short outOffset)
Usage Guidelines:
CSPSensitiveArrays
for the output value and invoke assertIntegrity(..)
after processing it.assertSensitiveResult(..)
.resourceId
- Resource owning the counter.counterType
- Counter type; one of the COUNTER constant values.outBuffer
- Output buffer for storing the counter value.outOffset
- Offset in the output buffer where the result should be written.CSPException
- with reason:
ILLEGAL_BUFFER
: Illegal input or output buffer [1001], [1004], [1005], [1006], [1007].ILLEGAL_VALUE
: Resource ID does not exist [2001] or illegal counter type [20A0].ILLEGAL_CONFIG
: CSP not activated [3001].NOT_ALLOWED
: Client not authenticated [5006].ILLEGAL_USE
: No limit configured [60A1].NOT_SUPPORTED
: Counter type [80A2] or capacity [80A3] not supported.hasCounter(..)
,
getValue(..)
,
getRemaining(..)
short isExhausted(short resourceId, byte counterType)
Usage Guidelines:
assertSensitiveResult(..)
.resourceId
- Resource owning the counter.counterType
- Counter type; one of the COUNTER constant values.TRUE
if exhausted; otherwise FALSE
.CSPException
- with reason:
ILLEGAL_VALUE
: Resource ID does not exist [2001] or illegal counter type [20A0].ILLEGAL_CONFIG
: CSP not activated [3001].NOT_ALLOWED
: Client not authenticated [5006].ILLEGAL_USE
: No limit configured [60A1].NOT_SUPPORTED
: Counter type [80A2] or capacity [80A3] not supported.void increment(short counterResourceId, short delta)
counterResourceId
- Counter resource.delta
- Delta to increment.CSPException
- with reason:
ILLEGAL_VALUE
: Resource ID does not exist [2001] or illegal counter type [20A0].ILLEGAL_CONFIG
: CSP not activated [3001].NOT_ALLOWED
: Client not authenticated [5006] or resource missing ACCESS_USE
[5007] or exhausted [50A0].void reset(byte counterResourceId)
COUNT_MANUAL
.counterResourceId
- Counter resource.CSPException
- with reason:
ILLEGAL_VALUE
: Resource ID does not exist [2001] or illegal counter type [20A0].ILLEGAL_CONFIG
: CSP not activated [3001].NOT_ALLOWED
: Client not authenticated [5006] or resource missing ACCESS_SETUP
[5008].Copyright © 2023-2025 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.