public interface ResourceService extends CSPService
Provides resource management services for keys, certificates, passwords, counters and timers.
clear(..)
method wipes a resource value (e.g., key) and resets it to STATE_UNINITIALIZED
.clearTransient(..)
method removes all transient data of this CSP Instance (transient keys, secure channel sessions, authenticated passwords).
Resources must be configured by the CSP Admin. The resource identifiers, assigned during creation, must be used in the methods provided by the ResourceService
.
For details on admin commands of the CSP-Protocol, see Chapter 7 of GlobalPlatform Amendment N [GPC_SPE_230].
Below are pseudo admin command examples using CSP-Protocol ASN.1 types.
// Create a shared secret used for key agreement. CSPCreateResource(SHARED_SECRET_ID, KEY_SHARED_SECRET, transient=true) // Create a PIN resource. CSPCreateResource(PIN_ID, PWD_NUMERIC, minSize=5, maxSize=5) // Configure access control and a policy rule requiring PUK authentication for unblocking the PIN. CSPConfigureResource(SHARED_SECRET_ID, ACR_CLEAR & ACR_SETUP & ACR_USE) CSPConfigureResource(PIN_ID, ACR_USE, ACR_SETUP & ACR_USE) // Configure algorithms and usage. CSPConfigureResource(SHARED_SECRET_ID, USAGE_KEY, KA_ECKA_DH) CSPConfigureResource(PIN_ID, USAGE_PASSWORD)
Sample code for using the ResourceService
:
// Retrieve CSP Shareable Instance. AID cspAID = JCSystem.lookupAID(CSP_AID_DATA, (short) 0, (byte) CSP_AID_DATA.length); GlobalService cspGlobalService = GPSystem.getService(cspAID, CSP.GLOBAL_SERVICE_ID); AID clientAID = JCSystem.getAID(); GPRegistryEntry clientRegistryEntry = GPSystem.getRegistryEntry(clientAID); CSP csp = (CSP) cspGlobalService.getServiceInterface(clientRegistryEntry, CSP.DEFAULT_SERVICE_ID, null, (short) 0, (short) 0); // Init service. ResourceService resourceService = csp.getKeyService(); switch (ins) { // Clear resource sample. case RESOURCE_CLEAR: if (resourceService.getState(SHARED_SECRET_ID) != ResourceService.STATE_UNINITIALIZED) { resourceService.clear(SHARED_SECRET_ID); } break; // Clear all transient data. case RESOURCE_CLEAR_TRANSIENT: resourceService.clearTransient(); // any resource service can be used break;
OffloadingService
Modifier and Type | Field and Description |
---|---|
static byte |
RESOURCE_CERTIFICATE
Resource of type CERTIFICATE (e.g., CVC, X509).
|
static byte |
RESOURCE_COUNTER
Resource of type COUNTER (e.g., manual counter, usage counter, transport counter).
|
static byte |
RESOURCE_KEY
Resource of type cryptographic KEY (e.g., AES, ECC, RSA).
|
static byte |
RESOURCE_PASSWORD
Resource of type PASSWORD (e.g., PIN, UTF-8).
|
static byte |
RESOURCE_TIMER
Resource of type TIMER (e.g., timeout, validity date).
|
static byte |
STATE_BLOCKED
The try counter of a password exceeded and password is BLOCKED for further use.
|
static byte |
STATE_EXHAUSTED
A resource counter of the resources is EXHAUSTED and is blocked for further use.
|
static byte |
STATE_EXPIRED
Resource in state EXPIRED and is blocked for further use.
|
static byte |
STATE_OPERATIONAL
Resource in state OPERATIONAL (fully initialized, ready for use).
|
static byte |
STATE_UNINITIALIZED
Resource in state UNINITIALIZED (has no value).
|
RESULT_FALSE, RESULT_TRUE
Modifier and Type | Method and Description |
---|---|
void |
clear(short resourceId)
Uninitialize a resource by removing its value and restoring all attributes to their default states.
|
void |
clearTransient()
Reset all transient data within the CSP Instance, including transient resources and authentication states.
|
byte |
getResourceType(short resourceId)
Retrieve the resource type.
|
byte |
getState(short resourceId)
Receive the current state of a resource.
|
assertSensitiveResult
static final byte RESOURCE_KEY
Available sub types:
KeyService
,
Constant Field Valuesstatic final byte RESOURCE_CERTIFICATE
CertificateService
,
Constant Field Valuesstatic final byte RESOURCE_PASSWORD
Available sub types:
PasswordService
,
Constant Field Valuesstatic final byte RESOURCE_COUNTER
Available sub types:
CounterService
,
Constant Field Valuesstatic final byte RESOURCE_TIMER
Available sub types:
TimeService
,
Constant Field Valuesstatic final byte STATE_UNINITIALIZED
The resource has no value set and cannot be used for cryptographic services.
A resource is reset to this state using the clear(..)
operation.
getState(..)
,
Constant Field Valuesstatic final byte STATE_OPERATIONAL
The resource is ready for use in cryptographic operations.
A resource is transitioned to this state following successful key generation
,
key derivation
, key agreement
,
key import
, certificate import
or
password updates
.
getState(..)
,
Constant Field Valuesstatic final byte STATE_EXPIRED
The validity date of the resource is expired and cannot be used for cryptographic services.
Expired resources are reset to state UNINITIALIZED
using the clear(..)
method.
getState(..)
,
Constant Field Valuesstatic final byte STATE_EXHAUSTED
A usage counter of the resource is over the limit expired and the resource cannot be used for cryptographic services.
Exhausted resources are reset to state UNINITIALIZED
using the clear(..)
method.
getState(..)
,
Constant Field Valuesstatic final byte STATE_BLOCKED
A try counter counting illegal password attempts reached its limit and and the resource cannot be used for cryptographic services.
Blocked resources are reset to state OPERATIONAL
using the resetAndUnblock(..)
method
or reset to state UNINITIALIZED
using the clear(..)
method.
getState(..)
,
Constant Field Valuesbyte getState(short resourceId)
Available types:
STATE_UNINITIALIZED
- Resource not ready for cryptographic operations.STATE_OPERATIONAL
- Resource value is set; validity, usage limit and (re)try limit are not exceeded.STATE_EXPIRED
- Validity period expired.STATE_EXHAUSTED
- Usage counter exhausted.STATE_BLOCKED
- (Re)try limit exceeded (only available for passwords).Usage Guidelines:
assertSensitiveResult(..)
.resourceId
- Resource.CSPException
- with reason:
ILLEGAL_VALUE
: Resource ID does not exist [2001].NOT_ALLOWED
: Client not authenticated [5006].byte getResourceType(short resourceId)
Available types:
resourceId
- Resource.CSPException
- with reason:
ILLEGAL_VALUE
: Resource ID does not exist [2001].NOT_ALLOWED
: Client not authenticated [5006].void clear(short resourceId)
Available for:
All resource types except INSTANCE_KEY_DEK
, INSTANCE_KEY_KENC
, and INSTANCE_KEY_KMAC
.
Method Behavior:
This method securely wipes the resource's value, resets all attributes, and sets the resource to STATE_UNINITIALIZED
.
resourceId
- Resource to be cleared.CSPException
- with reason:
ILLEGAL_VALUE
: Resource ID does not exist [2001].NOT_ALLOWED
: Client not authenticated [5006] or resource missing ACCESS_CLEAR
[5008].KeyService.initManage(..)
,
KeyService.generate(..)
,
KeyService.generateKeyPair(..)
,
KeyService.computePublicKey(..)
,
KeyService.derive(..)
,
KeyService.computeSharedSecret(..)
,
CertificateService.initManage(..)
void clearTransient()
Method Behavior:
This method performs:
ResourceService.clear(..)
for all transient keys.SecureChannelService.resetSecurity()
for each secure channel instance.PasswordService.reset(..)
for all password resources.CSPException
- with reason:
NOT_ALLOWED
: Client not authenticated [5006].clear(..)
,
KeyService.isTransient(..)
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.