update README.md

README.md

@@ -1,13 +1,94 @@
 # mod-entropy
 
-## abstract
-
 Apache module to generate entropy.
 
-## requires
+## Synopsis
+
+Add the following lines to your apache config file.
+
+    LoadModule entropy_module     modules/mod_entropy.so
+    SetInputFilter ENTROPY
+
+## Description
+
+This is an apache module the creates random values from incoming requests. It
+will only work on systems that have the RNDADDENTROPY ioctl, i only know of
+linux.
+
+If you use encryption on your pages either for ssl, by using mcrypt for stuff
+or ssh, gpg, etc. you will use the systems random source. This is filled up by
+the kernel via some irq and user interaction. So it fills quite slowly and it
+is limited. And it fills even slower on a server where no Keyboard Interrupts
+or such will happen most of the time.
+
+This problem is addressed by the existence of /dev/urandom which does some
+magic, so that the request for random numbers will never block. But the
+quality of these random numbers is a matter of discussion right now.
+
+So i came up with the idea that user interachtion on a webserver (request)
+related to time are also entropic in nature and decided to build an apache
+module to fill the kernel random pool by that way. This should increase the
+quality as well as the responsiveness of encryption.
+
+Actually i must confess that i have no really clue what a random number makes
+it cryptographically "good" and i would be happy to get some feedback on this.
+
+## Requirements
+
+### Add **cap_sys_admin** to apache.
+
+You need libcap being installed on your system to do this.
+Assuming your apache binary is /usr/sbin/apache2 do the following as root:
+
+    setcap cap_net_bind_service,cap_sys_admin=ep /usr/sbin/apache2
+
+And then make sure apache is started by the user configured in http.conf.
+This should prevent right drop while changing the effective user id.
+If apache2 does not start it most likely is related to some access rights.
+Just have a look in the error log as mentioned in this.
+
+**ATTENTION: This module adds data to the kernel random number pool. To do
+this the apache process needs CAP_SYS_ADMIN. Without any role based access
+control this is true only for the root user.
+
+An alternative is to assign CAP_SYS_ADMIN to the apache process. This still
+seems not to be the ideal solution as this would give the apache process
+access to several system internals like de-/activation of swap devices
+mount/unmount, etc. Anyway, this is the best i could figure out.
+
+It would be a good to have a special capabilty just for random pool
+administration but actually i have no clue if and how this might be possible.
+Anyway this still might lead to problems with the security of your encryption
+as an attacker might be able to add own random values to the random pool which
+in turn might compromize your encryption.
+
+Actually i have no good solution for this...maybe it is not a good idea at all
+to generate random numbers this way, i would be lucky to get feedback on this
+issue.**
+
+## Dependencies
+
+ * Apache 2
+
+## Contributing
+
+Just write me an email.
+
+## License
+
+    This program is free software: you can redistribute it and/or modify
+    it under the terms of the GNU General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+    
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
     
-Apache
+    You should have received a copy of the GNU General Public License
+    along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
-## status
+## Author
 
-unknown
+Georg Hopp <georg@steffers.org>