From ac912bbc14c5520349ef245bf269b657fa323c11 Mon Sep 17 00:00:00 2001 From: Rainer Gerhards Date: Wed, 16 Oct 2013 10:53:22 +0200 Subject: doc: describe mmrfc5424addhmac parameters --- doc/mmrfc5424addhmac.html | 104 ++++++++-------------------------------------- 1 file changed, 17 insertions(+), 87 deletions(-) diff --git a/doc/mmrfc5424addhmac.html b/doc/mmrfc5424addhmac.html index 16065a1f..74638a47 100644 --- a/doc/mmrfc5424addhmac.html +++ b/doc/mmrfc5424addhmac.html @@ -1,31 +1,19 @@ -IP Address Anonimization Module (mmanon) +mmrfc5424addhmac back -

IP Address Anonimization Module (mmanon)

mmrfc5424addhmac

Module Name: mmanon

Author: Rainer Gerhards <rgerhards@adiscon.com>

Available since: 7.3.7

Available since: 7.5.6

Description:

The mmanon module permits to anonymize IP addresses. It is a message -modification module that actually changes the IP address inside the message, -so after calling mmanon, the original message can no longer be obtained. -Note that anonymization will break digital signatures on the message, if -they exist. -

How are IP-Addresses defined? -

We assume that an IP address consists of four octets in dotted notation, -where each of the octets has a value between 0 and 255, inclusively. After -the last octet, there must be either a space or a colon. So, for example, -"1.2.3.4 Test" and "1.2.3.4:514 Test" are detected as containing valid IP -addresses, whereas this is not the case for "1.2.300.4 Test" or -"1.2.3.4-Test". The message text may contain multiple addresses. If so, -each of them is anonimized (according to the same rules). -Important: We may change the set of acceptable characters after -the last octet in the future, if there are good reasons to do so. +

This module adds a hmac to RFC5424 structured data if not already present. +This is a custom module and uses openssl as requested by the sponsor. +This works exclusively for RFC5424 formatted messages; all others are ignored.

Module Configuration Parameters:

@@ -33,86 +21,28 @@ the last octet in the future, if there are good reasons to do so.

Action Confguration Parameters:

mode - default "rewrite"
-There exists the "simple" and "rewrite" mode. In simple mode, only octets -as whole can be anonymized and the length of the message is never changed. -This means that when the last three octets of the address 10.1.12.123 are -anonymized, the result will be 10.0.00.000. This means that the length of the -original octets is still visible and may be used to draw some privacy-evasive -conclusions. This mode is slightly faster than "overwrite" mode, and this -may matter in high throughput environments.
-The default "rewrite" mode will do full anonymization of any number of bits -and it will also normlize the address, so that no information about the -original IP address is available. So in the above example, 10.1.12.123 would -be anonymized to 10.0.0.0. -
ipv4.bits - default 16
-This set the number of bits that should be anonymized (bits are from the -right, so lower bits are anonymized first). This setting permits to save -network information while still anonymizing user-specific data. The more -bits you discard, the better the anonymization obviously is. The default -of 16 bits reflects what German data privacy rules consider as being -sufficinetly anonymized. We assume, this can also be used as a rough -but conservative guideline for other countries.
-Note: when in simple mode, only bits on a byte boundary can be specified. -As such, any value other than 8, 16, 24 or 32 is invalid. If an invalid -value is given, it is rounded to the next byte boundary (so we favor stronger -anonymization in that case). For example, a bit value of 12 will become 16 in -simple mode (an error message is also emitted). -
replacementChar - default "x"
-In simple mode, this sets the character -that the to-be-anonymized part of the IP address is to be overwritten -with. In rewrite mode, this parameter is not permitted, as in -this case we need not necessarily rewrite full octets. As such, the anonymized -part is always zero-filled and replacementChar is of no use. If it is -specified, an error message is emitted and the parameter ignored. +
key
+The "key" (string) to be used to generate the hmac. +
hashfunction
+An openssl hash function name for the function to be used. This is passed +on to openssl, so see the openssl list of supported function names. +
sd_id
+The RFC5424 structured data ID to be used by this module. This is the +SD-ID that will be added. Note that nothing is added if this SD-ID +is already present.

Caveats/Known Bugs:

only IPv4 is supported +
currently none

Samples:

In this snippet, we write one file without anonymization and another one -with the message anonymized. Note that once mmanon has run, access to the -original message is no longer possible (execept if stored in user -variables before anonymization). -

module(load="mmanon") -action(type="omfile" file="/path/to/non-anon.log") -action(type="mmanon") -action(type="omfile" file="/path/to/anon.log") - - -

This next snippet is almost identical to the first one, but -here we anonymize the full IPv4 address. Note that by -modifying the number of bits, you can anonymize different parts -of the address. Keep in mind that in simple mode (used here), the bit values -must match IP address bytes, so for IPv4 only the values 8, 16, 24 and -32 are valid. Also, in this example the replacement is done -via asterisks instead of lower-case "x"-letters. Also keep in mind that -"replacementChar" can only be set in simple mode. -

module(load="mmanon") -action(type="omfile" file="/path/to/non-anon.log") -action(type="mmanon" ipv4.bits="32" mode="simple" replacementChar="*") -action(type="omfile" file="/path/to/anon.log") - - -

The next snippet is also based on the first one, but anonimzes an -"odd" number of bits, 12. The value of 12 is used by some folks as a -compromise between keeping privacy and still permiting to gain some -more in-depth insight from log files. Note that anonymizing 12 bits -may be insufficient to fulfill legal requirements (if such exist). -

module(load="mmanon") -action(type="omfile" file="/path/to/non-anon.log") -action(type="mmanon" ipv4.bits="12") -action(type="omfile" file="/path/to/anon.log") -

[rsyslog.conf overview] [manual index] [rsyslog site]

-- cgit v1.2.3