public interface SignatureService extends CSPService
Provides services to create and verify signatures.
init(..)
method initializes the signature service with a mode and resource.sign(..)
and signPreComputedHash(..)
methods in MODE_SIGN
create signatures.verify(..)
and verifyPreComputedHash(..)
methods in MODE_VERIFY
verify signatures.update(..)
method processes multiple data chunks for signature creation or verification.
Signature algorithms must be pre-configured by the CSP Admin and cannot be selected via the CSP-API.
Supported algorithms are defined in Section 6.2.1 of GlobalPlatform Amendment N [GPC_SPE_230] and may include:
Signature Algorithm | Padding Algorithm | Digest Algorithm | Key Type | Min Key Size |
---|---|---|---|---|
SIG_AES_CMAC128 | PAD_ISO9797_1_M2_ALG3 | ALG_NULL |
KEY_AES | 128 |
SIG_AES_MAC128 | PAD_NOPAD | ALG_NULL |
KEY_AES | 128 |
SIG_HMAC | PAD_NULL | ALG_SHA (SHA2, SHA3) |
KEY_HMAC | 256 |
SIG_RSA | PAD_PKCS1_PSS | ALG_SHA (SHA2, SHA3) |
KEY_RSA_* | 2048 |
SIG_ECDSA | PAD_NULL | ALG_SHA (SHA2, SHA3) |
KEY_ECC_* | 128 |
SIG_ECDSA_PLAIN | PAD_NULL | ALG_SHA (SHA2, SHA3) |
KEY_ECC_* | 256 |
SIG_EC_SCHNORR | PAD_NULL | ALG_SHA (SHA2, SHA3) |
KEY_ECC_* | 256 |
SIG_POA | PAD_NULL | ALG_SHA (SHA2, SHA3) |
2x KEY_ECC_* | 256 |
The CSP Admin may configure additional signature fields to be added to the data before signing. Supported fields are defined in Section 6.2.1.5 of GlobalPlatform Amendment N [GPC_SPE_230] and may include:
Log Field | Value (Hex) | Size (byte) |
---|---|---|
LOG_SYSTEM_TIME | 0x01 | 8 |
LOG_UPTIME | 0x02 | 2 |
LOG_USAGE_COUNTER | 0x03 | 2-4 |
LOG_CSP_CONFIG_VERSION | 0x04 | 2 |
LOG_CSP_PROTOCOL_VERSION | 0x05 | 1 |
LOG_CSP_ELF_VERSION | 0x06 | 2 |
LOG_RESOURCE_ID | 0x07 | 2 |
LOG_RESOURCE_STATE | 0x08 | 1 |
LOG_PUBLIC_KEY | 0x09 | n |
LOG_MANUAL_COUNTER | 0x0A | 2-4 |
LOG_MANUAL_COUNTER_LIMIT | 0x0B | 2-4 |
LOG_MANUAL_TIMER | 0x0C | 2-8 |
LOG_MANUAL_TIMER_LIMIT | 0x0D | 2-8 |
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 signature key pair resources. CSPCreateResource(SIG_KEY_ID, KEY_ECC_PRIVATE, CURVE_BRAINPOOL_P256_R1) CSPCreateResource(SIG_KEY_ID_PUBLIC, KEY_ECC_PUBLIC, CURVE_BRAINPOOL_P256_R1) // Generate the ECC key pair. CSPGenerateKey(SIG_KEY_ID) CSPComputePublicKey(SIG_KEY_ID, SIG_KEY_ID_PUBLIC) // Configure access control. CSPConfigureResource(SIG_KEY_ID, ACR_USE) CSPConfigureResource(SIG_KEY_ID_PUBLIC, ACR_USE) // Configure usage and algorithms. CSPConfigureResource(SIG_KEY_ID, USAGE_SIGNATURE, SIG_ECDSA, PAD_NULL, ALG_SHA_256) CSPConfigureResource(SIG_KEY_ID_PUBLIC, USAGE_SIGNATURE, SIG_ECDSA, PAD_NULL, ALG_SHA_256)
Sample code for using the SignatureService
:
// 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. SignatureService signatureService1 = csp.makeSignatureService(); SignatureService signatureService2 = csp.makeSignatureService(); switch (ins) { // Create signature sample. case SIGN_INIT: signatureService1.init(SignatureService.MODE_SIGN, SIG_KEY_ID); break; case SIGN_UPDATE: signatureService1.update(data, (short) 0, (short) data.length); break; case SIGN_SIGN: outputLength = signatureService1.sign(data, (short) 0, (short) data.length, outputBuffer, (short) 0); signatureService1.assertSensitiveResult(outputLength); // Process the computed signature ... SensitiveArrays.assertIntegrity(outputBuffer); break; // Verify signature sample. case VERIFY_INIT: signatureService2.init(SignatureService.MODE_VERIFY, SIG_KEY_ID_PUBLIC); break; case VERIFY_UPDATE: signatureService2.update(data, (short) 0, (short) data.length); break; case VERIFY_SIGN: result = signatureService2.verify(data, (short) 0, (short) data.length, signature, (short) 0, (short) signature.length); signatureService2.assertSensitiveResult(result); break; }
CipherService
Modifier and Type | Field and Description |
---|---|
static byte |
MODE_SIGN
Sets the service to signature creation mode.
|
static byte |
MODE_VERIFY
Sets the service to signature verification mode.
|
RESULT_FALSE, RESULT_TRUE
Modifier and Type | Method and Description |
---|---|
void |
init(byte mode,
short keyResourceId)
Initialize service for either signature creation or verification.
|
void |
init(byte mode,
short keyResourceId,
byte[] initializationData,
short initializationDataOffset,
short initializationDataLength)
Initialize service for either signature creation or verification with algorithm-specific parameters (e.g., iv data).
|
void |
init(byte mode,
short keyResourceId,
short secondResourceId)
Initialize service for either signature creation or verification and returns the commitment result.
|
void |
init(byte mode,
short keyResourceId,
short publicKeyResourceId,
short secondKeyResourceId,
short secondPublicKeyResourceId)
Initialize service for either signature creation or verification for algorithms requiring two public-private key pairs.
|
short |
sign(byte[] inBuffer,
short inOffset,
short inLength,
byte[] outBuffer,
short outOffset)
Create a signature of the given data.
|
short |
signPreComputedHash(byte[] hashBuffer,
short hashOffset,
short hashLength,
byte[] outBuffer,
short outOffset)
Create a signature the given precomputed hash data.
|
void |
update(byte[] inBuffer,
short inOffset,
short inLength)
Multipart signature creation or verification, depending on the mode set.
|
short |
verify(byte[] inBuffer,
short inOffset,
short inLength,
byte[] sigBuffer,
short sigOffset,
short sigLength)
Verify the signature of the given data.
|
short |
verifyPreComputedHash(byte[] hashBuffer,
short hashOffset,
short hashLength,
byte[] sigBuffer,
short sigOffset,
short sigLength)
Verify the signature for the given precomputed hash data.
|
assertSensitiveResult
static final byte MODE_SIGN
In this mode, the update(..)
and sign(..)
methods will create signatures.
init(..)
,
Constant Field Valuesstatic final byte MODE_VERIFY
In this mode, the update(..)
and sign(..)
methods will verify signatures.
init(..)
,
Constant Field Valuesvoid init(byte mode, short keyResourceId)
Available for
SIG_AES_CMAC128
SIG_AES_MAC128
SIG_HMAC
SIG_RSA
Method Behavior:
This method initializes the service for subsequent use with the update(..)
and/or sign(..)
methods
using the key parameters, signature, message digest and padding algorithms configured to the provided resource.
The method handles access control, counters, timers and events according to Section 6.2.3 of GlobalPlatform Amendment N.
mode
- SIGN
or VERIFY
.keyResourceId
- Key resource.CSPException
- with reason:
ILLEGAL_VALUE
: Unknown mode [2020], resource ID does not exist [2001] or is not a KEY
[2021].ILLEGAL_CONFIG
: CSP not activated [3001], resource not initialized [3003], inconsistent signature configuration [3020] or inconsistent policy config [3009].NOT_ALLOWED
: Client not authenticated [5006] or resource missing ACCESS_USE
[5007], exhausted [50A0], expired [50B1], not configured for USAGE_SIGNATURE
[5020] or a policy failed [500B].NOT_SUPPORTED
: Padding [8011], message digest [8021] or signature algorithm [8022] not supported.init(..)
,
update(..)
,
sign(..)
,
verify(..)
void init(byte mode, short keyResourceId, byte[] initializationData, short initializationDataOffset, short initializationDataLength)
Available for
SIG_RSA
SIG_ECDSA
SIG_ECDSA_PLAIN
Method Behavior:
This method initializes the service for subsequent use with the update(..)
and/or sign(..)
methods
using the key parameters, signature, message digest and padding algorithms configured to the provided resource, along with the
algorithm-specific initialization data provided.
The method handles access control, counters, timers and events according to Section 6.2.3 of GlobalPlatform Amendment N.
Usage Guidelines:
CSPSensitiveArrays
for the initialization data.mode
- SIGN
or VERIFY
.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 or output buffer [1002], [1004], [1005], [1006], [1007].ILLEGAL_VALUE
: Unknown mode [2020], resource ID does not exist [2001], is not a KEY
[2021] or initialization data is invalid [2022], [2023].ILLEGAL_CONFIG
: CSP not activated [3001], resource not initialized [3003], inconsistent signature configuration [3020] or inconsistent policy config [3009].NOT_ALLOWED
: Client not authenticated [5006] or resource missing ACCESS_USE
[5007], exhausted [50A0], expired [50B1], not configured for USAGE_SIGNATURE
[5020] or a policy failed [500B].NOT_SUPPORTED
: Padding [8011], message digest [8021] or signature algorithm [8022] not supported.init(..)
,
update(..)
,
sign(..)
,
verify(..)
void init(byte mode, short keyResourceId, short publicKeyResourceId, short secondKeyResourceId, short secondPublicKeyResourceId)
Available for
SIG_POA
Method Behavior:
This method initializes the service for subsequent use with the update(..)
and/or sign(..)
methods
using the key parameters, signature, message digest and padding algorithms configured to the provided resource.
It stores the computed commitment in the provided output resource.
The method handles access control, counters, timers and events according to Section 6.2.3 of GlobalPlatform Amendment N.
mode
- SIGN
or VERIFY
.keyResourceId
- Key resource.publicKeyResourceId
- Public part of the key resource.secondKeyResourceId
- Second resource, e.g.,t o compute the proof of association for SIG_POA
.secondPublicKeyResourceId
- Public part of the second key resource.CSPException
- with reason:
ILLEGAL_VALUE
: Unknown mode [2020], resource ID does not exist [2001] or is not a KEY
[2021].ILLEGAL_CONFIG
: CSP not activated [3001], resource not initialized [3003], inconsistent signature configuration [3020] or inconsistent policy config [3009].NOT_ALLOWED
: Client not authenticated [5006] or resource missing ACCESS_USE
[5007], exhausted [50A0], expired [50B1], not configured for USAGE_SIGNATURE
[5020] or a policy failed [500B].NOT_SUPPORTED
: Padding [8011], message digest [8021] or signature algorithm [8022] not supported.init(..)
,
update(..)
,
sign(..)
,
verify(..)
void init(byte mode, short keyResourceId, short secondResourceId)
Available for
SIG_EC_SCHNORR
Method Behavior:
This method initializes the service for subsequent use with the update(..)
and/or sign(..)
methods
using the key parameters, signature, message digest and padding algorithms configured to the provided resource.
It stores the computed commitment in the provided output resource.
The method handles access control, counters, timers and events according to Section 6.2.3 of GlobalPlatform Amendment N.
mode
- SIGN
or VERIFY
.keyResourceId
- Key resource.secondResourceId
- Second resource, e.g., to store the commitment result for SIG_EC_SCHNORR
.CSPException
- with reason:
ILLEGAL_VALUE
: Unknown mode [2020], resource ID does not exist [2001] or is not a KEY
[2021].ILLEGAL_CONFIG
: CSP not activated [3001], resource not initialized [3003], inconsistent signature configuration [3020] or inconsistent policy config [3009].NOT_ALLOWED
: Client not authenticated [5006] or resource missing ACCESS_USE
[5007], exhausted [50A0], expired [50B1], not configured for USAGE_SIGNATURE
[5020] or a policy failed [500B].NOT_SUPPORTED
: Padding [8011], message digest [8021] or signature algorithm [8022] not supported.init(..)
,
update(..)
,
sign(..)
,
verify(..)
void update(byte[] inBuffer, short inOffset, short inLength)
Method Behavior:
This method processes a data chunk for multipart signature creation or verification when the full dataset isn't available in one array.
Based on the mode from the last init(..)
call, it signs or verifies the data without finalizing this process.
Incomplete blocks are stored for processing in the next update(..)
, sign(..)
or verify(..)
call.
For input buffer length 0
this method does nothing.
The method handles access control, counters and events according to Section 6.2.3 of GlobalPlatform Amendment N.
Usage Guidelines:
CSPSensitiveArrays
for the input data.assertSensitiveResult(..)
.init(..)
before calling this method.sign(..)
or verify(..)
after one or more update(..)
calls.update(..)
if all data fits in a single byte array; use sign(..)
or verify(..)
instead.inBuffer
- Input data to sign or verify.inOffset
- Offset in the input buffer to start reading.inLength
- Length of the input data in bytes; can be 0
.CSPException
- with reason:
ILLEGAL_BUFFER
: Illegal input or output buffer [1002], [1004], [1005], [1006], [1007].ILLEGAL_CONFIG
: CSP not activated [3001], missing resource [3002], resource not initialized [3003] or invalid field configuration [30E0].INVALID_INIT
: Service not initialized [4020], [4021].NOT_ALLOWED
: Resource exhausted [50A0].ILLEGAL_USE
: Invalid input data [6020], [6021], or counter capacity reached [60A2].init(..)
,
verify(..)
,
verifyPreComputedHash(..)
,
sign(..)
,
signPreComputedHash(..)
short sign(byte[] inBuffer, short inOffset, short inLength, byte[] outBuffer, short outOffset)
Method Behavior:
This method computes the hash of the input data, generates the signature and writes it to the output buffer.
It uses the resource configuration from the last init(..)
call and finalizes the signing process.
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.2.3 of GlobalPlatform Amendment N.
Usage Guidelines:
CSPSensitiveArrays
for the input data.CSPSensitiveArrays
for the output signature and invoke assertIntegrity(..)
after processing it.assertSensitiveResult(..)
.init(..)
and MODE_SIGN
before calling this method.update(..)
as needed before finalizing with this method.inBuffer
- Input data containing the data to sign.inOffset
- Offset in the input buffer to start reading.inLength
- Length of the input data in bytes.outBuffer
- Output buffer for storing the signature.outOffset
- Offset in the output buffer where the signature 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], resource not initialized [3003] or invalid field configuration [30E0].INVALID_INIT
: Service not initialized for signing [4020].NOT_ALLOWED
: Resource exhausted [50A0].ILLEGAL_USE
: Invalid input data [6010], [6011], [6020], [6021], or counter capacity reached [60A2].init(..)
,
update(..)
,
signPreComputedHash(..)
,
verify(..)
short signPreComputedHash(byte[] hashBuffer, short hashOffset, short hashLength, byte[] outBuffer, short outOffset)
Method Behavior:
This method accepts a precomputed hash, generates the signature for the hash and writes it to the output buffer.
It uses the resource configuration from the last init(..)
call and finalizes the signing process.
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.2.3 of GlobalPlatform Amendment N.
Usage Guidelines:
CSPSensitiveArrays
for the input data.CSPSensitiveArrays
for the output signature and invoke assertIntegrity(..)
after processing it.assertSensitiveResult(..)
.init(..)
and MODE_SIGN
before calling this method.update(..)
as needed before finalizing with this method.hashBuffer
- Hash input data.hashOffset
- Offset in the hash buffer to start reading.hashLength
- Length of the hash data in bytes.outBuffer
- Output buffer for storing the signature.outOffset
- Offset in the output buffer where the signature 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 for signing [4020].NOT_ALLOWED
: Resource exhausted [50A0].ILLEGAL_USE
: Invalid input data [6022], [6023], or counter capacity reached [60A2].init(..)
,
update(..)
,
sign(..)
,
verifyPreComputedHash(..)
short verify(byte[] inBuffer, short inOffset, short inLength, byte[] sigBuffer, short sigOffset, short sigLength)
Method Behavior:
This method computes the hash of the input data and verifies the signature for this hash.
It uses the resource configuration from the last init(..)
call.
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.2.3 of GlobalPlatform Amendment N.
Usage Guidelines:
CSPSensitiveArrays
for the input data.CSPSensitiveArrays
for the signature buffer.assertSensitiveResult(..)
.init(..)
and MODE_VERIFY
before calling this method.update(..)
as needed before finalizing with this method.Editor's Note: Instead of returning the result of the verification, we could throw an error when verification fails.
inBuffer
- Input data containing the data to verify.inOffset
- Offset in the input buffer to start reading.inLength
- Length of the input data in bytes.sigBuffer
- Signature data.sigOffset
- Offset in the signature buffer to start reading.sigLength
- Length of the signature in bytes.TRUE
if signature is verified successfully, FALSE
otherwise.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 for verification [4021].NOT_ALLOWED
: Resource exhausted [50A0].ILLEGAL_USE
: Invalid input data [6010], [6011], [6020], [6021].init(..)
,
update(..)
,
sign(..)
,
verifyPreComputedHash(..)
short verifyPreComputedHash(byte[] hashBuffer, short hashOffset, short hashLength, byte[] sigBuffer, short sigOffset, short sigLength)
Method Behavior:
This method verifies the signature for the provided precomputed hash.
It uses the resource configuration from the last init(..)
call.
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.2.3 of GlobalPlatform Amendment N.
Usage Guidelines:
CSPSensitiveArrays
for the input data.CSPSensitiveArrays
for the signature buffer.assertSensitiveResult(..)
.init(..)
and MODE_VERIFY
before calling this method.update(..)
as needed before finalizing with this method.Editor's Note: Instead of returning the result of the verification, we could throw an error when verification fails.
hashBuffer
- Hash input data.hashOffset
- Offset in the hash buffer to start reading.hashLength
- Length of the hash data in bytes.sigBuffer
- Signature data.sigOffset
- Offset in the signature buffer to start reading.sigLength
- Length of the signature in bytes.TRUE
if signature is verified successfully, FALSE
otherwise.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 for verification [4021].NOT_ALLOWED
: Resource exhausted [50A0].ILLEGAL_USE
: Invalid input data [6022], [6023].init(..)
,
update(..)
,
sign(..)
,
signPreComputedHash(..)
,
verify(..)
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.