PingDirectory

Encrypting, sanitizing, and signing log files

Log files are useful for understanding server usage patterns and troubleshooting problems, but they can also contain sensitive data like attribute values that might appear in entry DNs or search filters.

Encrypting log files

To protect against exposing sensitive data, the server can log to encrypted files. File-based loggers include the following log encyrption configuration properties:

Property Description

encrypt-log

Indicates whether the log file should be encrypted.

encryption-settings-definition-id

Specifies the ID of the encryption settings definition that should be used to obtain the encryption key. If this is not specified, then the preferred definition is used.

If you need to access data in an encrypted log file, then the encrypt-file tool can be used to decrypt its content. This tool is discussed in more detail in the encrypt-file tool section. However, it might not be necessary to decrypt log files to be able to use them. Both the search-logs and summarize-access-log tools both provide support for operating on encrypted and compressed log files.

In most cases, no special handling is needed, because the log data is encrypted with a definition from the server’s encryption settings database, and the tool can obtain the appropriate definition from that database. However, if the encryption settings database is not available, such as if the tool is run from a system other than the one on which the server is running, or no longer contains the definition that was used to encrypt the log file, then the --encryptionPassphraseFile argument can be used to specify the passphrase used to generate that definition.

For additional information, see the config/sample-dsconfig-batch-files/create-encrypted-loggers.dsconfig batch file.

Sanitizing log files

Another way to prevent unauthorized access to sensitive information in log files is to remove or obscure that information.

The sanitize-log tool can be used to accomplish this. It classifies each log field into one of three categories found in the following table.

To sanitize log content as it’s being written, see Log sanitization.
Category Description

Preserve

The value of the field is preserved as it appeared in the log message. The sanitize-log tool is preconfigured with a set of log fields that should not contain any sensitive information and are considered safe to preserve, but you can add additional fields to this set using the --preserveField argument.

Tokenize

The value of the field is converted into a token, which is a number surrounded by curly braces (for example, the first tokenized value is "{1}", the second is "{2}", and so on). If the field value appears to be a DN or search filter, then only attribute values in that DN or filter are tokenized; otherwise, the entire value is tokenized. The same token is used for the same value every time it appears in a log file, which can make it easier to correlate information across operations without revealing what the value actually is. The tool is preconfigured with a set of log fields that are appropriate for tokenization, but you can add additional fields to this set with the --tokenizeField argument.

Redact

The entire value of the field will be replaced with the string ---REDACTED---. Any field that is not marked for preservation or tokenization is automatically redacted. If you want to redact a field whose value would otherwise be preserved or tokenzied by default, you can use the --redactField argument.

The sanitize-log tool automatically detects whether the log file is encrypted or compressed, and you can also optionally encrypt or compress the output. It provides the following arguments in support of this.

Argument Description

--inputEncryptionPassphraseFile

Specifies the path to a file containing the passphrase needed to decrypt the contents of the log file. This is generally not needed, as log files are encrypted with a key from the encryption settings database and the sanitize-log tool can automatically obtain the appropriate key from that database. However, if that key is not available for some reason, you can use this argument to provide the necessary passphrase.

--compressOutput

Indicates that the sanitized output should be compressed.

--encryptOutput

Indicates that the sanitized output should be encrypted.

--outputEncryptionPassphraseFile

Specifies the path to a file containing the passphrase that is used to encrypt the sanitized output. If this argument is not provided but the --encryptOutput argument is given, then the tool interactively prompts for the passphrase.

Signing log files

Regardless of whether they are encrypted, the server can digitally sign log files to provide a means of verifying that the content has not been altered in any way. This can be controlled by the sign-log property in the configuration for each logger.

Rather than signing log files as a whole, the server signs groups of one or more messages. Each time it writes a set of log messages to disk, a signature is generated for that set of messages. In the event that log messages are altered, or a set of messages are removed from the file, this provides a more fine-grained method for determining which content is trustworthy and which is not. Signature information can also carry over between rotated log files, so it is possible to determine if an entire log file has been removed.

The validate-file-signature tool can be used to verify the signatures in a log file to confirm that the content has not been altered. This tool supports the following arguments.

Argument Description

--file

Specifies the path to the file whose signature should be validated. If a chain of log files should be validated, then this should be the most recent file in the chain.

--encryptionPassphraseFile

Specifies the path to a file containing the passphrase that was used to encrypt the file contents. This should not be necessary if the file was encrypted with a key from the encryption settings database and that key is still accessible. If this argument is not provided and the encryption passphrase cannot be automatically retrieved, then the tool interactively prompts for the passphrase.

--validateLogChain

Indicates that the tool should validate a chain of log files. It starts with the file specified by the --file argument, but if that file was created after rotating from a previous file, then it works its way backwards through the chain of log files.

When the server is restarted, it cannot continue using the same signature chain that it was using before the restart, so the process of validating a chain automatically stops when it encounters a server restart.

--numFiles

Specifies the maximum number of log files in the chain that should be validated. By default, the tool attempts to verify as much of the chain as possible.

--logDuration

Specifies the minimum length of the time span that should be covered by the log content when validating a chain of files. If this is specified, then its value should be given as an integer followed by a time unit (for example, "10 minutes" or "1 day"), and the tool tries to iterate backwards through files in the chain until at least this length of time has been covered.

--ignoreMultipleSignedBlocks

Indicates that the tool should ignore errors that can arise if a log file contains multiple signed blocks. This can happen if the server was restarted and the logger is configured to append to any existing log file rather than rotating it and starting with a fresh log file.

--ignoreMissingEndOfSignature

Indicates that the tool should ignore an error if the target log file does not end with valid signature information. This might happen when trying to validate the active log file with the server still online.

--ignoreMissingFile

Indicates that the tool should ignore an error caused by attempting to follow a log file chain when a file indicates that it was created after rotating from an earlier log file, but that earlier log file does not exist. This might happen if the older log file has been deleted by log retention processing.