Add more documentation for the CommModule files
[cacert-codedocs.git] / source / directories.rst
1 ===================
2 Directory structure
3 ===================
4
5 root Directory
6 ==============
7
8 The root directory contains
9
10 - a :file:`.gitignore` file with a list of excluded files
11 - a :file:`LICENSE` file the `GPL`_ license text
12 - a :file:`README` file with very rudimentary documentation stating the
13 license and a list of system requirements
14
15 .. _GPL: https://www.gnu.org/licenses/old-licenses/gpl-2.0
16
17 .. index:: cgi-bin
18
19 Directory :file:`cgi-bin`
20 =========================
21
22 The `cgi-bin` directory contains
23
24 .. index:: php
25
26 .. _cgi-bin-siteseal-cgi:
27
28 - :file:`siteseal.cgi` a PHP CGI script that generates some JavaScript code
29 to invoke :ref:`sealgen.php <www-sealgen-php>`. The configuration on
30 www.cacert.org does not seem to support this script
31 https://www.cacert.org/cgi-bin/siteseal.cgi returns a 403 response.
32
33 .. todo: check whether this is linked anywhere or can be removed
34
35 .. index:: commmodule
36 .. index:: Perl
37 .. index:: bash
38
39 Directory :file:`CommModule`
40 ============================
41
42 This directory contains the CommModule that is implemented in Perl:
43
44 .. _commmodule-client-pl:
45
46 - :file:`client.pl` the :doc:`signer protocol <signer>` client, running
47 on the webserver and talking to the server via a serial link.
48
49 The style of the Perl code seems a bit inconsistent (mix of uppercase and
50 lowercase function names, usage of brackets). The code uses database polling
51 in a loop. It might be a better idea to use some kind of queueing (Redis,
52 AMQP, ...) to not waste resources when there is nothing to do). Function
53 parameters are not named which makes the code hard to read.
54
55 The script calls several system binaries that need to be present in
56 compatible versions:
57
58 - :program:`openssl`
59 - :program:`xdelta`
60
61 The script uses several Perl standard library modules as well as the
62 following third party modules:
63
64 .. index:: Perl, thirdparty
65
66 - `DBD::mysql <https://metacpan.org/pod/DBD::mysql>`_
67 - `DBI <https://metacpan.org/pod/DBI>`_
68 - `Device::SerialPort <https://metacpan.org/pod/Device::SerialPort>`_
69 - `File::CounterFile <https://metacpan.org/pod/File::CounterFile>`_
70
71 The script references several openssl configuration files in the HandleCerts
72 function that are not included in the code repository. There are some
73 openssl configuration files with similar names in
74 https://svn.cacert.org/CAcert/SystemAdministration/signer/
75
76 The database password is parsed from
77 :ref:`includes/mysql.php <includes-mysql-php>` and relies on the
78 exact code that is defined there. Database name, user and host are hardcoded
79 in the DBI->connect call.
80
81 The script implements the client side of the signer protocol which is
82 specified in :doc:`signer`.
83
84 The script performs the following operations:
85
86 - parse password from :file:`includes/mysql.php`
87 - read a list of CRL files and logs their SHA-1 hashes
88 - read :file:`serial.conf`, create a Device::SerialPort instance `$portObj`,
89 sets serial parameters and saves :file:`serial.conf`
90 - run a main loop as long as a file :file:`./client.pl-active` is present.
91 The main loop performs the following tasks
92
93 - handle pending OpenPGP key signing request via ``HandleGPG()``
94 - handle pending certificate signing requests:
95
96 - personal client certificates via ``HandleCerts(0, 0)``
97 - personal server certificates via ``HandleCerts(0, 1)``
98 - organization client certificates via ``HandleCerts(1, 0)``
99 - organization server certificates via ``HandleCerts(1, 1)``
100
101 - handle pending certificate revocation requests
102
103 - personal client certificates via ``RevokeCerts(0, 0)``
104 - personal server certificates via ``RevokeCerts(0, 1)``
105 - organization client certificates via ``RevokeCerts(1, 0)``
106 - organization server certificates via ``RevokeCerts(1, 1)``
107
108 - refresh :term:`CRLs <CRL>` via ``RefreshCRLs()`` in every 100st
109 iteration
110 - send a :ref:`NUL request <signer-nul-request-format>` to keep the signer
111 connection alive
112 - sleep for 2.7 seconds
113
114 There is potential for optimization in the main loop. The CRL update could
115 be performed if a certificate has been revoked. The NUL request needs only
116 to be sent if no other request has been sent.
117
118 The script uses a lot of temporary files instead of piping input and
119 output to and from external commands.
120
121 .. todo:: describe more in-depth what each of the main loop steps does
122
123 - :file:`commdaemon` a script to run :ref:`client.pl <commmodule-client-pl>`
124 or :ref:`server.pl <commmodule-server-pl>`
125
126 This bash script is automatically restarting the :file:`{script}` given as
127 the first parameter as long as a file :file:`{script}-active` exists.
128 Informational messages and errors are logged to syslog via
129 :command:`logger`.
130
131 The script is most probably used to recover from crashed scripts. This
132 could be implemented via :command:`supervisor` or :command:`systemd`
133 instead of a custom script.
134
135 - :file:`commmodule` a System V style init script for startup/shutdown of
136 CommModule
137
138 On test.cacert.org two slightly different versions are deployed in
139 :file:`/etc/init.d` the first version starts
140 :ref:`client.pl <commmodule-client-pl>` in
141 :file:`/home/cacert/www/CommModule/` and the
142 second variant starts :ref:`server.pl <commmodule-server-pl>` in
143 :file:`/home/signer/cacert-devel/CommModule/`.
144
145 - :file:`logclean.sh` maintenance script for logfiles generated by CommModule
146
147 The :file:`logclean.sh` script performs log rotation of signer logfiles.
148
149 .. todo::
150
151 discuss replacement of this script with :command:`logrotate` and a
152 custom logrotate.conf for the signer
153
154 - :file:`serial.conf` serial port configuration file
155
156 This file is read and written by both
157 :ref:`client.pl <commmodule-client-pl>` and
158 :ref:`server.pl <commmodule-server-pl>` therefore both cannot be run from
159 the same directory without interfering with each other.
160
161 .. todo::
162
163 add a serial.conf template and move the actual serial.conf into
164 configuration management
165
166 .. _commmodule-server-pl:
167
168 - :file:`server.pl` the real server, running on the signing server
169
170 This script implements the signer (server) side of the :doc:`signer
171 protocol <signer>` and performs the actual signing operations.
172
173 The script contains a some code that is duplicated by
174 :ref:`client.pl <commmodule-client-pl>`.
175
176 .. note::
177
178 The :file:`server.pl` used on test.cacert.org is different from the
179 version in the cacert-devel repository. The git origin is recorded as
180 `git://git-cacert.it-sls.de/cacert-devel.git` and there are some small
181 uncommitted changes too.
182
183 .. todo::
184
185 get the versions of server.pl on git.cacert.org, the real production
186 signer and the cacert-devel repository synchronized
187
188 - :file:`usbclient.pl` obsoleted USB version of
189 :ref:`client.pl <commmodule-client-pl>` above
190
191 .. todo:: remove unused file (usbclient.pl)
192
193 Directory :file:`includes`
194 ==============================
195
196 .. _includes-mysql-php:
197 .. _includes-mysql-php-sample:
198
199 - :file:`mysql.php.sample` is a template for the database connection handling
200 code that is meant to be copied to :file:`mysql.php`.
201
202 The template defines the MySQL connection as a session variable `mconn` and
203 tries to connect to that database. It also defines the session variables
204 `normalhostname`, `securehostname` and `tverify`.
205
206 The template defines a function :php:func:`sendmail` for sending mails.
207
208 .. php:function:: sendmail($to, $subject, $message, $from, $replyto="", \
209 $toname="", $fromname="", $errorsto="returns@cacert.org", \
210 $use_utf8=true)
211
212 Send an email. The function reimplements functionality that is readily
213 available in PHP. The function does not properly escape headers and
214 sends raw SMTP commands.
215
216 :param string $to: recipient email address
217 :param string $subject: subject
218 :param string $message: email body
219 :param string $from: from email address
220 :param string $replyto: reply-to email address
221 :param string $fromname: unused in the code
222 :param string $toname: unused in the code
223 :param string $errorsto: email address used for Sender and Errors-To
224 headers
225 :param bool $use_utf8: decides whether the Content-Type header uses
226 a charset parameter of utf-8 or iso-8859-1
227
228 Configuration and actual code are mixed. It would be better to have a
229 separate file that just includes configuration.
230
231 This file is parsed by :ref:`CommModule/client.pl <commmodule-client-pl>`
232 format changes might break the CommModule code.
233
234 Directory :file:`www`
235 =====================
236
237 This contains the PHP code that is the entry point to the application:
238
239 .. _www-sealgen-php:
240
241 - :file:`sealgen.php` generates a small site seal image from
242 :ref:`www/images/secured.png <www-images-secured-png>`. This could be
243 replaced with a static image if it is used at all. This is referenced
244 by :ref:`cgi-bin/siteseal.cgi <cgi-bin-siteseal-cgi>`
245
246 Directory :file:`www/images`
247 ============================
248
249 .. _www-images-secured-png:
250
251 - :file:`secured.png` is a small image used by
252 :ref:`www/sealgen.php <www-sealgen-php>`