public class CSPSensitiveArrays extends Object
makeIntegritySensitiveArrayView(..)
method
adds integrity protection to an existing array and creates an array view that can be shared with the CSP.
The CSP verifies the integrity of sensitive data exchanged in byte buffers between the Client Application and the CSP.
Therefore, the CSP will throw a CSPException
if:
assertIntegrity(..)
on the provided arrays fails [1007].
In Java Card 3.1, SensitiveArrays
combined with
javacard.framework.JCSystem.makeArrayView(..)
can be used
to create integrity-protected arrays and make them accessible to the CSP.
For older Java Card versions, or when the APDU
buffer shall be used
to exchange data with the CSP, the makeIntegritySensitiveArrayView(..)
method
must be used to create integrity-protected array views for these existing array objects before they can be shared with the CSP.
The CSP invokes SensitiveArrays.assertIntegrity(..)
on the input and output buffers used in the operations listed below.
Note: Although the CSP performs the integrity check, Client Applications are advised to additionally invoke
assertIntegrity(..)
after processing sensitive data received from the CSP.
Operation | Mode | Parameter | Description |
---|---|---|---|
CipherService.init | - | Input buffer | Algorithm-specific initialization data. |
CipherService.updateAAD | - | Input buffer | Input buffer containing the Additional Associated Data (AAD). |
CipherService.retrieveTag | ENCRYPT | Output buffer | Computed authentication tag. |
CipherService.verifyTag | DECRYPT | Input buffer | Authentication tag to verify. |
CipherService.update | - | Input buffer | Data block to encrypt or decrypt (multi-part). |
CipherService.update | - | Output buffer | The decrypted or encrypted data block (multi-part). |
CipherService.doFinal | - | Input buffer | Data to encrypt or decrypt. |
CipherService.doFinal | - | Output buffer | The decrypted or encrypted data. |
SignatureService.init | - | Input buffer | Algorithm-specific initialization data. |
SignatureService.update | - | Input buffer | Data block to sign or verify (multi-part). |
SignatureService.sign | SIGN | Input buffer | Final data to sign. |
SignatureService.sign | SIGN | Output buffer | The computed signature. |
SignatureService.signPreComputedHash | SIGN | Input buffer | Final data to sign. |
SignatureService.signPreComputedHash | SIGN | Output buffer | The computed signature. |
SignatureService.verify | MODE_VERIFY | Input buffer | The data to verify. |
SignatureService.verify | MODE_VERIFY | Input buffer | The signature. |
SignatureService.verifyPreComputedHash | MODE_VERIFY | Input buffer | The data to verify. |
SignatureService.verifyPreComputedHash | MODE_VERIFY | Input buffer | The signature. |
TransformService.init | - | Input buffer | Algorithm-specific initialization data. |
SecureChannelService.processSecurity | - | APDU input buffer | Input APDU buffer. |
SecureChannelService.processSecurity | - | APDU output buffer | Output APDU buffer. |
SecureChannelService.updateWrap | - | Data input buffer | Data to add session encryption (multi-part). |
SecureChannelService.updateUnwrap | - | Data output buffer | Decrypted data (multi-part). |
SecureChannelService.wrap | - | Data input buffer | Final data to add session encryption. |
SecureChannelService.unwrap | - | Data output buffer | Final decrypted data. |
AttestationService.updateInputData | - | Input data | Additional data, challenge or nonce to include in the attestation result. |
AttestationService.update | - | Output buffer | The attestation data computed by the CSP (multi-part). |
AttestationService.computeAttestation | - | Output buffer | The attestation data computed by the CSP. |
KeyService.updateManage | IMPORT | Input buffer | New public key value (multi-part). |
KeyService.updateManage | EXPORT | Output buffer | The exported public key value (multi-part). |
KeyService.manage | IMPORT | Input buffer | New public key value. |
KeyService.manage | EXPORT | Output buffer | The exported public key value. |
KeyService.derive | - | Input buffer | Key derivation data. |
CertificateService.updateManage | IMPORT | Input buffer | New certificate (multi-part). |
CertificateService.updateManage | EXPORT | Output buffer | The received certificate (multi-part). |
CertificateService.manage | IMPORT | Input buffer | New certificate. |
CertificateService.manage | EXPORT | Output buffer | The received certificate. |
CertificateService.getValidityDate | - | Output buffer | The returned validity date. |
PasswordService.check | - | Input buffer | The password to check. |
PasswordService.update | - | Input buffer | New password value. |
PasswordService.resetAndUnblock | - | Input buffer | New password value. |
CounterService.getValue | - | Output buffer | Retrieved counter value. |
CounterService.getRemaining | - | Output buffer | Retrieved remaining counter value. |
CounterService.getLimit | - | Output buffer | Retrieved counter limit. |
TimeService.getValue | - | Output buffer | The retrieved timer value. |
TimeService.setReferenceTime | - | Input buffer | New reference time. |
TimeService.setReferenceTime | - | Input buffer | Signature of the reference time. |
TimeService.getChallenge | - | Output buffer | The challenge used for timestamp signature verification. |
AuditService.dequeueEvent | - | Input data | Additional data for log message. |
AuditService.dequeueEvent | - | Output buffer | The generated log message. |
OffloadingService.initManage | - | Input buffer | Algorithm-specific initialization data. |
RandomDataService.nextBytes | - | Output buffer | The generated random data. |
Sample code for using the CSPSensitiveArrays
:
// 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); // Integrity protection using CSPSensitiveArrays. { // Add integrity-protection to an existing buffer (e.g., APDU buffer or local buffer). sensitiveArray = CSPSensitiveArrays.makeIntegritySensitiveArrayView(apduBuffer, (short) 0, (short) 255, csp); // Use the buffer (the CSP will perform the integrity check). SignatureService signatureService = csp.makeSignatureService(); signatureService.init(SIG_KEY_ID, SignatureService.MODE_SIGN); outputLength = signatureService.sign(sensitiveArray, (short) 0, (short) 50, sensitiveArray, (short) 50); // Process the computed signature ... // Additionally, perform an integrity check after processing the result. SensitiveArrays.assertIntegrity(sensitiveArray); } // Alternative: Integrity protection using javacard.framework.SensitiveArrays and ArrayViews. { // Create sensitive array with integrity-protection and copy the input data to it. sensitiveArray = (byte[]) SensitiveArrays.makeIntegritySensitiveArray(JCSystem.ARRAY_TYPE_SHORT, JCSystem.MEMORY_TYPE_TRANSIENT_DESELECT, (short) 100); Util.arrayCopy(apduBuffer, (short) 0, sensitiveArray, (short) 0, (short) 50); // Create shareable views of this sensitive array. byte[] inputData = JCSystem.makeArrayView(sensitiveArray, (short) 0, (short) 50, JCSystem.ATTR_READABLE_VIEW, csp); byte[] outputData = JCSystem.makeArrayView(sensitiveArray, (short) 50, (short) 100, JCSystem.ATTR_WRITABLE_VIEW, csp); // Use the buffer (the CSP will perform the integrity check). SignatureService signatureService = csp.makeSignatureService(); signatureService.init(SIG_KEY_ID, SignatureService.MODE_SIGN); outputLength = signatureService.sign(inputData, (short) 0, (short) 50, outputData, (short) 0); // Process the computed signature ... // Additionally, perform an integrity check after processing the result. SensitiveArrays.assertIntegrity(sensitiveArray); }
Constructor and Description |
---|
CSPSensitiveArrays() |
Modifier and Type | Method and Description |
---|---|
static byte[] |
makeIntegritySensitiveArrayView(byte[] array,
short offset,
short length,
Shareable cspInstance)
Adds integrity protection to an existing array and creates an array view accessible in the CSP context.
|
public static byte[] makeIntegritySensitiveArrayView(byte[] array, short offset, short length, Shareable cspInstance)
Available for:
Any existing local or global byte array, such as the APDU buffer.Method Behavior:
This method adds integrity protection on the specified array, allowing it to be verified
using SensitiveArrays.assertIntegrity(..)
.
Additionally, this method creates an integrity-protected array view for the array provided, so
that is accessible within the context of the CSP Application.
Note: SensitiveArrays.isIntegritySensitive(..)
invoked on
the result of this method will return true
.
array
- The array.offset
- The offset in the array where the view starts.length
- The number of elements in the view.cspInstance
- The CSP instance object (recipient context).CSPException
- with reason:
ILLEGAL_BUFFER
: Illegal input buffer [1002], [1004].ILLEGAL_VALUE
: Not a CSP instance [2003].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.