Copyright (C) 2009, 2010, 2011, 2012, 2013, 2014, 2015 Free Software
Foundation, Inc.

This file is free documentation; the Free Software Foundation gives
unlimited permission to copy, distribute and modify it.

## What Log4Legal is?

**Log4Legal is a tool that allows you to generate a library for records of logs allowing signatures at the register lines and subsequently used for legal purposes and operational security in the company.**

In addition, the Log4Legal performance is extraordinary (better than any of his)
competitors) and can be used in high-performance information systems without any
problem. Aside from the special format of the lines and the considerations of
performance is a tool, that once deployed, it is extremely simple to use as it is 
basically an instruction type printf for code C/C++ which submits to the corresponding 
line log file to register.

Note: up to here sounds good but as you'll see, if you are still reading, is not a
tool for newbies.

But, the performance achieved with Log4Legal has a price. To achieve this, it I have 
intentionally abused programming macros and decisions in time of compilation which 
makes her a little hard configuration/installation.

And obviously, this implies that the size of the generated binary will be significantly
greater (or not) than others achieved with a functions based version rather than macros.

## What does the "_Hello world!_" registration looks like?. 
The source that would achieve this feat would be the following:

1. `#include <string.h>`
2. `#include <stdio.h>`
3. `#include "l4l.h"`
4. `int main(int argc, char **argv) {`
5. `     int rc;`
6. `     rc = l4l_init("log.cfg","test",argc,argv);`
7. `     l4l_printf(0xFFFFFFFF,L4L_MSJ_Comentar,"Hola Mundo!");`
8. `     l4l_end();`
9. `     return(0);`
10.`}`

[3] Necessary to include the capabilities of log4legal.
[5] Resource id for log4legal code.
[6] Initialization settings registered in log.cfg data structures whose details will 
be later that come from configuration file.
Likewise this line needs to be defined two environment variables before
execution:

	L4L_KEY -> password needed for the chained hash.

	The description of the parameters of the l4l_init function is as follows:
	
	Param #1 Configuration file. Please see the file log.cfg used for test.cfg, in the test directory.
	Param #2 ID. that enables you to associate part of the configuration to the reserved resource 
	on [5] and it is part of the name of the configuration variable: 
	
		For example: log4legal.test.print_mask=0xffffffff.

	This allows to use the same configuration file for different behaviors depending on indicated 
	in the instruction l4l_init.
	
[7] It is a printf style statement with three parameters:

	Param #1 Mask -> This field replaces the parameter level of traces of other libraries
	and its meaning is as follows; is a logical AND with the configured value
	in the config file (log.cfg in our case) for the configuration variable
	log4legal.test.printmask=0xffffffff and if the result is different from 0 the trace is displayed,
	otherwise it is ignored.

	This allows you to have different level of traces for different environments: development, testing
	or production... or any use that you can think of this capability. The same mask is used to 
        sync the dump to disc (see config parameter _flush_mask_).
	
	Param #2 Format -> L4L_MSJ_Comentar is predefined (you can pre-define all want of them) with the 
	following value in l4lcompcfg.h:

		#define L4L_MSJ_Comentar ">%s< MSJ-Comentar: %%s",L4L_HASH
	
	where the first %s display encrypted information that gives legal value to the line and s is
	where inserted is "Hello world!". You can define as many values as you want in the format definition 
	if after you care when using it. By example if you define:
	
		#define L4L_TestREADME ">%s< README_TEST: %%s - %%d - %%f",L4L_HASH
	
	to define a new format and include a decimal and a float at the time of program You should 
	use the line:
	
		l4l_printf(0xFFFFFFFF,L4L_TestREADME,"Hello World!",1,(float)1/2);
		
	You must make this change in the l4lcompcfg.h file before compiling the library. This seems
	a little hard but it is only done once and the benefits are amazing for high-performance systems.	

	Param #3  -> list of values to be inserted in the printf style format and if the defined format
	is correct.

[8] It free log4legal reserved resources.

## CONFIG FILE OPTIONS

Each configuration line format is as follows:

	_log4legal.<sub>.<variable>_

Where <sub> is the value that the user decides to and that should be taken into account in the development
After using log4legal. And <variable> is the ability of configurable log4legal in This file. Its possible 
values are:

 	flush_mask: flush + fsync mask to configure the moment of the dump to disk.
 	print_mask: Mask to decide if the trace is registered or not.
 	hash_mask: Mask to decide if the hash is registered or not.
 	buffsize: Buffer size.
 	bufftype: Buffer type. Posible values:
 		_IOFBF: fully buffered. 
 		_IOLBF: line buffered. 
 		_IONBF: unbuffered. 
 	rotation.size: Max file size (in bytes) before rotate. 
 	rotation.seconds: Max time (in seconds) Before rotate.
 	compile.timestamp.url: Time server to negotiate a timestamp for the sign. Ej. http://www.originstamp.org/api/stamps, uncentralized timestamp descentralizada from bitcoin net.
 	timestamp.token: Required (in most of cases) as a param for times server. It is a token Ej. 854081b6dad0c28adcd2f1907f012e3f.
 	pki.public: path to public digital certificate. Format accepted: .crt
 	pki.private: path to private file key. Format accepted: .cer.
 	pki.hash.method: Posible values: md2, md4, md5, sha, sha1, sha224, sha256, sha384, sha512, dss1, mdc2 y ripemd160.
 	pki.hash.length: The length of the hash value that you must report in the trace. Ej 10.

## PROPOSED EXAMPLE RESULT

If is defined this macro in l4lcompcfg.h before compile:

	#define L4L_FILE_NAME "%s/nombre_%s_%ld.log",getenv("L4L_LOG_PATH"),l4l_now("%Y%m%d_%H%M%S"),getpid()

and defined the environmet variable L4L_LOG_PATH with the value "/tmp" you will obtain a file like this:
nombre_20150813_130943_34620.log

And the content of it will be a single line of logs between all lines of header and end. Something similar to this:

_MSJ-Version: L4L v.0.3 Copyright (c) 2015 Jose Antonio Ortiz <jaortizb@gmail.com>_

_MSJ-License: This software is released under the LGPL 2.1 license, see the LICENSE file._

_MSJ-Log: Log File Name /tmp/nombre_20150813_130943_34620.log_

_MSJ-Bin: Binary file >./test<_

_MSJ-Def: L4L_ROTATION: YES_

_MSJ-Def: L4L_HASH_METHOD: sha1_

_MSJ-Cfg: print_mask=0xffffffff, hash_mask=0xffffffff, sync_mask=0x0,flush_mask=0x0_

_MSJ-Cfg: buffsize=4098, bufftype=_IOFBF, max_size=5000000, max_seconds=3600_

_>3218575d1f< ffffffff 1439464184 [l4l.c:326] MSJ-Comentar: Timestamp: {"hash_sha256":"6e2f137e5d3ba780ee3298c5da6a5ac269c99560eaa372bb06a5e6e15b8c6a99","created_at":"2015-08-13T11:09:54.900Z","updated_at":"2015-08-13T11:09:54.900Z","submitted_at":null,"title":"L4L_Init"}_

_>fdfc9a5769< ffffffff 1439464184 [test.c:9] README_TEST: Hello World! - 1 - 0.5_

_>d997654e94< ffffffff 1439464186 [l4l.c:223] MSJ-Comentar: Timestamp: {"hash_sha256":"3ef1cc54951ce7b2b86758fdeaed7cefc12e27ebaa01e0558242404c37e17abc","created_at":"2015-08-13T11:09:56.792Z","updated_at":"2015-08-13T11:09:56.792Z","submitted_at":null,"title":"L4L_Close"}_

## PLEASE CONTACT US

I agree, it is hard to use this tool, but the benefits achieved are the best if you are looking for is 
performance and legality.

Contact me (jaortizb@gmail.com) and I will be happy to answer any questions you may have, so if you want 
to participate in the project as if you've seen interest to include it in your systems.