⁠14.2. Managing Logs for the Java Subsystems

The Certificate System subsystem log files record events related to operations within that specific subsystem instance. For each subsystem, different logs are kept for issues such as installation, access, and web servers.
The Java subsystems — CA, DRM, OCSP, and TKS — all have similar log configuration, options, and administrative paths.

⁠14.2.1. An Overview of Log Settings

The way that logs are configured can affect Certificate System performance. For example, log file rotation keeps logs from becoming too large, which slows down subsystem performance. This section explains the different kinds of logs recorded by Certificate System subsystems and covers important concepts such as log file rotation, buffered logging, and available log levels.

⁠14.2.1.1. Services That Are Logged

All major components and protocols of Certificate System log messages to log files. Table 14.2, “Services Logged” lists services that are logged by default. To view messages logged by a specific service, customize log settings accordingly. For details, see Section 14.2.2, “Viewing Logs”.
⁠

Table 14.2. Services Logged

Service Description
ACLs Logs events related to access control lists.
Administration Logs events related to administration activities, such as HTTPS communication between the Console and the instance.
All Logs events related to all the services.
Authentication Logs events related to activity with the authentication module.
Certificate Authority Logs events related to the Certificate Manager.
Database Logs events related to activity with the internal database.
HTTP
Logs events related to the HTTP activity of the server.

NOTE

HTTP events are actually logged to the errors log belonging to the Apache server incorporated with the Certificate System to provide HTTP services.
Key Recovery Authority Logs events related to the DRM.
LDAP Logs events related to activity with the LDAP directory, which is used for publishing certificates and CRLs.
OCSP Logs events related to OCSP, such as OCSP status GET requests.
Others Logs events related to other activities, such as command-line utilities and other processes.
Request Queue Logs events related to the request queue activity.
User and Group Logs events related to users and groups of the instance.

⁠14.2.1.2. Log Levels (Message Categories)

The different events logged by Certificate System services are determined by the log levels, which makes identifying and filtering events simpler. The different Certificate System log levels are listed in Table 14.3, “Log Levels and Corresponding Log Messages”.
Log levels are represented by numbers 0 to 6, each number indicating the level of logging to be performed by the server. The level sets how detailed the logging should be.
A higher priority level means less detail because only events of high priority are logged.
For the CA, DRM, TKS, and OCSP, the priority goes from lowest numeric log level to highest. This means that the smaller the log level, the higher the priority. The highest priority log level for the CA, DRM, TKS, and OCSP is 0. A lower priority level means greater detail because more kinds of events are recorded in the log file. The lowest priority log level is 6.
⁠

Table 14.3. Log Levels and Corresponding Log Messages

Log level Message category Description
0 Debugging These messages contain debugging information. This level is not recommended for regular use because it generates too much information.
1 Informational (default selection for audit log) These messages provide general information about the state of the Certificate System, including status messages such as Certificate System initialization complete and Request for operation succeeded.
2 Warning These messages are warnings only and do not indicate any failure in the normal operation of the server.
3 Failure; the default selection for system and error logs These messages indicate errors and failures that prevent the server from operating normally, including failures to perform a certificate service operation (User authentication failed or Certificate revoked) and unexpected situations that can cause irrevocable errors (The server cannot send back the request it processed for a client through the same channel the request came from the client).
4 Misconfiguration These messages indicate that a misconfiguration in the server is causing an error.
5 Catastrophic failure These messages indicate that, because of an error, the service cannot continue running.
6 Security-related events These messages identify occurrences that affect the security of the server. For example, Privileged access attempted by user with revoked or unlisted certificate.
Log levels can be used to filter log entries based on the severity of an event. By default, log level 3 (Failure) is set for all services.
The log level is successive; specifying a value of 3 causes levels 4, 5, and 6 to be logged. Log data can be extensive, especially at lower (more verbose) logging levels. Make sure that the host machine has sufficient disk space for all the log files. It is also important to define the logging level, log rotation, and server-backup policies appropriately so that all the log files are backed up and the host system does not get overloaded; otherwise, information can be lost.

⁠14.2.1.3. Buffered and Unbuffered Logging

The Java subsystems support buffered logging for all types of logs. The server can be configured for either buffered or unbuffered logging.
If buffered logging is configured, the server creates buffers for the corresponding logs and holds the messages in the buffers for as long as possible. The server flushes out the messages to the log files only when one of the following conditions occurs:
  • The buffer gets full. The buffer is full when the buffer size is equal to or greater than the value specified by the bufferSize configuration parameter. The default value for this parameter is 512 KB.
  • The flush interval for the buffer is reached. The flush interval is reached when the time interval since the last buffer flush is equal to or greater than the value specified by the flushInterval configuration parameter. The default value for this parameter is 5 seconds.
  • When current logs are read from Console. The server retrieves the latest log when it is queried for current logs.
If the server is configured for unbuffered logging, the server flushes out messages as they are generated to the log files. Because the server performs an I/O operation (writing to the log file) each time a message is generated, configuring the server for unbuffered logging decreases performance.
Setting log parameters is described in Section 14.2.3, “Configuring Logs in the Console”.

⁠14.2.1.4. Log File Rotation

The subsystem logs have an optional log setting that allows them to be rotated and start a new log file instead of letting log files grow idnefinitely. Log files are rotated when either of the following occur:
  • The size limit for the corresponding file is reached. The size of the corresponding log file is equal to or greater than the value specified by the maxFileSize configuration parameter. The default value for this parameter is 100 KB.
  • The age limit for the corresponding file is reached. The corresponding log file is equal to or older than the interval specified by the rolloverInterval configuration parameter. The default value for this parameter is 2592000 seconds (every thirty days).
When a log file is rotated, the old file is named using the name of the file with an appended time stamp. The appended time stamp is an integer that indicates the date and time the corresponding active log file was rotated. The date and time have the forms YYYYMMDD (year, month, day) and HHMMSS (hour, minute, second).
Log files, especially the audit log file, contain critical information. These files should be periodically archived to some backup medium by copying the entire logs/ directory to an archive medium.

NOTE

The Certificate System does not provide any tool or utility for archiving log files.
The Certificate System provides a command-line utility, signtool, that signs log files before archiving them as a means of tamper detection. For details, see Section 14.2.5.5, “Signing Log Files”.
Signing log files is an alternative to the signed audit logs feature. Signed audit logs create audit logs that are automatically signed with a subsystem signing certificate. See Section 14.2.5.3, “Configuring a Signed Audit Log in the Console” for details about signed audit logs.
By default, rotated log files are not deleted.

⁠14.2.2. Viewing Logs

To troubleshoot the subsystem, check the error or informational messages that the server has logged. Examining the log files can also monitor many aspects of the server's operation. Some log files can be viewed through the Console or by opening the files directly.
To view the contents of an active or rotated system log file:
  1. Log into the Console.
  2. Select the Status tab.
  3. Under Logs, select the log to view.
  4. Set the viewing preferences in the Display Options section.
    • Entries — The maximum number of entries to be displayed. When this limit is reached, the Certificate System returns any entries that match the search request. Zero (0) means no messages are returned. If the field is blank, the server returns every matching entry, regardless of the number found.
    • Source — Select the Certificate System component or service for which log messages are to be displayed. Choosing All means messages logged by all components that log to this file are displayed. For more information, see Section 14.2.1.1, “Services That Are Logged”.
    • Level — Select a message category that represents the log level for filtering messages. For more information on log levels, see Section 14.2.1.2, “Log Levels (Message Categories)”.
    • Filename — Select the log file to view. Choose Current to view the currently active system log file.
  5. Click Refresh.
    The table displays the system log entries. The entries are in reverse chronological order, with the most current entry placed at the top. Use the scroll arrows on the right edge of the panel to scroll through the log entries.
    Each entry has the following information shown:
    • Source — The component or resource that logged the message.
    • Level — The severity of the corresponding entry; see Table 14.3, “Log Levels and Corresponding Log Messages” for more information.
    • Date — The date on which the entry was logged.
    • Time — The time at which the entry was logged.
    • Details — A brief description of the log.
  6. To view a full entry, double-click it, or select the entry, and click View.

⁠14.2.3. Configuring Logs in the Console

Logs can be configured through both the subsystem Console and through the subsystem's CS.cfg file. Specialized logs, such as signed audit logs and custom logs, can also be created through the Console or configuration file.
System, transaction, and audit logs can be configured through the subsystem Console for the CA, OCSP, TKS, and DRM subsystems. TPS logs are only configured through the configuration file.
  1. In the navigation tree of the Configuration tab, select Log.
  2. The Log Event Listener Management tab lists the currently configured listeners.
    To create a new log instance, click Add, and select a module plug-in from the list in the Select Log Event Listener Plug-in Implementation window.
  3. Set or modify the fields in the Log Event Listener Editor window. The different parameters are listed in Table 14.4, “Log Event Listener Fields”.
⁠

Table 14.4. Log Event Listener Fields

Field Description
Log Event Listener ID Gives the unique name that identifies the listener. The names can have any combination of letters (aA to zZ), digits (0 to 9), an underscore (_), and a hyphen (-), but it cannot contain other characters or spaces.
type Gives the type of log file. system creates error and system logs; transaction records audit logs.
enabled Sets whether the log is active. Only enabled logs actually record events. The value is either true or false.
level Sets the log level in the text field. The level must be manually entered in the field; there is no selection menu. The choices are Debug, Information, Warning, Failure, Misconfiguration, Catastrophe, and Security. For more information, see Section 14.2.1.2, “Log Levels (Message Categories)”.
fileName Gives the full path, including the filename, to the log file. The subsystem user should have read/write permission to the file.
bufferSize Sets the buffer size in kilobytes (KB) for the log. Once the buffer reaches this size, the contents of the buffer are flushed out and copied to the log file. The default size is 512 KB. For more information on buffered logging, see Section 14.2.1.3, “Buffered and Unbuffered Logging”.
flushInterval Sets the amount of time before the contents of the buffer are flushed out and added to the log file. The default interval is 5 seconds.
maxFileSize Sets the size, in kilobytes (KB), a log file can become before it is rotated. Once it reaches this size, the file is copied to a rotated file, and the log file is started new. For more information on log file rotation, see Section 14.2.1.4, “Log File Rotation”. The default size is 2000 KB.
rolloverInterval Sets the frequency for the server to rotate the active log file. The available options are hourly, daily, weekly, monthly, and yearly. The default is monthly. For more information, see Section 14.2.1.4, “Log File Rotation”.

⁠14.2.4. Configuring Logs in the CS.cfg File

Along with configuring subsystem logging through the Console, logging can be configured by directory editing the CS.cfg for the instance. This may be a convenience for the CA, OCSP, DRM, and TKS. For the RA and the TPS, this is the only way to configure logging because, with the exception of TPS audit logging, there is no way to configure logging in the RA or TPS administrator web services.
  1. Stop the subsystem instance. 
    service instance_name stop
  2. Open the CS.cfg file in the /var/lib/instance_name/conf directory.
  3. To create a new log, copy all of the entries for either the system or transactions log. These are the parameters that begin with log.instance.Transactions or log.instance.System. Paste all entries at the bottom of the logging section and change the name of this instance by changing the word Transactions or System in each parameter to the new name.
  4. To configure a log instance, modify the parameters associated with that log. These parameters begin with log.instance.
    ⁠

    Table 14.5. Log Entry Parameters

    Parameter Description
    type The type of log file. system creates error and system logs; transaction records audit logs.
    enable Sets whether the log is active. Only enabled logs actually record events.
    level Sets the log level in the text field. The level must be manually entered in the field; there is no selection menu. The log level setting is a numeric value, as listed in Section 14.2.1.2, “Log Levels (Message Categories)”.
    fileName The full path, including the filename, to the log file. The subsystem user should have read/write permission to the file.
    bufferSize The buffer size in kilobytes (KB) for the log. Once the buffer reaches this size, the contents of the buffer are flushed out and copied to the log file. The default size is 512 KB. For more information on buffered logging, see Section 14.2.1.3, “Buffered and Unbuffered Logging”.
    flushInterval The amount of time, in seconds, before the contents of the buffer are flushed out and added to the log file. The default interval is 5 seconds.
    maxFileSize The size, kilobytes (KB), a log file can become before it is rotated. Once it reaches this size, the file is copied to a rotated file, and the log file is started new. For more information on log file rotation, see Section 14.2.1.4, “Log File Rotation”. The default size is 2000 KB.
    rolloverInterval The frequency which the server rotates the active log file. The available choices are hourly, daily, weekly, monthly, and yearly. The default selection is monthly. For more information, see Section 14.2.1.4, “Log File Rotation”.
    register ⁠[a] If this variable is set to false (the default value), the self-test messages are only logged to the log file specified by selftests.container.logger.fileName. If this variable is set to true, then the self-test messages are written to both the log file specified by selftests.container.logger.fileName as well as to the log file specified by log. instance .Transactions. fileName.
    logSigning ⁠[b] Enables signed logging. When this parameter is enabled, provide a value for the signedAuditCertNickname parameter. This option means the log can only be viewed by an auditor. The value is either true or false.
    signedAuditCertNickname[b] The nickname of the certificate used to sign audit logs. The private key for this certificate must be accessible to the subsystem in order for it to sign the log.
    events[b] Specifies which events are logged to the audit log. Table 14.6, “Audit Log Events” lists the loggable events. Log events are separated by commas with no spaces.
    [a] This is for self-test logs only.
    [b] This is for audit logs only.
  5. Save the file.
  6. Start the subsystem instance. 
    service instance_name start

⁠14.2.5. Managing Audit Logs

The audit log contains records for events that have been set up as recordable events. If the logSigning attribute is set to true, the audit log is signed with a log signing certificate belonging to the server. This certificate can be used by auditors to verify that the log has not been tampered with.
By default, regular audit logs are located in the /var/lib/instance_name/logs directory with other types of logs, while signed audit logs are written to /var/lib/instance_name/logs/signedAudit/. The default location for logs can be changed by modifying the configuration.
The signed audit log creates a log recording system events, and the events are selected from a list of potential events. When enabled, signed audit logs record a verbose set of messages about the selected event activity.
Signed audit logs are configured by default when the instance is first created, but it is possible to configure signed audits logs after installation. (See Section 14.2.5.2, “Enabling Signed Audit Logging after Installation”.) It is also possible to edit the configuration or change the signing certificates after configuration, as covered in Section 14.2.5.3, “Configuring a Signed Audit Log in the Console”.

⁠14.2.5.1. A List of Audit Events

⁠

Table 14.6. Audit Log Events

Event Log Messages
AUDIT_LOG_STARTUP The start of the subsystem, and thus the start of the audit function.
AUDIT_LOG_SHUTDOWN The shutdown of the subsystem, and thus the shutdown of the audit function.
ROLE_ASSUME A user assuming a role. A user assumes a role after passing through authentication and authorization systems. Only the default roles of administrator, auditor, and agent are tracked. Custom roles are not tracked.
CONFIG_CERT_PROFILE A change is made to the configuration settings for the certificate profile framework.
CONFIG_CRL_PROFILE A change is made to the configuration settings for the CRL framework, such as to the extensions, frequency, and CRL format.
CONFIG_CERT_POLICY Shows when a change has been made to a certificate's policy configuration.
CONFIG_OCSP_PROFILE A change is made to the configuration settings for the OCSP.
CONFIG_AUTH A change is made to the configuration settings for the authentication framework.
CONFIG_SERIAL_NUMBER A change is made to the serial number range assigned for certificates and keys. This is recorded by CA and DRM subsystems.
SECURITY_DOMAIN_UPDATE The security domain is changed by adding or removing subsystem instances.
CONFIG_SERIAL_NUMBER A change is made to the serial number range assigned for certificates and keys. This is recorded by CA and DRM subsystems.
CONFIG_ACL A change is made to the configuration settings for the ACL framework.
CONFIG_SIGNED_AUDIT A change is made to the configuration settings for the signed audit feature.
CONFIG_ENCRYPTION A change is made to the encryption settings, including certificate settings and SSL cipher preferences.
CONFIG_TRUSTED_PUBLIC_KEY The Certificate Setup Wizard is used to import certificates into the certificate database or any activity in Manage Certificates.
CONFIG_DRM The configuration associated with a DRM changes.
SELFTESTS_EXECUTION The self-tests are executed.
AUDIT_LOG_DELETE ⁠[a]
The signed audit log expires or is deleted.
LOG_PATH_CHANGE ⁠[b]
The path or name for the signed audit, system, transaction or any customized log is changed.
LOG_EXPIRATION_CHANGE Shows when the log expiration time has been changed.
PRIVATE_KEY_ARCHIVE_REQUEST Shows when an encryption private key is requested during enrollment.
PRIVATE_KEY_ARCHIVE_REQUEST_PROCESSED Shows when a private encryption key is archived in the DRM.
KEY_RECOVERY_REQUEST Shows when a request is made to recover a private encryption key stored in the DRM.
KEY_RECOVERY_AGENT_LOGIN Shows when DRM agents log in as recovery agents to approve key recovery requests.
KEY_GEN_ASYMMETRIC Shows when asymmetric keys are generated.
NON_PROFILE_CERT_REQUEST Shows when a certificate request is made outside the certificate profile framework.
PROFILE_CERT_REQUEST Shows when a certificate request is made through the certificate profile framework.
CERT_REQUEST_PROCESSED Shows when a certificate request is being processed.
CERT_STATUS_CHANGE_REQUEST Shows when the request is made to change the status of a certificate.
CERT_STATUS_CHANGE_REQUEST_PROCESSED Shows when a certificate status change is processed.
AUTHZ_SUCCESS Shows when a user is successfully processed by the authorization servlets.
AUTHZ_FAIL Shows when a user is not successfully processed by the authorization servlets.
INTER_BOUNDARY Records stat transfer between different subsystems.
AUTH_FAIL Shows when a user does not successfully authenticate.
AUTH_SUCCESS Shows when a user successfully authenticates.
CERT_PROFILE_APPROVAL Shows when a certificate profile sent by an administrator is approved by an agent.
PROOF_OF_POSSESSION Shows when proof of possession is checked during certificate enrollment.
CRL_RETRIEVAL Shows when a CRL is retrieved by the OCSP.
CRL_VALIDATION Shows when a CRL is retrieved and the validation process occurs.
CMC_SIGNED_REQUEST_SIG_VERIFY Used when CMC (agent pre-signed) certificate requests or revocation requests are submitted and the signature is verified.
COMPUTE_SESSION_KEY_REQUEST Shows when a request to compute a session key has been received by the TKS.
COMPUTE_SESSION_KEY_REQUEST_PROCESSED_SUCCESS Shows when a request to compute a session key has been succesfully processed by the TKS.
COMPUTE_SESSION_KEY_REQUEST_PROCESSED_FAILURE Shows when a request to compute a session key has been processed by the TKS and failed.
DIVERSIFY_KEY_REQUEST Shows when a request has been made for a key changeover.
DIVERSIFY_KEY_REQUEST_PROCESSED_SUCCESS Shows when a request for key changeover has been successfully processed by the TKS.
DIVERSIFY_KEY_REQUEST_PROCESSED_FAILURE Shows when a request key changeover has been request failed to process correctly.
ENCRYPT_DATA_REQUEST Shows when a request has been made to encrypt data.
ENCRYPT_DATA_REQUEST_PROCESSED_SUCCESS Shows when a request for encrypted data has been successfully processed.
ENCRYPT_DATA_REQUEST_PROCESSED_FAILURE Shows when a request for encrypted data failed to process.
COMPUTE_RANDOM_DATA_REQUEST Shows when a request has been made to generate or derive a random data set.
COMPUTE_RANDOM_DATA_REQUEST_PROCESSED_SUCCESS Shows when a request to generatea random data set has been successfully processed.
COMPUTE_RANDOM_DATA_REQUEST_PROCESSED_FAILURE Shows when a request to generatea random data set failed to process.
PRIVATE_KEY_EXPORT_REQUEST_PROCESSED_SUCCESS Shows when a private key export request has been successfully processed.
PRIVATE_KEY_EXPORT_REQUEST_PROCESSED_FAILURE Shows when a private key export request has been processed and returned a failed status.
SERVER_SIDE_KEYGEN_REQUEST Shows when a server-side key generation request has been processed.
SERVER_SIDE_KEYGEN_REQUEST_PROCESSED_SUCCESS Shows when a server-side key generation request has been successfully processed.
SERVER_SIDE_KEYGEN_REQUEST_PROCESSED_FAILURE Shows when a server-side key generation request has been processed but returned a failed status.
KEY_RECOVERY_REQUEST_ASYNC Shows when an asynchronous key recovery request has been made.
KEY_RECOVERY_REQUEST_PROCESSED Shows when a key recovery request has been processed.
KEY_RECOVERY_REQUEST_PROCESSED_ASYNC Shows when an asynchronous key recovery request has been processed.
CIMC_CERT_VERIFICATION Shows when a router (Cisco Integrated Management Controller) certificate verification request has been processed.
OCSP_ADD_CA_REQUEST Shows when a request has been made to add a new certificate authority to the OCSP Manager's configuration.
OCSP_ADD_CA_REQUEST_PROCESSED Shows when a request to add a certificate authority to the OCSP Manager's configuration has been completed.
OCSP_REMOVE_CA_REQUEST Shows when a request to remove a certificate authority from the OCSP Manager's configuration has been submitted.
OCSP_REMOVE_CA_REQUEST_PROCESSED_SUCCESS Shows when a request to remove a certificate authority from the OCSP Manager's configuration has been successfully completed.
OCSP_REMOVE_CA_REQUEST_PROCESSED_FAILURE Shows when a request to remove a certificate authority from the OCSP Manager's configuration has failed.
[a] The authorization system should not allow a signed audit log to be deleted.
[b] The authorization system should not allow the log path or name to be changed.

⁠14.2.5.2. Enabling Signed Audit Logging after Installation

Signed audit logs can be enabled by default when an instance is first created by using the -audit_group option with pkicreate. If, however, signed audit logs were not configured when an instance was created, they can be enabled afterwards by reassigning ownership of the audit log directory to the auditor system users group, such as pkiaudit.
  1. Stop the instance: 
    service instance_name stop
  2. Set the group ownership of the signed audit log directory to the PKI auditors operating system group, such as pkiaudit. This allows the users in the PKI auditors group to have the required read access to the signedAudit directory to verify the signatures on the log files. No user (except for the Certificate System user account, pkiuser) should have write access to the log files in this directory. 
    chgrp -R pkiaudit /var/logs/instance_name/signedAudit
  3. Restart the instance: 
    service instance_name start

⁠14.2.5.3. Configuring a Signed Audit Log in the Console

Signed audit logs are configured by default when the instance is first created, but it is possible to edit the configuration or change the signing certificates after configuration.

TIP

Provide enough space in the filesystem for the signed audit logs, since they can be large.

NOTE

The audit logs for an RA subsystem cannot be signed. TPS audit log signing is described in Section 14.3.3.2, “Configuring TPS Signed Audit Logging”.
A log is set to a signed audit log by setting the logSigning parameter to enable and providing the nickname of the certificate used to sign the log. A special log signing certificate is created when the CA, DRM, OCSP, TKS, and TPS subsystems are first configured.
Only a user with auditor privileges can access and view a signed audit log. Auditors can use the AuditVerify tool to verify that signed audit logs have not been tampered with.
The signed audit log is created and enabled when the subsystem is configured, but it needs additional configuration to begin creating and signing audit logs.
  1. Open the Console.

    NOTE

    To create or configure the audit log by editing the CS.cfg file, see Section 14.2.4, “Configuring Logs in the CS.cfg File”.
  2. In the navigation tree of the Configuration tab, select Log.
  3. In the Log Event Listener Management tab, select the SignedAudit entry.
  4. Click Edit/View.
  5. There are three fields which must be reset in the Log Event Listener Editor window.
    • Fill in the signedAuditCertNickname. This is the nickname of the certificate used to sign audit logs. An audit signing certificate is created when the subsystem is configured; it has a nickname like auditSigningCert cert-pki-ca.

      TIP

      To get the audit signing certificate nickname, list the certificates in the subsystem's certificate database using certutil. For example: 
      certutil -L -d /var/lib/pki-ca/alias

Certificate Authority - Example Domain    CT,c,
subsystemCert cert-subsystem              u,u,u
Server-Cert cert-example                  u,u,u
signedAuditCert cert-example              u,u,Pu
    • Set the logSigning field to true to enable signed logging.
    • Set any events which are logged to the audit log. Table 14.6, “Audit Log Events” lists the loggable events. Log events are separated by commas with no spaces.
  6. Set any other settings for the log, such as the filename, the log level, the file size, or the rotation schedule.

    NOTE

    By default, regular audit logs are located in the /var/lib/instance_name/logs directory with other types of logs, while signed audit logs are written to /var/lib/instance_name/logs/signedAudit/. The default location for logs can be changed by modifying the configuration.
  7. Save the log configuration.
After enabling signed audit logging, assign auditor users by creating the user and assigning that entry to the auditor group. Members of the auditor group are the only users who can view and verify the signed audit log. See Section 13.4.2.1, “Creating Users” for details about setting up auditors.
Auditors can verify logs by using the AuditVerify tool. See the Certificate System Command-Line Tools Guide for details about using this tool.

⁠14.2.5.4. Handling Audit Logging Failures

There are events that could cause the audit logging function to fail, so events cannot be written to the log. For example, audit logging can fail when the filesystem containing the audit log file is full or when the file permissions for the log file are accidentally changed. If audit logging fails, the Certificate System instance shuts down in the following manner.
  • Servlets are disabled and will not process new requests.
  • All pending and new requests are killed.
  • The subsystem is shut down.
When this happens, administrators and auditors should work together with the operating system administrator to resolve the disk space or file permission issues. When the IT problem is resolved, the auditor should make sure that the last audit log entries are signed. If not, they should be preserved by manual signing (Section 14.2.5.5, “Signing Log Files”), archived, and removed to prevent audit verification failures in the future. When this is completed, the administrators can restart the Certificate System.

⁠14.2.5.5. Signing Log Files

The Certificate System can digitally sign log files before they are archived or distributed for audit purposes. This feature allows files to be checked for tampering.
This is an alternative to the signed audit logs feature. The signed audit log feature creates audit logs that are automatically signed; this tool manually signs archived logs. See Section 14.2.5.3, “Configuring a Signed Audit Log in the Console” for details about signed audit logs.
For signing log files, use a command-line utility called the Signing Tool (signtool). For details about this utility, see http://www.mozilla.org/projects/security/pki/nss/tools/.
The utility uses information in the certificate, key, and security module databases of the subsystem instance.
To sign the log directories, use the signtool command: 
signtool -d secdb_dir -k cert_nickname -Z output input
  • secdb_dir specifies the path to the directory that contains the certificate, key, and security module databases for the CA.
  • cert_nickname specifies the nickname of the certificate to use for signing.
  • output specifies the name of the JAR file (a signed zip file).
  • input specifies the path to the directory that contains the log files.

⁠14.2.6. Managing Log Modules

The types of logs that are allowed and their behaviors are configured through log module plug-ins. New logging modules can be created and used to make custom logs.
New log plug-in modules can be registered through the Console. Registering a new module involves specifying the name of the module and the full name of the Java™ class that implements the log interface.
Before registering a plug-in module, put the Java™ class for the module in the classes directory; the implementation must be on the class path.
To register a log plug-in module with a subsystem instance:
  1. Optional. Download the job samples from the Certificate System Java SDK and edit an existing log module. For example: 
    wget http://docs.redhat.com/docs/en-US/Red_Hat_Certificate_System/7.1/html/Certificate_System_SDK/samples/logs/com/netscape/cms/logging/NTEventLog.html
  2. Create the custom job class. For this example, the custom log plug-in is called MyLog.java.
  3. Compile the new class. 
    javac -d . -classpath $CLASSPATH MyLog.java
  4. Create a directory in the CA's WEB-INF web directory to hold the custom classes, so that the CA can access them. 
    mkdir /var/lib/pki-ca/webapps/ca/WEB-INF/classes
  5. Copy the new plug-in files into the new classes directory, and set the owner to the Certificate System system user (pkiuser). 
    cp -pr com /var/lib/pki-ca/webapps/ca/WEB-INF/classes

chown -R pkiuser:pkiuser /var/lib/pki-ca/webapps/ca/WEB-INF/classes
  6. Register the plug-in.
    1. Log into the Console.
    2. In the Configuration tab, select Logs from the navigation tree. Then select the Log Event Listener Plug-in Registration tab.
    3. Click Register.
      The Register Log Event Listener Plug-in Implementation window appears.
    4. Give the name for the plug-in module and the Java™ class name.
      The Java™ class name is the full path to the implementing Java™ class. If this class is part of a package, include the package name. For example, registering a class named customLog in a package named com.customplugins, the class name would be com.customplugins.customLog.
    5. Click OK.
Unwanted log plug-in modules can be deleted through the Console. Before deleting a module, delete all the listeners based on this module; see Section 14.2.1.4, “Log File Rotation”.