diff options
| -rw-r--r-- | source/DIR-CommModule.rst | 164 | ||||
| -rw-r--r-- | source/DIR-cgi-bin.rst | 20 | ||||
| -rw-r--r-- | source/DIR-includes.rst | 117 | ||||
| -rw-r--r-- | source/DIR-locale.rst | 11 | ||||
| -rw-r--r-- | source/DIR-stamp.rst | 31 | ||||
| -rw-r--r-- | source/DIR-tmp.rst | 5 | ||||
| -rw-r--r-- | source/DIR-tverify.rst | 21 | ||||
| -rw-r--r-- | source/DIR-www.rst | 6 | ||||
| -rw-r--r-- | source/directories.rst | 389 |
9 files changed, 380 insertions, 384 deletions
diff --git a/source/DIR-CommModule.rst b/source/DIR-CommModule.rst new file mode 100644 index 0000000..eb010c7 --- /dev/null +++ b/source/DIR-CommModule.rst @@ -0,0 +1,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) diff --git a/source/DIR-cgi-bin.rst b/source/DIR-cgi-bin.rst new file mode 100644 index 0000000..5700cff --- /dev/null +++ b/source/DIR-cgi-bin.rst @@ -0,0 +1,20 @@ +.. index:: cgi-bin + +========================= +Directory :file:`cgi-bin` +========================= + +The `cgi-bin` directory contains + +.. index:: PHP + +.. sourcefile:: cgi-bin/siteseal.cgi + :links: + www/sealgen.php + + a PHP CGI script that generates some JavaScript code to invoke + :sourcefile:`sealgen.php <www/sealgen.php>`. The configuration on + www.cacert.org does not seem to support this script + https://www.cacert.org/cgi-bin/siteseal.cgi returns a 403 response. + + .. todo: check whether this is linked anywhere or can be removed diff --git a/source/DIR-includes.rst b/source/DIR-includes.rst new file mode 100644 index 0000000..85882c3 --- /dev/null +++ b/source/DIR-includes.rst @@ -0,0 +1,117 @@ +.. index:: includes +.. index:: PHP + +========================== +Directory :file:`includes` +========================== + +.. sourcefile:: includes/.cvsignore + + :file:`.cvsignore` includes the parameters for CVS, which files to ignore by + versioning + + .. note:: CVS is long dead, is this still used? + +.. sourcefile:: includes/.gitignore + + :file:`.gitignore` contains file patterns to be ignored by Git. + +.. sourcefile:: includes/about_menu.php + :links: + http://blog.cacert.org/ + http://wiki.CAcert.org/ + www/policy/ + //wiki.cacert.org/FAQ/Privileges + www/index.php?id=47 + www/logos.php + www/stats.php + http://blog.CAcert.org/feed/ + www/index.php?id=7 + //wiki.cacert.org/Board + https://lists.cacert.org/wws + www/src-lic.php + + :file:`about_menu.php` is a part (<div>) of a PHP-Page, containing most of + the CAcert-related links. + +.. sourcefile:: includes/account_stuff.php + +.. sourcefile:: includes/account.php + :uses: + includes/about_menu.php + .... showheader + +.. sourcefile:: includes/general_stuff.php + +.. sourcefile:: includes/general.php + +.. sourcefile:: includes/keygen.php + +.. sourcefile:: includes/loggedin.php + +.. sourcefile:: includes/mysql.php + + :file:`includes/mysql.php` is not contained in the :cacertgit:`cacert-devel` + repository but is used by several other files. The file is copied from + :sourcefile:`includes/mysql.php.sample` and defines the database connection + information. + + This file is parsed directly by :sourcefile:`CommModule/client.pl` + format changes might break the CommModule code. + +.. sourcefile:: 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. + +.. sourcefile:: includes/notary.inc.php + +.. sourcefile:: includes/shutdown.php + +.. sourcefile:: includes/sponsorinfo.php + +.. sourcefile:: includes/tverify_stuff.php + + +.. index:: includes/lib +.. index:: PHP + +Directory :file:`includes/lib` +============================== + +.. sourcefile:: includes/lib/account.php + +.. sourcefile:: includes/lib/check_weak_key.php + +.. sourcefile:: includes/lib/general.php + +.. sourcefile:: includes/lib/l10n.php diff --git a/source/DIR-locale.rst b/source/DIR-locale.rst new file mode 100644 index 0000000..c6c13b8 --- /dev/null +++ b/source/DIR-locale.rst @@ -0,0 +1,11 @@ +.. index:: locale + +======================== +Directory :file:`locale` +======================== + +.. sourcefile:: locale/cv.c + +.. sourcefile:: locale/escape_special_chars.php + +.. sourcefile:: locale/makefile diff --git a/source/DIR-stamp.rst b/source/DIR-stamp.rst new file mode 100644 index 0000000..c4cec6d --- /dev/null +++ b/source/DIR-stamp.rst @@ -0,0 +1,31 @@ +.. index:: scripts +.. index:: PHP +.. index:: txt + +======================= +Directory :file:`stamp` +======================= + +.. sourcefile:: stamp/certdet.php + +.. sourcefile:: stamp/common.php + +.. sourcefile:: stamp/displogo.php + +.. sourcefile:: stamp/.htaccess + +.. sourcefile:: stamp/index.php + +.. sourcefile:: stamp/old_showlogo.php.broken + +.. sourcefile:: stamp/report.php + +.. sourcefile:: stamp/showlogo.php + +.. sourcefile:: stamp/style.css + + +Directory :file:`stamp/images` +============================== + +.. sourcefile:: stamp/images/CAverify.png diff --git a/source/DIR-tmp.rst b/source/DIR-tmp.rst new file mode 100644 index 0000000..71fe328 --- /dev/null +++ b/source/DIR-tmp.rst @@ -0,0 +1,5 @@ +===================== +Directory :file:`tmp` +===================== + +.. sourcefile:: tmp/Makefile diff --git a/source/DIR-tverify.rst b/source/DIR-tverify.rst new file mode 100644 index 0000000..2e4a23d --- /dev/null +++ b/source/DIR-tverify.rst @@ -0,0 +1,21 @@ +.. index:: tverify + +========================= +Directory :file:`tverify` +========================= + +.. sourcefile:: tverify/favicon.ico + +.. sourcefile:: tverify/.htaccess + +.. sourcefile:: tverify/index + +.. sourcefile:: tverify/index.php + + +Directory :file:`tverify/index` +=============================== + +.. sourcefile:: tverify/index/0.php + +.. sourcefile:: tverify/index/1.php diff --git a/source/DIR-www.rst b/source/DIR-www.rst index 872ce43..2a1f51a 100644 --- a/source/DIR-www.rst +++ b/source/DIR-www.rst @@ -1,9 +1,9 @@ .. index:: WWW .. index:: PHP -============= -Directory www -============= +===================== +Directory :file:`www` +===================== This contains the PHP code that is the entry point to the application: diff --git a/source/directories.rst b/source/directories.rst index df84658..c006bd4 100644 --- a/source/directories.rst +++ b/source/directories.rst @@ -2,10 +2,7 @@ Directory structure =================== -root Directory -============== - -The root directory contains +The root directory of the :cacertgit:`cacert-devel` tree contains - a :file:`.gitignore` file with a list of excluded files - a :file:`LICENSE` file the `GPL`_ license text @@ -20,384 +17,14 @@ The root directory contains :caption: Documentation for subdirectories :name: directorytoc + DIR-cgi-bin + DIR-CommModule + DIR-includes + DIR-locale DIR-pages DIR-scripts + DIR-stamp + DIR-tmp + DIR-tverify DIR-www - -.. index:: cgi-bin - -Directory :file:`cgi-bin` -========================= - -The `cgi-bin` directory contains - -.. index:: PHP - -.. sourcefile:: cgi-bin/siteseal.cgi - :links: - www/sealgen.php - - a PHP CGI script that generates some JavaScript code to invoke - :sourcefile:`sealgen.php <www/sealgen.php>`. The configuration on - www.cacert.org does not seem to support this script - https://www.cacert.org/cgi-bin/siteseal.cgi returns a 403 response. - - .. 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: - -.. 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) - -.. index:: includes -.. index:: PHP - -Directory :file:`includes` -========================== - -.. sourcefile:: includes/.cvsignore - - :file:`.cvsignore` includes the parameters for CVS, which files to ignore by - versioning - - .. note:: CVS is long dead, is this still used? - -.. sourcefile:: includes/.gitignore - - :file:`.gitignore` contains file patterns to be ignored by Git. - -.. sourcefile:: includes/about_menu.php - :links: - http://blog.cacert.org/ - http://wiki.CAcert.org/ - www/policy/ - //wiki.cacert.org/FAQ/Privileges - www/index.php?id=47 - www/logos.php - www/stats.php - http://blog.CAcert.org/feed/ - www/index.php?id=7 - //wiki.cacert.org/Board - https://lists.cacert.org/wws - www/src-lic.php - - :file:`about_menu.php` is a part (<div>) of a PHP-Page, containing most of - the CAcert-related links. - -.. sourcefile:: includes/account_stuff.php - -.. sourcefile:: includes/account.php - :uses: - includes/about_menu.php - .... showheader - -.. sourcefile:: includes/general_stuff.php - -.. sourcefile:: includes/general.php - -.. sourcefile:: includes/keygen.php - -.. sourcefile:: includes/loggedin.php - -.. sourcefile:: includes/mysql.php - - :file:`includes/mysql.php` is not contained in the :cacertgit:`cacert-devel` - repository but is used by several other files. The file is copied from - :sourcefile:`includes/mysql.php.sample` and defines the database connection - information. - - This file is parsed directly by :sourcefile:`CommModule/client.pl` - format changes might break the CommModule code. - -.. sourcefile:: 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. - -.. sourcefile:: includes/notary.inc.php - -.. sourcefile:: includes/shutdown.php - -.. sourcefile:: includes/sponsorinfo.php - -.. sourcefile:: includes/tverify_stuff.php - - -.. index:: includes/lib -.. index:: PHP - -Directory :file:`includes/lib` -============================== - -.. sourcefile:: includes/lib/account.php - -.. sourcefile:: includes/lib/check_weak_key.php - -.. sourcefile:: includes/lib/general.php - -.. sourcefile:: includes/lib/l10n.php - - -.. index:: locale - -Directory :file:`locale` -======================== - -.. sourcefile:: locale/cv.c - -.. sourcefile:: locale/escape_special_chars.php - -.. sourcefile:: locale/makefile - - -.. index:: scripts -.. index:: PHP -.. index:: txt - -Directory :file:`stamp` -======================= - -.. sourcefile:: stamp/certdet.php - -.. sourcefile:: stamp/common.php - -.. sourcefile:: stamp/displogo.php - -.. sourcefile:: stamp/.htaccess - -.. sourcefile:: stamp/index.php - -.. sourcefile:: stamp/old_showlogo.php.broken - -.. sourcefile:: stamp/report.php - -.. sourcefile:: stamp/showlogo.php - -.. sourcefile:: stamp/style.css - - -Directory :file:`stamp/images` -============================== - -.. sourcefile:: stamp/images/CAverify.png - - -Directory :file:`tmp` -===================== - -.. sourcefile:: tmp/Makefile - - -.. index:: tverify - -Directory :file:`tverify` -========================= - -.. sourcefile:: tverify/favicon.ico - -.. sourcefile:: tverify/.htaccess - -.. sourcefile:: tverify/index - -.. sourcefile:: tverify/index.php - - -Directory :file:`tverify/index` -=============================== - -.. sourcefile:: tverify/index/0.php - -.. sourcefile:: tverify/index/1.php |