diff options
Diffstat (limited to 'doc/mmrfc5424addhmac.html')
| -rw-r--r-- | doc/mmrfc5424addhmac.html | 88 |
1 files changed, 88 insertions, 0 deletions
diff --git a/doc/mmrfc5424addhmac.html b/doc/mmrfc5424addhmac.html new file mode 100644 index 0000000..a54908c --- /dev/null +++ b/doc/mmrfc5424addhmac.html @@ -0,0 +1,88 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html><head> +<meta http-equiv="Content-Language" content="en"> +<title>mmrfc5424addhmac</title></head> + +<body> +<a href="rsyslog_conf_modules.html">back</a> + +<h1>mmrfc5424addhmac</h1> +<p><b>Module Name: mmrfc5424addhmac</b></p> +<p><b>Author: </b>Rainer Gerhards <rgerhards@adiscon.com></p> +<p><b>Available since</b>: 7.5.6</p> +<p><b>Description</b>:</p> +<p>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. +<p>If both <a href="mmpstrucdata.html">mmpstrucdata</a> +and mmrfc5424addhmac are to be used, the recommended calling sequence is +<ol> +<li>mmrfc5424addhmac +<li>mmpstrucdata +</ol> +with that sequence, the generated hash will become available for mmpstrucdata. +<p> </p> + +<p><b>Module Configuration Parameters</b>:</p> +<p>Currently none. +<p> </p> +<p><b>Action Confguration Parameters</b>:</p> +<ul> +<li><b>key</b><br> +The "key" (string) to be used to generate the hmac. +<li><b>hashfunction</b><br> +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. +<li><b>sd_id</b><br> +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. +</ul> + +<p><b>Verification method</b> +<p>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. +<p>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. +<p>So in a more formal description, verification of a message m can be done as follows: +<ol> +<li>let m' be m with the configured SD-ID removed (everything between []). Otherwise, +m' must be an exact duplicate of m. +<li>call openssl's HMAC function as follows:<br> +<code>HMAC(hashfunction, key, len(key), m', len(m'), hash, &hashlen);</code></br> +Where hashfunction and key are the configured values and hash is an output +buffer for the hash. +<li>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. +<li>now compare hash and h under consideration of the sizes. If these values match +the verification succeeds, otherwise the message was modified. +</ol> +<p>If you neeed help implementing a verifier function or want to sponsor development +of a verification tool, please simply email +<a href="sales@adiscon.com">sales@adiscon.com</a> for a quote. + +<p><b>See Also</b> +<ul> +<li><a href="http://www.rsyslog.com/how-to-add-a-hmac-to-rfc5424-structured-data-messages/">How to +add a HMAC to RFC5424 messages</a> +</ul> + +<p><b>Caveats/Known Bugs:</b> +<ul> +<li>none +</ul> + + +<p>[<a href="rsyslog_conf.html">rsyslog.conf overview</a>] [<a href="manual.html">manual +index</a>] [<a href="http://www.rsyslog.com/">rsyslog site</a>]</p> +<p><font size="2">This documentation is part of the +<a href="http://www.rsyslog.com/">rsyslog</a> project.<br> +Copyright © 2013 by <a href="http://www.gerhards.net/rainer">Rainer Gerhards</a> and +<a href="http://www.adiscon.com/">Adiscon</a>. Released under the GNU GPL +version 3 or higher.</font></p> + +</body></html> |