Bug-1443; first part of implementing complete directory
[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 .. index:: includes
194 .. index:: PHP
195
196 Directory :file:`includes`
197 ==============================
198
199 .. _includes-.cvsignore:
200
201 .. sourcefile: includes/.cvsignore
202
203 - :file:`.cvsignore` includes the parameters for CVS, which files to ignore by versioning
204
205 .. _includes-.directory:
206
207 .. sourcefile: includes/.gitignore
208
209 - :file:`.gitignore` includes the parameters for GIT, which files to ignore by versioning
210
211 .. _includes-about_menu.php:
212
213 .. sourcefile: includes/about_menu.php
214 :links: http://blog.cacert.org/
215 :links: http://wiki.CAcert.org/
216 :links: www/policy/
217 :links: //wiki.cacert.org/FAQ/Privileges
218 :links: www/index.php?id=47
219 :links: www/logos.php
220 :links: www/stats.php
221 :links: http://blog.CAcert.org/feed/
222 :links: www/index.php?id=7
223 :links: //wiki.cacert.org/Board
224 :links: https://lists.cacert.org/wws
225 :links: www/src-lic.php
226
227 - :file:`about_menu.php` is a part (<div>) of a PHP-Page, containing most of the CAcert-related links.
228
229 .. _includes-account_stuff.php:
230
231 .. sourcefile: includes/account_stuff.php
232
233 - :file:`account_stuff.php`
234
235 .. _includes-account.php:
236
237 .. sourcefile: includes/account.php
238 :uses: includes/about_menu.php
239 :uses: .... showheader
240
241 - :file:`account.php`
242
243 .. _includes-general_stuff.php:
244
245 .. sourcefile: includes/general_stuff.php
246
247 - :file:`general_stuff.php`
248
249 .. _includes-general.php:
250
251 .. sourcefile: includes/general.php
252
253 - :file:`general.php`
254
255 .. _includes-keygen.php:
256
257 .. sourcefile: includes/keygen.php
258
259 - :file:`keygen.php`
260
261 .. _includes-loggedin.php:
262
263 .. sourcefile: includes/loggedin.php
264
265 - :file:`loggedin.php`
266
267 .. _includes-mysql-php:
268 .. _includes-mysql-php-sample:
269
270 - :file:`mysql.php.sample` is a template for the database connection handling
271 code that is meant to be copied to :file:`mysql.php`.
272
273 The template defines the MySQL connection as a session variable `mconn` and
274 tries to connect to that database. It also defines the session variables
275 `normalhostname`, `securehostname` and `tverify`.
276
277 The template defines a function :php:func:`sendmail` for sending mails.
278
279 .. php:function:: sendmail($to, $subject, $message, $from, $replyto="", \
280 $toname="", $fromname="", $errorsto="returns@cacert.org", \
281 $use_utf8=true)
282
283 Send an email. The function reimplements functionality that is readily
284 available in PHP. The function does not properly escape headers and
285 sends raw SMTP commands.
286
287 :param string $to: recipient email address
288 :param string $subject: subject
289 :param string $message: email body
290 :param string $from: from email address
291 :param string $replyto: reply-to email address
292 :param string $fromname: unused in the code
293 :param string $toname: unused in the code
294 :param string $errorsto: email address used for Sender and Errors-To
295 headers
296 :param bool $use_utf8: decides whether the Content-Type header uses
297 a charset parameter of utf-8 or iso-8859-1
298
299 Configuration and actual code are mixed. It would be better to have a
300 separate file that just includes configuration.
301
302 This file is parsed by :ref:`CommModule/client.pl <commmodule-client-pl>`
303 format changes might break the CommModule code.
304
305 .. _includes-notary.inc.php:
306
307 .. sourcefile: includes/notary.inc.php
308
309 - :file:`notary.inc.php`
310
311 .. _includes-shutdown.php:
312
313 .. sourcefile: includes/shutdown.php
314
315 - :file:`shutdown.php`
316
317 .. _includes-sponsorinfo.php:
318
319 .. sourcefile: includes/sponsorinfo.php
320
321 - :file:`sponsorinfo.php`
322
323 .. _includes-tverify_stuff.php:
324
325 .. sourcefile: includes/tverify_stuff.php
326
327 - :file:`tverify_stuff.php`
328
329 .. index:: includes/lib
330 .. index:: PHP
331
332 Directory :file:`includes/lib`
333 ==============================
334
335 .. _includes-lib-account.php:
336
337 .. sourcefile: includes/lib/account.php
338
339 - :file:`account.php`
340
341 .. _includes-lib-check_weak_key.php:
342
343 .. sourcefile: includes/lib/check_weak_key.php
344
345 - :file:`check_weak_key.php`
346
347 .. _includes-lib-general.php:
348
349 .. sourcefile: includes/lib/general.php
350
351 - :file:`general.php`
352
353 .. _includes-lib-l10n.php:
354
355 .. sourcefile: includes/lib/l10n.php
356
357 - :file:`l10n.php`
358
359 .. index:: locale
360
361 Directory :file:`locale`
362 ========================
363
364 .. index:: C
365
366 .. _locale-cv.c:
367
368 .. sourcefile: locale/cv.c
369
370 - :file:`cv.c`
371
372 .. index:: PHP
373 .. _locale-escape_special_chars.php:
374
375 .. sourcefile: locale/escape_special_chars.php
376
377 - :file:`escape_special_chars.php`
378
379 .. index:: bash
380 .. _locale-makefile:
381
382 .. sourcefile: locale/makefile
383
384 - :file:`makefile`
385
386 .. index:: pages
387
388 Directory :file:`pages`
389 =======================
390
391 This directory only contains other (sub-) directorys, structured according to specific topics.
392
393 .. include:: DIR-pages.rst
394
395 .. index:: scripts
396 .. index:: PHP
397 .. index:: txt
398
399 Directory :file:`scripts`
400 =========================
401
402 .. include:: DIR-scripts.rst
403
404
405 .. index:: WWW
406 .. index:: PHP
407
408 Directory :file:`www`
409 =====================
410
411 This contains the PHP code that is the entry point to the application:
412
413 .. _www-sealgen-php:
414
415 - :file:`sealgen.php` generates a small site seal image from
416 :ref:`www/images/secured.png <www-images-secured-png>`. This could be
417 replaced with a static image if it is used at all. This is referenced
418 by :ref:`cgi-bin/siteseal.cgi <cgi-bin-siteseal-cgi>`
419
420 Directory :file:`www/images`
421 ============================
422
423 .. _www-images-secured-png:
424
425 - :file:`secured.png` is a small image used by
426 :ref:`www/sealgen.php <www-sealgen-php>`