public interface TransformService extends CSPService
Provides services to transfer encryption between different keys and algorithms.
init(..)
method initializes the service with decryption and encryption resources.doFinal(..)
method transfers data encryption.update(..)
method processes multiple data chunks for re-encryption.
Cipher algorithms must be pre-configured by the CSP Admin and cannot be selected via the CSP-API.
For supported algorithms, see CipherService
.
The cryptographic resources must be configured by the CSP Admin. Their resource identifiers,
assigned during creation, must then be used to initialize the service via one of the init(..)
methods.
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 an AES key for CBC transport encryption and import it. CSPCreateResource(TRANSPORT_KEY_ID, KEY_AES, 128) CSPSetValue(TRANSPORT_KEY_ID, data) // Create AES key for XTS storage-layer encryption and generate it. CSPCreateResource(STORAGE_KEY_ID, KEY_AES, 2x256) CSPGenerateKey(STORAGE_KEY_ID) // Configure access control. CSPConfigureResource(TRANSPORT_KEY_ID, ACR_USE) CSPConfigureResource(STORAGE_KEY_ID, ACR_USE) // Configure usage and algorithms. CSPConfigureResource(TRANSPORT_KEY_ID, USAGE_TRANSFORM, CIPHER_AES_XTS) CSPConfigureResource(STORAGE_KEY_ID, USAGE_TRANSFORM, CIPHER_AES_CBC)
Sample code for using the TransformService
:
// 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. TransformService transformService = csp.makeTransformService(); switch (ins) { // Convert transport-layer to storage-layer encryption. case CONVERT_TRANSPORT_TO_STORAGE: transformService.init(TRANSPORT_KEY_ID, STORAGE_KEY_ID); storageDataLen = transformService.doFinal(transportData, (short) 0, transportDataLen, storageData, (short) 0); transformService.assertSensitiveResult(storageDataLen); break; // Convert storage-layer to transport-layer encryption. case CONVERT_STORAGE_TO_TRANSPORT: transformService.init(STORAGE_KEY_ID, TRANSPORT_KEY_ID); transportDataLen = transformService.doFinal(storageData, (short) 0, storageDataLen, transportData, (short) 0); transformService.assertSensitiveResult(transportDataLen); break; }
CipherService
,
ConfidentialDataTransferService
RESULT_FALSE, RESULT_TRUE
Modifier and Type | Method and Description |
---|---|
short |
doFinal(byte[] inBuffer,
short inOffset,
short inLength,
byte[] outBuffer,
short outOffset)
Transform source encryption to destination encryption.
|
void |
init(byte decryptKeyId,
short encryptKeyId)
Initialize to transform encryption from decryptKeyId to encryptKeyId.
|
void |
init(byte decryptKeyId,
short encryptKeyId,
byte[] initializationData,
short initializationDataDecryptOff,
short initializationDataEncryptOff,
short initializationDataEncryptLen)
Initialize to transform encryption from decryptKeyId to encryptKeyId with iv data for both.
|
short |
update(byte[] inBuffer,
short inOffset,
short inLength,
byte[] outBuffer,
short outOffset)
Multipart transformation from source encryption to destination encryption.
|
assertSensitiveResult
void init(byte decryptKeyId, short encryptKeyId)
Method Behavior:
This method initializes the service for subsequent use with the update(..)
and/or doFinal(..)
methods
using the key parameters, cipher and padding algorithms configured to the provided resources.
The method handles access control, counters, timers and events according to Section 6.3.3 of GlobalPlatform Amendment N.
decryptKeyId
- Decryption key.encryptKeyId
- Encryption key.CSPException
- with reason:
ILLEGAL_VALUE
: A resource ID does not exist [2001] or is not a KEY
[2011].ILLEGAL_CONFIG
: CSP not activated [3001], resource not initialized [3003], inconsistent cipher configuration [3010] or inconsistent policy config [3009].NOT_ALLOWED
: Client not authenticated [5006] or resource missing ACCESS_USE
[5007], exhausted [50A0], expired [50B1], not configured for USAGE_TRANSFORM
[5030] or a policy failed [500B].NOT_SUPPORTED
: Padding [8011] or cipher algorithm [8012] not supported.void init(byte decryptKeyId, short encryptKeyId, byte[] initializationData, short initializationDataDecryptOff, short initializationDataEncryptOff, short initializationDataEncryptLen)
Method Behavior:
This method initializes the service for subsequent use with the update(..)
and/or doFinal(..)
methods
using the key parameters, cipher and padding algorithms configured to the provided resource, along with the cipher
initialization data provided.
The method handles access control, counters, timers and events according to Section 6.3.3 of GlobalPlatform Amendment N.
Usage Guidelines:
CSPSensitiveArrays
for the initialization data.decryptKeyId
- Decryption key.encryptKeyId
- Encryption key.initializationData
- Algorithm-specific initialization data, e.g., initialization vector (iv).initializationDataDecryptOff
- Offset in the buffer to start reading the initialization data.initializationDataEncryptOff
- Length of the initialization data for the decryption key.initializationDataEncryptLen
- Length of the initialization data for the encryption key.CSPException
- with reason:
ILLEGAL_BUFFER
: Illegal input buffer [1002], [1004], [1005], [1006], [1007].ILLEGAL_VALUE
: A resource ID does not exist [2001], is not a KEY
[2011] or initialization data is invalid [2012], [2013].ILLEGAL_CONFIG
: CSP not activated [3001], a resource not initialized [3003], inconsistent cipher configuration [3010] or inconsistent policy config [3009].NOT_ALLOWED
: Client not authenticated [5006] or resource missing ACCESS_USE
[5007], exhausted [50A0], expired [50B1], not configured for USAGE_TRANSFORM
[5030] or a policy failed [500B].NOT_SUPPORTED
: Padding [8011] or cipher algorithm [8012] not supported.short update(byte[] inBuffer, short inOffset, short inLength, byte[] outBuffer, short outOffset)
Method Behavior:
This method processes a data chunk for multipart encryption transformation when the full dataset isn't available in one array. It transforms the encryption without finalizing this process.
Incomplete blocks are stored for processing in the next update(..)
or doFinal(..)
call.
For input buffer length 0
this method does nothing.
The method handles access control, counters and events according to Section 6.3.3 of GlobalPlatform Amendment N.
Usage Guidelines:
assertSensitiveResult(..)
.init(..)
before calling this method.doFinal(..)
after one or more update(..)
calls.update(..)
if all data fits in a single byte array; use doFinal(..)
instead.inBuffer
- Input data to be transformed.inOffset
- Offset in the input buffer to start reading.inLength
- Length of the input data in bytes, can be 0
.outBuffer
- Output buffer for storing the result.outOffset
- Offset in the output buffer where the result should be written.CSPException
- with reason:
ILLEGAL_BUFFER
: Illegal input or output buffer [1001], [1003], [1004], [1005], [1006], [1007].ILLEGAL_CONFIG
: CSP not activated [3001], missing resource [3002] or resource not initialized [3003].INVALID_INIT
: Service not initialized [4030].NOT_ALLOWED
: Resource exhausted [50A0].ILLEGAL_USE
: Invalid input data [6012], [6013], [6015] or counter capacity reached [60A2].init(..)
,
doFinal(..)
short doFinal(byte[] inBuffer, short inOffset, short inLength, byte[] outBuffer, short outOffset)
Method Behavior:
This method transforms the encryption of the input data based on the last init(..)
call
and finalizes the transformation process.
After completion, the service requires a new init(..)
call to prepare for the next operation.
If update(..)
was previously invoked, it processes any buffered data before handling the new data provided.
The method handles access control, counters and events according to Section 6.3.3 of GlobalPlatform Amendment N.
Usage Guidelines:
assertSensitiveResult(..)
.init(..)
before calling this method.update(..)
as needed before finalizing with this method.inBuffer
- Input data to be transformed.inOffset
- Offset in the input buffer to start reading.inLength
- Length of the input data in bytes.outBuffer
- Output buffer for storing the result.outOffset
- Offset in the output buffer where the result should be written.CSPException
- with reason:
ILLEGAL_BUFFER
: Illegal input or output buffer [1001], [1002], [1004], [1005], [1006], [1007].ILLEGAL_CONFIG
: CSP not activated [3001], missing resource [3002] or resource not initialized [3003].INVALID_INIT
: Service not initialized [4030].NOT_ALLOWED
: Resource exhausted [50A0].ILLEGAL_USE
: Invalid input data [6010], [6011], [6012], [6013], [6014], [6015], [6016] or counter capacity reached [60A2].init(..)
,
update(..)
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.