|
|
|
===================
|
|
|
|
Directory structure
|
|
|
|
===================
|
|
|
|
|
|
|
|
root Directory
|
|
|
|
==============
|
|
|
|
|
|
|
|
The root directory contains
|
|
|
|
|
|
|
|
- a :file:`.gitignore` file with a list of excluded files
|
|
|
|
- a :file:`LICENSE` file the `GPL`_ license text
|
|
|
|
- a :file:`README` file with very rudimentary documentation stating the
|
|
|
|
license and a list of system requirements
|
|
|
|
|
|
|
|
.. _GPL: https://www.gnu.org/licenses/old-licenses/gpl-2.0
|
|
|
|
|
|
|
|
|
|
|
|
.. toctree::
|
|
|
|
:maxdepth: 2
|
|
|
|
:caption: Documentation for subdirectories
|
|
|
|
:name: directorytoc
|
|
|
|
|
|
|
|
DIR-pages
|
|
|
|
DIR-scripts
|
|
|
|
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
|