Start documenting CommModule
[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 real client, running on the webserver
47
48 The style of the Perl code seems a bit inconsistent (mix of uppercase and
49 lowercase function names, usage of brackets). The code uses database polling
50 in a loop. It might be a better idea to use some kind of queueing (Redis,
51 AMQP, ...) to not waste resources when there is nothing to do). Function
52 parameters are not named which makes the code hard to read.
53
54 The script calls several system binaries that need to be present in
55 compatible versions:
56
57 - :program:`openssl`
58 - :program:`xdelta`
59
60 The script uses several Perl standard library modules as well as the
61 following third party modules:
62
63 .. index:: Perl, thirdparty
64
65 - `DBD::mysql <https://metacpan.org/pod/DBD::mysql>`_
66 - `DBI <https://metacpan.org/pod/DBI>`_
67 - `Device::SerialPort <https://metacpan.org/pod/Device::SerialPort>`_
68 - `File::CounterFile <https://metacpan.org/pod/File::CounterFile>`_
69
70 The script references several openssl configuration files in the HandleCerts
71 function that are not included in the code repository. There are some
72 openssl configuration files with similar names in
73 https://svn.cacert.org/CAcert/SystemAdministration/signer/
74
75 The database password is parsed from
76 :ref:`includes/mysql.php <includes-mysql-php>` and relies on the
77 exact code that is defined there. Database name, user and host are hardcoded
78 in the DBI->connect call.
79
80 The script implements the client side of the signer protocol which is
81 specified in :doc:`signer`.
82
83 The script performs the following operations:
84
85 - parse password from :file:`includes/mysql.php`
86 - read a list of CRL files and logs their SHA-1 hashes
87 - read :file:`serial.conf`, create a Device::SerialPort instance `$portObj`,
88 sets serial parameters and saves :file:`serial.conf`
89 - run a main loop as long as a file :file:`./client.pl-active` is present.
90 The main loop performs the following tasks
91
92 - handle pending OpenPGP key signing request via ``HandleGPG()``
93 - handle pending certificate signing requests:
94
95 - personal client certificates via ``HandleCerts(0, 0)``
96 - personal server certificates via ``HandleCerts(0, 1)``
97 - organization client certificates via ``HandleCerts(1, 0)``
98 - organization server certificates via ``HandleCerts(1, 1)``
99
100 - handle pending certificate revocation requests
101
102 - personal client certificates via ``RevokeCerts(0, 0)``
103 - personal server certificates via ``RevokeCerts(0, 1)``
104 - organization client certificates via ``RevokeCerts(1, 0)``
105 - organization server certificates via ``RevokeCerts(1, 1)``
106
107 - refresh :term:`CRLs <CRL>` via ``RefreshCRLs()`` in every 100st
108 iteration
109 - send a :ref:`NUL request <signer-nul-request-format>` to keep the signer
110 connection alive
111 - sleep for 2.7 seconds
112
113 There is potential for optimization in the main loop. The CRL update could
114 be performed if a certificate has been revoked. The NUL request needs only
115 to be sent if no other request has been sent.
116
117 .. todo:: describe more in-depth what each of the main loop steps does
118
119 - :file:`commdaemon` a script to run :ref:`client.pl <commmodule-client-pl>`
120 or :ref:`server.pl <commmodule-server-pl>`
121
122 This bash script is automatically restarting the :file:`{script}` given as
123 the first parameter as long as a file :file:`{script}-active` exists.
124 Informational messages and errors are logged to syslog via
125 :command:`logger`.
126
127 The script is most probably used to recover from crashed scripts. This
128 could be implemented via :command:`supervisor` or :command:`systemd`
129 instead of a custom script.
130
131 - :file:`commmodule` a script for startup/shutdown of CommModule from
132 /etc/init.d
133 - :file:`logclean.sh` maintenance script for logfiles generated by CommModule
134 - :file:`serial.conf` serial port configuration file
135
136 .. _commmodule-server-pl:
137
138 - :file:`server.pl` the real server, running on the signing server
139
140 This script implements the signer (server) side of the signer protocol and
141 performs the actual signing operations.
142
143 The script contains a some code that is duplicated by
144 :ref:`client.pl <commmodule-client-pl>`.
145
146 - :file:`usbclient.pl` obsoleted USB version of
147 :ref:`client.pl <commmodule-client-pl>` above
148
149 .. todo: remove unused file (usbclient.pl)
150
151 .. todo: add a serial.conf template and move the actual serial.conf into
152 configuration management
153
154 .. todo: clarify why log rotation is implemented with a custom
155 logclean.sh script instead of using logrotate
156
157 Directory :file:`includes`
158 ==============================
159
160 .. _includes-mysql-php:
161 .. _includes-mysql-php-sample:
162
163 - :file:`mysql.php.sample` is a template for the database connection handling
164 code that is meant to be copied to :file:`mysql.php`.
165
166 The template defines the MySQL connection as a session variable `mconn` and
167 tries to connect to that database. It also defines the session variables
168 `normalhostname`, `securehostname` and `tverify`.
169
170 The template defines a function :php:func:`sendmail` for sending mails.
171
172 .. php:function:: sendmail($to, $subject, $message, $from, $replyto="", \
173 $toname="", $fromname="", $errorsto="returns@cacert.org", \
174 $use_utf8=true)
175
176 Send an email. The function reimplements functionality that is readily
177 available in PHP. The function does not properly escape headers and
178 sends raw SMTP commands.
179
180 :param string $to: recipient email address
181 :param string $subject: subject
182 :param string $message: email body
183 :param string $from: from email address
184 :param string $replyto: reply-to email address
185 :param string $fromname: unused in the code
186 :param string $toname: unused in the code
187 :param string $errorsto: email address used for Sender and Errors-To
188 headers
189 :param bool $use_utf8: decides whether the Content-Type header uses
190 a charset parameter of utf-8 or iso-8859-1
191
192 Configuration and actual code are mixed. It would be better to have a
193 separate file that just includes configuration.
194
195 This file is parsed by :ref:`CommModule/client.pl <commmodule-client-pl>`
196 format changes might break the CommModule code.
197
198 Directory :file:`www`
199 =====================
200
201 This contains the PHP code that is the entry point to the application:
202
203 .. _www-sealgen-php:
204
205 - :file:`sealgen.php` generates a small site seal image from
206 :ref:`www/images/secured.png <www-images-secured-png>`. This could be
207 replaced with a static image if it is used at all. This is referenced
208 by :ref:`cgi-bin/siteseal.cgi <cgi-bin-siteseal-cgi>`
209
210 Directory :file:`www/images`
211 ============================
212
213 .. _www-images-secured-png:
214
215 - :file:`secured.png` is a small image used by
216 :ref:`www/sealgen.php <www-sealgen-php>`