Compliance warning events

Edit online

CCA can generate warning events for operations that might need modifications to meet requirements for the request to be compliant. In the system log, the compliance warning indicates whether the request was compliant or not, while the request processes normally with no change in behavior noticeable to the application.

Using the system log for warning events

You set the environment variable CSU_CMP_WARN_MODE=SYSLOG to indicate that the generation of warning events is desired.

Warning events are generated for requests that can be successfully made compliant. When the request is potentially compliant, you can convert the used key tokens to compliant-tagged key tokens and the operation is successful.
When the request is non-compliant, the key tokens, the verb, or the verb and rule combination must be updated to be compliant before the key tokens used can be converted to be compliant-tagged.

Warning events are generated for potentially successful requests where at least one of the key tokens that are used is an internal, version 00 or version 01 DES key token and none of the key tokens is already compliant-tagged. This includes external key tokens and output key tokens. For services that do not accept compliant-tagged key tokens, only internal key tokens that are used as input to the service are included in the event. For services that accept compliant-tagged key tokens, all key tokens that are used are included in the event.

Warning events are generated in the form of SYSLOG entries. See Generating warning events for more information and examples.

For detailed information about the format of generated warning events and the required steps for making applications compliant, read Migrating applications to PCI-HSM 2016 compliance mode.

Using an alternative log for warning events

You can control to use an alternative log for warning events in an independent flat text file log that is managed by libcsulcca.so.

This new method is recommended for environments with systemd. Certain configurations of SYSLOG may not consistently be reliable for the purpose of putting every warning log message into the log file within a consistent time frame. This alternative log method is introduced to avoid potentially missing a compliance warning event.

To start using the new system log method, set the following environment variables using the allowed values and restart the application that is linked with libcsulcca.so.

To use the alternative log: export CSU_CMP_WARN_MODE=ALTLOG

To configure the alternative log file management, perform the following steps:

Specify a path to the log files.
The filename is not controlled by the user, but the path to the files is configurable. The path specified must be an absolute path, starting from the root of the filesystem. In practical terms it must begin with a slash ( '/'). Use the following command to set the environment variable for the path:
```
export CSU_CMP_WARN_FILE_PATH=<your-absolute-path>
```
If the environment variable is not set, the default path is used:
```
/tmp
```
Using the default path and the pre-determined file names, the full paths and names would be:
```
/tmp/csucmpwarnlog
/tmp/csucmpwarnlog.1
...
/tmp/csucmpwarnlog.<N>
```
File numbering starts at '0', so that <N> is the maximum count of files minus 1 (maximum - 1).
Define the maximum count of log files.
You can control the count of log files to maintain by using the following command:
```
export CSU_CMP_WARN_FILE_COUNT=<your-maximum-count>
```
The minimum value is 2. The maximum value is 25. The default value is 5.

Therefore a fully populated list of files at the default path and at default count would appear as shown:
```
/tmp/csucmpwarnlog 
/tmp/csucmpwarnlog.1 
/tmp/csucmpwarnlog.2 
/tmp/csucmpwarnlog.3 
/tmp/csucmpwarnlog.4
```
Define the maximum size of the log files.
Control the maximum size of each log file with the following environment variable:
```
export CSU_CMP_WARN_FILE_MAX=<your-maximum-size> 
```
The minimum value is 1048576 (1 MB). The maximum value is 30 * 1048576 (30 MB). The default value is 5 * 1048576 ( 5 MB).
Control the file rotation.
File rotation is triggered when the next log message would not fit into the current log file without increasing the file size beyond the maximum file size (as configured, or the default maximum if not configured).

File rotation proceeds as follows for a maximum file count of N:

The N-2 file is changed to be the N-1 file, the last numbered file, which causes an unlink of the N-1 file if there already was one.
```
/tmp/csucmpwarnlog.<N-2> --> /tmp/csucmpwarnlog.<N-1>
```
Default values are used for all settings:
```
/tmp/csucmpwarnlog.3 --> /tmp/csucmpwarnlog.4
```
This is repeated for (N-3) --> (N-2) and so on, until the file numbered 1 has been changed' to be file numbered 2:
```
/tmp/csucmpwarnlog.1 --> /tmp/csucmpwarnlog.2
```
Then the first file (with no number) is changed to be the file numbered 1:
```
/tmp/csucmpwarnlog --> /tmp/csucmpwarnlog.1
```
Then a new first log file is created and opened, and the pending log message is written to this file.

Notes:

If the CSU_CMP_WARN_FILE_COUNT is reduced, then libcsulcca.so does not manage any files past the new file count maximum number. These must be managed or deleted manually.
The default log file path of /tmp/ is often configured as a memory file-system, a non-persistent store. Therefore configure your own desired path. The default path is a location that is typically not constrained by size or access. It is suitable for initial testing. After this testing, you should select and configure a production store.

Restriction: Cryptographic coprocessors earlier than CEX6C do not respond to a specification of desired warning events. In addition, Linux sometimes buffers log entries before posting them, thus causing a short delay.