Home >

SDK Reference Guide > Design Considerations > Audit Logging

Audit Logging

By default, the HSM logs select events to the file hsm.log.

For more robust and verifiable logging, SafeNet HSM (after version 5.2) includes the Audit Logging feature, to log select HSM events to files that can be securely verified for audit purposes.

The HSM creates a log secret unique to the HSM, computed during the first initialization after manufacture. The log secret resides in flash memory (permanent, non-volatile memory), and is used to create log records that are sent to a log file. Later, the log secret is used to prove that a log record originated from a legitimate HSM and has not been tampered with.

Audit Log Records

A log record consists of two fields – the log message and the HMAC for the previous record. When the HSM creates a log record, it uses the log secret to compute the SHA256-HMAC of all data contained in that log message, plus the HMAC of the previous log entry. The HMAC is stored in HSM flash memory. The log message is then transmitted, along with the HMAC of the previous record, to the host. The host has a logging daemon to receive and store the log data on the host hard drive.

For the first log message ever returned from the HSM to the host there is no previous record and, therefore, no HMAC in flash. In this case, the previous HMAC is set to zero and the first HMAC is computed over the first log message concatenated with 32 zero-bytes. The first record in the log file then consists of the first log message plus 32 zero-bytes. The second record consists of the second message plus HMAC1 = HMAC (message1 || 0x0000). This results in the organization shown below.

MSG 1 HMAC 0
  . . .
MSG n-1 HMAC n-2
MSG n HMAC n-1
. . .  
MSG n+m HMAC n+m-1
MSG n+m+1 HMAC n+m
. . .  
MSG end HMAC n+m-1

 

Recent HMAC in NVRAM HMAC end

To verify a sequence of m log records which is a subset of the complete log, starting at index n, the host must submit the data illustrated above. The HSM calculates the HMAC for each record the same way as it did when the record was originally generated, and compares this HMAC to the value it received. If all of the calculated HMACs match the received HMACs, then the entire sequence verifies. If an HMAC doesn’t match, then the associated record and all following records can be considered suspect. Because the HMAC of each message depends on the HMAC of the previous one, inserting or altering messages would cause the calculated HMAC to be invalid.

The HSM always stores the HMAC of the most-recently generated log message in flash memory. When checking truncation, the host would send the newest record in its log to the HSM; and, the HSM would compute the HMAC and compare it to the one in flash. If it does not match, then truncation has occurred.

Audit Log Message Format

Each message is a fixed-length, comma delimited, and newline-terminated string. The table below shows the width and meaning of the fields in a message.

Offset    Length (Chars) Description   
0 10 Sequence number
10 1 Comma
11 17 Timestamp
28 1 Comma
29 256 Message text, interpreted from raw data   
285 1 Comma
286 64 HMAC of previous record as ASCII-HEX   
350 1 Comma   
351 96 Data for this record as ASCII-HEX (raw data)   
447 1 Newline '\n'

The raw data for the message is stored in ASCII-HEX form, along with a human-readable version. Although this format makes the messages larger, it simplifies the verification process, as the HSM expects to receive raw data records.

Example

The following example shows a sample log record. It is separated into multiple lines for readability even though it is a single record. Some white spaces are also omitted.

38,12/08/13 15:30:50,session 1 Access 2147483651:22621 operation LUNA_CREATE_CONTAINER
returned LUNA_RET_SM_UNKNOWN_TOSM_STATE(0x00300014) (using PIN (entry=LUNA_ENTRY_DATA_AREA)),
29C51014B6F131EC67CF48734101BBE301335C25F43EDF8828745C40755ABE25,
2600001003600B00EA552950140030005D580000030000800100000000000000000000000000000000000000
 

The sequence number is “38”. The time is “12/08/13 15:30:50”.

The log message is “session 1 Access 2147483651:22621 operation LUNA_CREATE_CONTAINER returned LUNA_RET_SM_UNKNOWN_TOSM_STATE(0x00300014) (using PIN (entry=LUNA_ENTRY_DATA_AREA))”. In the message text, the “who” is the session identified by “session 1 Access 2147483651:22621” (the application is identified by the access ID major = 2147483651, minor = 22621). The “what” is “LUNA_CREATE_CONTAINER”. The operation status is “LUNA_RET_SM_UNKNOWN_TOSM_STATE(0x00300014)”.

The HMAC of previous record is “29C51014B6F131EC67CF48734101BBE301335C25F43EDF8828745C40755ABE25”.

The remainder is the raw data for this record as ASCII-HEX.

Log External

An important element of the security audit logging feature is the ‘Log External’ function. This SafeNet extension to PKCS #11 allows a user application to insert text of the user’s choice into the log record stream. The function call is CA_LogExternal ( ). It can be used, for example, to insert an application name or the name of the user who is logged into the application and have the inserted text string protected as part of the audit log in the same way as records that have been generated by the HSM itself. It is recommended that applications use the CA_LogExternal ( ) function when the application starts to insert the application name and also to insert the user name each time an individual user logs into or out of the application. The function is called as:

CA_LogExternal(CK_SLOT_ID slotID, CK_SESSION_HANDLE hSession, CK_CHAR_PTR pData, CK_ULONG puldataLen);

where:

slotID is PKCS #11 slot containing the HSM or partition being addressed,

hSession is the handle of the session with which the record is to be associated,

pData is the pointer to the character array containing the external message and

puldataLen is the length of the character array.

Note that the input character array is limited to a maximum of 100 characters and it will be truncated at 100 characters if puldataLen > 100.

For applications that cannot add this function call, it is possible to use the lunacm command-line function audit log external within a startup script to insert a text record at the time the application is started.

When a user logs in to the SafeNet Network HSM lunash:> session, the CA_LogExternal ( ) function is automatically called to register the user name and access ID. Subsequent HSM operations can be tracked by the access ID.

You must configure the “log external” event category in order for the HSM to log the CA_LogExternal() messages.