Describe the missing parts of the signer protocol
[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 The script uses a lot of temporary files instead of piping input and
118 output to and from external commands.
119
120 .. todo:: describe more in-depth what each of the main loop steps does
121
122 - :file:`commdaemon` a script to run :ref:`client.pl <commmodule-client-pl>`
123 or :ref:`server.pl <commmodule-server-pl>`
124
125 This bash script is automatically restarting the :file:`{script}` given as
126 the first parameter as long as a file :file:`{script}-active` exists.
127 Informational messages and errors are logged to syslog via
128 :command:`logger`.
129
130 The script is most probably used to recover from crashed scripts. This
131 could be implemented via :command:`supervisor` or :command:`systemd`
132 instead of a custom script.
133
134 - :file:`commmodule` a script for startup/shutdown of CommModule from
135 /etc/init.d
136 - :file:`logclean.sh` maintenance script for logfiles generated by CommModule
137 - :file:`serial.conf` serial port configuration file
138
139 .. _commmodule-server-pl:
140
141 - :file:`server.pl` the real server, running on the signing server
142
143 This script implements the signer (server) side of the signer protocol and
144 performs the actual signing operations.
145
146 The script contains a some code that is duplicated by
147 :ref:`client.pl <commmodule-client-pl>`.
148
149 - :file:`usbclient.pl` obsoleted USB version of
150 :ref:`client.pl <commmodule-client-pl>` above
151
152 .. todo: remove unused file (usbclient.pl)
153
154 .. todo: add a serial.conf template and move the actual serial.conf into
155 configuration management
156
157 .. todo: clarify why log rotation is implemented with a custom
158 logclean.sh script instead of using logrotate
159
160 Directory :file:`includes`
161 ==============================
162
163 .. _includes-mysql-php:
164 .. _includes-mysql-php-sample:
165
166 - :file:`mysql.php.sample` is a template for the database connection handling
167 code that is meant to be copied to :file:`mysql.php`.
168
169 The template defines the MySQL connection as a session variable `mconn` and
170 tries to connect to that database. It also defines the session variables
171 `normalhostname`, `securehostname` and `tverify`.
172
173 The template defines a function :php:func:`sendmail` for sending mails.
174
175 .. php:function:: sendmail($to, $subject, $message, $from, $replyto="", \
176 $toname="", $fromname="", $errorsto="returns@cacert.org", \
177 $use_utf8=true)
178
179 Send an email. The function reimplements functionality that is readily
180 available in PHP. The function does not properly escape headers and
181 sends raw SMTP commands.
182
183 :param string $to: recipient email address
184 :param string $subject: subject
185 :param string $message: email body
186 :param string $from: from email address
187 :param string $replyto: reply-to email address
188 :param string $fromname: unused in the code
189 :param string $toname: unused in the code
190 :param string $errorsto: email address used for Sender and Errors-To
191 headers
192 :param bool $use_utf8: decides whether the Content-Type header uses
193 a charset parameter of utf-8 or iso-8859-1
194
195 Configuration and actual code are mixed. It would be better to have a
196 separate file that just includes configuration.
197
198 This file is parsed by :ref:`CommModule/client.pl <commmodule-client-pl>`
199 format changes might break the CommModule code.
200
201 Directory :file:`www`
202 =====================
203
204 This contains the PHP code that is the entry point to the application:
205
206 .. _www-sealgen-php:
207
208 - :file:`sealgen.php` generates a small site seal image from
209 :ref:`www/images/secured.png <www-images-secured-png>`. This could be
210 replaced with a static image if it is used at all. This is referenced
211 by :ref:`cgi-bin/siteseal.cgi <cgi-bin-siteseal-cgi>`
212
213 Directory :file:`www/images`
214 ============================
215
216 .. _www-images-secured-png:
217
218 - :file:`secured.png` is a small image used by
219 :ref:`www/sealgen.php <www-sealgen-php>`