public interface AttestationService extends CSPService
Provides attestation services to generate signed attestation data for SE platform or resources.
init(..)
methods initialize the service with resources and an attestation type.computeAttestation(..)
method computes the attestation depending on the attestation type set.updateInputData(..)
to provide input data to be included in the attestation result.update(..)
method processes multiple data chunks for attestation.
Attestation algorithms must be pre-configured by the CSP Admin and cannot be selected via the CSP-API.
Supported algorithms and the TLV format are defined in Section 6.6.1 of GlobalPlatform Amendment N [GPC_SPE_230] and may include:
Attestation Type | Attested Component | Attestation Algorithm | ASN.1 Format (GP AMD N) |
Platform Attestation |
SE chip | GP CASD (GP AMD A) | CSPPlatformAttestation (Section 6.6.5.5) |
Config Attestation |
CSP Instance Configuration | SignatureService algorithms |
CSPConfigAttestation (Section 6.6.5.6) |
Data Attestation |
External input data and CSP-internal fields |
SignatureService algorithms |
CSPDataAttestation (Section 6.6.5.7) |
Proof of Possession |
KEY_ECC_PUBLIC orKEY_RSA_PUBLIC |
SignatureService algorithms (inner/outer) |
CSPKeyPoPAttestation (Section 6.6.5.8) |
Key Generation |
New generatedKEY_ECC_PUBLIC orKEY_RSA_PUBLIC |
SignatureService algorithms (inner/outer) |
CSPKeyPoPAttestation (Section 6.6.5.8) |
0xF0 - 0xFF |
vendor-specific | vendor-specific | vendor-specific |
The cryptographic resources must be configured by the CSP Admin. Their resource identifiers,
assigned during creation, must be provided as parameters to the computeAttestation
methods.
Platform Attestation is set up according to GlobalPlatform Amendment A [GPC_SPE_007], while the other
attestation types must be configured through the CSP-Protocol.
Below are pseudo admin command examples using CSP-Protocol ASN.1 types.
For more details and commands, see Chapter 7 of GlobalPlatform Amendment N [GPC_SPE_230].
// Configure the Config Attestation. { // Create and import the key used for the CSP Instance attestation. CSPCreateResource(CSP_KEY_ID, KEY_ECC_PRIVATE, CURVE_SEC_P256_R1) CSPSetValue(CSP_KEY_ID, data) // Configure access control. CSPConfigureResource(CSP_KEY_ID, ACR_USE) // Configure usage and algorithms. CSPConfigureResource(CSP_KEY_ID, USAGE_ATTESTATION, SIG_ECDSA, ALG_256) // Set the new attestation key as CSP config attestation key. CSPSetup(configAttestationKey = CSP_KEY_ID) } // Configure a data attestation. { // Create a counter resource to increment and retrieve the attested counter value. CSPCreateResource(COUNTER_ID, RESOURCE_COUNTER) // Create and import the attestation key. CSPCreateResource(CSP_KEY_ID, KEY_ECC_PRIVATE, CURVE_SEC_P256_R1) CSPSetValue(CSP_KEY_ID, data) // Configure access control. CSPConfigureResource(COUNTER_ID, ACR_USE) CSPConfigureResource(CSP_KEY_ID, ACR_USE) // Configure usage and algorithms. CSPConfigureResource(CSP_KEY_ID, USAGE_ATTESTATION, SIG_ECDSA, ALG_256) } // Configure keys for a Proof of Possession (PoP). { // Create and generate the public key pair that shall be attested. CSPCreateResource(KEY_ID, KEY_ECC_PUBLIC, CURVE_SEC_P256_R1) CSPCreateResource(KEY_ID_PUBLIC, KEY_ECC_PUBLIC, CURVE_SEC_P256_R1) CSPGenerate(KEY_ID) CSPComputePublicKey(KEY_ID, KEY_ID_PUBLIC) // Create and import the attestation key. CSPCreateResource(CSP_KEY_ID, KEY_ECC_PRIVATE, CURVE_SEC_P256_R1) CSPCreateResource(CSP_KEY_ID_PUBLIC, KEY_ECC_PRIVATE, CURVE_SEC_P256_R1) CSPSetValue(CSP_KEY_ID, data) CSPComputePublicKey(CSP_KEY_ID, CSP_KEY_ID_PUBLIC) // Configure access control. CSPConfigureResource(KEY_ID, ACR_USE) CSPConfigureResource(KEY_ID_PUBLIC, ACR_USE) CSPConfigureResource(CSP_KEY_ID, ACR_USE) CSPConfigureResource(CSP_KEY_ID_PUBLIC, ACR_USE) // Configure usage and algorithms. CSPConfigureResource(KEY_ID, USAGE_ATTESTATION, SIG_ECDSA, ALG_256) CSPConfigureResource(CSP_KEY_ID, USAGE_ATTESTATION, SIG_ECDSA, ALG_256) }
Sample code for using the AttestationService
:
// 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. AttestationService attestationService = csp.makeAttestationService(); CounterService counterService = csp.getCounterService(); // Perform attestation operations. switch (ins) { // Platform Attestation case PLATFORM_ATTESTATION: attestationService.init(AttestationService.ATTESTATION_PLATFORM); attestationService.updateInputData(challenge, (short) 0, (short) challenge.length); outputLength = attestationService.computeAttestation(outputBuffer, (short) outputBuffer.length); attestationService.assertSensitiveResult(outputLength); // Process the attestation result ... SensitiveArrays.assertIntegrity(outputBuffer); break; // CSP Instance Attestation case CONFIG_ATTESTATION: attestationService.init(AttestationService.ATTESTATION_CONFIG); attestationService.updateInputData(challenge, (short) 0, (short) challenge.length); outputLength = attestationService.computeAttestation(outputBuffer, (short) outputBuffer.length); attestationService.assertSensitiveResult(outputLength); // Process the attestation result ... SensitiveArrays.assertIntegrity(outputBuffer); break; // Counter value attestation case COUNTER_VALUE_ATTESTATION: counterService.increment(COUNTER_ID, (short) 10); attestationService.init(AttestationService.ATTESTATION_DATA, COUNTER_ID, CSP_KEY_ID); attestationService.updateInputData(challenge, (short) 0, (short) challenge.length); outputLength = attestationService.computeAttestation(outputBuffer, (short) outputBuffer.length); attestationService.assertSensitiveResult(outputLength); // Process the attestation result ... SensitiveArrays.assertIntegrity(outputBuffer); break; // Proof of Possession case KEY_POP_ATTESTATION: attestationService.init(AttestationService.ATTESTATION_PROOF_OF_POSSESSION, KEY_ID, KEY_ID_PUBLIC, CSP_KEY_ID, CSP_KEY_ID_PUBLIC); attestationService.updateInputData(challenge, (short) 0, (short) challenge.length); outputLength = attestationService.computeAttestation(outputBuffer, (short) outputBuffer.length); attestationService.assertSensitiveResult(outputLength); // Process the attestation result ... SensitiveArrays.assertIntegrity(outputBuffer); break; // Key Generation case KEY_GENERATION_WITH_ATTESTATION: attestationService.init(AttestationService.ATTESTATION_KEY_GENERATION, KEY_ID, KEY_ID_PUBLIC, CSP_KEY_ID, CSP_KEY_ID_PUBLIC); attestationService.updateInputData(challenge, (short) 0, (short) challenge.length); outputLength = attestationService.computeAttestation(outputBuffer, (short) outputBuffer.length); attestationService.assertSensitiveResult(outputLength); // Process the attestation result ... SensitiveArrays.assertIntegrity(outputBuffer); break; }
Modifier and Type | Field and Description |
---|---|
static byte |
ATTESTATION_CONFIG
Sets the service to compute the config attestation of this CSP Instance.
|
static byte |
ATTESTATION_DATA
Sets the service to compute a data attestation, consisting of external input data and CSP-internal data (e.g.,
public key, counter, timer value or other fields).
|
static byte |
ATTESTATION_KEY_GENERATION
Sets the service to generate a public-private key pair and to compute a proof of possession (PoP) for the freshly generated key pair.
|
static byte |
ATTESTATION_PLATFORM
Sets the service to compute the platform attestation of the CSP-enabled Secure Element.
|
static byte |
ATTESTATION_PROOF_OF_POSSESSION
Sets the service to compute a proof of possession (PoP).
|
RESULT_FALSE, RESULT_TRUE
Modifier and Type | Method and Description |
---|---|
short |
computeAttestation(byte[] outBuffer,
short outOffset)
Computes the attestation depending on the attestation type set.
|
short |
getAttestationLength()
Retrieve the size, in bytes, of the output buffer required to write the computed attestation result.
|
void |
init(byte attestationType)
Initialize service to compute a system attestation.
|
void |
init(byte attestationType,
short attestationKeyId,
short resourceId)
Initialize service with the CSP resources required to compute the attestation.
|
void |
init(byte attestationType,
short attestationKeyId,
short publicAttestationKeyId,
short privateKeyId,
short publicKeyId)
Initialize service with the CSP resources required to compute the attestation.
|
short |
update(byte[] outBuffer,
short outOffset)
Multipart attestation computation.
|
void |
updateInputData(byte[] inputData,
short inputOffset,
short inputLength)
Multipart input data to be included in the attestation result.
|
assertSensitiveResult
static final byte ATTESTATION_PLATFORM
In this mode, computeAttestation(..)
and update(..)
generate the platform attestation,
returning attestation data as defined in CSPPlatformAttestation
(Section 6.6.5.5).
init(..)
,
Constant Field Valuesstatic final byte ATTESTATION_CONFIG
In this mode, computeAttestation(..)
and update(..)
generate the config attestation,
returning attestation data as defined in CSPConfigAttestation
(Section 6.6.5.6).
init(..)
,
Constant Field Valuesstatic final byte ATTESTATION_DATA
In this mode, computeAttestation(..)
and update(..)
generate the data attestation,
returning attestation data as defined in CSPDataAttestation
(Section 6.6.5.7).
init(..)
,
Constant Field Valuesstatic final byte ATTESTATION_PROOF_OF_POSSESSION
In this mode, computeAttestation(..)
and update(..)
generate the key attestation with proof of possession,
returning attestation data as defined in CSPKeyPoPAttestation
(Section 6.6.5.8).
init(..)
,
Constant Field Valuesstatic final byte ATTESTATION_KEY_GENERATION
In this mode, computeAttestation(..)
and update(..)
generate the key pair,
returning attestation data as defined in CSPKeyPoPAttestation
(Section 6.6.5.8).
init(..)
,
Constant Field Valuesvoid init(byte attestationType)
Available for
Method Behavior:
This method initializes the service for subsequent use with the update(..)
and/or computeAttestation(..)
methods
to generate a CSPPlatformAttestation
(Section 6.6.5.5) or CSPConfigAttestation
(Section 6.6.5.6) depending on the attestation type provided.
Both, the config attestation key and the CASD key for platform attestation must be configured by the CSP Admin.
The method handles access control, counters, timers and events according to Section 6.6.3 of GlobalPlatform Amendment N.
Usage Guidelines:
assertSensitiveResult(..)
.attestationType
- The type of the attestation to be computed; see AttestationService
.CSPException
- with reason:
ILLEGAL_VALUE
: Unknown attestation type [2060].ILLEGAL_CONFIG
: CSP not activated [3001], missing resource [3002], resource not initialized [3003], missing config attestation key [3008], No CASD attestation key configured [3006], inconsistent CASD configurations [3007] or inconsistent signature configuration [3020].NOT_ALLOWED
: Config attestation key missing ACCESS_USE
[5007], exhausted [50A0] or expired [50B1].NOT_SUPPORTED
: attestation type [8061], Padding [8011], message digest [8021] or signature algorithm [8022] not supported.void init(byte attestationType, short attestationKeyId, short resourceId)
Available for
Method Behavior:
This method initializes the service for subsequent use with the update(..)
and/or computeAttestation(..)
methods
to generate a CSPDataAttestation
(Section 6.6.5.7) for the resource provided
using the signature algorithm configured to the provided attestation key.
The method handles access control, counters, timers and events according to Section 6.6.3 of GlobalPlatform Amendment N.
Usage Guidelines:
assertSensitiveResult(..)
.attestationType
- The type of the attestation to be computed; see AttestationService
.attestationKeyId
- Attestation key used for signing.resourceId
- Resource value to include; optional, can be 0
.CSPException
- with reason:
ILLEGAL_VALUE
: Unknown attestation type [2060], resource ID(s) do not exist [2001] or the resource to be attested has illegal resource type [2061].ILLEGAL_CONFIG
: CSP not activated [3001], resource(s) not initialized [3003], inconsistent signature configuration of the provided attestation key [3020] or inconsistent policy config [3009].NOT_ALLOWED
: Client not authenticated [5006] or resource(s) missing ACCESS_USE
[5007], exhausted [50A0], expired [50B1], or private attestation key not configured for USAGE_ATTESTATION
[5060] or a policy failed [500B].NOT_SUPPORTED
: attestation type [8061], Padding [8011], message digest [8021] or signature algorithm [8022] not supported.void init(byte attestationType, short attestationKeyId, short publicAttestationKeyId, short privateKeyId, short publicKeyId)
Available for
Method Behavior:
This method initializes the service for subsequent use with the update(..)
and/or computeAttestation(..)
methods
to generate a CSPDataAttestation
(Section 6.6.5.7) or a CSPKeyPoPAttestation
(Section 6.6.5.8) depending on the attestation type provided.
The method handles access control, counters, timers and events according to Section 6.6.3 of GlobalPlatform Amendment N.
Usage Guidelines:
assertSensitiveResult(..)
.attestationType
- The type of the attestation to be computed; see AttestationService
.attestationKeyId
- Second key used to compute the attestation.publicAttestationKeyId
- Public part of the second key pair; optional, can be 0
.privateKeyId
- Resource to compute PoP.publicKeyId
- Public part of the resource.CSPException
- with reason:
ILLEGAL_VALUE
: Unknown attestation type [2060], resource ID(s) do not exist [2001].ILLEGAL_CONFIG
: CSP not activated [3001], resource(s) not initialized [3003], inconsistent signature configuration [3020] or inconsistent policy config [3009].NOT_ALLOWED
: Client not authenticated [5006] or resource(s) missing ACCESS_USE
[5007], exhausted [50A0], expired [50B1], or private attestation key not configured for USAGE_ATTESTATION
[5060], private PoP key missing USAGE_SIGNATURE
[5020] or a policy failed [500B].NOT_SUPPORTED
: attestation type [8062], Padding [8011], message digest [8021] or signature algorithm [8022] not supported.void updateInputData(byte[] inputData, short inputOffset, short inputLength)
Method Behavior:
This method adds input data to the attestation result. It supports multi-part operations, allowing multiple invocations when the full dataset is not available in a single array.
For input buffer length 0
this method does nothing.
Usage Guidelines:
CSPSensitiveArrays
for the input data.init(..)
methods before calling this method.update(..)
and computeAttestation(..)
to ensure the input data is processed correctly.inputData
- Input data to be added to the attestation result.inputOffset
- Offset in the input buffer to start reading.inputLength
- Length of the input data in bytes; optional, can be 0
.CSPException
- with reason:
ILLEGAL_BUFFER
: Illegal input buffer [1003], [1004], [1005], [1006], [1007].ILLEGAL_CONFIG
: CSP not activated [3001].INVALID_INIT
: Service not initialized [4060], or attestation computing already started [4061].computeAttestation(..)
short update(byte[] outBuffer, short outOffset)
Method Behavior:
This method processes a data chunk for multipart attestation computation when the full result should not be stored in one array.
Incomplete blocks are stored for processing in the next update(..)
or computeAttestation(..)
call.
The method handles access control, counters and events according to Section 6.6.3 of GlobalPlatform Amendment N.
Usage Guidelines:
CSPSensitiveArrays
for the output data and invoke assertIntegrity(..)
after processing it.assertSensitiveResult(..)
.init(..)
methods before calling this method.computeAttestation(..)
after one or more update(..)
calls.update(..)
if all data fits in a single byte array; use computeAttestation(..)
instead.outBuffer
- Output buffer for storing the attestation result.outOffset
- Offset in the output buffer where the result should be written.CSPException
- with reason:
ILLEGAL_BUFFER
: Illegal output buffer [1001], [1004], [1005], [1006], [1007].ILLEGAL_CONFIG
: CSP not activated [3001], missing resource [3002], not initialized [3003], inconsistent signature configuration [3020], or invalid field configuration [30E0].INVALID_INIT
: Service not initialized [4060].NOT_ALLOWED
: Resource(s) exhausted [50A0].ILLEGAL_USE
: Counter capacity reached [60A2]NOT_SUPPORTED
: Unsupported field used [80E0]computeAttestation(..)
short computeAttestation(byte[] outBuffer, short outOffset)
Method Behavior:
This method performs the attestation computation on the input data and resets the service.
After completion, the service requires a new init(..)
call to prepare for the next operation.
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.6.3 of GlobalPlatform Amendment N.
Usage Guidelines:
CSPSensitiveArrays
for the output data and invoke assertIntegrity(..)
after processing it.assertSensitiveResult(..)
.init(..)
methods before calling this method.update(..)
as needed before finalizing with this method.outBuffer
- Output buffer for storing the attestation result.outOffset
- Offset in the output buffer where the result should be written.CSPException
- with reason:
ILLEGAL_BUFFER
: Illegal output buffer [1001], [1004], [1005], [1006], [1007].ILLEGAL_CONFIG
: CSP not activated [3001], missing resource [3002], not initialized [3003], inconsistent signature configuration [3020] or invalid field configuration [30E0].INVALID_INIT
: Service not initialized [4060].NOT_ALLOWED
: Resource(s) exhausted [50A0].ILLEGAL_USE
: Counter capacity reached [60A2]NOT_SUPPORTED
: Unsupported field used [80E0]short getAttestationLength()
Method Behavior:
The returned size includes the input data already provided for the attestation computation.CSPException
- with reason:
ILLEGAL_CONFIG
: CSP not activated [3001].NOT_ALLOWED
: Client not authenticated [5006].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.