public interface CertificateService extends ResourceService
Provides certification management services.
manage
method in mode EXPORT
returns the certificate's plain content.manage
method in mode IMPORT
verifies and imports a certificate.extractPublicKey
method extracts the public key from the certificate to initialize a public key resource.getValidityDate
method returns the validity date included in the certificate.getTagLength
and extractTag
methods return a value corresponding to a given encoded tag from a certificate.Supported certificate types are defined in Section 6.8.1 of GlobalPlatform Amendment N [GPC_SPE_230] and may include:
Certificate Type | Certificate Format |
CERT_CVC | Card Verifiable Certificate (BSI TR-03110-3). |
CERT_X509 | X.509 version 3 certificate (ITU-T X.509). |
The resources required for certificate service must be configured by the CSP Admin.
The resource identifiers for certificate resources, assigned during creation, must be used in the methods provided by the CertificateService
.
For details on admin commands of the CSP-Protocol, see Chapter 7 of GlobalPlatform Amendment N.
Below are pseudo admin command examples using CSP-Protocol ASN.1 types.
// Create TA Certificate resource and import it. CSPCreateResource(TA_AT_CERT_ID, CERT_CVC) CSPSetValue(TA_AT_CERT_ID, data) // Create PACE PIN resource and import it. CSPCreateResource(PACE_PIN_ID, PASSWORD_NUMERIC, minSize=5, maxSize=5) CSPSetValue(PACE_PIN_ID, data) // Configure access control. CSPConfigureResource(PACE_PIN_ID, ACR_USE & ACR_SETUP) CSPConfigureResource(TA_AT_CERT_ID, ACR_CLEAR & ACR_SETUP & ACR_USE, POLICY_SECCHANNEL_ESTABLISHED (PACE_PIN_ID) ) // Configure usage and algorithms. CSPConfigureResource(PACE_PIN_ID, USAGE_SECCHANNEL, SEC_PACE) CSPConfigureResource(TA_AT_CERT_ID, USAGE_SECCHANNEL, SEC_TA2)
Sample code for using the CertificateService
:
// 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. CertificateService certificateService = csp.getCertificateService(); switch (ins) { // Certificate import sample. case IMPORT_INIT: certificateService.initManage(TA_AT_CERT_ID, CertificateService.MODE_IMPORT_CERTIFICATE); break; case IMPORT_UPDATE: len = certificateService.updateManage(inBuffer, (short) 0, (short) inBuffer.length); SensitiveArrays.assertIntegrity(inBuffer); certificateService.assertSensitiveResult(len); break; case IMPORT_DOFINAL: len = certificateService.manage(inBuffer, (short) 0, (short) inBuffer.length); SensitiveArrays.assertIntegrity(inBuffer); certificateService.assertSensitiveResult(len); break; // Certificate export sample. case EXPORT_INIT certificateService.initManage(TA_AT_CERT_ID, CertificateService.MODE_EXPORT_CERTIFICATE); certificateLength = certificateService.getManagedLength(TA_AT_CERT_ID); Util.setShort(outBuffer, outOffset, certificateLength); break; case EXPORT_UPDATE: len = certificateService.updateManage(outBuffer, outOffset, outLen); certificateService.assertSensitiveResult(len); break; case EXPORT_DOFINAL: len = certificateService.manage(outBuffer, outOffset, outLen); certificateService.assertSensitiveResult(len); break; }
KeyService
,
PasswordService
,
OffloadingService
Modifier and Type | Field and Description |
---|---|
static byte |
CERT_CVC
Card Verifiable Certificate (CVC).
|
static byte |
CERT_X509
X.509 certificate (X509).
|
static byte |
MANAGE_MODE_CERTIFICATE_EXPORT
Sets the service to certificate export mode.
|
static byte |
MANAGE_MODE_CERTIFICATE_IMPORT
Sets the service to certificate import/verification mode.
|
RESOURCE_CERTIFICATE, RESOURCE_COUNTER, RESOURCE_KEY, RESOURCE_PASSWORD, RESOURCE_TIMER, STATE_BLOCKED, STATE_EXHAUSTED, STATE_EXPIRED, STATE_OPERATIONAL, STATE_UNINITIALIZED
RESULT_FALSE, RESULT_TRUE
Modifier and Type | Method and Description |
---|---|
void |
extractPublicKey(short certResourceId,
short keyResourceId)
Extracts the public key from a certificate.
|
short |
extractTag(short certResourceId,
byte[] tagBuffer,
short tagOffset,
short tagLength,
byte[] outBuffer,
short outOffset)
Extracts a value corresponding to a given encoded tag from the certificate.
|
short |
getManagedLength(short certResourceId)
Retrieve the size, in bytes, of the buffer required for exporting the certificate.
|
byte |
getPublicKeyCurve(short certResourceId)
Retrieve the ECC curve of the public key included in the certificate.
|
byte |
getPublicKeySize(short certResourceId)
Retrieve the key size in bits of the public key included in the certificate.
|
byte |
getPublicKeyType(short certResourceId)
Retrieve the type of the public key included in the certificate.
|
short |
getTagLength(short certResourceId,
byte[] tagBuffer,
short tagOffset,
short tagLength)
Returns the length of the value corresponding to a given tag in the certificate.
|
byte |
getType(short certResourceId)
Retrieve the certificate type.
|
short |
getValidityDate(short certResourceId,
byte[] outBuffer,
short outOffset)
Retrieve the validity date included in the certificate.
|
void |
initManage(short certResourceId,
byte mode,
short trustCertOrPubKeyResourceId)
Initializes the service for either certificate import or export.
|
short |
manage(byte[] buffer,
short offset,
short length)
Import or export a certificate, depending on the mode set.
|
short |
updateManage(byte[] buffer,
short offset,
short length)
Multipart certificate import or export, depending on the mode set.
|
clear, clearTransient, getResourceType, getState
assertSensitiveResult
static final byte CERT_CVC
CVC certificates contain either ECC or RSA public keys and are encoded using ASN.1 DER format. Tags in this format are encoded typically as 1–3 bytes.
RESOURCE_CERTIFICATE
,
Constant Field Valuesstatic final byte CERT_X509
X.509 certificates contain either ECC or RSA public keys and are encoded using ASN.1 DER format. Tags in this format are encoded typically as 1–3 bytes.
RESOURCE_CERTIFICATE
,
Constant Field Valuesstatic final byte MANAGE_MODE_CERTIFICATE_IMPORT
In this mode, the manage(..)
and updateManage(..)
methods are used to verify and import a certificate.
initManage(..)
,
Constant Field Valuesstatic final byte MANAGE_MODE_CERTIFICATE_EXPORT
In this mode, the manage(..)
and updateManage(..)
methods are used to export a certificate.
initManage(..)
,
Constant Field Valuesvoid initManage(short certResourceId, byte mode, short trustCertOrPubKeyResourceId)
Method Behavior:
This method initializes the service for subsequent use with the updateManage(..)
and/or manage(..)
methods
to import or export the provided certificate.
If the trustCertOrPubKeyResourceId
parameter is provided for IMPORT
,
the CSP verifies the authenticity of the certificate to import by checking its signature using the referenced certificate or public key.
Additional checks, such as issuer matching or validity period, may be performed depending on the certificate type.
The method handles access control and events according to Section 6.8.3 of GlobalPlatform Amendment N.
certResourceId
- Certificate resource.mode
- IMPORT
or EXPORT
.trustCertOrPubKeyResourceId
- Certificate or public key resource used to verify the certificate to import; optional, may be 0
.CSPException
- with reason:
ILLEGAL_VALUE
: Unknown mode [2081], resource ID does not exist [2001] or is not a CERTIFICATE
[2080].ILLEGAL_CONFIG
: CSP not activated [3001], resource not initialized for EXPORT
[3003], resource already initialized for IMPORT
[3004] or inconsistent policy config [3009].NOT_ALLOWED
: Client not authenticated [5006] or
updateManage(..)
,
manage(..)
,
clear(..)
short updateManage(byte[] buffer, short offset, short length)
Method Behavior:
This method processes a data chunk for multipart import or export when the full certificate cannot be transported in one array.
Based on the mode from the last initManage(..)
call, it imports or exports the certificate without finalizing this process.
The method handles access control and events according to Section 6.8.3 of GlobalPlatform Amendment N.
Usage Guidelines:
CSPSensitiveArrays
for the input data in IMPORT
.CSPSensitiveArrays
for the output buffer in EXPORT
and invoke assertIntegrity(..)
after processing it.assertSensitiveResult(..)
in EXPORT
.initManage(..)
before calling this method.manage(..)
after one or more updateManage(..)
calls.buffer
- Input buffer for IMPORT
or output buffer for EXPORT
.offset
- Start offset in the buffer for reading or writing.length
- Number of bytes to read or write.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 for EXPORT
[3003] or resource already initialized for IMPORT
[3004].INVALID_INIT
: Service not initialized [4080].ILLEGAL_USE
: Invalid input data [6080].initManage(..)
,
manage(..)
short manage(byte[] buffer, short offset, short length)
Method Behavior:
Imports or exports a certificate based on the last initManage(..)
call.
For import, the CSP verifies the certificate corresponding trust anchor certificate or public key provided within the initManage(..)
method.
After completion, a new initManage(..)
call is required to prepare the service for the next import or export.
The method handles access control and events according to Section 6.8.3 of GlobalPlatform Amendment N.
Usage Guidelines:
CSPSensitiveArrays
for the input data in IMPORT
.CSPSensitiveArrays
for the output buffer in EXPORT
and invoke assertIntegrity(..)
after processing it.assertSensitiveResult(..)
in EXPORT
.initManage(..)
before calling this method.updateManage(..)
as needed before finalizing with this method.buffer
- Input buffer for IMPORT
or output buffer for EXPORT
.offset
- Start offset in the buffer for reading or writing.length
- Number of bytes to read or write.TRUE
for IMPORT
; returns the number of bytes successfully read or written for EXPORT
.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 for EXPORT
[3003] or resource already initialized for IMPORT
[3004].INVALID_INIT
: Service not initialized [4080].NOT_ALLOWED
: Certificate verification failed [5080].ILLEGAL_USE
: Invalid input data [6080] or illegal output buffer [6081].initManage(..)
,
updateManage(..)
short getManagedLength(short certResourceId)
certResourceId
- The certificate.CSPException
- with reason:
ILLEGAL_VALUE
: Resource ID does not exist [2001] or is not a CERTIFICATE
[2080].ILLEGAL_CONFIG
: CSP not activated [3001] or resource not initialized [3003].NOT_ALLOWED
: Client not authenticated [5006].void extractPublicKey(short certResourceId, short keyResourceId)
Available for:
Method Behavior:
This method extracts the public key from the provided certificate resource and uses it to initialize the specified public key resource.
It transitions the public key resource from STATE_UNINITIALIZED
to STATE_OPERATIONAL
.
Additionally, it sets a validity date for the public key resource if the certificate includes a validity date and verifies that the key type, size, or curve configured for the public key resource matches the key type, size, or curve of the public key in the certificate.
The method handles access control, counters, timers and events according to Section 6.8.3 of GlobalPlatform Amendment N.
If an error occurs, all changes are rolled back to the state prior to this method's invocation.
Usage Guidelines:
STATE_OPERATIONAL
.clear(..)
if it is not in STATE_UNINITIALIZED
.certResourceId
- Certificate resource.keyResourceId
- Public key resource.CSPException
- for:
ILLEGAL_VALUE
: A resource ID does not exist [2001].ILLEGAL_CONFIG
: Certificate not initialized [3003] or is not a CERTIFICATE
[2080], public key already initialized [3004] or is not a public key [3073].NOT_ALLOWED
: Client not authenticated [5006], Certificate missing ACCESS_USE
[5007], exhausted [50A0], expired [50B1] or public key missing ACCESS_SETUP
[5008].ILLEGAL_USE
: Illegal public key extraction [6082].byte getType(short certResourceId)
certResourceId
- Certificate resource.CSPException
- with reason:
ILLEGAL_VALUE
: Resource ID does not exist [2001] or is not a CERTIFICATE
[2080].NOT_ALLOWED
: Client not authenticated [5006].byte getPublicKeyType(short certResourceId)
Available types:
certResourceId
- Certificate resource.CSPException
- with reason:
ILLEGAL_VALUE
: Resource ID does not exist [2001] or is not a CERTIFICATE
[2080].ILLEGAL_CONFIG
: CSP not activated [3001] or resource not initialized [3003].NOT_ALLOWED
: Client not authenticated [5006].NOT_SUPPORTED
: Certificate type [8081] not supported.byte getPublicKeySize(short certResourceId)
certResourceId
- Certificate resource.CSPException
- with reason:
ILLEGAL_VALUE
: Resource ID does not exist [2001] or is not a CERTIFICATE
[2080].ILLEGAL_CONFIG
: CSP not activated [3001] or resource not initialized [3003].NOT_ALLOWED
: Client not authenticated [5006].NOT_SUPPORTED
: Certificate type [8081] not supported.byte getPublicKeyCurve(short certResourceId)
Available types:
0x01
: CURVE_BRAINPOOL_P256_R1
0x02
: CURVE_BRAINPOOL_P384_R1
0x03
: CURVE_BRAINPOOL_P512_R1
0x04
: CURVE_SEC_P256_R1
0x05
: CURVE_SEC_P384_R1
0x06
: CURVE_SEC_P521_R1
certResourceId
- Certificate resource.CSPException
- with reason:
ILLEGAL_VALUE
: Resource ID does not exist [2001] or is not a CERTIFICATE
[2080].ILLEGAL_CONFIG
: CSP not activated [3001] or resource not initialized [3003].NOT_ALLOWED
: Client not authenticated [5006].NOT_SUPPORTED
: Certificate type [8081] not supported.short getValidityDate(short certResourceId, byte[] outBuffer, short outOffset)
This method returns the validity date in the same format as stored in the certificate.
Usage Guidelines:
CSPSensitiveArrays
for the output buffer and invoke assertIntegrity(..)
after processing it.certResourceId
- Certificate resource.outBuffer
- Output buffer for the validity date.outOffset
- Offset in the output buffer for writing the result.CSPException
- with reason:
ILLEGAL_BUFFER
: Illegal input or output buffer [1001], [1004], [1005], [1006], [1007].ILLEGAL_VALUE
: Resource ID does not exist [2001] or is not a CERTIFICATE
[2080].ILLEGAL_CONFIG
: CSP not activated [3001] or resource not initialized [3003].NOT_ALLOWED
: Client not authenticated [5006].NOT_SUPPORTED
: Certificate type [8081] not supported.short getTagLength(short certResourceId, byte[] tagBuffer, short tagOffset, short tagLength)
This can be used to determine the buffer size needed for extractTag(..)
.
The encoding used is specified by the certificate type of the certificate resource, e.g.,
ASN.1 DER format for CVC
and X509
.
certResourceId
- Certificate resource.tagBuffer
- Buffer containing the tag to search for.tagOffset
- Offset within tagBuffer where the tag starts.tagLength
- Length of the tag within the tagBuffer.CSPException
- with reason:
ILLEGAL_BUFFER
: Illegal input buffer [1002], [1004], [1005].ILLEGAL_VALUE
: Resource ID does not exist [2001], is not a CERTIFICATE
[2080] or tag not found [2082].ILLEGAL_CONFIG
: CSP not activated [3001] or resource not initialized [3003].NOT_ALLOWED
: Client not authenticated [5006].NOT_SUPPORTED
: Certificate type [8081] not supported.short extractTag(short certResourceId, byte[] tagBuffer, short tagOffset, short tagLength, byte[] outBuffer, short outOffset)
Method Behavior:
This method searches for the specified encoded tag within the certificate and, if found,
copies the corresponding value into the provided output buffer.
If the output buffer is too small, no data is written and ILLEGAL_BUFFER
is thrown.
The encoding used is specified by the certificate type of the certificate resource, e.g.,
ASN.1 DER format for CVC
and X509
.
Usage Guidelines:
getTagLength(..)
.certResourceId
- Certificate resource.tagBuffer
- Buffer containing the tag to search for.tagOffset
- Offset within tagBuffer where the tag starts.tagLength
- Length of the tag within the tagBuffer.outBuffer
- Output buffer to hold the extracted tag value.outOffset
- Offset in output buffer for writing.CSPException
- with reason:
ILLEGAL_BUFFER
: Illegal input or output buffer [1001], [1002], [1004], [1005].ILLEGAL_VALUE
: Resource ID does not exist [2001], is not a CERTIFICATE
[2080] or tag not found [2082].ILLEGAL_CONFIG
: CSP not activated [3001] or resource not initialized [3003].NOT_ALLOWED
: Client not authenticated [5006].NOT_SUPPORTED
: Certificate type [8081] not supported.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.