allow log format to have groups that may or may not appear
[cryptolog.git] / README
1 Cryptolog is a simple log filter program that reads log file entries from 
2 standard input and writes to either a file or pipes them to the standard input 
3 of another program (like logrotate or cronolog). The filter takes the IP 
4 address in the entry (everything before the first space character) and 
5 encrypts it, throwing away the key.
6
7 Technically, cryptolog takes 16 bytes of random data from /dev/urandom and 
8 stores it in a file (called the salt). It then calculates a sha256 hash of the 
9 salt concatonated with the original IP address, base64-encodes that, and chops 
10 off the first six characters of the result. That's what gets stored instead of 
11 the IP address in the resulting log entry. Of course this means that if someone 
12 who wishes to know the original IP addresses gets access to these logs, all 
13 they need to know is the salt (which is also stored on the hard drive) to 
14 uncover the original IPs. In order to prevent this, the salt gets updated once 
15 a day with a new random 16 bytes. At worst, an attacker can only get the last 
16 day's worth of original IP addresses.  
17
18 Cryptolog makes logs that look like this:
19
20 67.169.69.72 - - [12/May/2011:17:58:07 -0700] "GET / HTTP/1.1" 200 430
21
22 Looks like this instead:
23
24 UkezVh - - [12/May/2011:17:58:07 -0700] "GET / HTTP/1.1" 200 430
25
26 The string that replaces the IP address will remain the same for the same day, 
27 so you can tell the difference between unique visitors and pageviews.
28
29 Here are some example CustomLog lines for your Apache config files:
30
31 CustomLog "| /usr/bin/cryptolog -w /root/cryptolog-access.log" combined
32 CustomLog "| /usr/bin/cryptolog -c /usr/bin/cronolog\\\ /root/cryptolog-access-%Y-%m-%d.log" combined
33 CustomLog "| /usr/bin/cryptolog -s /tmp/salt_file -w /root/cryptolog-access.log" combined
34
35 Notice that if you're using the -c option, you need to escape spaces in the 
36 command you're running with three backslashes.
37