Split directories.rst into per directory files
[cacert-codedocs.git] / source / DIR-CommModule.rst
1 ============================
2 Directory :file:`CommModule`
3 ============================
4
5 This directory contains the CommModule that is implemented in Perl:
6
7 .. sourcefile:: CommModule/client.pl
8 :uses:
9 includes/mysql.php
10
11 :file:`client.pl` implements the :doc:`signer protocol <signer>` client,
12 running on the webserver and talking to the server via a serial link.
13
14 The style of the Perl code seems a bit inconsistent (mix of uppercase and
15 lowercase function names, usage of brackets). The code uses database polling
16 in a loop. It might be a better idea to use some kind of queueing (Redis,
17 AMQP, ...) to not waste resources when there is nothing to do). Function
18 parameters are not named which makes the code hard to read.
19
20 The script calls several system binaries that need to be present in
21 compatible versions:
22
23 - :program:`openssl`
24 - :program:`xdelta`
25
26 The script uses several Perl standard library modules as well as the
27 following third party modules:
28
29 .. index:: Perl, thirdparty
30
31 - `DBD::mysql <https://metacpan.org/pod/DBD::mysql>`_
32 - `DBI <https://metacpan.org/pod/DBI>`_
33 - `Device::SerialPort <https://metacpan.org/pod/Device::SerialPort>`_
34 - `File::CounterFile <https://metacpan.org/pod/File::CounterFile>`_
35
36 The script references several openssl configuration files in the HandleCerts
37 function that are not included in the code repository. There are some
38 openssl configuration files with similar names in
39 https://svn.cacert.org/CAcert/SystemAdministration/signer/
40
41 The database password is parsed from
42 :sourcefile:`includes/mysql.php` and relies on the
43 exact code that is defined there. Database name, user and host are hardcoded
44 in the DBI->connect call.
45
46 The script implements the client side of the signer protocol which is
47 specified in :doc:`signer`.
48
49 The script performs the following operations:
50
51 - parse password from :sourcefile:`includes/mysql.php`
52 - read a list of CRL files and logs their SHA-1 hashes
53 - read :file:`serial.conf`, create a Device::SerialPort instance `$portObj`,
54 sets serial parameters and saves :file:`serial.conf`
55 - run a main loop as long as a file :file:`./client.pl-active` is present.
56 The main loop performs the following tasks
57
58 - handle pending OpenPGP key signing request via ``HandleGPG()``
59 - handle pending certificate signing requests:
60
61 - personal client certificates via ``HandleCerts(0, 0)``
62 - personal server certificates via ``HandleCerts(0, 1)``
63 - organization client certificates via ``HandleCerts(1, 0)``
64 - organization server certificates via ``HandleCerts(1, 1)``
65
66 - handle pending certificate revocation requests
67
68 - personal client certificates via ``RevokeCerts(0, 0)``
69 - personal server certificates via ``RevokeCerts(0, 1)``
70 - organization client certificates via ``RevokeCerts(1, 0)``
71 - organization server certificates via ``RevokeCerts(1, 1)``
72
73 - refresh :term:`CRLs <CRL>` via ``RefreshCRLs()`` in every 100st
74 iteration
75 - send a :ref:`NUL request <signer-nul-request-format>` to keep the signer
76 connection alive
77 - sleep for 2.7 seconds
78
79 The script uses a lot of temporary files instead of piping input and
80 output to and from external commands.
81
82 .. todo:: describe more in-depth what each of the main loop steps does
83
84 .. sourcefile:: CommModule/commdaemon
85
86 :file:`commdaemon` is a script to run
87 :sourcefile:`client.pl <CommModule/client.pl>`
88 or :sourcefile:`server.pl <CommModule/server.pl>`.
89
90 This bash script is automatically restarting the :file:`{script}` given as
91 the first parameter as long as a file :file:`{script}-active` exists.
92 Informational messages and errors are logged to syslog via
93 :command:`logger`.
94
95 The script is most probably used to recover from crashed scripts. This
96 could be implemented via :command:`supervisor` or :command:`systemd`
97 instead of a custom script.
98
99 .. sourcefile:: CommModule/commmodule
100
101 :file:`commodule` is a System V style init script for startup/shutdown of
102 CommModule
103
104 On test.cacert.org two slightly different versions are deployed in
105 :file:`/etc/init.d` the first version starts
106 :sourcefile:`client.pl <CommModule/client.pl>` in
107 :file:`/home/cacert/www/CommModule/` and the
108 second variant starts :sourcefile:`server.pl <CommModule/server.pl>` in
109 :file:`/home/signer/cacert-devel/CommModule/`.
110
111 .. sourcefile:: CommModule/logclean.sh
112
113 :file:`logclean.sh` is a maintenance script for logfiles generated by
114 CommModule.
115
116 The :file:`logclean.sh` script performs log rotation of signer logfiles.
117
118 .. todo::
119
120 discuss replacement of this script with :command:`logrotate` and a
121 custom logrotate.conf for the signer
122
123 .. sourcefile:: CommModule/serial.conf
124
125 `serial.conf` serial port configuration file
126
127 This file is read and written by both
128 :sourcefile:`client.pl <CommModule/client.pl>` and
129 :sourcefile:`server.pl <CommModule/server.pl>` therefore both cannot be run
130 from the same directory without interfering with each other.
131
132 .. todo::
133
134 add a serial.conf template and move the actual serial.conf into
135 configuration management
136
137 .. sourcefile:: CommModule/server.pl
138
139 :file:`server.pl` is the signing server software.
140
141 This script implements the signer (server) side of the :doc:`signer
142 protocol <signer>` and performs the actual signing operations.
143
144 The script contains a some code that is duplicated by
145 :sourcefile:`client.pl <CommModule/client.pl>`.
146
147 .. note::
148
149 The :file:`server.pl` used on test.cacert.org is different from the
150 version in the cacert-devel repository. The git origin is recorded as
151 `git://git-cacert.it-sls.de/cacert-devel.git` and there are some small
152 uncommitted changes too.
153
154 .. todo::
155
156 get the versions of :file:`server.pl` on git.cacert.org, the real
157 production signer and the cacert-devel repository synchronized
158
159 .. sourcefile:: CommModule/usbclient.pl
160
161 :file:`usbclient.pl` is an obsoleted USB version of
162 :sourcefile:`client.pl <CommModule/client.pl>` above
163
164 .. todo:: remove unused file (usbclient.pl)