cacert/cacert-codedocs
9
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Merge pull request #1 from CAcertOrg/master

Browse source 
get info from original
This commit is contained in:
Karl-Heinz Gödderz 2018-11-11 16:34:35 +01:00 committed by GitHub
commit ff1a605ee3
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
15 changed files with 1468 additions and 249 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

164
source/DIR-CommModule.rst Normal file
View file

@ -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)

20
source/DIR-cgi-bin.rst Normal file
View file

@ -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

117
source/DIR-includes.rst Normal file
View file

@ -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

11
source/DIR-locale.rst Normal file
View file

@ -0,0 +1,11 @@
.. index:: locale
========================
Directory :file:`locale`
========================
.. sourcefile:: locale/cv.c
.. sourcefile:: locale/escape_special_chars.php
.. sourcefile:: locale/makefile

278
source/DIR-pages.rst Normal file
View file

@ -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

213
source/DIR-scripts.rst Normal file
View file

@ -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

31
source/DIR-stamp.rst Normal file
View file

@ -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

5
source/DIR-tmp.rst Normal file
View file

@ -0,0 +1,5 @@
=====================
Directory :file:`tmp`
=====================
.. sourcefile:: tmp/Makefile

21
source/DIR-tverify.rst Normal file
View file

@ -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

367
source/DIR-www.rst Normal file
View file

@ -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.

5
source/conf.py
View file

@ -16,8 +16,8 @@ from datetime import datetime
import os import os
import certifi import certifi
import requests import requests
# import sys import sys
# sys.path.insert(0, os.path.abspath('.')) sys.path.insert(0, os.path.abspath('.'))
from git import repo from git import repo
from docutils import nodes, utils from docutils import nodes, utils
@ -65,6 +65,7 @@ extensions = [
'sphinxcontrib.phpdomain', 'sphinxcontrib.phpdomain',
'sphinxcontrib.blockdiag', 'sphinxcontrib.blockdiag',
'sphinxcontrib.seqdiag', 'sphinxcontrib.seqdiag',
'sphinxext.cacert',
] ]
# Add any paths that contain templates here, relative to this directory. # Add any paths that contain templates here, relative to this directory.

254
source/directories.rst
View file

@ -2,10 +2,7 @@
Directory structure Directory structure
=================== ===================
root Directory The root directory of the :cacertgit:`cacert-devel` tree contains
==============
The root directory contains
- a :file:`.gitignore` file with a list of excluded files - a :file:`.gitignore` file with a list of excluded files
- a :file:`LICENSE` file the `GPL`_ license text - 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 .. _GPL: https://www.gnu.org/licenses/old-licenses/gpl-2.0
.. index:: cgi-bin
Directory :file:`cgi-bin` .. toctree::
========================= :maxdepth: 2
: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
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`
============================
.. _www-images-secured-png:
- :file:`secured.png` is a small image used by
:ref:`www/sealgen.php <www-sealgen-php>`

18
source/signer.rst
View file

@ -60,7 +60,7 @@ Format of NUL requests
---------------------- ----------------------
NUL requests are sent at the end of each iteration in 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 .. table:: NUL request header format
@ -95,7 +95,7 @@ Format of X.509 signing request messages
---------------------------------------- ----------------------------------------
X.509 signing request messages are sent in 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. certificate.
.. table:: X.509 certificate signing request header format .. table:: X.509 certificate signing request header format
@ -149,11 +149,11 @@ table which is one of
.. note:: .. note::
The CA root identifier is retrieved from the database by 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. decremented by 1 before it is sent to the server.
The server in :ref:`server.pl <commmodule-server-pl>` restricts the allowed The server in :sourcefile:`server.pl <CommModule/server.pl>` restricts the
root id in its ``CheckSystem`` function. allowed root id in its ``CheckSystem`` function.
.. _table-cert-profiles: .. _table-cert-profiles:
@ -178,7 +178,7 @@ table which is one of
.. note:: .. 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. 5, 6, 8 and 9 only.
.. _table-md-ids: .. _table-md-ids:
@ -202,7 +202,7 @@ Format of OpenPGP key signing request messages
---------------------------------------------- ----------------------------------------------
OpenPGP key signing request messages are sent in 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. OpenPGP key.
.. table:: OpenPGP key signing request header format .. table:: OpenPGP key signing request header format
@ -227,7 +227,7 @@ OpenPGP key.
- "" - ""
.. [#unused-server] the field is unused in .. [#unused-server] the field is unused in
:ref:`server.pl <commmodule-server-pl>` :sourcefile:`server.pl <CommModule/server.pl>`
.. _signer-csr-request-format: .. _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 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. X.509 certificate revocation.
==== =========================== ==== ===========================

0
source/sphinxext/__init__.py Normal file
View file

213
source/sphinxext/cacert.py Normal file
View file

@ -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__}