summaryrefslogtreecommitdiff
path: root/source/directories.rst
diff options
context:
space:
mode:
Diffstat (limited to 'source/directories.rst')
-rw-r--r--source/directories.rst167
1 files changed, 167 insertions, 0 deletions
diff --git a/source/directories.rst b/source/directories.rst
index fd67962..cce7201 100644
--- a/source/directories.rst
+++ b/source/directories.rst
@@ -14,11 +14,15 @@ The root directory contains
.. _GPL: https://www.gnu.org/licenses/old-licenses/gpl-2.0
+.. index:: cgi-bin
+
Directory :file:`cgi-bin`
=========================
The `cgi-bin` directory contains
+.. index:: php
+
.. _cgi-bin-siteseal-cgi:
- :file:`siteseal.cgi` a PHP CGI script that generates some JavaScript code
@@ -28,6 +32,169 @@ The `cgi-bin` directory contains
.. todo: check whether this is linked anywhere or can be removed
+.. index:: commmodule
+.. index:: Perl
+.. index:: bash
+
+Directory :file:`CommModule`
+============================
+
+This directory contains the CommModule that is implemented in Perl:
+
+.. _commmodule-client-pl:
+
+- :file:`client.pl` the real client, running on the webserver
+
+ 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
+ :ref:`includes/mysql.php <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 :file:`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
+
+ There is potential for optimization in the main loop. The CRL update could
+ be performed if a certificate has been revoked. The NUL request needs only
+ to be sent if no other request has been sent.
+
+ .. todo:: describe more in-depth what each of the main loop steps does
+
+- :file:`commdaemon` a script to run :ref:`client.pl <commmodule-client-pl>`
+ or :ref:`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.
+
+- :file:`commmodule` a script for startup/shutdown of CommModule from
+ /etc/init.d
+- :file:`logclean.sh` maintenance script for logfiles generated by CommModule
+- :file:`serial.conf` serial port configuration file
+
+.. _commmodule-server-pl:
+
+- :file:`server.pl` the real server, running on the signing server
+
+ This script implements the signer (server) side of the signer protocol and
+ performs the actual signing operations.
+
+ The script contains a some code that is duplicated by
+ :ref:`client.pl <commmodule-client-pl>`.
+
+- :file:`usbclient.pl` obsoleted USB version of
+ :ref:`client.pl <commmodule-client-pl>` above
+
+.. todo: remove unused file (usbclient.pl)
+
+.. todo: add a serial.conf template and move the actual serial.conf into
+ configuration management
+
+.. todo: clarify why log rotation is implemented with a custom
+ logclean.sh script instead of using logrotate
+
+Directory :file:`includes`
+==============================
+
+.. _includes-mysql-php:
+.. _includes-mysql-php-sample:
+
+- :file:`mysql.php.sample` is a template for the database connection handling
+ code that is meant to be copied to :file:`mysql.php`.
+
+ The template defines the MySQL connection as a session variable `mconn` and
+ tries to connect to that database. It also defines the session variables
+ `normalhostname`, `securehostname` and `tverify`.
+
+ The template defines a function :php:func:`sendmail` for sending mails.
+
+ .. php:function:: sendmail($to, $subject, $message, $from, $replyto="", \
+ $toname="", $fromname="", $errorsto="returns@cacert.org", \
+ $use_utf8=true)
+
+ Send an email. The function reimplements functionality that is readily
+ available in PHP. The function does not properly escape headers and
+ sends raw SMTP commands.
+
+ :param string $to: recipient email address
+ :param string $subject: subject
+ :param string $message: email body
+ :param string $from: from email address
+ :param string $replyto: reply-to email address
+ :param string $fromname: unused in the code
+ :param string $toname: unused in the code
+ :param string $errorsto: email address used for Sender and Errors-To
+ headers
+ :param bool $use_utf8: decides whether the Content-Type header uses
+ a charset parameter of utf-8 or iso-8859-1
+
+ Configuration and actual code are mixed. It would be better to have a
+ separate file that just includes configuration.
+
+ This file is parsed by :ref:`CommModule/client.pl <commmodule-client-pl>`
+ format changes might break the CommModule code.
+
Directory :file:`www`
=====================