public interface OffloadingService extends ResourceService
Provides resource streaming services.
manage
method in mode EXPORT
exports an encrypted, streamed resource.manage
method in mode IMPORT
imports an encrypted, streamed resource.Note: The resource streaming format is vendor-specific.
To export or import resources, the CSP Admin must configure ACCESS_MOVE
for the resources.
For details on admin commands of the CSP-Protocol, see Chapter 7 of GlobalPlatform Amendment N.
Below are pseudo admin command examples using CSP-Protocol ASN.1 types.
// Create a key resource. CSPCreateResource(RESOURCE_ID, KEY_ECC_PRIVATE) CSPGenerate(RESOURCE_ID) // Create the offloading cipher resource. CSPCreateResource(CIPHER_KEY_ID, KEY_AES) CSPGenerate(CIPHER_KEY_ID) // Configure access control. CSPConfigureResource(RESOURCE_ID, ACR_USE & ACR_MOVE) CSPConfigureResource(CIPHER_KEY_ID, ACR_USE) // Configure usage and algorithms. CSPConfigureResource(CIPHER_KEY_ID, USAGE_OFFLOADING, CIPHER_AES_XTS)
Sample code for using the OffloadingService
:
// 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 services. OffloadingService offloadingService = csp.getOffloadingService(); switch (ins) { // Resource import sample. case IMPORT_INIT: offloadingService.initManage(RESOURCE_ID, OffloadingService.MODE_IMPORT_RESOURCE, CIPHER_KEY_ID); break; case IMPORT_UPDATE: len = offloadingService.updateManage(inBuffer, (short) 0, (short) inBuffer.length); offloadingService.assertSensitiveResult(len); break; case IMPORT_DOFINAL: len = offloadingService.manage(inBuffer, (short) 0, (short) inBuffer.length); offloadingService.assertSensitiveResult(len); break; // Resource export sample. case EXPORT_INIT offloadingService.initManage(RESOURCE_ID, OffloadingService.MODE_EXPORT_RESOURCE, CIPHER_KEY_ID); resourceLength = offloadingService.getManagedLength(RESOURCE_ID); Util.setShort(outBuffer, outOffset, resourceLength); break; case EXPORT_UPDATE: len = offloadingService.updateManage(outBuffer, outOffset, outLen); offloadingService.assertSensitiveResult(len); break; case EXPORT_DOFINAL: len = offloadingService.manage(outBuffer, outOffset, outLen); offloadingService.assertSensitiveResult(len); break; }
ResourceService
,
KeyService
,
CertificateService
Modifier and Type | Field and Description |
---|---|
static byte |
MANAGE_MODE_OFFLOAD_EXPORT
Sets the service to resource streaming export mode.
|
static byte |
MANAGE_MODE_OFFLOAD_IMPORT
Sets the service to resource streaming import mode.
|
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 |
getManagedLength(short resourceId)
Retrieve the size, in bytes, of the buffer required for importing or exporting the resource.
|
void |
initManage(short resourceId,
byte mode,
short cipherKeyId)
Initializes the service for either resource import or export.
|
void |
initManage(short resourceId,
byte mode,
short cipherKeyId,
byte[] initializationData,
short initializationDataOffset,
short initializationDataLength)
Initializes the service for either resource import or export using algorithm-specific parameters (e.g., iv data).
|
short |
manage(byte[] buffer,
short offset,
short length)
Import or export an encrypted resource stream, depending on the mode set.
|
short |
updateManage(byte[] buffer,
short offset,
short length)
Multipart encrypted resource stream import or export, depending on the mode set.
|
clear, clearTransient, getResourceType, getState
assertSensitiveResult
static final byte MANAGE_MODE_OFFLOAD_IMPORT
In this mode, the manage(..)
and updateManage(..)
methods are used
to import the complete resource, including its value and all resource parameters.
initManage(..)
,
Constant Field Valuesstatic final byte MANAGE_MODE_OFFLOAD_EXPORT
In this mode, the manage(..)
and updateManage(..)
methods are used
to export the complete resource, including its value and all resource parameters.
initManage(..)
,
Constant Field Valuesvoid initManage(short resourceId, byte mode, short cipherKeyId)
Method Behavior:
This method initializes the service for subsequent use with the updateManage(..)
and/or manage(..)
methods
to import or export the provided resource.
The method handles access control and events according to Section 6.13.3 of GlobalPlatform Amendment N.
resourceId
- Resource to be streamed.mode
- IMPORT
or EXPORT
.cipherKeyId
- The cipher key used to encrypt/decrypt the resource stream.CSPException
- with reason:
ILLEGAL_VALUE
: Unknown mode [2081] or resource ID does not exist [2001].ILLEGAL_CONFIG
: CSP not activated [3001], resource not initialized for EXPORT
[3003], resource already initialized for IMPORT
[3004] or inconsistent policy config [3009].NOT_ALLOWED
: Client not authenticated [5006] or resource missing ACCESS_MOVE
[500A], exhausted [50A0] or expired [50B1], or has an active usage counter [50D1], a policy failed [500B] or cipher key missing USAGE_OFFLOADING
[50D0].updateManage(..)
,
manage(..)
,
clear(..)
void initManage(short resourceId, byte mode, short cipherKeyId, byte[] initializationData, short initializationDataOffset, short initializationDataLength)
Method Behavior:
This method initializes the service for subsequent use with the updateManage(..)
and/or manage(..)
methods
to import or export the provided resource.
The method handles access control and events according to Section 6.13.3 of GlobalPlatform Amendment N.
Usage Guidelines:
CSPSensitiveArrays
for the initialization data.resourceId
- Resource to be streamed.mode
- IMPORT
or EXPORT
.cipherKeyId
- The cipher key used to encrypt/decrypt the resource stream.initializationData
- Algorithm-specific initialization data, e.g., initialization vector (iv).initializationDataOffset
- Offset in the buffer to start reading the initialization data.initializationDataLength
- Length of the initialization data in bytes.CSPException
- with reason:
ILLEGAL_BUFFER
: Illegal input buffer [1002], [1004], [1005], [1006], [1007].ILLEGAL_VALUE
: Unknown mode [2081] or resource ID does not exist [2001].ILLEGAL_CONFIG
: CSP not activated [3001], resource not initialized for EXPORT
[3003], resource already initialized for IMPORT
[3004] or inconsistent policy config [3009].NOT_ALLOWED
: Client not authenticated [5006] or resource missing ACCESS_MOVE
[500A], exhausted [50A0] or expired [50B1], or has an active usage counter [50D1], a policy failed [500B] or cipher key missing USAGE_OFFLOADING
[50D0].updateManage(..)
,
manage(..)
,
clear(..)
short updateManage(byte[] buffer, short offset, short length)
Method Behavior:
This method processes a data chunk for multipart import or export when the resource cannot be transported in one array.
Based on the mode from the last initManage(..)
call, it imports or exports the resource without finalizing this process.
The method handles access control and events according to Section 6.13.3 of GlobalPlatform Amendment N.
Usage Guidelines:
assertSensitiveResult(..)
in MANAGE_MODE_OFFLOAD_EXPORT
.initManage(..)
before calling this method.manage(..)
after one or more updateManage(..)
calls.buffer
- Input buffer for IMPORT
or output buffer for EXPORT
.offset
- Start offset in the buffer for reading or writing.length
- Number of bytes to read or write.CSPException
- with reason:
ILLEGAL_BUFFER
: Illegal input or output buffer [1001], [1002], [1004], [1005].ILLEGAL_CONFIG
: CSP not activated [3001], missing resource [3002], resource not initialized for EXPORT
[3003] or resource already initialized for IMPORT
[3004].INVALID_INIT
: Service not initialized [4080].NOT_ALLOWED
: Stream missing validity date [50D2].ILLEGAL_USE
: Invalid input data [6080], illegal output buffer [6081], counter capacity reached [60A2] or stream missing validity date [60D1].initManage(..)
,
manage(..)
short manage(byte[] buffer, short offset, short length)
Method Behavior:
Imports or exports a resource based on the last initManage(..)
call.
After completion, a new initManage(..)
call is required to prepare the service for the next import or export.
The method handles access control and events according to Section 6.13.3 of GlobalPlatform Amendment N.
Usage Guidelines:
assertSensitiveResult(..)
in EXPORT
.initManage(..)
before calling this method.updateManage(..)
as needed before finalizing with this method.buffer
- Input buffer for IMPORT
or output buffer for EXPORT
.offset
- Start offset in the buffer for reading or writing.length
- Number of bytes to read or write.CSPException
- with reason:
ILLEGAL_BUFFER
: Illegal input or output buffer [1001], [1002], [1004], [1005].ILLEGAL_CONFIG
: CSP not activated [3001], missing resource [3002], resource not initialized for EXPORT
[3003] or resource already initialized for IMPORT
[3004].INVALID_INIT
: Service not initialized [4080].ILLEGAL_USE
: Invalid input data [6080], illegal output buffer [6081], counter capacity reached [60A2] or stream missing validity date [60D1].initManage(..)
,
updateManage(..)
short getManagedLength(short resourceId)
resourceId
- The resource.CSPException
- with reason:
ILLEGAL_VALUE
: Resource ID does not exist [2001].ILLEGAL_CONFIG
: CSP not activated [3001] or resource not initialized [3003].NOT_ALLOWED
: Client not authenticated [5006].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.