public interface CipherService extends CSPService
Provides services to encrypt and decrypt data.
init(..)
method initializes the service with a mode and resource.doFinal(..)
method in MODE_ENCRYPT
encrypts data.doFinal(..)
method in MODE_DECRYPT
decrypts data.update(..)
method processes multiple data chunks for encryption or decryption.init(nonce,..)
, updateAAD(..)
, retrieveTag(..)
and verifyTag(..)
methods process Authenticated Encryption with Associated Data (AEAD).
Cipher algorithms must be pre-configured by the CSP Admin and cannot be selected via the CSP-API.
Supported algorithms are defined in Section 6.1.1 of GlobalPlatform Amendment N [GPC_SPE_230] and may include:
Cipher Algorithm | Padding Algorithm | Key Type | Min Key Size (bits) | Initialization Data |
---|---|---|---|---|
CIPHER_AES_CBC | PAD_NOPAD | KEY_AES | 128 | Requires unpredictable 128-bit initialization vector. |
CIPHER_AES_CFB | PAD_NULL | KEY_AES | 128 | Requires unpredictable 128-bit initialization vector. |
CIPHER_AES_CTR | PAD_NULL | KEY_AES | 128 | Requires 64 to 128-bit nonce |
CIPHER_AES_GCM | PAD_NULL | KEY_AES | 128 | Requires 94-bit nonce; optional AEAD support. |
CIPHER_AES_CCM | PAD_NULL | KEY_AES | 128 | Requires 7 to 13-byte nonce; optional AEAD support |
CIPHER_AES_XTS | PAD_NULL | KEY_AES | 256 (2x 128) | Requires 128-bit tweak. |
CIPHER_RSA | PAD_PKCS1_OAEP (SHA2, SHA3) | KEY_RSA_* | 2048 | Requires padding-specific data equal to the hash output size (e.g., 256 bit for SHA-256). |
The key resource 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 128 bit key and generate its key value. CSPCreateResource(AES_KEY_ID, KEY_AES, 128) CSPGenerateKey(AES_KEY_ID) // Create a private RSA 4096 bit key and import it. CSPCreateResource(RSA_KEY_ID, KEY_RSA_PRIVATE, 4096) CSPCreateResource(RSA_KEY_ID_PUBLIC, KEY_RSA_PUBLIC, 4096) CSPSetValue(RSA_KEY_ID, data) CSPComputePublicKey(RSA_KEY_ID, RSA_KEY_ID_PUBLIC) // Configure access control. CSPConfigureResource(AES_KEY_ID, ACR_USE) CSPConfigureResource(RSA_KEY_ID, ACR_USE) CSPConfigureResource(RSA_KEY_ID_PUBLIC, ACR_USE) // Configure maximum usage limitation 100,000 for the AES key. CSPConfigureResource(AES_KEY_ID, usageLimit=100000) // Configure usage and algorithms. CSPConfigureResource(AES_KEY_ID, USAGE_CIPHER, CIPHER_AES_GCM) CSPConfigureResource(RSA_KEY_ID, USAGE_CIPHER, CIPHER_RSA, PAD_PKCS1_OAEP)
Sample code for using the CipherService
:
// 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. CipherService cipherService1 = csp.makeCipherService(); CipherService cipherService2 = csp.makeCipherService(); switch (ins) { // Data encryption sample. case ENCRYPT_INIT: cipherService1.init(CipherService.MODE_ENCRYPT, AES_KEY_ID); encryptedOffset = 0; break; case ENCRYPT_UPDATE: len = cipherService1.update(input, (short) 0, (short) encryptedData.length, encryptedOffset, encryptedOffset); SensitiveArrays.assertIntegrity(input); cipherService1.assertSensitiveResult(len); encryptedOffset += len; // Process the encrypted data ... SensitiveArrays.assertIntegrity(encryptedData); break; case ENCRYPT_DOFINAL: len = cipherService1.doFinal(input, (short) 0, (short) encryptedData.length, encryptedOffset, encryptedOffset); SensitiveArrays.assertIntegrity(input); cipherService1.assertSensitiveResult(len); encryptedOffset += len; // Process the encrypted data ... SensitiveArrays.assertIntegrity(encryptedData); break; // Data decryption sample. case DECRYPT_INIT: cipherService2.init(CipherService.MODE_DECRYPT, RSA_KEY_ID); decryptedOffset = 0; break; case DECRYPT_UPDATE: len = cipherService2.update(input, (short) 0, (short) data.length, decryptedData, decryptedOffset); SensitiveArrays.assertIntegrity(decryptedData); cipherService2.assertSensitiveResult(len); decryptedOffset += len; // Process the decrypted data ... SensitiveArrays.assertIntegrity(decryptedData); break; case DECRYPT_DOFINAL: len = cipherService2.doFinal(input, (short) 0, (short) data.length, decryptedData, decryptedOffset); SensitiveArrays.assertIntegrity(decryptedData); cipherService2.assertSensitiveResult(len); decryptedOffset += len; // Process the decrypted data ... SensitiveArrays.assertIntegrity(decryptedData); break; }
Modifier and Type | Field and Description |
---|---|
static byte |
MODE_DECRYPT
Sets the service to decryption mode.
|
static byte |
MODE_ENCRYPT
Sets the service to encryption mode.
|
RESULT_FALSE, RESULT_TRUE
Modifier and Type | Method and Description |
---|---|
short |
doFinal(byte[] inBuffer,
short inOffset,
short inLength,
byte[] outBuffer,
short outOffset)
Encrypt or decrypt data, depending on the mode set.
|
void |
init(byte mode,
short keyResourceId)
Initialize service for either encryption or decryption.
|
void |
init(byte mode,
short keyResourceId,
byte[] initializationData,
short initializationDataOffset,
short initializationDataLength)
Initialize service for either encryption or decryption using algorithm-specific initialization data (e.g., iv data).
|
void |
init(byte mode,
short keyResourceId,
byte[] nonce,
short nonceOffset,
short nonceLength,
short aadLength,
short messageLength,
short tagSize)
Initialize service for either encryption or decryption using Authenticated Encryption with Associated Data (AEAD) cipher parameters.
|
short |
retrieveTag(byte[] outBuffer,
short outOffset,
short outLength)
Retrieves the authentication tag for AEAD cipher.
|
short |
update(byte[] inBuffer,
short inOffset,
short inLength,
byte[] outBuffer,
short outOffset)
Multipart encryption or decryption, depending on the mode set.
|
void |
updateAAD(byte[] aadBuffer,
short aadOffset,
short aadLength)
Multipart update of the Additional Associated Data (AAD) for AEAD cipher.
|
short |
verifyTag(byte[] tagBuffer,
short tagOffset,
short tagLength)
Verifies the provided authentication tag.
|
assertSensitiveResult
static final byte MODE_DECRYPT
In this mode, the update(..)
and doFinal(..)
methods will decrypt data.
init(..)
,
Constant Field Valuesstatic final byte MODE_ENCRYPT
In this mode, the update(..)
and doFinal(..)
methods will encrypt data.
init(..)
,
Constant Field Valuesvoid init(byte mode, short keyResourceId)
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.
The method handles access control, counters, timers and events according to Section 6.1.3 of GlobalPlatform Amendment N.
mode
- DECRYPT
or ENCRYPT
.keyResourceId
- Key resource.CSPException
- with reason:
ILLEGAL_VALUE
: Unknown mode [2010], 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].INVALID_INIT
: Offline cipher, requiring AAD [4011].NOT_ALLOWED
: Client not authenticated [5006] or resource missing ACCESS_USE
[5007], exhausted [50A0], expired [50B1], not configured for USAGE_CIPHER
[5010] or a policy failed [500B].NOT_SUPPORTED
: Padding [8011] or cipher algorithm [8012] not supported.init(..)
,
update(..)
,
doFinal(..)
void init(byte mode, short keyResourceId, byte[] initializationData, short initializationDataOffset, short initializationDataLength)
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.1.3 of GlobalPlatform Amendment N.
Usage Guidelines:
CSPSensitiveArrays
for the initialization data.mode
- DECRYPT
or ENCRYPT
.keyResourceId
- Key resource.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 [2010], resource ID does not exist [2001], is not a KEY
[2011] or initialization data is invalid [2012], [2013].ILLEGAL_CONFIG
: CSP not activated [3001], resource not initialized [3003], inconsistent cipher configuration [3010] or inconsistent policy config [3009].INVALID_INIT
: Offline cipher, requiring AAD [4011].NOT_ALLOWED
: Client not authenticated [5006] or resource missing ACCESS_USE
[5007], exhausted [50A0], expired [50B1], not configured for USAGE_CIPHER
[5010] or a policy failed [500B].NOT_SUPPORTED
: Padding [8011] or cipher algorithm [8012] not supported.init(..)
,
update(..)
,
doFinal(..)
void init(byte mode, short keyResourceId, byte[] nonce, short nonceOffset, short nonceLength, short aadLength, short messageLength, short tagSize)
Available for
CIPHER_AES_GCM
CIPHER_AES_CCM
Method Behavior:
This method initializes the service for subsequent use with the updateAAD(..)
, update(..)
and/or doFinal(..)
methods,
using the key parameters, cipher and padding algorithms configured to the provided resource, along with nonce and additional data lengths,
allowing for Authenticated Encryption with Associated Data (AEAD).
The method handles access control, counters, timers and events according to Section 6.1.3 of GlobalPlatform Amendment N.
mode
- DECRYPT
or ENCRYPT
.keyResourceId
- Key resource.nonce
- Buffer containing the nonce.nonceOffset
- Offset in the nonce buffer to start reading.nonceLength
- Length of the nonce data in bytes.aadLength
- Total Additional Associated Data (AAD) length in bytes to be passed to updateAAD(..)
.messageLength
- Total message length (plaintext or ciphertext) in bytes, as sum of lengths to be passed to update(..)
and doFinal(..)
.tagSize
- Authentication tag length in bytes.CSPException
- with reason:
ILLEGAL_BUFFER
: Illegal input buffer [1002], [1004], [1005], [1006], [1007].ILLEGAL_VALUE
: Unknown mode [2010], resource ID does not exist [2001], is not a KEY
[2011] or initialization data is invalid [2012], [2013].ILLEGAL_CONFIG
: CSP not activated [3001], resource not initialized [3003], inconsistent cipher configuration [3010] or inconsistent policy config [3009].INVALID_INIT
: Online cipher, not supporting AAD [4012].NOT_ALLOWED
: Client not authenticated [5006] or resource missing ACCESS_USE
[5007], exhausted [50A0], expired [50B1], not configured for USAGE_CIPHER
[5010] or a policy failed [500B].NOT_SUPPORTED
: Padding [8011] or cipher algorithm [8012] not supported.updateAAD(..)
,
update(..)
,
doFinal(..)
void updateAAD(byte[] aadBuffer, short aadOffset, short aadLength)
Method Behavior:
This method continues updating the AAD to be verified with the authentication tag.
Usage Guidelines:
CSPSensitiveArrays
for the AAD input buffer.update(..)
and doFinal(..)
to ensure the AAD is processed correctly.aadBuffer
- Buffer containing the Additional Associated Data (AAD).aadOffset
- Offset in the AAD buffer to start reading.aadLength
- Length of the AAD data in bytes.CSPException
- with reason:
ILLEGAL_BUFFER
: Illegal input buffer [1002], [1004], [1005], [1006], [1007].INVALID_INIT
: Size different to total AAD length [2015].ILLEGAL_USE
: Illegal cipher state [6018].init(..)
short retrieveTag(byte[] outBuffer, short outOffset, short outLength)
Method Behavior:
This method writes the calculated authentication tag of the requested length to the output buffer.
Usage Guidelines:
CSPSensitiveArrays
for the output buffer and invoke assertIntegrity(..)
after processing it.assertSensitiveResult(..)
.MODE_ENCRYPT
after doFinal(..)
.outBuffer
- Buffer to store the authentication tag.outOffset
- Offset in the output buffer where the result should be written.outLength
- Length of the tag to retrieve.CSPException
- with reason:
ILLEGAL_BUFFER
: Illegal output buffer [1001], [1004], [1005], [1006], [1007].ILLEGAL_VALUE
: Unsupported tag length [2014].ILLEGAL_USE
: doFinal
not yet called [6017].short verifyTag(byte[] tagBuffer, short tagOffset, short tagLength)
Method Behavior:
This method compares the provided tag against the internally calculated tag.
Usage Guidelines:
CSPSensitiveArrays
for the tag data.assertSensitiveResult(..)
.MODE_DECRYPT
after doFinal(..)
.Editor's Note: Instead of returning the result of the verification, we could throw an error when verification fails.
tagBuffer
- Buffer containing the tag to verify.tagOffset
- Offset in the tag buffer to start reading.tagLength
- Length of the tag in bytes.TRUE
if tag is verified successfully, FALSE
otherwise.CSPException
- with reason:
ILLEGAL_BUFFER
: Illegal input buffer [1002], [1004], [1005], [1006], [1007].ILLEGAL_VALUE
: Unsupported tag length [2014].ILLEGAL_USE
: doFinal
not yet called [6017].short update(byte[] inBuffer, short inOffset, short inLength, byte[] outBuffer, short outOffset)
Method Behavior:
This method processes a data chunk for multipart encryption or decryption when the full dataset isn't available in one array.
Based on the mode from the last init(..)
call, it encrypts or decrypts the data 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.1.3 of GlobalPlatform Amendment N.
Usage Guidelines:
CSPSensitiveArrays
for the input data.CSPSensitiveArrays
for the output buffer and invoke assertIntegrity(..)
after processing it.assertSensitiveResult(..)
in MODE_DECRYPT
.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 encrypted or decrypted.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 [4010].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 performs the cipher operation on the input data and resets the service.
It encrypts or decrypts based on the last init(..)
call and finalizes the cipher 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.1.3 of GlobalPlatform Amendment N.
Usage Guidelines:
CSPSensitiveArrays
for the input data.CSPSensitiveArrays
for the output buffer and invoke assertIntegrity(..)
after processing it.assertSensitiveResult(..)
in MODE_DECRYPT
.init(..)
before calling this method.update(..)
as needed before finalizing with this method.inBuffer
- Input data to be encrypted or decrypted.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 [4010].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.