public interface ConfidentialDataTransferService extends SecureChannelService
Extends SecureChannelService
to provide confidential data transfer services,
converting session encryption to storage-layer encryption and vice versa.
SecureChannelService
is also supported by this service.confidentialWrap(..)
method converts storage encryption to session encryption.confidentialUnwrap(..)
method converts session encryption to storage encryption.updateConfidentialWrap(..)
updateConfidentialUnwrap(..)
methods process multiple data chunks for confidential wrapping and unwrapping.Cipher and secure messaging algorithms must be pre-configured by the CSP Admin and cannot be selected via the CSP-API. Supported algorithms include:
SecureChannelService
for session encryption.CipherService
for storage encryption.
The key, certificate and password resources must be configured by the CSP Admin. Their resource identifiers,
assigned during creation, must then be used to initialize the service via the init(..)
method.
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.
// Configure PACE PIN, TA Certificate and CA Key. CSPCreateResource(PACE_PIN_ID, PASSWORD_NUMERIC, minSize=5, maxSize=5) CSPCreateResource(TA_AT_CERT_ID, CERT_CVC) CSPCreateResource(CA2_KEY_ID, KEY_ECC_PRIVATE, CURVE_BRAINPOOL_P256_R1) CSPSetValue(PACE_PIN_ID, data) CSPSetValue(TA_AT_CERT_ID, data) CSPGenerateKey(CA2_KEY_ID) // Generate storage-layer encryption key. CSPCreateResource(STORAGE_KEY, KEY_AES, 256) CSPGenerateKey(STORAGE_KEY) // Configure access control. CSPConfigureResource(PACE_PIN_ID, ACR_USE & ACR_SETUP) CSPConfigureResource(TA_AT_CERT_ID, ACR_CLEAR & ACR_SETUP & ACR_USE) CSPConfigureResource(CA2_KEY_ID, ACR_USE) CSPConfigureResource(STORAGE_KEY, ACR_USE) // Configure usage and algorithms. CSPConfigureResource(PACE_PIN_ID, USAGE_SECCHANNEL, SEC_PACE) CSPConfigureResource(TA_AT_CERT_ID, USAGE_SECCHANNEL, SEC_TA2) CSPConfigureResource(CA2_KEY_ID, USAGE_SECCHANNEL, SEC_CA2) CSPConfigureResource(STORAGE_KEY, USAGE_CONFIDENTIAL, CIPHER_AES_GCM)
Sample code for using the ConfidentialDataTransferService
:
// 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. ConfidentialDataTransferService confidentialService = csp.makeConfidentialDataTransferService(SecureChannelService.PROTOCOL_EAC_ID); confidentialService.init(PACE_PIN_ID); confidentialService.init(TA_AT_CERT_ID); confidentialService.init(CA2_KEY_ID); confidentialService.init(STORAGE_KEY_ID); switch (ins) { // Process PACE, TA2 & CA2 authentication. case INS_AUTHENTICATE: // Remove session encryption from incoming APDU. confidentialService.initUnwrap(); apduLen = confidentialService.unwrap(inputBuffer, (short) 0, inputLen, apduData, (short) 0); confidentialService.assertSensitiveResult(apduLen); // Process the authentication and create the response APDU. responseLen = confidentialService.processSecurity(apduData, (short) 0, apduLen, responseAPDU, (short) 0); // Add session encryption to the response APDU. outputLen = confidentialService.initWrap(responseLen); confidentialService.wrap(responseAPDU, (short) 0, responseLen, outputBuffer, (short) 0); confidentialService.assertSensitiveResult(outputLen); break; // Reset the secure channel session. case INS_TERMINATE: confidentialService.resetSecurity(); break; // Import confidential data securely. case INS_IMPORT_DATA: // Convert incoming data: remove session encryption and apply storage encryption for long-term storing. confidentialService.initConfidentialUnwrap(); confidentialLen = confidentialService.confidentialUnwrap(inputBuffer, (short) 0, inputLen, confidentialData, (short) 0); confidentialService.assertSensitiveResult(confidentialLen); // Optionally store the confidential data locally. // storeData(confidentialData, (short) 0, confidentialLen); // Alternatively, store it externally by adding session encryption on top of storage encryption to send it back. outputLen = confidentialService.initWrap(confidentialLen); confidentialService.wrap(confidentialData, (short) 0, confidentialLen, outputBuffer, (short) 0); confidentialService.assertSensitiveResult(outputLen); break; // Export confidential data securely. case INS_EXPORT_DATA: // Optionally retrieve the confidential data from local storage. // confidentialLen = readData(confidentialData, (short) 0); // Alternatively, receive storage-encrypted data from the external source and remove session encryption. confidentialService.initUnwrap(); confidentialLen = confidentialService.unwrap(inputBuffer, (short) 0, inputLen, confidentialData, (short) 0); confidentialService.assertSensitiveResult(confidentialLen); // Convert confidential data: remove storage encryption and add session encryption for secure transmission. outputLen = confidentialService.initConfidentialWrap(confidentialLen); confidentialService.confidentialWrap(confidentialData, (short) 0, confidentialLen, outputBuffer, (short) 0); confidentialService.assertSensitiveResult(outputLen); break; }
CipherService
,
TransformService
PROTOCOL_EAC_ID, PROTOCOL_EAC_MRTD, PROTOCOL_PACE, PROTOCOL_PACE_CAM, PROTOCOL_SCP03, PROTOCOL_SCP04
RESULT_FALSE, RESULT_TRUE
Modifier and Type | Method and Description |
---|---|
short |
confidentialUnwrap(byte[] inBuffer,
short inOffset,
short inLength,
byte[] outBuffer,
short outOffset)
Transfer data from session to storage-layer encryption.
|
short |
confidentialWrap(byte[] inBuffer,
short inOffset,
short inLength,
byte[] outBuffer,
short outOffset)
Transfer data from storage-layer to session encryption.
|
void |
init(short resourceId)
Initialize service with the the key for storage encryption or cryptographic resources required by the protocol.
|
void |
init(short resourceId,
byte[] initializationData,
short initializationDataOffset,
short initializationDataLength)
Initialize service with the key for storage encryption and algorithm-specific initialization data (e.g., iv data).
|
void |
initConfidentialUnwrap()
Prepare the service to transfer data from session to storage-layer encryption.
|
short |
initConfidentialWrap(short dataLength)
Prepare the service to transfer data from storage-layer encryption to session encryption.
|
short |
updateConfidentialUnwrap(byte[] inBuffer,
short inOffset,
short inLength,
byte[] outBuffer,
short outOffset)
Multipart transformation from session to storage-layer encryption.
|
short |
updateConfidentialWrap(byte[] inBuffer,
short inOffset,
short inLength,
byte[] outBuffer,
short outOffset)
Multipart transformation from storage-layer to session encryption.
|
getSecurityState, initUnwrap, initWrap, processSecurity, resetSecurity, unwrap, updateUnwrap, updateWrap, wrap
assertSensitiveResult
void init(short resourceId)
Method Behavior:
This method initializes this service using the parameters and algorithms configured to the provided resource.
If a resource for a specific algorithm is re-provided, it replaces the previous one.
The method handles access control and events according to Section 6.5.3 of GlobalPlatform Amendment N.
Usage Guidelines:
init
in interface SecureChannelService
resourceId
- Resource with USAGE_CONFIDENTIAL
as storage key or USAGE_SECCHANNEL
required by the protocol.CSPException
- with reason:
ILLEGAL_VALUE
: Resource ID does not exist [2001].ILLEGAL_CONFIG
: CSP not activated [3001], storage-key is not initialized [3003] or has inconsistent cipher configuration [3010].NOT_ALLOWED
: Client not authenticated [5006] or resource missing ACCESS_USE
[5007], protocol resource is not configured for USAGE_CONFIDENTIAL
[5050]. storage key is exhausted [50A0], expired [50B1] or not configured for USAGE_CONFIDENTIAL
[5050].NOT_SUPPORTED
: Padding [8011] or cipher algorithm [8012] not supported.processSecurity(..)
void init(short resourceId, byte[] initializationData, short initializationDataOffset, short initializationDataLength)
Method Behavior:
This method initializes the service with the key storage encryption for subsequent use with
initConfidentialWrap(..)
or initConfidentialUnwrap(..)
using the key parameters, cipher and padding algorithms configured to the provided resource, along with the cipher
initialization data provided.
If a resource for a specific algorithm is re-provided, it replaces the previous one.
The method handles access control and events according to Section 6.5.3 of GlobalPlatform Amendment N.
resourceId
- Resource with USAGE_CONFIDENTIAL
as storage key.initializationData
- Cipher-specific initialization data for the storage encryption, 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
: 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].NOT_ALLOWED
: Client not authenticated [5006] or resource missing ACCESS_USE
[5007], exhausted [50A0], expired [50B1] or not configured for USAGE_CONFIDENTIAL
[5050].NOT_SUPPORTED
: Padding [8011] or cipher algorithm [8012] not supported.processSecurity(..)
short initConfidentialWrap(short dataLength)
Method Behavior:
This method sets the service to confidential-wrapping mode.If already in unwrapping or confidential-unwrapping mode, it switches to confidential-wrapping mode without error.
The method handles access control, timers, counters, secure channel timeout and events according to Section 6.5.3 of GlobalPlatform Amendment N.
dataLength
- Length of the data to be transferred; can be 0
.CSPException
- with reason:
INVALID_INIT
: Wrapping mode active [4043], unwrapping mode active [4044], confidential-unwrapping mode active [4054] or no session keys established [4054].NOT_ALLOWED
: A policy failed [500B]confidentialWrap(..)
,
updateConfidentialWrap(..)
,
processSecurity(..)
short updateConfidentialWrap(byte[] inBuffer, short inOffset, short inLength, byte[] outBuffer, short outOffset)
Method Behavior:
This method processes a data chunk for multipart storage-layer decryption using the storage key set through init(..)
and session-layer re-encryption when the full dataset isn't available in one array.
Incomplete blocks are stored for processing in the next updateConfidentialWrap(..)
or confidentialWrap(..)
call.
For input buffer length 0
, this method does nothing.
The method handles access control and events according to Section 6.5.3 of GlobalPlatform Amendment N.
Usage Guidelines:
assertSensitiveResult(..)
.processSecurity(..)
before calling this method.init(..)
before calling this method.initConfidentialWrap(..)
before calling this method.confidentialWrap(..)
after one or more updateConfidentialWrap(..)
calls.confidentialWrap(..)
if all data fits in one array.inBuffer
- Input message to be decrypted and wrapped.inOffset
- Offset in the input buffer to start reading.inLength
- Length of the input message in bytes.outBuffer
- Output buffer for storing the wrapped message.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].INVALID_INIT
: Confidential wrapping not initialized [4051] or no session keys established [4054].ILLEGAL_USE
: Counter capacity reached [60A2]short confidentialWrap(byte[] inBuffer, short inOffset, short inLength, byte[] outBuffer, short outOffset)
Method Behavior:
This method removes the storage-layer encryption using the storage key set through init(..)
and adds the session encryption.
If updateConfidentialWrap(..)
was previously invoked, it processes any buffered data before handling the new data provided.
The method handles access control and events according to Section 6.5.3 of GlobalPlatform Amendment N.
Usage Guidelines:
assertSensitiveResult(..)
.processSecurity(..)
before calling this method.init(..)
before calling this method.initConfidentialWrap(..)
before calling this method.updateConfidentialWrap(..)
as needed before finalizing with this method.inBuffer
- Input message to be decrypted and wrapped.inOffset
- Offset in the input buffer to start reading.inLength
- Length of the input message in bytes.outBuffer
- Output buffer for storing the wrapped message.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].INVALID_INIT
: Confidential wrapping not initialized [4051] or no session keys established [4054].ILLEGAL_USE
: Counter capacity reached [60A2]void initConfidentialUnwrap()
Method Behavior:
This method sets the service to confidential-unwrapping mode.If already in unwrapping mode, it switches to confidential-wrapping mode without error.
The method handles access control, timers, counters, secure channel timeout and events according to Section 6.5.3 of GlobalPlatform Amendment N.
CSPException
- with reason:
INVALID_INIT
: Wrapping mode active [4043], unwrapping mode active [4044], confidential-wrapping mode active [4053] or no session keys established [4054].NOT_ALLOWED
: A policy failed [500B]confidentialUnwrap(..)
,
updateConfidentialUnwrap(..)
,
processSecurity(..)
short updateConfidentialUnwrap(byte[] inBuffer, short inOffset, short inLength, byte[] outBuffer, short outOffset)
Method Behavior:
This method processes a data chunk for multipart session decryption and storage-layer re-encryption when the full dataset isn't available in one array,
using storage key set through init(..)
.
Incomplete blocks are stored for processing in the next updateConfidentialUnwrap(..)
or confidentialUnwrap(..)
call.
For input buffer length 0
, this method does nothing.
The method handles access control and events according to Section 6.5.3 of GlobalPlatform Amendment N.
Usage Guidelines:
assertSensitiveResult(..)
.processSecurity(..)
before calling this method.init(..)
before calling this method.initConfidentialUnwrap(..)
before calling this method.inBuffer
- Input message to be unwrapped and encrypted.inOffset
- Offset in the input buffer to start reading.inLength
- Length of the input message in bytes.outBuffer
- Output buffer for storing the wrapped message.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].INVALID_INIT
: Confidential unwrapping not initialized [4052] or no session keys established [4054].ILLEGAL_USE
: Counter capacity reached [60A2]short confidentialUnwrap(byte[] inBuffer, short inOffset, short inLength, byte[] outBuffer, short outOffset)
Method Behavior:
This method removes session encryption from the input data using session keys and re-encrypts the data using the
storage key set through init(..)
.
If updateConfidentialUnwrap(..)
was previously invoked, it processes any buffered data before handling the new data provided.
The method handles access control and events according to Section 6.5.3 of GlobalPlatform Amendment N.
Usage Guidelines:
assertSensitiveResult(..)
.processSecurity(..)
before calling this method.init(..)
before calling this method.initConfidentialUnwrap(..)
before calling this method.updateConfidentialUnwrap(..)
as needed before finalizing with this method.inBuffer
- Input message to be unwrapped and encrypted.inOffset
- Offset in the input buffer to start reading.inLength
- Length of the input message in bytes.outBuffer
- Output buffer for storing the wrapped message.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].INVALID_INIT
: Confidential unwrapping not initialized [4052] or no session keys established [4054].ILLEGAL_USE
: Counter capacity reached [60A2]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.