summaryrefslogtreecommitdiff
path: root/source/DIR-CommModule.rst
diff options
context:
space:
mode:
Diffstat (limited to 'source/DIR-CommModule.rst')
-rw-r--r--source/DIR-CommModule.rst164
1 files changed, 164 insertions, 0 deletions
diff --git a/source/DIR-CommModule.rst b/source/DIR-CommModule.rst
new file mode 100644
index 0000000..eb010c7
--- /dev/null
+++ b/source/DIR-CommModule.rst
@@ -0,0 +1,164 @@
+============================
+Directory :file:`CommModule`
+============================
+
+This directory contains the CommModule that is implemented in Perl:
+
+.. sourcefile:: CommModule/client.pl
+ :uses:
+ includes/mysql.php
+
+ :file:`client.pl` implements the :doc:`signer protocol <signer>` client,
+ running on the webserver and talking to the server via a serial link.
+
+ The style of the Perl code seems a bit inconsistent (mix of uppercase and
+ lowercase function names, usage of brackets). The code uses database polling
+ in a loop. It might be a better idea to use some kind of queueing (Redis,
+ AMQP, ...) to not waste resources when there is nothing to do). Function
+ parameters are not named which makes the code hard to read.
+
+ The script calls several system binaries that need to be present in
+ compatible versions:
+
+ - :program:`openssl`
+ - :program:`xdelta`
+
+ The script uses several Perl standard library modules as well as the
+ following third party modules:
+
+ .. index:: Perl, thirdparty
+
+ - `DBD::mysql <https://metacpan.org/pod/DBD::mysql>`_
+ - `DBI <https://metacpan.org/pod/DBI>`_
+ - `Device::SerialPort <https://metacpan.org/pod/Device::SerialPort>`_
+ - `File::CounterFile <https://metacpan.org/pod/File::CounterFile>`_
+
+ The script references several openssl configuration files in the HandleCerts
+ function that are not included in the code repository. There are some
+ openssl configuration files with similar names in
+ https://svn.cacert.org/CAcert/SystemAdministration/signer/
+
+ The database password is parsed from
+ :sourcefile:`includes/mysql.php` and relies on the
+ exact code that is defined there. Database name, user and host are hardcoded
+ in the DBI->connect call.
+
+ The script implements the client side of the signer protocol which is
+ specified in :doc:`signer`.
+
+ The script performs the following operations:
+
+ - parse password from :sourcefile:`includes/mysql.php`
+ - read a list of CRL files and logs their SHA-1 hashes
+ - read :file:`serial.conf`, create a Device::SerialPort instance `$portObj`,
+ sets serial parameters and saves :file:`serial.conf`
+ - run a main loop as long as a file :file:`./client.pl-active` is present.
+ The main loop performs the following tasks
+
+ - handle pending OpenPGP key signing request via ``HandleGPG()``
+ - handle pending certificate signing requests:
+
+ - personal client certificates via ``HandleCerts(0, 0)``
+ - personal server certificates via ``HandleCerts(0, 1)``
+ - organization client certificates via ``HandleCerts(1, 0)``
+ - organization server certificates via ``HandleCerts(1, 1)``
+
+ - handle pending certificate revocation requests
+
+ - personal client certificates via ``RevokeCerts(0, 0)``
+ - personal server certificates via ``RevokeCerts(0, 1)``
+ - organization client certificates via ``RevokeCerts(1, 0)``
+ - organization server certificates via ``RevokeCerts(1, 1)``
+
+ - refresh :term:`CRLs <CRL>` via ``RefreshCRLs()`` in every 100st
+ iteration
+ - send a :ref:`NUL request <signer-nul-request-format>` to keep the signer
+ connection alive
+ - sleep for 2.7 seconds
+
+ The script uses a lot of temporary files instead of piping input and
+ output to and from external commands.
+
+ .. todo:: describe more in-depth what each of the main loop steps does
+
+.. sourcefile:: CommModule/commdaemon
+
+ :file:`commdaemon` is a script to run
+ :sourcefile:`client.pl <CommModule/client.pl>`
+ or :sourcefile:`server.pl <CommModule/server.pl>`.
+
+ This bash script is automatically restarting the :file:`{script}` given as
+ the first parameter as long as a file :file:`{script}-active` exists.
+ Informational messages and errors are logged to syslog via
+ :command:`logger`.
+
+ The script is most probably used to recover from crashed scripts. This
+ could be implemented via :command:`supervisor` or :command:`systemd`
+ instead of a custom script.
+
+.. sourcefile:: CommModule/commmodule
+
+ :file:`commodule` is a System V style init script for startup/shutdown of
+ CommModule
+
+ On test.cacert.org two slightly different versions are deployed in
+ :file:`/etc/init.d` the first version starts
+ :sourcefile:`client.pl <CommModule/client.pl>` in
+ :file:`/home/cacert/www/CommModule/` and the
+ second variant starts :sourcefile:`server.pl <CommModule/server.pl>` in
+ :file:`/home/signer/cacert-devel/CommModule/`.
+
+.. sourcefile:: CommModule/logclean.sh
+
+ :file:`logclean.sh` is a maintenance script for logfiles generated by
+ CommModule.
+
+ The :file:`logclean.sh` script performs log rotation of signer logfiles.
+
+ .. todo::
+
+ discuss replacement of this script with :command:`logrotate` and a
+ custom logrotate.conf for the signer
+
+.. sourcefile:: CommModule/serial.conf
+
+ `serial.conf` serial port configuration file
+
+ This file is read and written by both
+ :sourcefile:`client.pl <CommModule/client.pl>` and
+ :sourcefile:`server.pl <CommModule/server.pl>` therefore both cannot be run
+ from the same directory without interfering with each other.
+
+ .. todo::
+
+ add a serial.conf template and move the actual serial.conf into
+ configuration management
+
+.. sourcefile:: CommModule/server.pl
+
+ :file:`server.pl` is the signing server software.
+
+ This script implements the signer (server) side of the :doc:`signer
+ protocol <signer>` and performs the actual signing operations.
+
+ The script contains a some code that is duplicated by
+ :sourcefile:`client.pl <CommModule/client.pl>`.
+
+ .. note::
+
+ The :file:`server.pl` used on test.cacert.org is different from the
+ version in the cacert-devel repository. The git origin is recorded as
+ `git://git-cacert.it-sls.de/cacert-devel.git` and there are some small
+ uncommitted changes too.
+
+ .. todo::
+
+ get the versions of :file:`server.pl` on git.cacert.org, the real
+ production signer and the cacert-devel repository synchronized
+
+.. sourcefile:: CommModule/usbclient.pl
+
+ :file:`usbclient.pl` is an obsoleted USB version of
+ :sourcefile:`client.pl <CommModule/client.pl>` above
+
+ .. todo:: remove unused file (usbclient.pl)