public interface AuditService extends CSPService
Provides secure auditing, generating signed, integrity-protected log messages for system and resource events.
AuditListener
: Notifies Client Applications of new events.notifyPendingEvents()
method triggers the AuditListener
.dequeueEvent(..)
method signs and fetches log messages from the audit event queue.getNumberOfPendingEvents()
and getRemainingCapacity()
methods provide queue capacity details.When an event occurs, the CSP stores it in an internal queue. Due to limited storage, the Client Application must fetch events regularly. To manage a full audit queue, the CSP Admin can configure the following behavior options:
AUDIT_MODE_OFF
: Audit logging is deactivated.AUDIT_MODE_OVERWRITE
: The oldest event is overwritten when the queue is full.AUDIT_MODE_STRICT
: The CSP throws a CSPException#INVALID_INIT
if the queue is full.
Events to be logged must be pre-configured by the CSP Admin and cannot be selected via the CSP-API.
Supported event types are defined in GlobalPlatform Amendment N [GPC_SPE_230] and may include:
Category | Event | Value (Hex) | Value (Int) |
---|---|---|---|
General | EVENT_CSP_START | 0x0001 | 1 |
General | EVENT_CSP_UPDATE_STARTED | 0x0002 | 2 |
General | EVENT_CSP_UPDATE_FINISHED | 0x0003 | 3 |
General | EVENT_CSP_CONFIG_UPDATED | 0x0004 | 4 |
General | EVENT_CSP_ERROR | 0x0005 | 5 |
General | EVENT_RESOURCE_CLEARED | 0x1000 | 4096 |
General | EVENT_RESOURCE_VALUE_SET | 0x1001 | 4097 |
Cipher | EVENT_CIPHER_ENCRYPTED | 0x1010 | 4112 |
Cipher | EVENT_CIPHER_DECRYPTED | 0x1011 | 4113 |
Signature | EVENT_SIGNATURE_CREATED | 0x1020 | 4128 |
Signature | EVENT_SIGNATURE_VERIFIED | 0x1021 | 4129 |
Signature | EVENT_SIGNATURE_VERIFICATION_FAILED | 0x1022 | 4130 |
Secure Channel | EVENT_SECURE_CHANNEL_ESTABLISHED | 0x1040 | 4160 |
Secure Channel | EVENT_SECURE_CHANNEL_AUTHENTICATION_FAILED | 0x1041 | 4161 |
Key | EVENT_KEY_GENERATED | 0x1070 | 4208 |
Key | EVENT_KEY_DERIVED | 0x1071 | 4209 |
Key | EVENT_KEY_SHARED_SECRET_COMPUTED | 0x1072 | 4210 |
Key | EVENT_KEY_PUBLIC_VALUE_SET | 0x1073 | 4211 |
Certificate | EVENT_KEY_CERTIFICATE_VALUE_SET | 0x1080 | 4224 |
Password | EVENT_PASSWORD_UPDATED | 0x1090 | 4240 |
Password | EVENT_PASSWORD_UPDATE_FAILED | 0x1091 | 4241 |
Password | EVENT_PASSWORD_AUTHENTICATED | 0x1092 | 4242 |
Password | EVENT_PASSWORD_CHECK_FAILED | 0x1093 | 4243 |
Password | EVENT_PASSWORD_BLOCKED | 0x1094 | 4244 |
Password | EVENT_PASSWORD_UNBLOCKED | 0x1095 | 4245 |
Counter | EVENT_COUNTER_EXHAUSTED | 0x10A0 | 4256 |
Timer | EVENT_TIMER_EXPIRED | 0x10B0 | 4272 |
Timer | EVENT_CSP_SET_TIME | 0x00B0 | 176 |
Offloading | EVENT_RESOURCE_IMPORTED | 0x10D0 | 4304 |
Offloading | EVENT_RESOURCE_EXPORTED | 0x10D1 | 4305 |
Audit mode and the events to be logged, the log message format and signature algorithms must be configured by the CSP Admin and cannot be selected via the CSP-API. 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 the signing key to sign audit log messages CSPCreateResource(AUDIT_KEY_ID, KEY_ECC_PRIVATE, CURVE_BRAINPOOL_P256_R1) CSPConfigureResource(AUDIT_KEY_ID, USAGE_AUDIT, SIG_ECDSA) // Configure audit settings CSPSetup( auditMode=AUDIT_MODE_OVERWRITE, auditSigningKeyId=AUDIT_KEY_ID, signatureFields=[FIELD_SYSTEM_TIME, FIELD_USAGE_COUNTER], systemEvents=[EVENT_CSP_SET_TIME] ) // Create signature key and configure that the signing operations shall be counted and logged CSPCreateResource(SIG_KEY_ID, KEY_ECC_PRIVATE, CURVE_BRAINPOOL_P256_R1) CSPConfigureResource(SIG_KEY_ID, SIG_ECDSA, [EVENT_SIGNATURE_CREATED]) // Create PIN and configure that failed password verifications shall be logged CSPCreateResource(PIN_ID, PWD_NUMERIC, minSize=5, maxSize=5) CSPConfigureResource(PIN_ID, [EVENT_PASSWORD_CHECK_FAILED, EVENT_PASSWORD_BLOCKED])
AuditListener
RESULT_FALSE, RESULT_TRUE
Modifier and Type | Method and Description |
---|---|
short |
dequeueEvent(byte[] inputData,
short inputOffset,
short inputLength,
byte[] outBuffer,
short outOffset)
Generate the log message for the oldest event and remove it from the queue.
|
short |
getNumberOfPendingEvents()
Retrieve the current number of pending events in the audit event queue.
|
short |
getRemainingCapacity()
Retrieve the remaining capacity of the audit event queue.
|
short |
notifyPendingEvents()
Returns
TRUE if there are pending events. |
assertSensitiveResult
short notifyPendingEvents()
TRUE
if there are pending events.
This method should be called after system boot to check for events that occurred before the last boot.
If the queue is not empty, the CSP notifies the Client Application via
AuditListener.auditEventsPending(..)
.
If called with no pending events, it returns 0
without throwing an exception.
TRUE
if events are pending; otherwise FALSE
.CSPException
- with reason:
NOT_ALLOWED
: Client not authenticated [5006].AuditListener.auditEventOccurred(..)
short getRemainingCapacity()
dequeueEvent(..)
.
If zero, the next event may overwrite the oldest one, depending on the audit mode configured. See Section 6.12.2 of GlobalPlatform Amendment N.
CSPException
- with reason:
NOT_ALLOWED
: Client not authenticated [5006].dequeueEvent(..)
short getNumberOfPendingEvents()
dequeueEvent(..)
.CSPException
- with reason:
NOT_ALLOWED
: Client not authenticated [5006].dequeueEvent(..)
short dequeueEvent(byte[] inputData, short inputOffset, short inputLength, byte[] outBuffer, short outOffset)
Method Behavior:
This method creates the log message, adds input data and signature fields, and signs the result using the signature algorithm configured to the audit key.
Signature fields, like system time or counter values, configured to the audit signing key are integrated into the log message; see Section 6.2.1.5 of GlobalPlatform Amendment N.
If called with no pending events, this method returns 0
and does not write to the output buffer, without throwing an exception.
Editor's Note: Please provide feedback if throwing an exception would be better.
The method handles access control, counters, timers and events configured to the audit key according to Section 6.12.3 of GlobalPlatform Amendment.
Usage Guidelines:
CSPSensitiveArrays
for the input data.CSPSensitiveArrays
for the output buffer and invoke assertIntegrity(..)
after processing it.assertSensitiveResult(..)
.inputData
- Input data to be added to the log message, can be null
.inputOffset
- Offset in the input buffer to start reading; can be 0
.inputLength
- Length of the input data in bytes; can be 0
.outBuffer
- Output buffer for the log message.outOffset
- Offset in the output buffer for writing the log message.CSPException
- with reason:
ILLEGAL_BUFFER
: Illegal input or output buffer [1001], [1003], [1004], [1005], [1006], [1007].ILLEGAL_CONFIG
: CSP not activated [3001], no audit key configured [30C0], missing resource [3002], resource not initialized [3003] or inconsistent signature configuration [3020].NOT_ALLOWED
: Client not authenticated [5006] or resource missing ACCESS_USE
[5007], not configured for USAGE_AUDIT
[50C0], exhausted [50A0] or expired [50B1].NOT_SUPPORTED
: Padding algorithm [8011], hash algorithm [8021] or signature algorithm [8022] 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.