public interface TimeService extends ResourceService
Provides services for timers and time management.
getValue(..)
method returns the current timer value, e.g., of a validity date or a timeout.isExpired(..)
method checks if the timer is expired.reset(..)
method resets a manual timer.setReferenceTime(..)
method sets a new reference time to estimate a system time.Due to the limited capacity of secure elements, the CSP relies on an external time source to set a reference time. This reference time is used to estimate the system time by adding the time since boot to the reference time and then subtracting the elapsed time recorded when the reference time was set.
Available mechanisms for updating the reference time:
setReferenceTime(..)
without restrictions.setReferenceTime(.., signature)
. The CSP verifies the time signature and/or accepts only newer updates.Time management and timers 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 automatic time synchronization based on TA2 (Terminal Authentication v2) certificates. { CSPSetup(timeMode = STRICT, timeSync = SYNC_FROM_TA2 & SYNC_ENFORCE_NEWER) } // Enable Client Applications to configure a reference time. { // Import time verification key. CSPCreateResource(TIME_KEY_ID, KEY_ECC_PUBLIC, CURVE_BRAINPOOL_P256_R1) CSPSetValue(TIME_KEY_ID, data) // Configure usage and access control. CSPConfigureResource(TIME_KEY_ID, ACR_USE) CSPConfigureResource(TIME_KEY_ID, USAGE_TIME, SIG_ECDSA, PAD_NULL, ALG_SHA_256) // Configure time management. CSPSetup(timeMode = STRICT, timeSync = SYNC_FROM_CLIENT & SYNC_ENFORCE_NEWER & SYNC_PERSIST & SYNC_VERIFY_SIG) timeSyncClientAIDs = AID_data timeSignatureVerificationKey = TIME_KEY_ID) }
CounterService
Modifier and Type | Field and Description |
---|---|
static byte |
TIMER_AUTH_TIMEOUT
Authentication timeout for password resources.
|
static byte |
TIMER_MANUAL_DATE
Manual timer with a specific expiration date.
|
static byte |
TIMER_MANUAL_PERIOD
Manual timer with an expiration date based on a time period.
|
static byte |
TIMER_VALIDITY_CERTIFICATE
Validity date of certificate resources.
|
static byte |
TIMER_VALIDITY_DATE
Specific validity date for a key or password resource.
|
static byte |
TIMER_VALIDITY_PERIOD
Validity period for a key or password resource.
|
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 |
getChallenge(byte[] outBuffer,
short outOffset)
Retrieve the pre-generated challenge used to verify the signature of a newly provided reference time.
|
short |
getValue(short resourceId,
byte timerType,
byte[] outBuffer,
short outOffset)
Retrieve the current value of a timer.
|
short |
hasTimer(short resourceId,
byte timerType)
Retrieve whether a specific timer type is activated for the resource.
|
short |
isExpired(short resourceId,
byte timerType)
Check if the timer is expired.
|
void |
reset(byte timerResourceId)
Reset a timer of type
TIMER_MANUAL_PERIOD . |
short |
setReferenceTime(byte[] timeBuffer,
short timeOffset)
Convenience method that invokes
setReferenceTime(newTime, newTimeOffset, null, (short) 0, (short) 0)
without requiring a signature. |
short |
setReferenceTime(byte[] timeBuffer,
short timeOffset,
byte[] sigBuffer,
short sigOffset,
short sigLen)
Sets a new reference time to the CSP Instance.
|
clear, clearTransient, getResourceType, getState
assertSensitiveResult
static final byte TIMER_MANUAL_DATE
The limit is an 8-byte timestamp, used directly as the timer value.
This timer is evaluated only upon isExpired(..)
.
When expired, the counter resource changes to EXPIRED
.
static final byte TIMER_MANUAL_PERIOD
The limit is a 4-byte duration. The 8-byte timer value is calculated upon reset(byte)
.
This timer is evaluated only upon isExpired(..)
.
When expired, the counter resource changes to EXPIRED
.
static final byte TIMER_VALIDITY_PERIOD
The limit is a 4-byte duration, with the 8-byte timer value calculated during resource import or generation based on the current estimated system time. The CSP evaluates this timer during cryptographic operations that use the resource.
When expired, the resource changes to EXPIRED
.
static final byte TIMER_VALIDITY_DATE
The limit is an 8-byte timestamp, used directly as the timer value. The CSP evaluates this timer during cryptographic operations that use the resource.
When expired, the resource changes to EXPIRED
.
static final byte TIMER_VALIDITY_CERTIFICATE
The limit is an 8-byte timestamp, extracted from the certificate. The CSP evaluates this timer during cryptographic operations that use the certificate.
When expired, the certificate resource changes to EXPIRED
.
static final byte TIMER_AUTH_TIMEOUT
The limit is an 2-byte timestamp with a 4byte timer value calculated during after successful PasswordService.check(..)
based on the current time since boot. The CSP evaluates this timer during
cryptographic operations requiring an authenticated password.
When expired, the authenticated flag of the password is reset.
short hasTimer(short resourceId, byte timerType)
Usage Guidelines:
assertSensitiveResult(..)
.resourceId
- Resource to check.timerType
- Timer type; one of the TIMER constant values.TRUE
if the timer is activated, FALSE
otherwise.CSPException
- with reason:
ILLEGAL_VALUE
: Resource ID does not exist [2001] or illegal timer type [20B0].ILLEGAL_CONFIG
: CSP not activated [3001].NOT_ALLOWED
: Client not authenticated [5006] or resource missing ACCESS_USE
[5008].NOT_SUPPORTED
: Timer type [80B4] not supported.getValue(..)
short getValue(short resourceId, byte timerType, byte[] outBuffer, short outOffset)
Usage Guidelines:
CSPSensitiveArrays
for the output value and invoke assertIntegrity(..)
after processing it.assertSensitiveResult(..)
.resourceId
- Resource owning the timer.timerType
- Timer type; one of the TIMER constant values.outBuffer
- Output buffer for storing the timer value.outOffset
- Offset in the output buffer where the result should be written.CSPException
- with reason:
ILLEGAL_BUFFER
: Illegal output buffer [1001], [1004], [1005], [1006], [1007].ILLEGAL_VALUE
: Resource ID does not exist [2001] or illegal timer type [20B0].ILLEGAL_CONFIG
: CSP not activated [3001] or resource not initialized [3003].NOT_ALLOWED
: Client not authenticated [5006], resource missing ACCESS_USE
[5008] or expired [50B1].NOT_SUPPORTED
: Timer type [80B4] not supported.hasTimer(..)
short isExpired(short resourceId, byte timerType)
Usage Guidelines:
assertSensitiveResult(..)
.resourceId
- Resource owning the timer.timerType
- Timer type; one of the TIMER constant values.TRUE
if expired; otherwise FALSE
.CSPException
- with reason:
ILLEGAL_VALUE
: Resource ID does not exist [2001] or illegal timer type [20B0].ILLEGAL_CONFIG
: CSP not activated [3001].NOT_ALLOWED
: Client not authenticated [5006].NOT_SUPPORTED
: Timer type [80B4] not supported.short setReferenceTime(byte[] timeBuffer, short timeOffset, byte[] sigBuffer, short sigOffset, short sigLen)
Data Format:
Requires a UNIX timestamp as 8-byte signed integer in "TIMESTAMP" format, as specified in Section 6.11.1.4 of GlobalPlatform Amendment N.
Method Behavior:
This method sets the internal reference time to the timestamp provided in the input buffer, replacing any previous reference time.
If TIME_SYNC_PERSIST
is enabled, the new time is saved in persistent memory.
If TIME_SYNC_VERIFY_SIG_WITH_CHALLENGE
is enabled, the methods generates a new challenge for the next update.
The method handles access control, counters, timers and events according to Section 6.11.3 of GlobalPlatform Amendment N.
This method will do nothing (no exception, no update of the reference time):
TIME_SYNC_ENFORCE_NEWER
is enabled, but the provided timestamp is older than the last.Usage Guidelines:
CSPSensitiveArrays
for the new reference time.CSPSensitiveArrays
for the signature.timeBuffer
- An 8-byte array containing a Unix timestamp in seconds.timeOffset
- Offset in the time buffer from where to start reading.sigBuffer
- Signature of the timestamp for verification; optional, can be null.sigOffset
- Offset in the signature buffer from which to start reading.sigLen
- Length of the signature buffer.TRUE
if the time is updated successfully, FALSE
otherwise.CSPException
- with reason:
ILLEGAL_BUFFER
: Illegal input buffer [1002], [1003], [1004], [1005], [1006], [1007].ILLEGAL_CONFIG
: CSP not activated [3001], no time verification key configured [30B0], missing resource [3002], resource not initialized [3003] or inconsistent signature configuration [3020].NOT_ALLOWED
: Client not authenticated [5006], calling AID not a time admin [50B2], time verification key missing ACCESS_USE
[5007], not configured for USAGE_TIME
[50B0], exhausted [50A0] or expired [50B1], or time signature verification failed [50B3].ILLEGAL_USE
: Illegal time format [60B0].NOT_SUPPORTED
: Padding [8011], message digest [8021] or signature algorithm [8022] not supported.getChallenge(..)
short setReferenceTime(byte[] timeBuffer, short timeOffset)
setReferenceTime(newTime, newTimeOffset, null, (short) 0, (short) 0)
without requiring a signature.timeBuffer
- An 8-byte array containing a Unix timestamp in seconds.timeOffset
- Offset in the time buffer from where to start reading.TRUE
if new reference time is set, FALSE
otherwise.CSPException
- same as setReferenceTime(..)
short getChallenge(byte[] outBuffer, short outOffset)
Method Behavior:
This method returns the challenge that was generated at system start or when a new reference time was set. This challenge, stored in transient memory (CLEAR_ON_RESET), is used to verify the signature of the reference time.
Returns a length of 0 if TIME_SYNC_VERIFY_SIG_WITH_CHALLENGE
is disabled.
Usage Guidelines:
CSPSensitiveArrays
for the output value and invoke assertIntegrity(..)
after processing it.assertSensitiveResult(..)
.outBuffer
- Output buffer for storing the challenge.outOffset
- Offset in the output buffer where the result should be written.CSPException
- with reason:
ILLEGAL_BUFFER
: Illegal output buffer [1001], [1004], [1005], [1006], [1007].NOT_ALLOWED
: Client not authenticated [5006].setReferenceTime(..)
void reset(byte timerResourceId)
TIMER_MANUAL_PERIOD
.timerResourceId
- Timer resource.CSPException
- with reason:
ILLEGAL_VALUE
: Resource ID does not exist [2001] or illegal timer type [20B0].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.