This section explains how to use the Console to configure logs maintained by the Certificate System instance and how to view log contents.
This section contains the following subsections:
The Certificate System subsystems create log files that record events related to activities, such as administration, communications using any of the protocols the server supports, and various other processes employed by the subsystems. While a subsystem instance is running, it keeps a log of information and error messages on all the components it manages. Additionally, the Apache and Tomcat web servers generate error and access logs.
Log plug-in modules are listeners which are implemented as Java™ classes and are registered in the configuration framework.
Each subsystem instance maintains its own log files.
All the log files and rotated log files, except for audit logs, are located in the /var/lib/instance_id/logs directory.
Audit logs, signed and regular, are located in the /var/lib/instance_id/logs/signedAudit directory. The default location for logs can be changed by modifying the configuration.
This log, system, records information about requests to the server (all HTTP and HTTPS requests) and the responses from the server. Information recorded in this log includes the IP address of the client machine that accessed the server; operations performed, such as search, add, and edit; and the result of the access, such as the number of entries returned. This log is on by default.
This log, transactions, records messages specific to the certificate service, such as certificate requests, renewal requests, revocation requests, and CRL publication, and can detect any unauthorized access or activity. This log is on by default.
Debug logs for each subsystem record much more detailed information than system, transaction, and access logs. Debug logs contain very specific information for every operation performed by the subsystem, including plug-ins and servlets which are run, connection information, and server request and response messages.
The general types of services which are recorded to the debug log are briefly discussed in Section 3.9.2, “Services That Are Logged”. These services include authorization requests, processing certificate requests, certificate status checks, and archiving and recovering keys, and access to web services.
For example, the CA contains certificate request information:
[06/Jun/2008:14:59:38][http-9443-Processor24]: ProfileSubmitServlet: key=$request.profileapprovedby$ value=admin [06/Jun/2008:14:59:38][http-9443-Processor24]: ProfileSubmitServlet: key=$request.cert_request$ value=MIIBozCCAZ8wggEFAgQqTfoHMIHHgAECpQ4wDDEKMAgGA1UEAxMBeKaBnzANBgkqhkiG9w0BAQEFAAOBjQAwgYkCgYEA63rhLAVqvVrmdjGgcLTWMb5Czx3DdHLrGO4MS8wfl8EP1bFhKDmxpXYOlsCTznAXby4iinwutOcBXcp2xICrNHwoVZPR2A4ZifIV+vj2qrohyUlTYbL+bTrIWZAnzAW8scKynfMmeRuSPtoBPT1M58SWjB05pTqpuB8Bcc8tEUUCAwEAAakQMA4GA1UdDwEB/wQEAwIF4DAzMBUGCSsGAQUFBwUBAQwIcmVnVG9rZW4wGgYJKwYBBQUHBQECDA1hdXRoZW50aWNhdG9yoYGTMA0GCSqGSIb3DQEBBQUAA4GBAH8Hg6uvDTVC5pDQtWkB4q2DFhou9pcMp1Ar84OX4d2TMoqCQfKBecx3+e423m9PAjTv+ck/xW0Nj8H32krmv7DzWzXkLBD2MSMTmxBORX5dCsxkCdiHCEgCfTOnxCJpdmjHPuSPOaQmtKBpAEVaQoUwnEytOqDkCkhlZ1nt02w1 [06/Jun/2008:14:59:38][http-9443-Processor24]: ProfileSubmitServlet: key=$request.profile$ value=true [06/Jun/2008:14:59:38][http-9443-Processor24]: ProfileSubmitServlet: key=$request.cert_request_type$ value=crmf [06/Jun/2008:14:59:38][http-9443-Processor24]: ProfileSubmitServlet: key=$request.requestversion$ value=1.0.0 [06/Jun/2008:14:59:38][http-9443-Processor24]: ProfileSubmitServlet: key=$request.req_locale$ value=en [06/Jun/2008:14:59:38][http-9443-Processor24]: ProfileSubmitServlet: key=$request.requestowner$ value=RA-test4.redbudcomputer.local-4747 [06/Jun/2008:14:59:38][http-9443-Processor24]: ProfileSubmitServlet: key=$request.dbstatus$ value=NOT_UPDATED [06/Jun/2008:14:59:38][http-9443-Processor24]: ProfileSubmitServlet: key=$request.subject$ value=uid=jsmith, e=jsmith@example.com [06/Jun/2008:14:59:38][http-9443-Processor24]: ProfileSubmitServlet: key=$request.requeststatus$ value=begin [06/Jun/2008:14:59:38][http-9443-Processor24]: ProfileSubmitServlet: key=$request.auth_token.user$ value=uid=RA-test4.redbudcomputer.local-4747,ou=People,dc=test4.redbudcomputer.local-pki-ca [06/Jun/2008:14:59:38][http-9443-Processor24]: ProfileSubmitServlet: key=$request.req_key$ value=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDreuEsBWq9WuZ2MaBwtNYxvkLP^M HcN0cusY7gxLzB+XwQ/VsWEoObGldg6WwJPOcBdvLiKKfC605wFdynbEgKs0fChV^M k9HYDhmJ8hX6+PaquiHJSVNhsv5tOshZkCfMBbyxwrKd8yZ5G5I+2gE9PUznxJaM^M HTmlOqm4HwFxzy0RRQIDAQAB [06/Jun/2008:14:59:38][http-9443-Processor24]: ProfileSubmitServlet: key=$request.auth_token.authmgrinstname$ value=raCertAuth [06/Jun/2008:14:59:38][http-9443-Processor24]: ProfileSubmitServlet: key=$request.auth_token.uid$ value=RA-test4.redbudcomputer.local-4747 [06/Jun/2008:14:59:38][http-9443-Processor24]: ProfileSubmitServlet: key=$request.auth_token.userid$ value=RA-test4.redbudcomputer.local-4747 [06/Jun/2008:14:59:38][http-9443-Processor24]: ProfileSubmitServlet: key=$request.requestor_name$ value= [06/Jun/2008:14:59:38][http-9443-Processor24]: ProfileSubmitServlet: key=$request.profileid$ value=caRAagentCert [06/Jun/2008:14:59:38][http-9443-Processor24]: ProfileSubmitServlet: key=$request.auth_token.userdn$ value=uid=RA-test4.redbudcomputer.local-4747,ou=People,dc=test4.redbudcomputer.local-pki-ca [06/Jun/2008:14:59:38][http-9443-Processor24]: ProfileSubmitServlet: key=$request.requestid$ value=20 [06/Jun/2008:14:59:38][http-9443-Processor24]: ProfileSubmitServlet: key=$request.auth_token.authtime$ value=1212782378071 [06/Jun/2008:14:59:38][http-9443-Processor24]: ProfileSubmitServlet: key=$request.req_x509info$ value=MIICIKADAgECAgEAMA0GCSqGSIb3DQEBBQUAMEAxHjAcBgNVBAoTFVJlZGJ1ZGNv^M bXB1dGVyIERvbWFpbjEeMBwGA1UEAxMVQ2VydGlmaWNhdGUgQXV0aG9yaXR5MB4X^M DTA4MDYwNjE5NTkzOFoXDTA4MTIwMzE5NTkzOFowOzEhMB8GCSqGSIb3DQEJARYS^M anNtaXRoQGV4YW1wbGUuY29tMRYwFAYKCZImiZPyLGQBARMGanNtaXRoMIGfMA0G^M CSqGSIb3DQEBAQUAA4GNADCBiQKBgQDreuEsBWq9WuZ2MaBwtNYxvkLPHcN0cusY^M 7gxLzB+XwQ/VsWEoObGldg6WwJPOcBdvLiKKfC605wFdynbEgKs0fChVk9HYDhmJ^M 8hX6+PaquiHJSVNhsv5tOshZkCfMBbyxwrKd8yZ5G5I+2gE9PUznxJaMHTmlOqm4^M HwFxzy0RRQIDAQABo4HFMIHCMB8GA1UdIwQYMBaAFG8gWeOJIMt+aO8VuQTMzPBU^M 78k8MEoGCCsGAQUFBwEBBD4wPDA6BggrBgEFBQcwAYYuaHR0cDovL3Rlc3Q0LnJl^M ZGJ1ZGNvbXB1dGVyLmxvY2FsOjkwODAvY2Evb2NzcDAOBgNVHQ8BAf8EBAMCBeAw^M HQYDVR0lBBYwFAYIKwYBBQUHAwIGCCsGAQUFBwMEMCQGA1UdEQQdMBuBGSRyZXF1^M ZXN0LnJlcXVlc3Rvcl9lbWFpbCQ=
Likewise, the OCSP shows OCSP request information:
[07/Jul/2008:06:25:40][http-11080-Processor25]: OCSPServlet: OCSP Request: [07/Jul/2008:06:25:40][http-11080-Processor25]: OCSPServlet: MEUwQwIBADA+MDwwOjAJBgUrDgMCGgUABBSEWjCarLE6/BiSiENSsV9kHjqB3QQU
Every time a subsystem is created either through the initial installation or creating additional instances with pkicreate, an installation file with the complete debug output from the installation, including any errors and, if the installation is successful, the URL and PIN to the configuration interface for the instance. The file is created in the default log directory, /var/log, with a name in the form instance_ID-install.log. For example:
/var/log/rhpki-ca-install.log
The self-tests log records information obtained during the self-tests run when the server starts or when the self-tests are manually run. The tests can be viewed by opening this log. This log is not configurable through the Console. This log can only be configured by changing settings in the CS.cfg file. The information about logs in this section does not pertain to this log. See Section 3.10, “Self-Tests” for more information about self-tests.
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. See Section 3.9.13, “Signed Audit Log”.
The CA, RA, DRM, OCSP, and TKS subsystems use a Tomcat web server instance for their agent and end-entities' interfaces. The TPS subsystem uses an Apache web server.
Error and access logs are created by the Apache and Tomcat web servers, which are installed with the Certificate System and provide HTTP services. The error log contains the HTTP error messages the server has encountered. The access log lists access activity through the HTTP interface.
| Apache (TPS) | Tomcat (CA, RA, DRM, OCSP, TKS) |
|---|---|
| access_log | admin.timestamp |
| error_log | catalina.timestamp |
| catalina.out | |
| host-manager.timestamp | |
| localhost.timestamp | |
| localhost_access_log.timestamp | |
| manager.timestamp |
These logs are not available or configurable within the Certificate System; they are only configurable within Apache or Tomcat. See the Apache documentation for information about configuring these logs.
All major components and protocols of Certificate System log messages to log files. Table 3.8, “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 3.9.9, “Monitoring Logs”.
| 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. NOTEHTTP 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. |
The different events logged by Certificate System services are deteremined by the log levels, which makes identifying and filtering events more simple. The different Certificate System log levels are listed in Table 3.9, “Log Levels and Corresponding Log Messages” and Table 3.10, “TPS Log Levels and Log Entries”.
All of the Certificate System subsystems (CA, RA, DRM, TKS, and OCSP) have seven log levels, 0 to 6, except for the TPS subsystem, which has eleven log levels (0 to 10).
Log levels are represented by numbers 0 to 6 (0 to 10 for TPS), each number indicating the level of logging to be performed by the server. The level sets how detailed the logging should be.
| 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.
|
There are an additional four log levels available for TPS subsystem logs:
| Log level | Message category | Description |
|---|---|---|
| 7 | PDU related events (debugging) | These messages contain debugging information for PDU events. This level is not recommended for regular use because it generates too much information for normal use. |
| 8 | PDU related events | These messages relate transactions and rules processed on a PDU, such as creating MAC tokens. |
| 9 | PDU related events | This log levels gives verbose log messages for events processed on a PDU, such as creating MAC tokens. |
| 10 | All logging levels | This log level enabled all logging levels for the TPS logs. |
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.
The Certificate System supports 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.
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. Periodically archive rotated log files to some archive media. Log files are archived by copying the entire /logs directory to an archive medium.
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 3.9.10, “Signing Log Files”.
Signing log files is an alternative to the signed audit logs feature. Signed audit logs creates audit logs that are automatically signed; using signtool manually signs archived logs. See Section 3.9.1.6, “Signed Audit Log” for details about signed audit logs.
By default, rotated log files are not deleted.
This procedure describes how to configure system, transaction, and audit logs.
To configure logs for a Certificate System instance:
Open the Console.
In the navigation tree of the Configuration tab, select Log.
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.
To delete a log instance, select a listener to delete in the Log Event Listener list. Click Delete.
To modify an existing log instance, select a listener to modify in the Log Event Listener list. Click Edit/View.
Change the fields in the Log Event Listener Editor window.
Log Event Listener ID . 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 . The type of log file. Set transaction to create a listener that records audit logs. For error and system logs, select system.
enabled . Select to enable; deselect to disable. Only enabled logs actually record events.
level . Sets the log level. The choices are Debug, Information, Warning, Failure, Misconfiguration, Catastrophe, and Security. The level field does not have a drop-down list. It is a simple text field that needs to be filled in with one of the above categories. For more information, see Section 3.9.3, “Log Levels (Message Categories)”.
fileName . The full path, including the filename, to the file to write messages. The server should have read/write permission to the file.
bufferSize . The buffer size in kilobytes (KB) for the log. The default size is 512 KB. For more information, see Section 3.9.4, “Buffered Versus Unbuffered Logging”. Once the buffer reaches this size, the contents of the buffer are flushed out and copied to the log file.
flushInterval . The interval, in seconds, to flush the buffer to the file. The default interval is 5 seconds. The flushInterval is the amount of time before the contents of the buffer are flushed out and added to the log file.
maxFileSize . The file size in kilobytes (KB) for the error log. The default size is 100 KB. The maxFileSize determines how large 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 anew. For more information, see Section 3.9.5, “Log File Rotation”.
rolloverInterval . Sets the frequency at which the server rotates the active error log file. The available choices are hourly, daily, weekly, monthly, and yearly. The default selection is monthly. For more information, see Section 3.9.5, “Log File Rotation”.
The signed audit log has these additional settings:
logSigning . Enables signed logging. When this parameter is enabled, provide a value for the signedAuditCertNickname parameter. This feature means, the log can only be viewed by an auditor. See Section 3.9.1.6, “Signed Audit Log” for more information about signed audit logs.
signedAuditCertNickname . 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 . Specifies which events are logged to the audit log. Lists each event separated by a comma with no spaces. Events can be removed from the list. See Table 3.11, “Signed Audit Log Events” for a complete list of auditable logging events.
Click OK.
To modify the configuration settings for logs:
Stop the subsystem instance.
Open the CS.cfg file in the /var/lib/instance/conf directory.
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.
To configure a log instance, modify the parameters associated with that log. These parameters begin with log.instance and include the following:
bufferSize . Specify the buffer size in kilobytes (KB) for the log. The default size is 512 KB. For more information, see Section 3.9.4, “Buffered Versus Unbuffered Logging”. Once the buffer reaches this size, the contents of the buffer are flushed out and copied to the log file.
enable . Specify true to enable; false to disable. Only enabled logs actually record events.
fileName . Specify the full path, including the filename, to the file to write messages. The server should have read/write permission to the file.
flushInterval . Specify the interval, in seconds, to flush the buffer to the file. The default interval is 5 seconds. The flushInterval is the amount of time before the contents of the buffer are flushed out and added to the log file.
level . Specify a log level. The choices are 0 for debug, 1 for information, 2 for warning, 3 for failure, 4 for misconfiguration, 5 for catastrophe, and 6 for security. The default selection is 1. For more information, see Section 3.9.3, “Log Levels (Message Categories)”.
maxFileSize . Specify the file size in kilobytes (KB) for the error log. The default size is 100 KB. The maxFileSize determines how large 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 anew. For more information, see Section 3.9.5, “Log File Rotation”.
register . 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.
rolloverInterval . Specify the frequency at which the server rotates the active error log file. The available choices are hourly, daily, weekly, monthly, and yearly. The default selection is monthly. For more information, see Section 3.9.5, “Log File Rotation”.
type . Set to transaction or system.
Save the file.
Start the subsystem instance.
Logging TPS instance activities is handled differently than in the other subsystems. There are three TPS instance logs:
tps-debug.log
tps-error.log
tps-audit.log
These logs are stored in the /var/log/instance_ID directory. Other types of logs, such as transaction logs and system logs, are not generated by the TPS instance.
Additionally, certain log features that are available to the other subsystems' logs do not apply to TPS logging:
Log rotation
Log signing
Registering and deleting log modules
Buffered logging
For each log generated by a TPS instance, there are three parameters which can be configured:
enable, which sets whether the log is generated.
filename, which sets the name and location of the log.
level, which sets the log level, the amount of information, and types of events logged. The log level is a number between 0 and 10. The log levels are described in Section 3.9.3, “Log Levels (Message Categories)”.
Since the TPS subsystem does not utilize an administrative console, the logging levels and log information is configured directly in the CS.cfg file. The following parameters configure the three TPS logs:
logging.audit.enable=true logging.audit.filename=/var/lib/rhpki-tps/logs/tps-audit.log logging.audit.level=10 logging.debug.enable=true logging.debug.filename=/var/lib/rhpki-tps/logs/tps-debug.log logging.debug.level=7 logging.error.enable=true logging.error.filename=/var/lib/rhpki-tps/logs/tps-error.log logging.error.level=10
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. See Section 3.9.1, “About Logs” for information on the location of logs and the log files available.
To view the contents of an active or rotated system log file:
Log into the Console.
Select the Status tab.
Under Logs, select the log to view.
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 3.9.2, “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 3.9.3, “Log Levels (Message Categories)”.
Filename . Select the log file to view. Choose Current to view the currently active system log file.
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 3.9, “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.
To view a full entry, double-click it, or select the entry, and click View.
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 3.9.1.6, “Signed Audit Log” 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 following command with the appropriate information:
signtool -dsecdb_dir-kcert_nickname-Zoutput 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.
It is possible to create new log modules using the CS SDK. New log modules must be registered before they are available for use.
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:
Log into the Console.
In the Configuration tab, select Logs from the navigation tree. Then select the Log Event Listener Plug-in Registration tab.
Click Register.
The Register Log Event Listener Plug-in Implementation window appears.
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.
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 3.9.5, “Log File Rotation”.
To delete a module:
Log into the Console.
In the Configuration tab, select Logs, and then select the Log Event Listener Plug-in Registration tab.
In the Plug-in Name list, select the module to delete, and click Delete.
When prompted, confirm the delete.
The signed audit log creates a log recording system events; the events that are recorded are selected from a list of potential events. This feature, when enabled, records all selected system events and produces a verbose set of messages about the activity. Be careful to provide enough space in the filesystem for this log when using signed audit logs. The signed audit log feature is disabled by default.
The audit logs for a TPS subsystem cannot be signed.
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.
When a log is set as a signed audit log, only a user with auditor privileges can access and view the log. Auditors can use the AuditVerify tool to verify that signed audit logs have not been tampered with.
If there is not a dedicated certificate to sign audit logs, the subsystem signing certificate can be used to sign logs. To do this for a Certificate Manager, specify caSigningCert cert-CA_instance name as the value in the signedAuditCertNickname parameter. For other systems, specify the appropriate signing certificate.
Which events are recorded in the log are configured by adding or deleting the event type from the value of the events parameter. Table 3.11, “Signed Audit Log Events” lists the loggable events. To add an event, add the logging event to the list; to delete an event, remove it from the list. Log events are separated by commas with no spaces.
| Logging Event | Type of Log Messages Generated |
|---|---|
| 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_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_ROLE | A change is made to the configuration settings for roles, including changes made to users or groups. |
| 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 |
The signed audit log expires or is deleted. NOTEThe authorization system should not allow a signed audit log to be deleted. |
| LOG_PATH_CHANGE |
The path or name for the signed audit, system, transaction or any customized log is changed. NOTEThe authorization system should not allow such a change. |
| PRIVATE_KEY_ARCHIVE | Shows when an encryption private key is requested during enrollment. |
| PRIVATE_KEY_ARCHIVE_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_RECOVERY_PROCESSED | Shows when a key recovery has been processed. |
| 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. |
| AUDIT_LOG_SIGNING | Shows when the audit buffer is signed and flushed to disk. |
To set up signed audit logs:
Set up the caAuditCert certificate profile. See Section 13.3, “Setting up Certificate Profiles” for information about setting up certificate profiles.
Approve the caAuditCert certificate profile by approving it in the agent services interface.
If the request for this certificate is received in the end-entities page of a Certificate Manager, enable the caAuditCert profile in that Certificate Manager.
Use the Certificate Setup Wizard to obtain a certificate request for the private keys and certificates that will be used to sign the log files. When running the wizard, specify that the request is of the type Other .
Submit the PKCS#10 request generated to the Manual Log Signing Certificate Enrollment form in the end-entities page of the Certificate Manager that will issue the certificate.
Set the signed audit log . Follow the procedure in the section Section 3.9.6, “Configuring Logs in the Console”. Specify the nickname of the log in the previous step as the value of the signedAuditCertNickname parameter, and set the events that will be logged in the events parameter.
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 17.2, “Creating Users” for details about setting up auditors.
Auditors can view signed audit logs from the IT environment. Auditors can verify logs by using the AuditVerify tool. See the Certificate System Command-Line Tools Guide for details about using this tool.
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 3.9.10, “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.