public interface CSP extends Shareable
This is the main interface for accessing pre-configured cryptographic services provided by the Cryptographic Service Provider (CSP).
1. Create a CSP Instance:
Instantiate a CSP Application within a dedicated Security Domain (SD) using the install command shown below. For more details, see Section 4.5 of GlobalPlatform Amendment N [GPC_SPE_230]:
80 E6 0C 00 <LC> # INSTALL [for install and make selectable] 08 A0 00 00 01 51 43 53 50 # AID CSP ELF 09 A0 00 00 01 51 43 53 50 00 # AID CSP EM <L1> <CSPAID> # AID CSP 03 00 01 00 # Privileges required by the CSP 08 C9 00 EF 04 CB 02 8B 00 # Install parameters required by the CSP 00 00; # Placeholder for delegated management (disabled)
2. Verify the CSP:
Use the CSP-Protocol to perform an attestation of the CSP platform and to check supported features and algorithms using the enforce command. The pseudo admin command examples below demonstrate these operations. For more details, see Chapter 7 of GlobalPlatform Amendment N [GPC_SPE_230].
// Verify authenticity and identity of the CSP platform (If available; see Section 6.6 in GP AMD N). CSPComputeAttestation(ATTESTATION_PLATFORM, challenge) // Alternatively, use CSP config attestation to verify the authenticity and identity of the CSP Instance (if available; see Section 6.6 in GP AMD N). CSPComputeAttestation(ATTESTATION_CONFIG, challenge) // Check features and algorithms supported. CSPEnforce( keySupport: { keyTypes = [ (KEY_AES, 128), (KEY_AES, 256), (KEY_ECC_PRIVATE, 256)] curves = [BRAINPOOL_P256_R1] derivationAlgorithm = [KDF_ECC] } ) CSPEnforce( signatureSupport: { required = true signatureAlgorithms = [SIG_ECDSA]} ) CSPEnforce( passwordSupport: { required = true })3. Register Client Application(s)
Install Client Applications(s) and register them within the CSP. The pseudo admin command examples below demonstrate this process. For more details, see Chapter 7 of GlobalPlatform Amendment N [GPC_SPE_230].
// Register an Application with AID 'clientAID' installed on a Security Domain with AID 'clientSDAID'. CSPRegisterClientApplication(clientAID, clientSDAID) // Unregister the Client Application. CSPUnregisterClientApplication(clientAID)4. Retrieve CSP Instance
Registered Client Applications can retrieve the CSP Instance via org.globalplatform.GlobalService#getServiceInterface
.
The CSP verifies if the calling application is authorized and may throw CSPException.NOT_ALLOWED
for:
org.globalplatform.GPRegistryEntry
provided [5002].5. CSP Usage
The CSP Admin may configure the CSP API to require an active secure channel. This requirement is verified
during CSP service invocations, which may throw CSPException.NOT_ALLOWED
Client not authenticated [5006].
Sample code for retrieving the CSP Instance:
import javacard.framework.AID; import javacard.framework.JCSystem; import org.globalplatform.GPRegistryEntry; import org.globalplatform.GPSystem; import org.globalplatform.GlobalService; import org.globalplatform.csp.api.CSP; // AID of the CSP Instance. AID cspAID = JCSystem.lookupAID(CSP_AID_DATA, (short) 0, (byte) CSP_AID_DATA.length); // Retrieve the Global Service for the CSP Instance. GlobalService cspGlobalService = GPSystem.getService(cspAID, (short) (GPSystem.FAMILY_CSP<<8|0x00)); // AID of the Client Application that wants to use CSP services. AID clientAID = JCSystem.getAID(); // Retrieve the Registry Entry of the Client Application. GPRegistryEntry clientRegistryEntry = GPSystem.getRegistryEntry(clientAID); // Retrieve the CSP Shareable Object; performs access control checks using the clientRegistryEntry. CSP csp = (CSP) cspGlobalService.getServiceInterface(clientRegistryEntry, (short) (GPSystem.FAMILY_CSP<<8|0x00), null, (short) 0, (short) 0); // Init services. PasswordService pwdService = csp.getPasswordService(); KeyService keyService = csp.getKeyService(); SignatureService sigService = csp.makeSignatureService(); CipherService cipherService = csp.makeCipherService();
Modifier and Type | Field and Description |
---|---|
static short |
DEFAULT_SERVICE_ID
Shareable identifier.
|
static short |
GLOBAL_SERVICE_ID
GlobalService identifier.
|
Modifier and Type | Method and Description |
---|---|
AuditService |
getAuditService()
Returns the service for logging and audit.
|
CertificateService |
getCertificateService()
Returns the service for certificate management.
|
short |
getConfigName(byte[] outBuffer,
short outOffset)
Retrieve the name of the configuration of this CSP.
|
short |
getConfigVersion()
Retrieve the version of the configuration of this CSP.
|
CounterService |
getCounterService()
Returns the service for counter management.
|
KeyService |
getKeyService()
Returns the service for key management, including key generation, key derivation and key agreement.
|
OffloadingService |
getOffloadingService()
Returns the service for offloading, covering import and export of CSP resources.
|
PasswordService |
getPasswordService()
Returns the service for password management.
|
RandomDataService |
getRandomDataService()
Returns the service for random data generation.
|
TimeService |
getTimerService()
Returns the service for time management.
|
AttestationService |
makeAttestationService()
Instantiates a service for attestation computation.
|
CipherService |
makeCipherService()
Instantiates a service for encryption and decryption.
|
ConfidentialDataTransferService |
makeConfidentialDataTransferService(byte protocolType)
Instantiates a service for transferring session encryption to storage-layer encryption, and vice-versa.
|
SecureChannelService |
makeSecureChannelService(byte protocolType)
Instantiates a service for secure messaging and authentication.
|
SignatureService |
makeSignatureService()
Instantiates a service for creating and verifying signatures.
|
TransformService |
makeTransformService()
Instantiates a service for transferring encryption between keys and/or algorithms.
|
static final short GLOBAL_SERVICE_ID
Parameter to retrieve the GlobalService of the CSP:
import org.globalplatform.GPSystem; import org.globalplatform.GlobalService; import org.globalplatform.csp.api.CSP; // Retrieve the Global Service for the CSP Instance. GlobalService cspGlobalService = GPSystem.getService(cspAID, CSP.GLOBAL_SERVICE_ID);
static final short DEFAULT_SERVICE_ID
Used to retrieve the CSP
Shareable instance from the CSP GlobalService.
import org.globalplatform.GPRegistryEntry; import org.globalplatform.GPSystem; import org.globalplatform.GlobalService; import org.globalplatform.csp.api.CSP; // Retrieve the Global Service for the CSP Instance. GlobalService cspGlobalService = GPSystem.getService(cspAID, CSP.GLOBAL_SERVICE_ID); // Retrieve the Registry Entry of the Client Application. GPRegistryEntry clientRegistryEntry = GPSystem.getRegistryEntry(clientAID); // Retrieve the CSP Shareable Object. The CSP uses the clientRegistryEntry to check if the Client Application is really registered to this CSP Instance. CSP csp = (CSP) cspGlobalService.getServiceInterface(clientRegistryEntry, CSP.DEFAULT_SERVICE_ID, null, (short) 0, (short) 0);
Note: GLOBAL_SERVICE_ID
and #SERVICE_ID
both have the value 0x8B00
. It will work even if mixed up.
short getConfigVersion()
This version is set by the CSP Admin using the CSPSetup command.
short getConfigName(byte[] outBuffer, short outOffset)
This name is set by the CSP Admin using the CSPSetup command.
outBuffer
- Output buffer for storing the result.outOffset
- Offset in the output buffer where the result should be written.CipherService makeCipherService()
Note: Each invocation allocates memory.
CSPException
- with reason:
INVALID_INIT
: CSP not activated [3001].NOT_SUPPORTED
: Cipher module not supported [8010].makeSignatureService
,
makeTransformService
,
makeConfidentialDataTransferService
,
makeOffloadingService
SignatureService makeSignatureService()
Note: Each invocation allocates memory.
CSPException
- with reason:
INVALID_INIT
: CSP not activated [3001].NOT_SUPPORTED
: Signature module not supported [8020].makeCipherService
,
getAttestationService
,
getAuditService
TransformService makeTransformService()
Note: Each invocation allocates memory.
CSPException
- with reason:
INVALID_INIT
: CSP not activated [3001].NOT_SUPPORTED
: Transform module not supported [8030].makeCipherService
,
makeConfidentialDataTransferService
SecureChannelService makeSecureChannelService(byte protocolType)
If confidential data transfer is supported, this method is equivalent to makeConfidentialDataTransferService(byte)
,
as ConfidentialDataTransferService
extends SecureChannelService
.
Therefore, the returned instance can be cast to ConfidentialDataTransferService
.
Note: Each invocation allocates memory.
protocolType
- The secure channel protocol type; see SecureChannelService
.CSPException
- with reason:
INVALID_INIT
: CSP not activated [3001].ILLEGAL_VALUE
: Unknown protocol type [2040].NOT_SUPPORTED
: Confidential data transfer module [8040] or protocol [0x8041] not supported.makeConfidentialDataTransferService
ConfidentialDataTransferService makeConfidentialDataTransferService(byte protocolType)
The returned service extends SecureChannelService
, providing all its functionalities along with additional features for confidential data transfer.
Note: Each invocation allocates memory.
protocolType
- The secure channel protocol type; see SecureChannelService
.CSPException
- with reason:
INVALID_INIT
: CSP not activated [3001].ILLEGAL_VALUE
: Unknown protocol type [2040].NOT_SUPPORTED
: Confidential data transfer module [8050] or protocol [0x8041] not supported.makeSecureChannelService
AttestationService makeAttestationService()
Note: Each invocation allocates memory.
CSPException
- with reason:
INVALID_INIT
: CSP not activated [3001].NOT_SUPPORTED
: Attestation module not supported [8060].makeSignatureService
KeyService getKeyService()
Note: This method always returns the same instance.
CSPException
- with reason:
INVALID_INIT
: CSP not activated [3001].NOT_SUPPORTED
: Key module not supported [8070].getCertificateService
,
getPasswordService
CertificateService getCertificateService()
Note: This method always returns the same instance.
CSPException
- with reason:
INVALID_INIT
: CSP not activated [3001].NOT_SUPPORTED
: Certificate module not supported [8080].getKeyService
,
getPasswordService
PasswordService getPasswordService()
Note: This method always returns the same instance.
CSPException
- with reason:
INVALID_INIT
: CSP not activated [3001].NOT_SUPPORTED
: Password module not supported [8090].getKeyService
,
getCertificateService
CounterService getCounterService()
Note: This method always returns the same instance.
CSPException
- with reason:
INVALID_INIT
: CSP not activated [3001].NOT_SUPPORTED
: Counter module not supported [80A0].getTimerService
TimeService getTimerService()
Note: This method always returns the same instance.
CSPException
- with reason:
INVALID_INIT
: CSP not activated [3001].NOT_SUPPORTED
: Time module not supported [80B0].getCounterService
AuditService getAuditService()
Note: This method always returns the same instance.
CSPException
- with reason:
INVALID_INIT
: CSP not activated [3001].NOT_SUPPORTED
: Audit module not supported [80C0].makeSignatureService
OffloadingService getOffloadingService()
Note: This method always returns the same instance.
CSPException
- with reason:
INVALID_INIT
: CSP not activated [3001].NOT_SUPPORTED
: Offloading module not supported [80D0].makeCipherService
RandomDataService getRandomDataService()
Note: This method always returns the same instance.
CSPException
- with reason:
INVALID_INIT
: CSP not activated [3001].NOT_SUPPORTED
: Random data module not supported [8100].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.