public class CSPException extends CardRuntimeException
The CSP-API throws CSPException
instances as JCRE-owned Temporary Entry Point Objects, managed by the Java Card runtime.
These exceptions can be thrown and caught by any applet but cannot be stored in class or instance variables, as they may change
or be cleared by the runtime after the operation.
The following error types may be thrown by the CSP:
ILLEGAL_BUFFER
: An input buffer is null, out of bounds, inaccessible in the caller’s context or integrity-verification failed.ILLEGAL_CONFIG
: A configuration is missing or is inconsistent.ILLEGAL_VALUE
: Any input parameter provided is outside the allowed bounds.INVALID_INIT
: The CSP, a service or a resource has not been correctly initialized.NOT_ALLOWED
: An operation was invoked that is not permitted.ILLEGAL_USE
: Data cannot be processed for cryptographic operation.NOT_SUPPORTED
: An algorithm or feature is not supported by the platform.
Each error type includes detailed reason codes for specific sub-errors, such as '0x7090 New password is too short' for ILLEGAL_VALUE
.
If configured for ERROR_MODE_DETAILED
, the CSP returns these codes through getReason
.
The CSP-API methods list exception codes used. However, the following errors are not specified in the methods:
To ensure consistent error behavior across different CSP Implementations, the CSP throws the errors in the sequence they are listed to the methods within this API specification. Editor's Note: Please provide feedback if this is not feasible, either generally or for specific methods.
ERROR_MODE_DETAILED
:
Category | Reason (Hex) | Description |
---|---|---|
General | 0x1000 | Illegal buffer: Not further specified. |
General | 0x1001 | Output buffer null: The output buffer is required but is null. |
General | 0x1002 | Input buffer null: The input buffer is required but is null. |
General | 0x1003 | Null buffer with length: Buffer is null , but length is not 0. |
General | 0x1004 | Illegal buffer index: Buffer offset or length out of bounds. |
General | 0x1005 | Illegal buffer context: Buffer not accessible in the caller's context (e.g., not a global array). |
General | 0x1006 | Missing integrity protection: A provided buffer is not supporting Sensitive Arrays. |
General | 0x1007 | Integrity check failed: CSPSensitiveArrays verification detected inconsistencies. |
Category | Reason (Hex) | Description |
---|---|---|
General | 0x2000 | Illegal input parameter: Not further specified. |
General | 0x2001 | Resource does not exist: The resource identifier provided does not refer to any existing resource. |
General | 0x2003 | Not a CSP Instance: The provided service context is not a instance of org.globalplatform.csp.api.CSP. |
Cipher | 0x2010 | Unknown cipher mode: The cipher mode provided is not defined. |
Cipher | 0x2011 | Illegal resource type: Only key resources can be used for cipher operations. |
Cipher | 0x2012 | Invalid initialization data: Initialization data not supported by the algorithm. |
Cipher | 0x2013 | Invalid initialization data length: Incorrect byte length of the algorithm-specific initialization data. |
Cipher | 0x2014 | Unsupported tag length: The requested tag length is not supported for this Authenticated Encryption with Associated Data (AEAD) cipher. |
Cipher | 0x2015 | AAD update failed: Total Additional Associated data (AAD) length specified in the init method is not identical to the AAD length. |
Signature | 0x2020 | Unknown signature mode: The signature mode provided is not defined. |
Signature | 0x2021 | Illegal resource type: Only key resources can be used for signature operations. |
Signature | 0x2022 | Invalid initialization data: Initialization data not supported by the algorithm. |
Signature | 0x2023 | Invalid initialization data length: Incorrect byte length of the algorithm-specific initialization data. |
Transform | 0x2030 | Illegal resource type: Only key resources can be used for encryption transformation. |
Secure Channel | 0x2040 | Unknown protocol type: The protocol type provided is not defined. |
Secure Channel | 0x2041 | Illegal resource type: the resource type provided is not accepted by the protocol. |
Confidential | 0x2050 | Illegal resource type: Only key resources can be used for confidential data transfer. |
Attestation | 0x2060 | Unknown attestation type: The attestation type provided is not defined. |
Attestation | 0x2061 | Illegal resource type: Only public key, counter and timer resources can be used for ATTESTATION_DATA . |
Key | 0x2070 | Illegal resource type: Only key resources can be used for key operations. |
Key | 0x2071 | Illegal key type: the resource provided is not a symmetric or private key. |
Key | 0x2072 | Illegal key type: the resource provided is not a private key. |
Key | 0x2073 | Illegal key type: the resource provided is not a public key. |
Key | 0x2074 | Unknown key mode: The key management mode provided is not defined. |
Certificate | 0x2080 | Illegal resource type: Only certificate resources can be used for certificate operations. |
Certificate | 0x2081 | Unknown certificate mode: The certificate management mode provided is not defined. |
Certificate | 0x2082 | Tag not found: The specified tag could not be found in the certificate structure. |
Password | 0x2090 | Illegal resource type: Only password resources can be used for password operations. |
Counter | 0x20A0 | Illegal counter type: Counter type is not supported by the operation. |
Time | 0x20B0 | Illegal timer type: Timer type is not supported by the operation. |
Category | Reason (Hex) | Description |
---|---|---|
General | 0x3000 | Illegal configuration: Not further specified. |
General | 0x3001 | CSP not activated: The configuration of this CSP Instance has not been activated. |
General | 0x3002 | Missing resource: The resource, corresponding to an CSP-Instance-specific configuration (e.g., the config attestation key), does not exist. |
General | 0x3003 | Resource not initialized: Resource is in STATE_UNINITIALIZED and cannot be used for cryptographic or security-related operations. |
General | 0x3004 | Resource already initialized: Resource is not in STATE_UNINITIALIZED and cannot be re-initialized. |
General | 0x3006 | Missing platform attestation key: No CASD attestation key configured. |
General | 0x3007 | Inconsistent platform attestation config: The CASD attestation has inconsistent cryptographic configurations. |
General | 0x3008 | Missing config attestation key: No CSP Instance-specific config attestation key configured. |
General | 0x3009 | Inconsistent policy config: Owner resource, constraining resource or additional data are incompatible with the policy type. |
Cipher | 0x3010 | Inconsistent cipher config: Padding, key type or key size incompatible with the cipher algorithm. |
Signature | 0x3020 | Inconsistent signature config: Hash, padding, key type, size or curve incompatible with the signature algorithm. |
Secure Channel | 0x3040 | Inconsistent sec channel config: Key type, size, curve or algorithm incompatible with the protocol. |
Attestation | 0x3060 | Inconsistent attestation config: Hash, padding, key type, size or curve incompatible with the signature algorithm. |
Key | 0x3070 | Inconsistent key derivation config: Key type, hash, size or curve incompatible with the key derivation algorithm. |
Key | 0x3071 | Inconsistent key agreement config: Key type, size or curve incompatible with the key agreement scheme. |
Time | 0x30B0 | Missing configuration: No CSP Instance-specific time verification key configured. |
Audit | 0x30C0 | Missing configuration: No CSP Instance-specific audit signing key configured. |
Field | 0x30E0 | Invalid field config: A resource ID is either missing (but required by a field) or provided (but not required). |
Category | Reason (Hex) | Description |
---|---|---|
General | 0x4000 | Not initialized: Not further specified. |
Cipher | 0x4010 | Cipher not initialized: The service has not been successfully initialized through any of the init.. methods. |
Cipher | 0x4011 | Cipher not initialized: This Authenticated Encryption with Associated Data (AEAD) cipher operates in offline mode and requires nonce, AAD length, and message length to be specified during initialization. |
Cipher | 0x4012 | Cipher not initialized: This Authenticated Encryption with Associated Data (AEAD) cipher operates in online mode; specifying nonce, AAD length, and message length during initialization is not supported. |
Signature | 0x4020 | Signing not initialized: The service has not been successfully initialized through any of the init.. methods. |
Signature | 0x4021 | Verifying not initialized: The service has not been successfully initialized through any of the init.. methods. |
Transform | 0x4030 | Transform not initialized: The service has not been successfully initialized through any of the init.. methods. |
Secure Channel | 0x4040 | Security not initialized: sc.init not invoked. |
Secure Channel | 0x4041 | Wrapping not initialized: initWrap not invoked. |
Secure Channel | 0x4042 | Unwrapping not initialized: initUnwrap not invoked. |
Secure Channel | 0x4043 | Wrapping mode active: Finalize with wrap before switching modes. |
Secure Channel | 0x4044 | Unwrapping mode active: Finalize with unwrap before switching modes. |
Confidential | 0x4050 | Confidential transfer not initialized: Missing storage key; sc.init not invoked with USAGE_CONFIDENTIAL . |
Confidential | 0x4051 | Confidential wrapping not initialized: initConfidentialWrap not invoked. |
Confidential | 0x4052 | Confidential unwrapping not initialized: initConfidentialUnwrap not invoked. |
Confidential | 0x4053 | Confidential wrapping mode active: Finalize with confidentialWrap before switching mode. |
Confidential | 0x4054 | Confidential unwrapping mode active: Finalize with confidentialUnwrap before switching mode. |
Confidential | 0x4054 | Security not established: Insufficient for confidential data transfer. |
Attestation | 0x4060 | Attestation not initialized: The service has not been successfully initialized through any of the init.. methods. |
Attestation | 0x4061 | Attestation already in process: Cannot add input data, the service is already computing the attestation. |
Key | 0x4070 | Key service not initialized: The key management has not been successfully initialized through the initManage method. |
Certificate | 0x4080 | Certificate service not initialized: The certificate management has not been successfully initialized through the initManage method. |
Time | 0x40B0 | Time not synchronized: No reference time set for the current session and time mode is set to TIME_MODE_STRICT . |
Audit | 0x40C0 | Events not fetched: The audit event queue is full and audit is operated in AUDIT_MODE_STRICT . |
Category | Reason (Hex) | Description |
---|---|---|
General | 0x5000 | Not allowed: Not further specified. |
General | 0x5001 | Not allowed: The AID of the Client Application is unknown. |
General | 0x5002 | Not allowed: The AID of the invoking Application does not match the AID of the org.globalplatform.GPRegistryEntry . |
General | 0x5003 | Not allowed: Illegal Security Domain AID of the Client Application. |
General | 0x5004 | Not allowed: Illegal LFDBH of the Client Application. |
General | 0x5005 | Not allowed: Missing DAP verification for the Client Application. |
General | 0x5006 | Not authenticated: A Client Authentication is required to use the operation. |
General | 0x5007 | Not allowed: At least one resource used is missing the USE right for this operation. |
General | 0x5008 | Not allowed: At least one resource used is missing the SETUP right for this operation. |
General | 0x5009 | Not allowed: At least one resource used is missing the CLEAR right for this operation. |
General | 0x500A | Not allowed: At least one resource used is missing the MOVE right for this operation. |
General | 0x500B | Policy violation: A policy failed. |
Cipher | 0x5010 | Wrong usage: Resource not configured for USAGE_CIPHER . |
Signature | 0x5020 | Wrong usage: Resource not configured for USAGE_SIGNATURE . |
Transform | 0x5030 | Wrong usage: The decryption key is not configured for USAGE_TRANSFORM . |
Secure Channel | 0x5040 | Wrong usage: Resource not configured for USAGE_SECCHANNEL . |
Confidential | 0x5050 | Wrong usage: The storage key is not configured for USAGE_CONFIDENTIAL . |
Attestation | 0x5060 | Wrong usage: Private attestation key is not configured for USAGE_ATTESTATION . |
Key | 0x5070 | Wrong usage: The source key used for key management operations is not configured for USAGE_KEY . |
Certificate | 0x5080 | Certificate verification failed: The certificate could not be verified using the provided trust anchor. |
Password | 0x5090 | Wrong usage: The password to check is not configured for USAGE_PASSWORD . |
Password | 0x5091 | Password not authenticated: The operation requires the password to be authenticated . |
Password | 0x5092 | Password blocked: A password used is in or has changed to STATE_BLOCKED . |
Counter | 0x50A0 | Counter exhausted: A resource used is in or has changed to STATE_EXHAUSTED . |
Time | 0x50B0 | Wrong usage: Resource not configured for USAGE_TIME . |
Time | 0x50B1 | Timer expired: A resource used is in or has changed to STATE_EXPIRED . |
Time | 0x50B2 | Not a time admin: The Client Application AID is not granted to update the reference time. |
Time | 0x50B3 | Time signature verification failed: Signature verification was enabled but did not succeed for the provided timestamp. |
Audit | 0x50C0 | Wrong usage: Resource not configured for USAGE_AUDIT . |
Offloading | 0x50D0 | Wrong usage: Resource not configured for USAGE_OFFLOADING . |
Offloading | 0x50D1 | Export not allowed: Resource has an active usage counter. |
Category | Reason (Hex) | Description |
---|---|---|
General | 0x6000 | Illegal use: Not further specified. |
Cipher | 0x6010 | Not block aligned: PAD_NOPAD configured, but the input data is not a multiple of the block size. |
Cipher | 0x6011 | Missing input: PAD_NOPAD or PAD_NULL configured and no input data was provided. |
Cipher | 0x6012 | Invalid input: The input data is not supported by the algorithm. |
Cipher | 0x6013 | Modulus exceeded: The input value is greater than or equal to the modulus. |
Cipher | 0x6014 | Decryption failed: The decrypted data lacks the expected padding, indicating a decryption issue. |
Cipher | 0x6015 | CCM cipher failed: Additional Associated Data (AAD) was not provided in the init method. |
Cipher | 0x6016 | CCM cipher failed: Total message length specified in the init method is not identical to the message length. |
Cipher | 0x6017 | AEAD tag retrieval failed: doFinal not yet called. |
Cipher | 0x6018 | AAD update failed: Updating Additional Associated Data (AAD) is not permitted in the current cipher state. |
Signature | 0x6020 | Illegal input: The input data is not supported by the algorithm. |
Signature | 0x6021 | Consistency check failed: A consistency check of the generated output failed. |
Signature | 0x6022 | Invalid hash length: The provided hash length does not match the message digest algorithm's length. |
Signature | 0x6023 | Illegal hash: No message digest computed before applying cryptographic operations (ALG_NULL). |
Secure Channel | 0x6040 | Illegal APDU: The provided APDU is incompatible with the protocol type or state. |
Key | 0x6070 | Illegal public key import: The public key value provided is not compatible to the resource it shall be imported to. |
Key | 0x6071 | Export buffer too small: Buffer length is insufficient to export the public key. |
Key | 0x6072 | Illegal input data: Additional input data is not supported by the algorithm. |
Certificate | 0x6080 | Illegal certificate import: The data provided is not compatible to the resource it shall be imported to. |
Key | 0x6082 | Illegal public key extraction: The public key within the certificate is not compatible to the resource it shall be imported to. |
Password | 0x6090 | Illegal password: The new password value is too short. |
Password | 0x6091 | Illegal password: The new password value is too long. |
Counter | 0x60A0 | Capacity exceeds short: getValueAsShort cannot be used. |
Counter | 0x60A1 | No limit configured: getLimit and getRemaining cannot be used. |
Counter | 0x60A2 | Counter Capacity Reached: The counter reached its modification limit to prevent memory wear. |
Time | 0x60B0 | Unsupported time format: The reference time is not in TIMESTAMP format. |
Offloading | 0x60D0 | Illegal import data: The data provided is not compatible to the resource it shall be imported to. |
Offloading | 0x60D1 | Missing validity date: Resource has a validity period, but no validity date is provided in the import data. |
Category | Reason (Hex) | Description |
---|---|---|
General | 0x8000 | Unsupported: Not further specified. |
General | 0x8002 | Unsupported: The resource type is not supported. |
General | 0x8003 | Unsupported: The policy mode is not supported. |
General | 0x8004 | Unsupported: The policy type is not supported and POLICY_MODE_STRICT is set. |
Cipher | 0x8010 | Unsupported: The cipher module is not supported. |
Cipher | 0x8011 | Unsupported: The padding algorithm is not supported. |
Cipher | 0x8012 | Unsupported: The cipher algorithm is not supported. |
Signature | 0x8020 | Unsupported: The signature module is not supported. |
Signature | 0x8021 | Unsupported: The message digest algorithm is not supported. |
Signature | 0x8022 | Unsupported: The signature algorithm is not supported. |
Transform | 0x8030 | Unsupported: The transform module is not supported. |
Secure Channel | 0x8040 | Unsupported: The secure channel module is not supported. |
Secure Channel | 0x8041 | Unsupported: The protocol type is not supported. |
Confidential | 0x8050 | Unsupported: The confidential data transfer module is not supported. |
Attestation | 0x8060 | Unsupported: The attestation module is not supported. |
Attestation | 0x8061 | Unsupported: The data attestation is not supported. |
Attestation | 0x8062 | Unsupported: The proof-of-possession key attestation is not supported. |
Key | 0x8070 | Unsupported: The key module is not supported. |
Key | 0x8071 | Unsupported: The key type is not supported. |
Key | 0x8072 | Unsupported: The key size is not supported. |
Key | 0x8073 | Unsupported: The curve is not supported. |
Key | 0x8074 | Unsupported: The key derivation algorithm is not supported. |
Key | 0x8075 | Unsupported: The key agreement scheme is not supported. |
Certificate | 0x8080 | Unsupported: The certificate module is not supported. |
Certificate | 0x8081 | Unsupported: The certificate type is not supported. |
Password | 0x8090 | Unsupported: The password module is not supported. |
Counter | 0x80A0 | Unsupported: The counter module is not supported. |
Counter | 0x80A1 | Unsupported: The counter mode is not supported. |
Counter | 0x80A2 | Unsupported: The counter type is not supported and COUNTER_MODE_STRICT is set. |
Counter | 0x80A3 | Unsupported: The counter capacity is not supported and COUNTER_MODE_STRICT is set. |
Time | 0x80B0 | Unsupported: The time module is not supported. |
Time | 0x80B1 | Unsupported: Time since boot is not supported and TIME_MODE_STRICT is set. |
Time | 0x80B2 | Unsupported: System time is not supported and TIME_MODE_STRICT is set. |
Time | 0x80B3 | Unsupported: The time mode is not supported. |
Time | 0x80B4 | Unsupported: The timer type is not supported and TIME_MODE_STRICT is set. |
Audit | 0x80C0 | Unsupported: The audit module is not supported. |
Audit | 0x80C1 | Unsupported: The audit mode is not supported. |
Audit | 0x80C2 | Unsupported: The event type is not supported and AUDIT_MODE_STRICT is set. |
Offloading | 0x80D0 | Unsupported: The offloading module is not supported. |
Field | 0x80E0 | Unsupported: The field is not supported and FIELD_MODE_STRICT is set. |
Random | 0x8100 | Unsupported: The random data module is not supported. |
Modifier and Type | Field and Description |
---|---|
static short |
ILLEGAL_BUFFER
Thrown when an input buffer is null, out of bounds, inaccessible in the caller’s context or integrity-verification failed.
|
static short |
ILLEGAL_CONFIG
Thrown when a configuration is uninitialized or cryptographically misconfigured.
|
static short |
ILLEGAL_USE
Thrown when data cannot be processed for cryptographic operations, such as non-block-aligned input.
|
static short |
ILLEGAL_VALUE
Thrown when one or more input parameters are out of the allowed bounds.
|
private static CSPException |
instance
The Java Card runtime environment-owned instance of this exception.
|
static short |
INVALID_INIT
Thrown when a CSP service is not properly initialized.
|
static short |
NOT_ALLOWED
Thrown when an operation is not allowed due to the current state or configuration.
|
static short |
NOT_SUPPORTED
Thrown when an algorithm or feature is not supported by the platform.
|
Constructor and Description |
---|
CSPException(short reason)
Constructs a
CSPException with the specified reason. |
Modifier and Type | Method and Description |
---|---|
static void |
throwIt(short reason)
Throws the Java Card runtime environment-owned instance of the
CSPException class with the specific reason. |
getReason, setReason
public static final short ILLEGAL_BUFFER
Reason code: 0x1000 in ERROR_MODE_BASIC
; 0x1XXX with detailed reasons in ERROR_MODE_DETAILED
, see CSPException
.
public static final short ILLEGAL_VALUE
javacard.security.CryptoException#ILLEGAL_VALUE
.
Reason code: 0x2000 in ERROR_MODE_BASIC
; 0x2XXX with detailed reasons in ERROR_MODE_DETAILED
, see CSPException
.
public static final short ILLEGAL_CONFIG
javacard.security.CryptoException#UNINITIALIZED_KEY
.
Reason code: 0x3000 in ERROR_MODE_BASIC
; 0x3XXX with detailed reasons in ERROR_MODE_DETAILED
, see CSPException
.
public static final short INVALID_INIT
javacard.security.CryptoException#INVALID_INIT
.
Reason code: 0x4000 in ERROR_MODE_BASIC
; 0x4XXX with detailed reasons in ERROR_MODE_DETAILED
, see CSPException
.
public static final short NOT_ALLOWED
Reason code: 0x5000 in ERROR_MODE_BASIC
; 0x5XXX with detailed reasons in ERROR_MODE_DETAILED
, see CSPException
.
public static final short ILLEGAL_USE
javacard.security.CryptoException#ILLEGAL_USE
.
Reason code: 0x6000 in ERROR_MODE_BASIC
; 0x6XXX with detailed reasons in ERROR_MODE_DETAILED
, see CSPException
.
public static final short NOT_SUPPORTED
CryptoException.NO_SUCH_ALGORITHM
.
Reason code: 0x8000 in ERROR_MODE_BASIC
; 0x8XXX with detailed reasons in ERROR_MODE_DETAILED
, see CSPException
.
private static CSPException instance
public CSPException(short reason)
CSPException
with the specified reason. To conserve on resources use throwIt(..)
to
use the Java Card runtime environment-owned instance of this class.reason
- The reason for the exception.public static void throwIt(short reason) throws CSPException
CSPException
class with the specific reason.
Java Card runtime environment-owned instances of exception classes are temporary Java Card runtime environment Entry Point Objects and can be accessed from any applet context. References to these temporary objects cannot be stored in class variables or instance variables or array components. See Runtime Environment Specification, Java Card Platform, Classic Edition, section 6.2.1 for details.
reason
- The reason for the exception.CSPException
- alwaysCopyright © 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.