From 7ccedc242ee2c2d97cf37a02e16e0b9c00f3766e Mon Sep 17 00:00:00 2001 From: Rainer Gerhards Date: Thu, 26 Sep 2013 15:53:27 +0200 Subject: change version number to reflect custom branch --- configure.ac | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/configure.ac b/configure.ac index 987d1f85..4263d8e5 100644 --- a/configure.ac +++ b/configure.ac @@ -2,7 +2,7 @@ # Process this file with autoconf to produce a configure script. AC_PREREQ(2.61) -AC_INIT([rsyslog],[7.4.4],[rsyslog@lists.adiscon.com]) +AC_INIT([rsyslog],[7.4.4.c10.1],[rsyslog@lists.adiscon.com]) AM_INIT_AUTOMAKE m4_ifdef([AM_SILENT_RULES], [AM_SILENT_RULES([yes])]) -- cgit v1.2.3 From 20bf00187c7bdd6a1baab6fd99477cab375cfb56 Mon Sep 17 00:00:00 2001 From: Rainer Gerhards Date: Tue, 15 Oct 2013 15:53:50 +0200 Subject: doc: add base doc for mmrfc5424addhmac while it probably is not of general interest, at least some rough facts are conveyed. --- doc/mmrfc5424addhmac.html | 119 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 119 insertions(+) create mode 100644 doc/mmrfc5424addhmac.html diff --git a/doc/mmrfc5424addhmac.html b/doc/mmrfc5424addhmac.html new file mode 100644 index 00000000..16065a1f --- /dev/null +++ b/doc/mmrfc5424addhmac.html @@ -0,0 +1,119 @@ + + + +IP Address Anonimization Module (mmanon) + + +back + +

IP Address Anonimization Module (mmanon)

+

Module Name:    mmanon

+

Author: Rainer Gerhards <rgerhards@adiscon.com>

+

Available since: 7.3.7

+

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. +

 

+ +

Module Configuration Parameters:

+

Currently none. +

 

+

Action Confguration Parameters:

+ + +

Caveats/Known Bugs: +

+ +

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). +

+ +

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. +

+ +

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). +

+ +

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

+

This documentation is part of the +rsyslog project.
+Copyright © 2008-2013 by Rainer Gerhards and +Adiscon. Released under the GNU GPL +version 3 or higher.

+ + -- cgit v1.2.3 From db2f23d4f6cdb293fd34c8528b96ed43eafa0e16 Mon Sep 17 00:00:00 2001 From: Rainer Gerhards Date: Wed, 16 Oct 2013 10:14:36 +0200 Subject: doc: describe mmrfc5424addhmac log verification method --- doc/mmrfc5424addhmac.html | 28 +++++++++++++++++++++++++++- 1 file changed, 27 insertions(+), 1 deletion(-) diff --git a/doc/mmrfc5424addhmac.html b/doc/mmrfc5424addhmac.html index 16065a1f..9b68da80 100644 --- a/doc/mmrfc5424addhmac.html +++ b/doc/mmrfc5424addhmac.html @@ -67,9 +67,35 @@ part is always zero-filled and replacementChar is of no use. If it is specified, an error message is emitted and the parameter ignored. +

Verification method +

rsyslog does not contain any tools to verify a log file (this was not +part of the custom project). So you need to write your own verifier. +

When writing the verifier, keep in mind that the log file contains messages +with the hash SD-ID included. For obvious reasons, this SD-ID was not present when +the hash was created. So before the actual verification is done, this SD-ID must be +removed, and the remaining (original) message be verified. Also, it is important to +note that the output template must write the exact same message format that was +received. Otherwise, a verification failure will obviously occur - and must +so, because the message content actually was altered. +

So in a more formal description, verification of a message m can be done as follows: +

    +
  1. let m' be m with the configured SD-ID removed (everything between []). Otherwise, +m' must be an exact duplicate of m. +
  2. call openssl's HMAC function as follows:
    +HMAC(hashfunction, key, len(key), m', len(m'), hash, &hashlen);
    +Where hashfunction and key are the configured values and hash is an output +buffer for the hash. +
  3. let h be the extracted hash value obtained from m within the relevant SD-ID. Be sure to convert the hex string back to the actual byte values. +
  4. now compare hash and h under consideration of the sizes. If these values match +the verification succeeds, otherwise the message was modified. +
+

If you neeed help implementing a verifier function or want to sponsor development +of a verification tool, please simply email +sales@adiscon.com for a quote. +

Caveats/Known Bugs:

    -
  • only IPv4 is supported +
  • none

Samples:

-- cgit v1.2.3 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). -

- -

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. -

- -

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). -

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

This documentation is part of the rsyslog project.
-Copyright © 2008-2013 by Rainer Gerhards and +Copyright © 2013 by Rainer Gerhards and Adiscon. Released under the GNU GPL version 3 or higher.

-- cgit v1.2.3 From 5fd3d8e59334fac9bb21062d66d83fce511c8af9 Mon Sep 17 00:00:00 2001 From: Rainer Gerhards Date: Wed, 16 Oct 2013 11:09:13 +0200 Subject: doc: linking between mmrfc5424addhmac resources --- doc/mmrfc5424addhmac.html | 6 ++++++ doc/rsyslog_conf_modules.html | 2 ++ 2 files changed, 8 insertions(+) diff --git a/doc/mmrfc5424addhmac.html b/doc/mmrfc5424addhmac.html index 2e386d6f..a54908c4 100644 --- a/doc/mmrfc5424addhmac.html +++ b/doc/mmrfc5424addhmac.html @@ -65,6 +65,12 @@ the verification succeeds, otherwise the message was modified. of a verification tool, please simply email sales@adiscon.com for a quote. +

See Also +

+

Caveats/Known Bugs:

  • none diff --git a/doc/rsyslog_conf_modules.html b/doc/rsyslog_conf_modules.html index 18d6b8a1..858e4954 100644 --- a/doc/rsyslog_conf_modules.html +++ b/doc/rsyslog_conf_modules.html @@ -118,6 +118,8 @@ enabled structured log messages.
  • mmsnmptrapd - uses information provided by snmptrapd inside the tag to correct the original sender system and priority of messages. Implemented via the output module interface. +
  • mmrfc5424addhmac - custom module for adding HMACs to +rfc5424-formatted messages if not already present

String Generator Modules

-- cgit v1.2.3