summaryrefslogtreecommitdiff
path: root/source/directories.rst
diff options
context:
space:
mode:
authorJan Dittberner <jandd@cacert.org>2018-11-10 16:57:13 +0100
committerJan Dittberner <jandd@cacert.org>2018-11-10 16:57:13 +0100
commita82c617c1bbdfbc6cb5fa9287c751327e77160e3 (patch)
treef530a2020ba8efb5c4b20207539bfac62195840d /source/directories.rst
parentdf77ed3191ad1f36f61fcb37ecb3c9c3a00dbb74 (diff)
downloadcacert-codedocs-a82c617c1bbdfbc6cb5fa9287c751327e77160e3.tar.gz
cacert-codedocs-a82c617c1bbdfbc6cb5fa9287c751327e77160e3.tar.xz
cacert-codedocs-a82c617c1bbdfbc6cb5fa9287c751327e77160e3.zip
Split directories.rst into per directory files
Diffstat (limited to 'source/directories.rst')
-rw-r--r--source/directories.rst389
1 files changed, 8 insertions, 381 deletions
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