summaryrefslogtreecommitdiff
path: root/source/DIR-CommModule.rst
blob: eb010c72f01fc8e6bea76adc64a681decb256a51 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
============================
Directory :file:`CommModule`
============================

This directory contains the CommModule that is implemented in Perl:

.. sourcefile:: CommModule/client.pl
   :uses:
      includes/mysql.php

   :file:`client.pl` implements the :doc:`signer protocol <signer>` client,
   running on the webserver and talking to the server via a serial link.

   The style of the Perl code seems a bit inconsistent (mix of uppercase and
   lowercase function names, usage of brackets). The code uses database polling
   in a loop. It might be a better idea to use some kind of queueing (Redis,
   AMQP, ...) to not waste resources when there is nothing to do). Function
   parameters are not named which makes the code hard to read.

   The script calls several system binaries that need to be present in
   compatible versions:

   - :program:`openssl`
   - :program:`xdelta`

   The script uses several Perl standard library modules as well as the
   following third party modules:

   .. index:: Perl, thirdparty

   - `DBD::mysql <https://metacpan.org/pod/DBD::mysql>`_
   - `DBI <https://metacpan.org/pod/DBI>`_
   - `Device::SerialPort <https://metacpan.org/pod/Device::SerialPort>`_
   - `File::CounterFile <https://metacpan.org/pod/File::CounterFile>`_

   The script references several openssl configuration files in the HandleCerts
   function that are not included in the code repository. There are some
   openssl configuration files with similar names in
   https://svn.cacert.org/CAcert/SystemAdministration/signer/

   The database password is parsed from
   :sourcefile:`includes/mysql.php` and relies on the
   exact code that is defined there. Database name, user and host are hardcoded
   in the DBI->connect call.

   The script implements the client side of the signer protocol which is
   specified in :doc:`signer`.

   The script performs the following operations:

   - parse password from :sourcefile:`includes/mysql.php`
   - read a list of CRL files and logs their SHA-1 hashes
   - read :file:`serial.conf`, create a Device::SerialPort instance `$portObj`,
     sets serial parameters and saves :file:`serial.conf`
   - run a main loop as long as a file :file:`./client.pl-active` is present.
     The main loop performs the following tasks

     - handle pending OpenPGP key signing request via ``HandleGPG()``
     - handle pending certificate signing requests:

       - personal client certificates via ``HandleCerts(0, 0)``
       - personal server certificates via ``HandleCerts(0, 1)``
       - organization client certificates via ``HandleCerts(1, 0)``
       - organization server certificates via ``HandleCerts(1, 1)``

     - handle pending certificate revocation requests

       - personal client certificates via ``RevokeCerts(0, 0)``
       - personal server certificates via ``RevokeCerts(0, 1)``
       - organization client certificates via ``RevokeCerts(1, 0)``
       - organization server certificates via ``RevokeCerts(1, 1)``

     - refresh :term:`CRLs <CRL>` via ``RefreshCRLs()`` in every 100st
       iteration
     - send a :ref:`NUL request <signer-nul-request-format>` to keep the signer
       connection alive
     - sleep for 2.7 seconds

   The script uses a lot of temporary files instead of piping input and
   output to and from external commands.

   .. todo:: describe more in-depth what each of the main loop steps does

.. sourcefile:: CommModule/commdaemon

   :file:`commdaemon` is a script to run
   :sourcefile:`client.pl <CommModule/client.pl>`
   or :sourcefile:`server.pl <CommModule/server.pl>`.

   This bash script is automatically restarting the :file:`{script}` given as
   the first parameter as long as a file :file:`{script}-active` exists.
   Informational messages and errors are logged to syslog via
   :command:`logger`.

   The script is most probably used to recover from crashed scripts. This
   could be implemented via :command:`supervisor` or :command:`systemd`
   instead of a custom script.

.. sourcefile:: CommModule/commmodule

   :file:`commodule` is a System V style init script for startup/shutdown of
   CommModule

   On test.cacert.org two slightly different versions are deployed in
   :file:`/etc/init.d` the first version starts
   :sourcefile:`client.pl <CommModule/client.pl>` in
   :file:`/home/cacert/www/CommModule/` and the
   second variant starts :sourcefile:`server.pl <CommModule/server.pl>` in
   :file:`/home/signer/cacert-devel/CommModule/`.

.. sourcefile:: CommModule/logclean.sh

   :file:`logclean.sh` is a maintenance script for logfiles generated by
   CommModule.

   The :file:`logclean.sh` script performs log rotation of signer logfiles.

   .. todo::

      discuss replacement of this script with :command:`logrotate` and a
      custom logrotate.conf for the signer

.. sourcefile:: CommModule/serial.conf

   `serial.conf` serial port configuration file

   This file is read and written by both
   :sourcefile:`client.pl <CommModule/client.pl>` and
   :sourcefile:`server.pl <CommModule/server.pl>` therefore both cannot be run
   from the same directory without interfering with each other.

   .. todo::

      add a serial.conf template and move the actual serial.conf into
      configuration management

.. sourcefile:: CommModule/server.pl

   :file:`server.pl` is the signing server software.

   This script implements the signer (server) side of the :doc:`signer
   protocol <signer>` and performs the actual signing operations.

   The script contains a some code that is duplicated by
   :sourcefile:`client.pl <CommModule/client.pl>`.

   .. note::

      The :file:`server.pl` used on test.cacert.org is different from the
      version in the cacert-devel repository. The git origin is recorded as
      `git://git-cacert.it-sls.de/cacert-devel.git` and there are some small
      uncommitted changes too.

   .. todo::

      get the versions of :file:`server.pl` on git.cacert.org, the real
      production signer and the cacert-devel repository synchronized

.. sourcefile:: CommModule/usbclient.pl

   :file:`usbclient.pl` is an obsoleted USB version of
   :sourcefile:`client.pl <CommModule/client.pl>` above

   .. todo:: remove unused file (usbclient.pl)