HMAC Message Integrity (pm_hmac)

To protect log messages, this module provides cryptographic checksumming on messages using the HMAC algorithm with a specific hash function. Messages protected this way cannot be altered, deleted, or inserted without detection. A separate verification procedure using the pm_hmac_check module is necessary for the receiver.

This module is being phased out and will be removed in a future release.

When the module starts, it creates an initial random hash value which is signed with the private key and stored in $nxlog.hmac_initial field. As messages pass through the module, it calculates a hash value using the previous hash value, the initial hash value, and the fields of the log message. This calculated value is added to the log message as a new field called $nxlog.hmac, and can be used to later verify the integrity of the message.

If the attacker can insert messages at the source, this module will add an HMAC value and the activity will go unnoticed. This method only secures messages that are already protected with an HMAC value.

For this method to work more securely, the private key should be protected by a password and the password should not be stored with the key (the configuration file should not contain the password). This will force the agent to prompt for the password when it is started.

Configuration

The pm_hmac module accepts the following directives in addition to the common module directives. The CertKeyFile directive is required.

Required directives

The following directives are required for the module to start.

CertKeyFile

This mandatory directive specifies the path of the private key file to be used to sign the initial hash value.

Optional directives

Fields

This directive accepts a comma-separated list of fields. These fields will be used for calculating the HMAC value. This directive is optional, and the $raw_event field will be used if it is not specified.

HashMethod

This directive sets the hash function. The following message digest methods can be used: md2, md5, mdc2, rmd160, sha, sha1, sha224, sha256, sha384, and sha512. The default is md5.

KeyPass

This specifies the password of the CertKeyFile.

Fields

The following fields are used by pm_hmac.

$nxlog.hmac (type: string): The digest value calculated from the log message fields.

$nxlog.hmac_initial (type: string): The initial HMAC value which starts the chain.

$nxlog.hmac_sig (type: string): The signature of nxlog.hmac_initial created with the private key.

Examples

Example 1. Protecting Messages with a HMAC Value

This configuration uses the im_uds module to read log messages from a socket. It then adds a hash value to each message. Finally, it forwards them via TCP to another NXLog Agent instance in the binary format.

nxlog.conf

<Input uds>
    Module      im_uds
    UDS         /dev/log
</Input>

<Processor hmac>
    Module      pm_hmac
    CertKeyFile %CERTDIR%/client-key.pem
    KeyPass     secret
    HashMethod  SHA1
</Processor>

<Output tcp>
    Module      om_tcp
    Host        192.168.1.1:1514
    OutputType  Binary
</Output>

<Route uds_to_tcp>
    Path        uds => hmac => tcp
</Route>