summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorKarl-Heinz Gödderz <Devel@GuKK-Online.de>2018-11-11 16:34:35 +0100
committerGitHub <noreply@github.com>2018-11-11 16:34:35 +0100
commitff1a605ee386e5755f65852f27d4d17188373146 (patch)
treef530a2020ba8efb5c4b20207539bfac62195840d
parente50ea1e734f23a38c4f17a84d7b476a896070b84 (diff)
parenta82c617c1bbdfbc6cb5fa9287c751327e77160e3 (diff)
downloadcacert-codedocs-ff1a605ee386e5755f65852f27d4d17188373146.tar.gz
cacert-codedocs-ff1a605ee386e5755f65852f27d4d17188373146.tar.xz
cacert-codedocs-ff1a605ee386e5755f65852f27d4d17188373146.zip
Merge pull request #1 from CAcertOrg/master
get info from original
-rw-r--r--source/DIR-CommModule.rst164
-rw-r--r--source/DIR-cgi-bin.rst20
-rw-r--r--source/DIR-includes.rst117
-rw-r--r--source/DIR-locale.rst11
-rw-r--r--source/DIR-pages.rst278
-rw-r--r--source/DIR-scripts.rst213
-rw-r--r--source/DIR-stamp.rst31
-rw-r--r--source/DIR-tmp.rst5
-rw-r--r--source/DIR-tverify.rst21
-rw-r--r--source/DIR-www.rst367
-rw-r--r--source/conf.py5
-rw-r--r--source/directories.rst252
-rw-r--r--source/signer.rst18
-rw-r--r--source/sphinxext/__init__.py0
-rw-r--r--source/sphinxext/cacert.py213
15 files changed, 1467 insertions, 248 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-pages.rst b/source/DIR-pages.rst
new file mode 100644
index 0000000..a3240a2
--- /dev/null
+++ b/source/DIR-pages.rst
@@ -0,0 +1,278 @@
+.. index:: pages
+
+=======================
+Directory :file:`pages`
+=======================
+
+This directory only contains other (sub-) directorys, structured according to specific topics.
+
+
+.. index:: pages/account
+
+Directory :file:`pages/account`
+===============================
+
+.. sourcefile:: pages/account/0.php
+
+.. sourcefile:: pages/account/1.php
+
+.. sourcefile:: pages/account/2.php
+
+.. sourcefile:: pages/account/3.php
+
+.. sourcefile:: pages/account/4.php
+
+.. sourcefile:: pages/account/5.php
+
+.. sourcefile:: pages/account/6.php
+
+.. sourcefile:: pages/account/7.php
+
+.. sourcefile:: pages/account/8.php
+
+.. sourcefile:: pages/account/9.php
+
+.. sourcefile:: pages/account/10.php
+
+.. sourcefile:: pages/account/11.php
+
+.. sourcefile:: pages/account/12.php
+
+.. sourcefile:: pages/account/13.php
+
+.. sourcefile:: pages/account/14.php
+
+.. sourcefile:: pages/account/15.php
+
+.. sourcefile:: pages/account/16.php
+
+.. sourcefile:: pages/account/17.php
+
+.. sourcefile:: pages/account/18.php
+
+.. sourcefile:: pages/account/19.php
+
+.. sourcefile:: pages/account/20.php
+
+.. sourcefile:: pages/account/21.php
+
+.. sourcefile:: pages/account/22.php
+
+.. sourcefile:: pages/account/23.php
+
+.. sourcefile:: pages/account/24.php
+
+.. sourcefile:: pages/account/25.php
+
+.. sourcefile:: pages/account/26.php
+
+.. sourcefile:: pages/account/27.php
+
+.. sourcefile:: pages/account/28.php
+
+.. sourcefile:: pages/account/29.php
+
+.. sourcefile:: pages/account/30.php
+
+.. sourcefile:: pages/account/31.php
+
+.. sourcefile:: pages/account/32.php
+
+.. sourcefile:: pages/account/33.php
+
+.. sourcefile:: pages/account/34.php
+
+.. sourcefile:: pages/account/35.php
+
+.. sourcefile:: pages/account/36.php
+
+.. sourcefile:: pages/account/37.php
+
+.. sourcefile:: pages/account/38.php
+
+.. sourcefile:: pages/account/39.php
+
+.. sourcefile:: pages/account/40.php
+
+.. sourcefile:: pages/account/41.php
+
+.. sourcefile:: pages/account/42.php
+
+.. sourcefile:: pages/account/43.php
+
+.. sourcefile:: pages/account/44.php
+
+.. sourcefile:: pages/account/45.php
+
+.. sourcefile:: pages/account/46.php
+
+.. sourcefile:: pages/account/47.php
+
+.. sourcefile:: pages/account/48.php
+
+.. sourcefile:: pages/account/49.php
+
+.. sourcefile:: pages/account/50.php
+
+.. sourcefile:: pages/account/51.php
+
+.. sourcefile:: pages/account/52.php
+
+.. sourcefile:: pages/account/53.php
+
+.. sourcefile:: pages/account/54.php
+
+.. sourcefile:: pages/account/55.php
+
+.. sourcefile:: pages/account/56.php
+
+.. sourcefile:: pages/account/57.php
+
+.. sourcefile:: pages/account/58.php
+
+.. sourcefile:: pages/account/59.php
+
+
+.. index:: pages/advertising
+
+Directory :file:`pages/advertising`
+===================================
+
+.. sourcefile:: pages/advertising/0.php
+
+.. sourcefile:: pages/advertising/1.php
+
+
+.. index:: pages/disputes
+
+Directory :file:`pages/disputes`
+================================
+
+.. sourcefile:: pages/disputes/0.php
+
+.. sourcefile:: pages/disputes/1.php
+
+.. sourcefile:: pages/disputes/2.php
+
+.. sourcefile:: pages/disputes/3.php
+
+.. sourcefile:: pages/disputes/4.php
+
+.. sourcefile:: pages/disputes/5.php
+
+.. sourcefile:: pages/disputes/6.php
+
+
+.. index:: pages/gpg
+
+Directory :file:`pages/gpg`
+===========================
+
+.. sourcefile:: pages/gpg/0.php
+
+.. sourcefile:: pages/gpg/2.php
+
+.. sourcefile:: pages/gpg/3.php
+
+
+.. index:: pages/help
+
+Directory :file:`pages/help`
+============================
+
+.. sourcefile:: pages/help/0.php
+
+.. sourcefile:: pages/help/2.php
+
+.. sourcefile:: pages/help/3.php
+
+.. sourcefile:: pages/help/4.php
+
+.. sourcefile:: pages/help/5.php
+
+.. sourcefile:: pages/help/6.php
+
+.. sourcefile:: pages/help/7.php
+
+.. sourcefile:: pages/help/8.php
+
+.. sourcefile:: pages/help/9.php
+
+
+.. index:: pages/index
+
+Directory :file:`pages/index`
+===============================
+
+.. sourcefile:: pages/index/0.php
+
+.. sourcefile:: pages/index/1.php
+
+.. sourcefile:: pages/index/2.php
+
+.. sourcefile:: pages/index/3.php
+
+.. sourcefile:: pages/index/4.php
+
+.. sourcefile:: pages/index/5.php
+
+.. sourcefile:: pages/index/6.php
+
+.. sourcefile:: pages/index/7.php
+
+.. sourcefile:: pages/index/8.php
+
+.. sourcefile:: pages/index/10.php
+
+.. sourcefile:: pages/index/11.php
+
+.. sourcefile:: pages/index/12.php
+
+.. sourcefile:: pages/index/13.php
+
+.. sourcefile:: pages/index/16.php
+
+.. sourcefile:: pages/index/17.php
+
+.. sourcefile:: pages/index/18.php
+
+.. sourcefile:: pages/index/19.php
+
+.. sourcefile:: pages/index/21.php
+
+.. sourcefile:: pages/index/47.php
+
+.. sourcefile:: pages/index/51.php
+
+
+.. index:: pages/wot
+
+Directory :file:`pages/wot`
+===========================
+
+.. sourcefile:: pages/wot/0.php
+
+.. sourcefile:: pages/wot/1.php
+
+.. sourcefile:: pages/wot/2.php
+
+.. sourcefile:: pages/wot/3.php
+
+.. sourcefile:: pages/wot/4.php
+
+.. sourcefile:: pages/wot/5.php
+
+.. sourcefile:: pages/wot/6.php
+
+.. sourcefile:: pages/wot/8.php
+
+.. sourcefile:: pages/wot/9.php
+
+.. sourcefile:: pages/wot/10.php
+
+.. sourcefile:: pages/wot/12.php
+
+.. sourcefile:: pages/wot/13.php
+
+.. sourcefile:: pages/wot/15.php
+
diff --git a/source/DIR-scripts.rst b/source/DIR-scripts.rst
new file mode 100644
index 0000000..81530f7
--- /dev/null
+++ b/source/DIR-scripts.rst
@@ -0,0 +1,213 @@
+=========================
+Directory :file:`scripts`
+=========================
+
+.. sourcefile:: scripts/49de-lt2013-berlin-email.txt
+
+.. sourcefile:: scripts/49de-lt2013-berlin-mail.php.txt
+
+.. sourcefile:: scripts/50de-ate-luebeck-email.txt
+
+.. sourcefile:: scripts/50de-ate-luebeck-mail.php.txt
+
+.. sourcefile:: scripts/51at-ate-graz-email.txt
+
+.. sourcefile:: scripts/51at-ate-graz-mail.php.txt
+
+.. sourcefile:: scripts/52at-ate-wien-email.txt
+
+.. sourcefile:: scripts/52at-ate-wien-mail.php.txt
+
+.. sourcefile:: scripts/53de-ate-amberg-email.txt
+
+.. sourcefile:: scripts/53de-ate-amberg-mail.php.txt
+
+.. sourcefile:: scripts/54at-ate-linz-email.txt
+
+.. sourcefile:: scripts/54at-ate-linz-mail.php.txt
+
+.. sourcefile:: scripts/55de-ate-wiesbaden-email.txt
+
+.. sourcefile:: scripts/55de-ate-wiesbaden-mail.php.txt
+
+.. sourcefile:: scripts/56at-ate-oberwart-email.txt
+
+.. sourcefile:: scripts/56at-ate-oberwart-mail.php.txt
+
+.. sourcefile:: scripts/57at-ate-graz-email.txt
+
+.. sourcefile:: scripts/57at-ate-graz-mail.php.txt
+
+.. sourcefile:: scripts/58at-ate-wien-email.txt
+
+.. sourcefile:: scripts/58at-ate-wien-mail.php.txt
+
+.. sourcefile:: scripts/59de-ate-freiburg-email.txt
+
+.. sourcefile:: scripts/59de-ate-freiburg-mail.php.txt
+
+.. sourcefile:: scripts/60de-ate-bremen-email.txt
+
+.. sourcefile:: scripts/60de-ate-bremen-mail.php.txt
+
+.. sourcefile:: scripts/61de-ate-dresden-email.txt
+
+.. sourcefile:: scripts/61de-ate-dresden-mail.php.txt
+
+.. sourcefile:: scripts/62de-froscon2015-email.txt
+
+.. sourcefile:: scripts/62de-froscon2015-mail.php.txt
+
+.. sourcefile:: scripts/63dk-ate-nykobing-email.txt
+
+.. sourcefile:: scripts/63dk-ate-nykobing-mail.php.txt
+
+.. sourcefile:: scripts/addpoints.php
+
+.. sourcefile:: scripts/assurer.php
+
+.. sourcefile:: scripts/assurer.txt
+
+.. sourcefile:: scripts/cleanthem.pl
+
+.. sourcefile:: scripts/clientcerts.php
+
+.. sourcefile:: scripts/consistence.php
+
+.. sourcefile:: scripts/country.php
+
+.. sourcefile:: scripts/cron
+
+.. sourcefile:: scripts/db_migrations
+
+.. sourcefile:: scripts/DumpWeakCerts.pl
+
+.. sourcefile:: scripts/findexp3.pl
+
+.. sourcefile:: scripts/findnull.pl
+
+.. sourcefile:: scripts/gpgcerts.php
+
+.. sourcefile:: scripts/gpgcheck3.php
+
+.. sourcefile:: scripts/gpgfillmissingemail.php
+
+.. sourcefile:: scripts/gpgfillmissingkeyid.php
+
+.. sourcefile:: scripts/mail-weak-keys.php
+
+.. sourcefile:: scripts/Makefile
+
+.. sourcefile:: scripts/mass-revoke.php
+
+.. sourcefile:: scripts/newslettercebit.php
+
+.. sourcefile:: scripts/newsletter.php
+
+.. sourcefile:: scripts/notify.php
+
+.. sourcefile:: scripts/oa03-csr_org_client_cert.php.txt
+
+.. sourcefile:: scripts/oa03-csr_org_client_cert.txt
+
+.. sourcefile:: scripts/perl_mysql.sample
+
+.. sourcefile:: scripts/resetpermissions.php
+
+.. sourcefile:: scripts/runclient.c
+
+.. sourcefile:: scripts/rungpg.c
+
+.. sourcefile:: scripts/runserver.c
+
+.. sourcefile:: scripts/scanforexponents.php
+
+.. sourcefile:: scripts/send_heartbleed.php
+
+.. sourcefile:: scripts/send_policy_cca_20140916.php
+
+.. sourcefile:: scripts/send_policy_cca_correct_20150221_1.php
+
+.. sourcefile:: scripts/send_policy_cca_correct_20150221_2.php
+
+.. sourcefile:: scripts/send_thawte.php.txt
+
+.. sourcefile:: scripts/servercerts.php
+
+.. sourcefile:: scripts/test.c
+
+
+Directory :file:`scripts/cron`
+==============================
+
+.. sourcefile:: scripts/cron/permissionreview.php
+
+.. sourcefile:: scripts/cron/refresh_stats.php
+
+.. sourcefile:: scripts/cron/removedead.php
+
+.. sourcefile:: scripts/cron/updatesort.php
+
+.. sourcefile:: scripts/cron/warning.php
+
+
+.. index:: bash
+
+Directory :file:`scripts/db_migrations`
+=======================================
+
+.. sourcefile:: scripts/db_migrations/version1.sh
+
+.. sourcefile:: scripts/db_migrations/version2.sh
+
+.. sourcefile:: scripts/db_migrations/version3.sh
+
+.. sourcefile:: scripts/db_migrations/version4.sh
+
+.. sourcefile:: scripts/db_migrations/version5.sh
+
+.. sourcefile:: scripts/db_migrations/version6.sh
+
+
+Directory :file:`scripts/mailing archive`
+=========================================
+
+.. sourcefile:: scripts/mailing archive/45au-ate-melbourne-email.txt
+
+.. sourcefile:: scripts/mailing archive/45au-ate-melbourne-mail.php.txt
+
+.. sourcefile:: scripts/mailing archive/46us-ate-raleigh-email.txt
+
+.. sourcefile:: scripts/mailing archive/46us-ate-raleigh-mail.php.txt
+
+.. sourcefile:: scripts/mailing archive/47us-fudcon-lawrence-email.txt
+
+.. sourcefile:: scripts/mailing archive/47us-fudcon-lawrence-mail.php.txt
+
+.. sourcefile:: scripts/mailing archive/48de-ate-kiel-email.txt
+
+.. sourcefile:: scripts/mailing archive/48de-ate-kiel-mail.php.txt
+
+.. sourcefile:: scripts/mailing archive/oa01-allowance.php.txt
+
+.. sourcefile:: scripts/mailing archive/oa01-allowance.txt
+
+.. sourcefile:: scripts/mailing archive/oa02-mailingtextCats.txt
+
+.. sourcefile:: scripts/mailing archive/oa02-mailingtextPointsCats.txt
+
+.. sourcefile:: scripts/mailing archive/oa02-mailingtextPoints.txt
+
+.. sourcefile:: scripts/mailing archive/oa02-orgainformation.php.txt
+
+.. sourcefile:: scripts/mailing archive/thawte_DE.txt
+
+.. sourcefile:: scripts/mailing archive/thawte_EN.txt
+
+.. sourcefile:: scripts/mailing archive/thawte_ES.txt
+
+.. sourcefile:: scripts/mailing archive/thawte_FR.txt
+
+.. sourcefile:: scripts/mailing archive/thawte_NL.txt
+
+.. sourcefile:: scripts/mailing archive/thawte_RU.txt
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
new file mode 100644
index 0000000..2a1f51a
--- /dev/null
+++ b/source/DIR-www.rst
@@ -0,0 +1,367 @@
+.. index:: WWW
+.. index:: PHP
+
+=====================
+Directory :file:`www`
+=====================
+
+This contains the PHP code that is the entry point to the application:
+
+.. sourcefile:: www/account.php
+
+.. sourcefile:: www/ac.js
+
+.. sourcefile:: www/ac.php
+
+.. sourcefile:: www/advertising.php
+
+.. sourcefile:: www/alert_hash_collision.php
+
+.. sourcefile:: www/analyse.php
+
+.. sourcefile:: www/cap.html.php
+
+.. sourcefile:: www/capnew.php
+
+.. sourcefile:: www/cap.php
+
+.. sourcefile:: www/coap.html.php
+
+.. sourcefile:: www/coapnew.php
+
+.. sourcefile:: www/disputes.php
+
+.. sourcefile:: www/error403.php
+
+.. sourcefile:: www/error404.php
+
+.. sourcefile:: www/favicon.ico
+
+.. sourcefile:: www/gpg.php
+
+.. sourcefile:: www/help.php
+
+.. sourcefile:: www/.htaccess
+
+.. sourcefile:: www/index.php
+
+.. sourcefile:: www/keygenIE.js
+
+.. sourcefile:: www/logos.php
+
+.. sourcefile:: www/news.php
+
+.. sourcefile:: www/rss.php
+
+.. sourcefile:: www/sealgen.php
+ :uses:
+ www/images/secured.png
+
+ :file:`sealgen.php` generates a small site seal image from
+ :sourcefile:`www/images/secured.png`. This could be replaced with a static
+ image if it is used at all.
+
+.. sourcefile:: www/siteimages
+
+.. sourcefile:: www/sqldump.php
+
+.. sourcefile:: www/src-lic.php
+
+.. sourcefile:: www/stats.php
+
+.. sourcefile:: www/ttp.php
+
+.. sourcefile:: www/verify.php
+
+.. sourcefile:: www/wot.php
+
+
+Directory :file:`www/api`
+=========================
+
+.. sourcefile:: www/api/ccsr.php
+
+.. sourcefile:: www/api/cemails.php
+
+.. sourcefile:: www/api/edu.php
+
+.. sourcefile:: www/api/index.php
+
+
+Directory :file:`www/cats`
+==========================
+
+.. sourcefile:: www/cats/cats_import.php
+
+
+Directory :file:`www/certs`
+===========================
+
+.. sourcefile:: www/certs/cacert.asc
+
+.. sourcefile:: www/certs/CAcert_Root_Certificates.msi
+
+.. sourcefile:: www/certs/class3.crt
+
+.. sourcefile:: www/certs/class3.der
+
+.. sourcefile:: www/certs/class3.txt
+
+.. sourcefile:: www/certs/root.crt
+
+.. sourcefile:: www/certs/root.der
+
+.. sourcefile:: www/certs/root.txt
+
+
+Directory :file:`www/docs`
+===========================
+
+.. sourcefile:: www/docs/banner.jpg
+
+.. sourcefile:: www/docs/cacert0304.pdf
+
+.. sourcefile:: www/docs/cacert_display.pdf
+
+.. sourcefile:: www/docs/cacert_display.sxw
+
+.. sourcefile:: www/docs/CAcert_Rules.pdf
+
+.. sourcefile:: www/docs/CAcert_Rules.sxw
+
+.. sourcefile:: www/docs/encryption in the real world.sxi
+
+.. sourcefile:: www/docs/flyer.sxw
+
+.. sourcefile:: www/docs/incorporation.jpg
+
+.. sourcefile:: www/docs/keys.pdf
+
+.. sourcefile:: www/docs/keys.ps
+
+
+Directory :file:`www/iistutorial`
+=================================
+
+.. sourcefile:: www/iistutorial/image001.jpg
+
+.. sourcefile:: www/iistutorial/image002.jpg
+
+.. sourcefile:: www/iistutorial/image003.gif
+
+.. sourcefile:: www/iistutorial/image004.gif
+
+.. sourcefile:: www/iistutorial/image005.gif
+
+.. sourcefile:: www/iistutorial/image006.gif
+
+.. sourcefile:: www/iistutorial/image007.gif
+
+.. sourcefile:: www/iistutorial/image008.gif
+
+.. sourcefile:: www/iistutorial/image009.gif
+
+.. sourcefile:: www/iistutorial/image010.gif
+
+.. sourcefile:: www/iistutorial/image011b.png
+
+.. sourcefile:: www/iistutorial/image011.jpg
+
+.. sourcefile:: www/iistutorial/image012.gif
+
+.. sourcefile:: www/iistutorial/image013.gif
+
+.. sourcefile:: www/iistutorial/image014.jpg
+
+.. sourcefile:: www/iistutorial/image015.gif
+
+
+Directory :file:`www/images`
+============================
+
+.. sourcefile:: www/images/bit.png
+
+.. sourcefile:: www/images/btn_paynowCC_LG.gif
+
+.. sourcefile:: www/images/btn_subscribeCC_LG.gif
+
+.. sourcefile:: www/images/cacert2.png
+
+.. sourcefile:: www/images/cacert3.png
+
+.. sourcefile:: www/images/cacert4.png
+
+.. sourcefile:: www/images/cacert-draft.png
+
+.. sourcefile:: www/images/CAcert-logo-colour-1000.png
+
+.. sourcefile:: www/images/CAcert-logo-mono-1000.png
+
+.. sourcefile:: www/images/cacert-policy.png
+
+.. sourcefile:: www/images/nlnet.png
+
+.. sourcefile:: www/images/oan.png
+
+.. sourcefile:: www/images/payment2a.png
+
+.. sourcefile:: www/images/payment2.png
+
+.. sourcefile:: www/images/secured.png
+
+.. sourcefile:: www/images/sonance.png
+
+.. sourcefile:: www/images/tunix.png
+
+.. sourcefile:: www/images/valid-xhtml11-blue
+
+
+Directory :file:`www/logos`
+===========================
+
+.. sourcefile:: www/logos/animated.gif
+
+.. sourcefile:: www/logos/cacert1.png
+
+.. sourcefile:: www/logos/cacert-free-certificates2.png
+
+.. sourcefile:: www/logos/cacert-free-certificates3.png
+
+.. sourcefile:: www/logos/cacert-free-certificates4.png
+
+.. sourcefile:: www/logos/cacert-grey2.png
+
+.. sourcefile:: www/logos/cacert-grey.png
+
+.. sourcefile:: www/logos/CAcert-logo-colour-1000.png
+
+.. sourcefile:: www/logos/CAcert-logo-colour.eps
+
+.. sourcefile:: www/logos/CAcert-logo-mono-1000.png
+
+.. sourcefile:: www/logos/CAcert-logo-mono.eps
+
+.. sourcefile:: www/logos/cacert-secured3.png
+
+.. sourcefile:: www/logos/cacert-secured4.png
+
+.. sourcefile:: www/logos/cacert-secured5.png
+
+.. sourcefile:: www/logos/cacert-secured7.png
+
+.. sourcefile:: www/logos/cacert-secure-site2.png
+
+.. sourcefile:: www/logos/cacert-secure-site.png
+
+.. sourcefile:: www/logos/small-ssl-secured-site.png
+
+.. sourcefile:: www/logos/small-ssl-security.png
+
+
+Directory :file:`www/policy`
+============================
+
+.. sourcefile:: www/policy/AssurancePolicy.html
+
+.. sourcefile:: www/policy/AssurancePolicy.php
+
+.. sourcefile:: www/policy/CAcertCommunityAgreement.html
+
+.. sourcefile:: www/policy/CAcertCommunityAgreement.php
+
+.. sourcefile:: www/policy/CertificationPracticeStatement.html
+
+.. sourcefile:: www/policy/CertificationPracticeStatement.php
+
+.. sourcefile:: www/policy/ConfigurationControlSpecification.html
+
+.. sourcefile:: www/policy/DisputeResolutionPolicy.html
+
+.. sourcefile:: www/policy/DisputeResolutionPolicy.php
+
+.. sourcefile:: www/policy/images
+
+.. sourcefile:: www/policy/index.php
+
+.. sourcefile:: www/policy/NRPDisclaimerAndLicence.php
+
+.. sourcefile:: www/policy/OrganisationAssurancePolicy_Australia.html
+
+.. sourcefile:: www/policy/OrganisationAssurancePolicy_Europe.html
+
+.. sourcefile:: www/policy/OrganisationAssurancePolicy_Germany.html
+
+.. sourcefile:: www/policy/OrganisationAssurancePolicy.html
+
+.. sourcefile:: www/policy/OrganisationAssurancePolicy.php
+
+.. sourcefile:: www/policy/PolicyOnJuniorAssurersMembers.html
+
+.. sourcefile:: www/policy/PolicyOnPolicy.html
+
+.. sourcefile:: www/policy/PolicyOnPolicy.php
+
+.. sourcefile:: www/policy/PrivacyPolicy.html
+
+.. sourcefile:: www/policy/PrivacyPolicy.php
+
+.. sourcefile:: www/policy/RootDistributionLicense.html
+
+.. sourcefile:: www/policy/RootDistributionLicense.php
+
+.. sourcefile:: www/policy/SecurityPolicy.html
+
+.. sourcefile:: www/policy/TTPAssistedAssurancePolicy.html
+
+
+Directory :file:`www/siteimages`
+================================
+
+.. sourcefile:: www/siteimages/bg_grad.jpg
+
+.. sourcefile:: www/siteimages/bg_nav.jpg
+
+.. sourcefile:: www/siteimages/gblnav_left.gif
+
+.. sourcefile:: www/siteimages/glblnav_selected.gif
+
+.. sourcefile:: www/siteimages/glbnav_background.gif
+
+.. sourcefile:: www/siteimages/glbnav_right.gif
+
+.. sourcefile:: www/siteimages/tl_curve_white.gif
+
+.. sourcefile:: www/siteimages/tr_curve_white.gif
+
+
+Directory :file:`www/styles`
+============================
+
+.. sourcefile:: www/styles/default.css
+
+
+Directory :file:`www/tverify`
+=============================
+
+.. sourcefile:: www/tverify/seclayer.php
+
+
+Directory :file:`www/utf8_to_ascii`
+===================================
+
+.. sourcefile:: www/utf8_to_ascii/ChangeLog
+
+.. sourcefile:: www/utf8_to_ascii/LICENSE
+
+.. sourcefile:: www/utf8_to_ascii/README
+
+.. sourcefile:: www/utf8_to_ascii/utf8_to_ascii.php
+
+.. _www-utf8_to_ascii-db:
+.. index:: utf8-to-ascii; database
+
+Directory :file:`www/utf8_to_ascii/db`
+======================================
+
+This Directory contains files :file:`x00.php` to :file:`xFF.php` in which an
+array is built to convert the symbols from UTF8-coding to ASCII-coding.
diff --git a/source/conf.py b/source/conf.py
index 5ebc900..4e0e14b 100644
--- a/source/conf.py
+++ b/source/conf.py
@@ -16,8 +16,8 @@ from datetime import datetime
import os
import certifi
import requests
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
+import sys
+sys.path.insert(0, os.path.abspath('.'))
from git import repo
from docutils import nodes, utils
@@ -65,6 +65,7 @@ extensions = [
'sphinxcontrib.phpdomain',
'sphinxcontrib.blockdiag',
'sphinxcontrib.seqdiag',
+ 'sphinxext.cacert',
]
# Add any paths that contain templates here, relative to this directory.
diff --git a/source/directories.rst b/source/directories.rst
index 3cba141..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
@@ -14,239 +11,20 @@ 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
- to invoke :ref:`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:
-
-.. _commmodule-client-pl:
-
-- :file:`client.pl` 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
- :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.
-
- 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
-
-- :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 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
- :ref:`client.pl <commmodule-client-pl>` in
- :file:`/home/cacert/www/CommModule/` and the
- second variant starts :ref:`server.pl <commmodule-server-pl>` in
- :file:`/home/signer/cacert-devel/CommModule/`.
-
-- :file:`logclean.sh` 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
-
-- :file:`serial.conf` serial port configuration file
-
- This file is read and written by both
- :ref:`client.pl <commmodule-client-pl>` and
- :ref:`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
-
-.. _commmodule-server-pl:
-
-- :file:`server.pl` the real server, running on the signing server
-
- 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
- :ref:`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 server.pl on git.cacert.org, the real production
- signer and the cacert-devel repository synchronized
-
-- :file:`usbclient.pl` obsoleted USB version of
- :ref:`client.pl <commmodule-client-pl>` above
-
- .. todo:: remove unused file (usbclient.pl)
-
-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`
-=====================
-
-This contains the PHP code that is the entry point to the application:
-
-.. _www-sealgen-php:
-
-- :file:`sealgen.php` generates a small site seal image from
- :ref:`www/images/secured.png <www-images-secured-png>`. This could be
- replaced with a static image if it is used at all. This is referenced
- by :ref:`cgi-bin/siteseal.cgi <cgi-bin-siteseal-cgi>`
-Directory :file:`www/images`
-============================
+.. toctree::
+ :maxdepth: 2
+ :caption: Documentation for subdirectories
+ :name: directorytoc
-.. _www-images-secured-png:
+ DIR-cgi-bin
+ DIR-CommModule
+ DIR-includes
+ DIR-locale
+ DIR-pages
+ DIR-scripts
+ DIR-stamp
+ DIR-tmp
+ DIR-tverify
+ DIR-www
-- :file:`secured.png` is a small image used by
- :ref:`www/sealgen.php <www-sealgen-php>`
diff --git a/source/signer.rst b/source/signer.rst
index ea8f18e..fb930d4 100644
--- a/source/signer.rst
+++ b/source/signer.rst
@@ -60,7 +60,7 @@ Format of NUL requests
----------------------
NUL requests are sent at the end of each iteration in
-:ref:`client.pl <commmodule-client-pl>`'s main loop.
+:sourcefile:`client.pl <CommModule/client.pl>`'s main loop.
.. table:: NUL request header format
@@ -95,7 +95,7 @@ Format of X.509 signing request messages
----------------------------------------
X.509 signing request messages are sent in
-:ref:`client.pl <commmodule-client-pl>`'s main loop for each requested
+:sourcefile:`client.pl <CommModule/client.pl>`'s main loop for each requested
certificate.
.. table:: X.509 certificate signing request header format
@@ -149,11 +149,11 @@ table which is one of
.. note::
The CA root identifier is retrieved from the database by
- :ref:`client.pl <commmodule-client-pl>` the value that is found there is
+ :sourcefile:`client.pl <CommModule/client.pl>` the value that is found there is
decremented by 1 before it is sent to the server.
- The server in :ref:`server.pl <commmodule-server-pl>` restricts the allowed
- root id in its ``CheckSystem`` function.
+ The server in :sourcefile:`server.pl <CommModule/server.pl>` restricts the
+ allowed root id in its ``CheckSystem`` function.
.. _table-cert-profiles:
@@ -178,7 +178,7 @@ table which is one of
.. note::
- :ref:`client.pl <commmodule-client-pl>` supports profiles 0, 1, 2, 4,
+ :sourcefile:`client.pl <CommModule/client.pl>` supports profiles 0, 1, 2, 4,
5, 6, 8 and 9 only.
.. _table-md-ids:
@@ -202,7 +202,7 @@ Format of OpenPGP key signing request messages
----------------------------------------------
OpenPGP key signing request messages are sent in
-:ref:`client.pl <commmodule-client-pl>`'s main loop for each requested
+:sourcefile:`client.pl <CommModule/client.pl>`'s main loop for each requested
OpenPGP key.
.. table:: OpenPGP key signing request header format
@@ -227,7 +227,7 @@ OpenPGP key.
- ""
.. [#unused-server] the field is unused in
- :ref:`server.pl <commmodule-server-pl>`
+ :sourcefile:`server.pl <CommModule/server.pl>`
.. _signer-csr-request-format:
@@ -235,7 +235,7 @@ Format of X.509 certificate revocation request messages
-------------------------------------------------------
X.509 certificate revocation request messages are sent in
-:ref:`client.pl <commmodule-client-pl>`'s main loop for each requested
+:sourcefile:`client.pl <Commmodule/client.pl>`'s main loop for each requested
X.509 certificate revocation.
==== ===========================
diff --git a/source/sphinxext/__init__.py b/source/sphinxext/__init__.py
new file mode 100644
index 0000000..e69de29
--- /dev/null
+++ b/source/sphinxext/__init__.py
diff --git a/source/sphinxext/cacert.py b/source/sphinxext/cacert.py
new file mode 100644
index 0000000..22153fa
--- /dev/null
+++ b/source/sphinxext/cacert.py
@@ -0,0 +1,213 @@
+# -*- python -*-
+# This module provides the following project specific sphinx directives
+#
+# sourcefile
+
+from docutils import nodes
+from docutils.parsers.rst import Directive
+from sphinx import addnodes, roles
+from sphinx.util.nodes import make_refnode, set_source_info
+
+_SOURCEFILES = 'cacert_sourcefiles'
+
+__version__ = '0.1.0'
+
+
+# noinspection PyPep8Naming
+class sourcefile_node(nodes.Structural, nodes.Element):
+ pass
+
+
+def file_list(argument):
+ if argument is None:
+ return []
+ else:
+ file_names = [s.strip() for s in argument.splitlines()]
+ return file_names
+
+
+class SourceFileRole(roles.XRefRole):
+ def __init__(self, fix_parens=False, lowercase=False, nodeclass=None,
+ warn_dangling=True):
+ super().__init__(fix_parens, lowercase, nodeclass, nodes.literal,
+ warn_dangling)
+
+ def process_link(self, env, refnode, has_explicit_title, title, target):
+ return title, 'sourcefile-{}'.format(nodes.make_id(target))
+
+ def result_nodes(self, document, env, node, is_ref):
+ try:
+ indexnode = addnodes.index()
+ targetid = 'index-%s' % env.new_serialno('index')
+ targetnode = nodes.target('', '', ids=[targetid])
+ doctitle = document.traverse(nodes.title)[0].astext()
+ idxtext = "%s; %s" % (node.astext(), doctitle)
+ idxtext2 = "%s; %s" % ('sourcefile', node.astext())
+ indexnode['entries'] = [
+ ('single', idxtext, targetid, '', None),
+ ('single', idxtext2, targetid, '', None),
+ ]
+ return [indexnode, targetnode, node], []
+ except KeyError as e:
+ return [node], [e.args[0]]
+
+
+def _source_file_info(env):
+ if not hasattr(env, _SOURCEFILES):
+ env.cacert_sourcefiles = {}
+ return env.cacert_sourcefiles
+
+
+class SourceFile(Directive):
+ """
+ A sourcefile entry in the form of an admonition.
+ """
+
+ has_content = True
+ required_arguments = 1
+ optional_arguments = 0
+ final_argument_whitespace = True
+ option_spec = {
+ 'uses': file_list,
+ 'links': file_list,
+ }
+
+ def run(self):
+ env = self.state.document.settings.env
+
+ file_name = self.arguments[0]
+
+ target_id = 'sourcefile-{}'.format(nodes.make_id(file_name))
+ section = nodes.section(ids=[target_id])
+
+ section += nodes.title(text=file_name)
+
+ par = nodes.paragraph()
+ self.state.nested_parse(self.content, self.content_offset, par)
+
+ node = sourcefile_node()
+ node.attributes['file_name'] = file_name
+ node += section
+
+ _source_file_info(env)[file_name] = {
+ 'docname': env.docname,
+ 'lineno': self.lineno,
+ 'target_id': target_id,
+ 'uses': self.options.get('uses', []),
+ 'links': self.options.get('links', [])
+ }
+
+ node += par
+ set_source_info(self, node)
+
+ return [node]
+
+
+def _get_sourcefile_index_text(place_info):
+ return "Source file; {}".format(place_info['filename'])
+
+
+def by_filename(item):
+ return item[2].lower()
+
+
+def _add_reference_list(node, title, target_list, fromdocname, app):
+ if target_list:
+ para = nodes.paragraph()
+ para += nodes.emphasis(text=title)
+ items = nodes.bullet_list()
+ para += items
+ for item in sorted(target_list, key=by_filename):
+ list_item = nodes.list_item()
+ items += list_item
+ refnode = nodes.reference('', '')
+ innernode = nodes.literal(text=item[2])
+ refnode['refdocname'] = item[0]
+ refnode['refuri'] = "{}#{}".format(
+ app.builder.get_relative_uri(fromdocname, item[0]),
+ item[1])
+ refnode += innernode
+ refpara = nodes.paragraph()
+ refpara += refnode
+ list_item += refpara
+ node.insert(-1, para)
+
+
+def process_sourcefiles(app, doctree):
+ env = app.builder.env
+
+ source_file_info = _source_file_info(env)
+ for node in doctree.traverse(sourcefile_node):
+ file_name = node.attributes['file_name']
+ info = source_file_info[file_name]
+ outgoing_uses = [
+ (item['docname'], item['target_id'], use)
+ for item, use in [
+ (source_file_info[use], use)
+ for use in source_file_info[file_name]['uses']
+ if use in source_file_info]]
+ outgoing_links = [
+ (item['docname'], item['target_id'], link)
+ for item, link in [
+ (source_file_info[link], link)
+ for link in source_file_info[file_name]['links']
+ if link in source_file_info]]
+ incoming_uses = [
+ (value['docname'], value['target_id'], key)
+ for key, value in source_file_info.items()
+ if file_name in value['uses']]
+ incoming_links = [
+ (value['docname'], value['target_id'], key)
+ for key, value in source_file_info.items()
+ if file_name in value['links']]
+ _add_reference_list(
+ node, 'Uses', outgoing_uses, env.docname, app)
+ _add_reference_list(
+ node, 'Links to', outgoing_links, env.docname, app)
+ _add_reference_list(
+ node, 'Used by', incoming_uses, env.docname, app)
+ _add_reference_list(
+ node, 'Linked from', incoming_links, env.docname, app)
+
+
+def resolve_missing_references(app, env, node, contnode):
+ if node['reftype'] == 'sourcefile':
+ target = [
+ value for value in _source_file_info(env).values()
+ if value['target_id'] == node['reftarget']]
+ if len(target) == 1:
+ return make_refnode(
+ app.builder, node['refdoc'], target[0]['docname'],
+ node['reftarget'], contnode)
+
+
+def purge_sourcefiles(app, env, docname):
+ if not hasattr(env, 'cacert_sourcefiles'):
+ return
+ env.cacert_sourcefiles = dict([
+ (key, value) for key, value in env.cacert_sourcefiles.items()
+ if value['docname'] != docname])
+
+
+def visit_sourcefile_node(self, node):
+ self.visit_admonition(node)
+
+
+def depart_sourcefile_node(self, node):
+ self.depart_admonition(node)
+
+
+def setup(app):
+ app.add_node(
+ sourcefile_node,
+ html=(visit_sourcefile_node, depart_sourcefile_node))
+
+ app.add_role('sourcefile', SourceFileRole())
+
+ app.add_directive('sourcefile', SourceFile)
+
+ app.connect('doctree-read', process_sourcefiles)
+ app.connect('missing-reference', resolve_missing_references)
+ app.connect('env-purge-doc', purge_sourcefiles)
+
+ return {'version': __version__}