summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--.gitignore1
-rw-r--r--LICENSE339
-rw-r--r--Pipfile5
-rw-r--r--Pipfile.lock104
-rw-r--r--README.md38
-rw-r--r--cacert.pem83
-rw-r--r--help-files/PARAM-files21
-rw-r--r--help-files/PROGRAM-files34
-rw-r--r--source/DIR-CommModule.rst164
-rw-r--r--source/DIR-cgi-bin.rst20
-rw-r--r--source/DIR-includes.rst1138
-rw-r--r--source/DIR-locale.rst11
-rw-r--r--source/DIR-pages.rst282
-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.rst382
-rw-r--r--source/_static/.keep0
-rw-r--r--source/building.rst95
-rw-r--r--source/conf.py35
-rw-r--r--source/database.rst6
-rw-r--r--source/directories.rst30
-rw-r--r--source/general.rst26
-rw-r--r--source/globals.rst161
-rw-r--r--source/glossary.rst16
-rw-r--r--source/index.rst18
-rw-r--r--source/signer.rst486
-rw-r--r--source/sphinxext/__init__.py0
-rw-r--r--source/sphinxext/cacert.py213
-rw-r--r--source/structure.txt30
31 files changed, 3979 insertions, 29 deletions
diff --git a/.gitignore b/.gitignore
index f2a277b..8981fc7 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,3 +1,4 @@
.*.swp
.idea/
build
+.ropeproject/
diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000..d159169
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,339 @@
+ GNU GENERAL PUBLIC LICENSE
+ Version 2, June 1991
+
+ Copyright (C) 1989, 1991 Free Software Foundation, Inc.,
+ 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+ Preamble
+
+ The licenses for most software are designed to take away your
+freedom to share and change it. By contrast, the GNU General Public
+License is intended to guarantee your freedom to share and change free
+software--to make sure the software is free for all its users. This
+General Public License applies to most of the Free Software
+Foundation's software and to any other program whose authors commit to
+using it. (Some other Free Software Foundation software is covered by
+the GNU Lesser General Public License instead.) You can apply it to
+your programs, too.
+
+ When we speak of free software, we are referring to freedom, not
+price. Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+this service if you wish), that you receive source code or can get it
+if you want it, that you can change the software or use pieces of it
+in new free programs; and that you know you can do these things.
+
+ To protect your rights, we need to make restrictions that forbid
+anyone to deny you these rights or to ask you to surrender the rights.
+These restrictions translate to certain responsibilities for you if you
+distribute copies of the software, or if you modify it.
+
+ For example, if you distribute copies of such a program, whether
+gratis or for a fee, you must give the recipients all the rights that
+you have. You must make sure that they, too, receive or can get the
+source code. And you must show them these terms so they know their
+rights.
+
+ We protect your rights with two steps: (1) copyright the software, and
+(2) offer you this license which gives you legal permission to copy,
+distribute and/or modify the software.
+
+ Also, for each author's protection and ours, we want to make certain
+that everyone understands that there is no warranty for this free
+software. If the software is modified by someone else and passed on, we
+want its recipients to know that what they have is not the original, so
+that any problems introduced by others will not reflect on the original
+authors' reputations.
+
+ Finally, any free program is threatened constantly by software
+patents. We wish to avoid the danger that redistributors of a free
+program will individually obtain patent licenses, in effect making the
+program proprietary. To prevent this, we have made it clear that any
+patent must be licensed for everyone's free use or not licensed at all.
+
+ The precise terms and conditions for copying, distribution and
+modification follow.
+
+ GNU GENERAL PUBLIC LICENSE
+ TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+
+ 0. This License applies to any program or other work which contains
+a notice placed by the copyright holder saying it may be distributed
+under the terms of this General Public License. The "Program", below,
+refers to any such program or work, and a "work based on the Program"
+means either the Program or any derivative work under copyright law:
+that is to say, a work containing the Program or a portion of it,
+either verbatim or with modifications and/or translated into another
+language. (Hereinafter, translation is included without limitation in
+the term "modification".) Each licensee is addressed as "you".
+
+Activities other than copying, distribution and modification are not
+covered by this License; they are outside its scope. The act of
+running the Program is not restricted, and the output from the Program
+is covered only if its contents constitute a work based on the
+Program (independent of having been made by running the Program).
+Whether that is true depends on what the Program does.
+
+ 1. You may copy and distribute verbatim copies of the Program's
+source code as you receive it, in any medium, provided that you
+conspicuously and appropriately publish on each copy an appropriate
+copyright notice and disclaimer of warranty; keep intact all the
+notices that refer to this License and to the absence of any warranty;
+and give any other recipients of the Program a copy of this License
+along with the Program.
+
+You may charge a fee for the physical act of transferring a copy, and
+you may at your option offer warranty protection in exchange for a fee.
+
+ 2. You may modify your copy or copies of the Program or any portion
+of it, thus forming a work based on the Program, and copy and
+distribute such modifications or work under the terms of Section 1
+above, provided that you also meet all of these conditions:
+
+ a) You must cause the modified files to carry prominent notices
+ stating that you changed the files and the date of any change.
+
+ b) You must cause any work that you distribute or publish, that in
+ whole or in part contains or is derived from the Program or any
+ part thereof, to be licensed as a whole at no charge to all third
+ parties under the terms of this License.
+
+ c) If the modified program normally reads commands interactively
+ when run, you must cause it, when started running for such
+ interactive use in the most ordinary way, to print or display an
+ announcement including an appropriate copyright notice and a
+ notice that there is no warranty (or else, saying that you provide
+ a warranty) and that users may redistribute the program under
+ these conditions, and telling the user how to view a copy of this
+ License. (Exception: if the Program itself is interactive but
+ does not normally print such an announcement, your work based on
+ the Program is not required to print an announcement.)
+
+These requirements apply to the modified work as a whole. If
+identifiable sections of that work are not derived from the Program,
+and can be reasonably considered independent and separate works in
+themselves, then this License, and its terms, do not apply to those
+sections when you distribute them as separate works. But when you
+distribute the same sections as part of a whole which is a work based
+on the Program, the distribution of the whole must be on the terms of
+this License, whose permissions for other licensees extend to the
+entire whole, and thus to each and every part regardless of who wrote it.
+
+Thus, it is not the intent of this section to claim rights or contest
+your rights to work written entirely by you; rather, the intent is to
+exercise the right to control the distribution of derivative or
+collective works based on the Program.
+
+In addition, mere aggregation of another work not based on the Program
+with the Program (or with a work based on the Program) on a volume of
+a storage or distribution medium does not bring the other work under
+the scope of this License.
+
+ 3. You may copy and distribute the Program (or a work based on it,
+under Section 2) in object code or executable form under the terms of
+Sections 1 and 2 above provided that you also do one of the following:
+
+ a) Accompany it with the complete corresponding machine-readable
+ source code, which must be distributed under the terms of Sections
+ 1 and 2 above on a medium customarily used for software interchange; or,
+
+ b) Accompany it with a written offer, valid for at least three
+ years, to give any third party, for a charge no more than your
+ cost of physically performing source distribution, a complete
+ machine-readable copy of the corresponding source code, to be
+ distributed under the terms of Sections 1 and 2 above on a medium
+ customarily used for software interchange; or,
+
+ c) Accompany it with the information you received as to the offer
+ to distribute corresponding source code. (This alternative is
+ allowed only for noncommercial distribution and only if you
+ received the program in object code or executable form with such
+ an offer, in accord with Subsection b above.)
+
+The source code for a work means the preferred form of the work for
+making modifications to it. For an executable work, complete source
+code means all the source code for all modules it contains, plus any
+associated interface definition files, plus the scripts used to
+control compilation and installation of the executable. However, as a
+special exception, the source code distributed need not include
+anything that is normally distributed (in either source or binary
+form) with the major components (compiler, kernel, and so on) of the
+operating system on which the executable runs, unless that component
+itself accompanies the executable.
+
+If distribution of executable or object code is made by offering
+access to copy from a designated place, then offering equivalent
+access to copy the source code from the same place counts as
+distribution of the source code, even though third parties are not
+compelled to copy the source along with the object code.
+
+ 4. You may not copy, modify, sublicense, or distribute the Program
+except as expressly provided under this License. Any attempt
+otherwise to copy, modify, sublicense or distribute the Program is
+void, and will automatically terminate your rights under this License.
+However, parties who have received copies, or rights, from you under
+this License will not have their licenses terminated so long as such
+parties remain in full compliance.
+
+ 5. You are not required to accept this License, since you have not
+signed it. However, nothing else grants you permission to modify or
+distribute the Program or its derivative works. These actions are
+prohibited by law if you do not accept this License. Therefore, by
+modifying or distributing the Program (or any work based on the
+Program), you indicate your acceptance of this License to do so, and
+all its terms and conditions for copying, distributing or modifying
+the Program or works based on it.
+
+ 6. Each time you redistribute the Program (or any work based on the
+Program), the recipient automatically receives a license from the
+original licensor to copy, distribute or modify the Program subject to
+these terms and conditions. You may not impose any further
+restrictions on the recipients' exercise of the rights granted herein.
+You are not responsible for enforcing compliance by third parties to
+this License.
+
+ 7. If, as a consequence of a court judgment or allegation of patent
+infringement or for any other reason (not limited to patent issues),
+conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License. If you cannot
+distribute so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you
+may not distribute the Program at all. For example, if a patent
+license would not permit royalty-free redistribution of the Program by
+all those who receive copies directly or indirectly through you, then
+the only way you could satisfy both it and this License would be to
+refrain entirely from distribution of the Program.
+
+If any portion of this section is held invalid or unenforceable under
+any particular circumstance, the balance of the section is intended to
+apply and the section as a whole is intended to apply in other
+circumstances.
+
+It is not the purpose of this section to induce you to infringe any
+patents or other property right claims or to contest validity of any
+such claims; this section has the sole purpose of protecting the
+integrity of the free software distribution system, which is
+implemented by public license practices. Many people have made
+generous contributions to the wide range of software distributed
+through that system in reliance on consistent application of that
+system; it is up to the author/donor to decide if he or she is willing
+to distribute software through any other system and a licensee cannot
+impose that choice.
+
+This section is intended to make thoroughly clear what is believed to
+be a consequence of the rest of this License.
+
+ 8. If the distribution and/or use of the Program is restricted in
+certain countries either by patents or by copyrighted interfaces, the
+original copyright holder who places the Program under this License
+may add an explicit geographical distribution limitation excluding
+those countries, so that distribution is permitted only in or among
+countries not thus excluded. In such case, this License incorporates
+the limitation as if written in the body of this License.
+
+ 9. The Free Software Foundation may publish revised and/or new versions
+of the General Public License from time to time. Such new versions will
+be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+Each version is given a distinguishing version number. If the Program
+specifies a version number of this License which applies to it and "any
+later version", you have the option of following the terms and conditions
+either of that version or of any later version published by the Free
+Software Foundation. If the Program does not specify a version number of
+this License, you may choose any version ever published by the Free Software
+Foundation.
+
+ 10. If you wish to incorporate parts of the Program into other free
+programs whose distribution conditions are different, write to the author
+to ask for permission. For software which is copyrighted by the Free
+Software Foundation, write to the Free Software Foundation; we sometimes
+make exceptions for this. Our decision will be guided by the two goals
+of preserving the free status of all derivatives of our free software and
+of promoting the sharing and reuse of software generally.
+
+ NO WARRANTY
+
+ 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
+FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
+OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
+PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
+OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS
+TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
+PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
+REPAIR OR CORRECTION.
+
+ 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
+REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
+INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
+OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
+TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
+YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
+PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGES.
+
+ END OF TERMS AND CONDITIONS
+
+ How to Apply These Terms to Your New Programs
+
+ If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+ To do so, attach the following notices to the program. It is safest
+to attach them to the start of each source file to most effectively
+convey the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+
+ <one line to give the program's name and a brief idea of what it does.>
+ Copyright (C) <year> <name of author>
+
+ This program is free software; you can redistribute it and/or modify
+ it under the terms of the GNU General Public License as published by
+ the Free Software Foundation; either version 2 of the License, or
+ (at your option) any later version.
+
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ GNU General Public License for more details.
+
+ You should have received a copy of the GNU General Public License along
+ with this program; if not, write to the Free Software Foundation, Inc.,
+ 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
+Also add information on how to contact you by electronic and paper mail.
+
+If the program is interactive, make it output a short notice like this
+when it starts in an interactive mode:
+
+ Gnomovision version 69, Copyright (C) year name of author
+ Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
+ This is free software, and you are welcome to redistribute it
+ under certain conditions; type `show c' for details.
+
+The hypothetical commands `show w' and `show c' should show the appropriate
+parts of the General Public License. Of course, the commands you use may
+be called something other than `show w' and `show c'; they could even be
+mouse-clicks or menu items--whatever suits your program.
+
+You should also get your employer (if you work as a programmer) or your
+school, if any, to sign a "copyright disclaimer" for the program, if
+necessary. Here is a sample; alter the names:
+
+ Yoyodyne, Inc., hereby disclaims all copyright interest in the program
+ `Gnomovision' (which makes passes at compilers) written by James Hacker.
+
+ <signature of Ty Coon>, 1 April 1989
+ Ty Coon, President of Vice
+
+This General Public License does not permit incorporating your program into
+proprietary programs. If your program is a subroutine library, you may
+consider it more useful to permit linking proprietary applications with the
+library. If this is what you want to do, use the GNU Lesser General
+Public License instead of this License.
diff --git a/Pipfile b/Pipfile
index d8026a3..91155e2 100644
--- a/Pipfile
+++ b/Pipfile
@@ -6,6 +6,11 @@ name = "pypi"
[packages]
sphinx = "*"
GitPython = "*"
+certifi = "*"
+requests = "*"
+sphinxcontrib-phpdomain = "*"
+sphinxcontrib-blockdiag = "*"
+sphinxcontrib-seqdiag = "*"
[dev-packages]
diff --git a/Pipfile.lock b/Pipfile.lock
index c7f5957..534cb7a 100644
--- a/Pipfile.lock
+++ b/Pipfile.lock
@@ -1,7 +1,7 @@
{
"_meta": {
"hash": {
- "sha256": "79ff5ee916caddd1a501ea9f2a89f04e6f4b7ace5aee173ebdbf80e5d49ea6de"
+ "sha256": "49436bd593c2b93213655f26a631e356f4630a0358f6515516588831ff8ee25f"
},
"pipfile-spec": 6,
"requires": {
@@ -30,11 +30,19 @@
],
"version": "==2.6.0"
},
+ "blockdiag": {
+ "hashes": [
+ "sha256:8dd6570a2ac41b3c0dfe5706de20913cdbebe1bbd2e6dea9ebc13db79df8c151",
+ "sha256:929125db1cb59145e09dc561021389c7ca71108ef4e4c51a12728eea5b75fccc"
+ ],
+ "version": "==1.5.4"
+ },
"certifi": {
"hashes": [
"sha256:339dc09518b07e2fa7eda5450740925974815557727d6bd35d319c1524a04a4c",
"sha256:6d58c986d22b038c8c0df30d639f23a3e6d172a05c3583e766f4c0b785c0986a"
],
+ "index": "pypi",
"version": "==2018.10.15"
},
"chardet": {
@@ -52,12 +60,17 @@
],
"version": "==0.14"
},
+ "funcparserlib": {
+ "hashes": [
+ "sha256:b7992eac1a3eb97b3d91faa342bfda0729e990bd8a43774c1592c091e563c91d"
+ ],
+ "version": "==0.3.6"
+ },
"gitdb2": {
"hashes": [
"sha256:83361131a1836661a155172932a13c08bda2db3674e4caa32368aa6eb02f38c2",
"sha256:e3a0141c5f2a3f635c7209d56c496ebe1ad35da82fe4d3ec4aaa36278d70648a"
],
- "markers": "python_version != '3.1.*' and python_version != '3.2.*' and python_version != '3.3.*' and python_version != '3.0.*' and python_version >= '2.7'",
"version": "==2.0.5"
},
"gitpython": {
@@ -80,7 +93,6 @@
"sha256:3f349de3eb99145973fefb7dbe38554414e5c30abd0c8e4b970a7c9d09f3a1d8",
"sha256:f3832918bc3c66617f92e35f5d70729187676313caa60c187eb0f28b8fe5e3b5"
],
- "markers": "python_version != '3.2.*' and python_version != '3.0.*' and python_version != '3.1.*' and python_version != '3.3.*' and python_version >= '2.7'",
"version": "==1.1.0"
},
"jinja2": {
@@ -101,9 +113,43 @@
"sha256:0886227f54515e592aaa2e5a553332c73962917f2831f1b0f9b9f4380a4b9807",
"sha256:f95a1e147590f204328170981833854229bb2912ac3d5f89e2a8ccd2834800c9"
],
- "markers": "python_version != '3.0.*' and python_version != '3.1.*' and python_version != '3.2.*' and python_version >= '2.6'",
"version": "==18.0"
},
+ "pillow": {
+ "hashes": [
+ "sha256:00203f406818c3f45d47bb8fe7e67d3feddb8dcbbd45a289a1de7dd789226360",
+ "sha256:0616f800f348664e694dddb0b0c88d26761dd5e9f34e1ed7b7a7d2da14b40cb7",
+ "sha256:1f7908aab90c92ad85af9d2fec5fc79456a89b3adcc26314d2cde0e238bd789e",
+ "sha256:2ea3517cd5779843de8a759c2349a3cd8d3893e03ab47053b66d5ec6f8bc4f93",
+ "sha256:48a9f0538c91fc136b3a576bee0e7cd174773dc9920b310c21dcb5519722e82c",
+ "sha256:5280ebc42641a1283b7b1f2c20e5b936692198b9dd9995527c18b794850be1a8",
+ "sha256:5e34e4b5764af65551647f5cc67cf5198c1d05621781d5173b342e5e55bf023b",
+ "sha256:63b120421ab85cad909792583f83b6ca3584610c2fe70751e23f606a3c2e87f0",
+ "sha256:696b5e0109fe368d0057f484e2e91717b49a03f1e310f857f133a4acec9f91dd",
+ "sha256:870ed021a42b1b02b5fe4a739ea735f671a84128c0a666c705db2cb9abd528eb",
+ "sha256:916da1c19e4012d06a372127d7140dae894806fad67ef44330e5600d77833581",
+ "sha256:9303a289fa0811e1c6abd9ddebfc770556d7c3311cb2b32eff72164ddc49bc64",
+ "sha256:9577888ecc0ad7d06c3746afaba339c94d62b59da16f7a5d1cff9e491f23dace",
+ "sha256:987e1c94a33c93d9b209315bfda9faa54b8edfce6438a1e93ae866ba20de5956",
+ "sha256:99a3bbdbb844f4fb5d6dd59fac836a40749781c1fa63c563bc216c27aef63f60",
+ "sha256:99db8dc3097ceafbcff9cb2bff384b974795edeb11d167d391a02c7bfeeb6e16",
+ "sha256:a5a96cf49eb580756a44ecf12949e52f211e20bffbf5a95760ac14b1e499cd37",
+ "sha256:aa6ca3eb56704cdc0d876fc6047ffd5ee960caad52452fbee0f99908a141a0ae",
+ "sha256:aade5e66795c94e4a2b2624affeea8979648d1b0ae3fcee17e74e2c647fc4a8a",
+ "sha256:b78905860336c1d292409e3df6ad39cc1f1c7f0964e66844bbc2ebfca434d073",
+ "sha256:b92f521cdc4e4a3041cc343625b699f20b0b5f976793fb45681aac1efda565f8",
+ "sha256:bfde84bbd6ae5f782206d454b67b7ee8f7f818c29b99fd02bf022fd33bab14cb",
+ "sha256:c2b62d3df80e694c0e4a0ed47754c9480521e25642251b3ab1dff050a4e60409",
+ "sha256:c5e2be6c263b64f6f7656e23e18a4a9980cffc671442795682e8c4e4f815dd9f",
+ "sha256:c99aa3c63104e0818ec566f8ff3942fb7c7a8f35f9912cb63fd8e12318b214b2",
+ "sha256:dae06620d3978da346375ebf88b9e2dd7d151335ba668c995aea9ed07af7add4",
+ "sha256:db5499d0710823fa4fb88206050d46544e8f0e0136a9a5f5570b026584c8fd74",
+ "sha256:f36baafd82119c4a114b9518202f2a983819101dcc14b26e43fc12cbefdce00e",
+ "sha256:f52b79c8796d81391ab295b04e520bda6feed54d54931708872e8f9ae9db0ea1",
+ "sha256:ff8cff01582fa1a7e533cb97f628531c4014af4b5f38e33cdcfe5eec29b6d888"
+ ],
+ "version": "==5.3.0"
+ },
"pygments": {
"hashes": [
"sha256:78f3f434bcc5d6ee09020f92ba487f95ba50f1e3ef83ae96b9d5ffa1bab25c5d",
@@ -116,7 +162,6 @@
"sha256:bc6c7146b91af3f567cf6daeaec360bc07d45ffec4cf5353f4d7a208ce7ca30a",
"sha256:d29593d8ebe7b57d6967b62494f8c72b03ac0262b1eed63826c6f788b3606401"
],
- "markers": "python_version != '3.0.*' and python_version != '3.1.*' and python_version != '3.2.*' and python_version >= '2.6'",
"version": "==2.2.2"
},
"pytz": {
@@ -131,9 +176,16 @@
"sha256:99dcfdaaeb17caf6e526f32b6a7b780461512ab3f1d992187801694cba42770c",
"sha256:a84b8c9ab6239b578f22d1c21d51b696dcfe004032bb80ea832398d6909d7279"
],
- "markers": "python_version != '3.1.*' and python_version != '3.2.*' and python_version != '3.3.*' and python_version != '3.0.*' and python_version < '4' and python_version >= '2.7'",
+ "index": "pypi",
"version": "==2.20.0"
},
+ "seqdiag": {
+ "hashes": [
+ "sha256:78104e7644c1a4d3a5cacb68de6a7f720793f08dd78561ef0e9e80bed63702bf",
+ "sha256:887cf56b00bd2492e17ef3a16c4270ff263df3c249eddea85844bb61b594785a"
+ ],
+ "version": "==0.9.6"
+ },
"six": {
"hashes": [
"sha256:70e8a77beed4562e7f14fe23a786b54f6296e34344c23bc42f07b15018ff98e9",
@@ -146,7 +198,6 @@
"sha256:0555a7bf4df71d1ef4218e4807bbf9b201f910174e6e08af2e138d4e517b4dde",
"sha256:29a9ffa0497e7f2be94ca0ed1ca1aa3cd4cf25a1f6b4f5f87f74b46ed91d609a"
],
- "markers": "python_version != '3.1.*' and python_version != '3.2.*' and python_version != '3.3.*' and python_version != '3.0.*' and python_version >= '2.7'",
"version": "==2.0.5"
},
"snowballstemmer": {
@@ -164,21 +215,50 @@
"index": "pypi",
"version": "==1.8.1"
},
+ "sphinxcontrib-blockdiag": {
+ "hashes": [
+ "sha256:2d2ccde16bafb061ae8d2008f9524726e8ccd2a8502651b76a1e7f07a4ffd8eb",
+ "sha256:7cdff966d8f372b9536374954314a6cf4280e0e48bc2321a4f25cc7f2114f8f0"
+ ],
+ "index": "pypi",
+ "version": "==1.5.5"
+ },
+ "sphinxcontrib-phpdomain": {
+ "hashes": [
+ "sha256:14ecb0b477dddf8ce2c69b72ab15e3455a591d077264808a4f0d35f488b54a5f",
+ "sha256:ec0286d66233839994a2c812345bbd3f02feca28da941b552bce7d48eb8980f4"
+ ],
+ "index": "pypi",
+ "version": "==0.4.1"
+ },
+ "sphinxcontrib-seqdiag": {
+ "hashes": [
+ "sha256:83c3fdac7e083c5b217f65359c03b75af753209028db6b261b196aff19e7003f",
+ "sha256:c83f2b552e8e0829dbee22a13c5025f33c0b31a7e87bb589611928c2883d3db5"
+ ],
+ "index": "pypi",
+ "version": "==0.8.5"
+ },
"sphinxcontrib-websupport": {
"hashes": [
"sha256:68ca7ff70785cbe1e7bccc71a48b5b6d965d79ca50629606c7861a21b206d9dd",
"sha256:9de47f375baf1ea07cdb3436ff39d7a9c76042c10a769c52353ec46e4e8fc3b9"
],
- "markers": "python_version != '3.1.*' and python_version != '3.0.*' and python_version >= '2.7' and python_version != '3.3.*' and python_version != '3.2.*'",
"version": "==1.1.0"
},
"urllib3": {
"hashes": [
- "sha256:a68ac5e15e76e7e5dd2b8f94007233e01effe3e50e8daddf69acfd81cb686baf",
- "sha256:b5725a0bd4ba422ab0e66e89e030c806576753ea3ee08554382c14e685d117b5"
+ "sha256:41c3db2fc01e5b907288010dec72f9d0a74e37d6994e6eb56849f59fea2265ae",
+ "sha256:8819bba37a02d143296a4d032373c4dd4aca11f6d4c9973335ca75f9c8475f59"
],
- "markers": "python_version != '3.1.*' and python_version != '3.0.*' and python_version < '4' and python_version != '3.3.*' and python_version != '3.2.*' and python_version >= '2.6'",
- "version": "==1.23"
+ "version": "==1.24"
+ },
+ "webcolors": {
+ "hashes": [
+ "sha256:030562f624467a9901f0b455fef05486a88cfb5daa1e356bd4aacea043850b59",
+ "sha256:b3b88e5ef2b35fa9e01e3fabe99dddf49da074459c44774c59f3ccab3be4f121"
+ ],
+ "version": "==1.8.1"
}
},
"develop": {}
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..d339ceb
--- /dev/null
+++ b/README.md
@@ -0,0 +1,38 @@
+CAcert code documentation repository
+====================================
+
+This repository contains documentation for the CAcert code base at
+https://git.cacert.org/gitweb/?p=cacert-devel.git;a=shortlog;h=refs/heads/release
+which is mirrored to https://github.com/CAcertOrg/cacert-devel.
+
+The canonical repository is hosted at
+https://git.cacert.org/gitweb/?p=cacert-codedocs.git. An automatically updated
+mirror is available at https://github.com/CAcertOrg/cacert-codedocs. Feel free
+to fork the repository on Github and send pull requests.
+
+Contributing
+------------
+
+Instructions on how to work on the documentation are available at
+https://codedocs.cacert.org/building.html or
+https://github.com/CAcertOrg/cacert-codedocs/blob/master/source/building.rst
+
+License
+-------
+
+Copyright (C) 2018 CAcert
+
+This documentation is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 2 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License along
+with this program; if not, write to the Free Software Foundation, Inc.,
+51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
diff --git a/cacert.pem b/cacert.pem
new file mode 100644
index 0000000..51cbcb5
--- /dev/null
+++ b/cacert.pem
@@ -0,0 +1,83 @@
+-----BEGIN CERTIFICATE-----
+MIIHWTCCBUGgAwIBAgIDCkGKMA0GCSqGSIb3DQEBCwUAMHkxEDAOBgNVBAoTB1Jv
+b3QgQ0ExHjAcBgNVBAsTFWh0dHA6Ly93d3cuY2FjZXJ0Lm9yZzEiMCAGA1UEAxMZ
+Q0EgQ2VydCBTaWduaW5nIEF1dGhvcml0eTEhMB8GCSqGSIb3DQEJARYSc3VwcG9y
+dEBjYWNlcnQub3JnMB4XDTExMDUyMzE3NDgwMloXDTIxMDUyMDE3NDgwMlowVDEU
+MBIGA1UEChMLQ0FjZXJ0IEluYy4xHjAcBgNVBAsTFWh0dHA6Ly93d3cuQ0FjZXJ0
+Lm9yZzEcMBoGA1UEAxMTQ0FjZXJ0IENsYXNzIDMgUm9vdDCCAiIwDQYJKoZIhvcN
+AQEBBQADggIPADCCAgoCggIBAKtJNRFIfNImflOUz0Op3SjXQiqL84d4GVh8D57a
+iX3h++tykA10oZZkq5+gJJlz2uJVdscXe/UErEa4w75/ZI0QbCTzYZzA8pD6Ueb1
+aQFjww9W4kpCz+JEjCUoqMV5CX1GuYrz6fM0KQhF5Byfy5QEHIGoFLOYZcRD7E6C
+jQnRvapbjZLQ7N6QxX8KwuPr5jFaXnQ+lzNZ6MMDPWAzv/fRb0fEze5ig1JuLgia
+pNkVGJGmhZJHsK5I6223IeyFGmhyNav/8BBdwPSUp2rVO5J+TJAFfpPBLIukjmJ0
+FXFuC3ED6q8VOJrU0gVyb4z5K+taciX5OUbjchs+BMNkJyIQKopPWKcDrb60LhPt
+XapI19V91Cp7XPpGBFDkzA5CW4zt2/LP/JaT4NsRNlRiNDiPDGCbO5dWOK3z0luL
+oFvqTpa4fNfVoIZwQNORKbeiPK31jLvPGpKK5DR7wNhsX+kKwsOnIJpa3yxdUly6
+R9Wb7yQocDggL9V/KcCyQQNokszgnMyXS0XvOhAKq3A6mJVwrTWx6oUrpByAITGp
+rmB6gCZIALgBwJNjVSKRPFbnr9s6JfOPMVTqJouBWfmh0VMRxXudA/Z0EeBtsSw/
+LIaRmXGapneLNGDRFLQsrJ2vjBDTn8Rq+G8T/HNZ92ZCdB6K4/jc0m+YnMtHmJVA
+BfvpAgMBAAGjggINMIICCTAdBgNVHQ4EFgQUdahxYEyIE/B42Yl3tW3Fid+8sXow
+gaMGA1UdIwSBmzCBmIAUFrUyG9TH8+DmjvO90rA67rI5GNGhfaR7MHkxEDAOBgNV
+BAoTB1Jvb3QgQ0ExHjAcBgNVBAsTFWh0dHA6Ly93d3cuY2FjZXJ0Lm9yZzEiMCAG
+A1UEAxMZQ0EgQ2VydCBTaWduaW5nIEF1dGhvcml0eTEhMB8GCSqGSIb3DQEJARYS
+c3VwcG9ydEBjYWNlcnQub3JnggEAMA8GA1UdEwEB/wQFMAMBAf8wXQYIKwYBBQUH
+AQEEUTBPMCMGCCsGAQUFBzABhhdodHRwOi8vb2NzcC5DQWNlcnQub3JnLzAoBggr
+BgEFBQcwAoYcaHR0cDovL3d3dy5DQWNlcnQub3JnL2NhLmNydDBKBgNVHSAEQzBB
+MD8GCCsGAQQBgZBKMDMwMQYIKwYBBQUHAgEWJWh0dHA6Ly93d3cuQ0FjZXJ0Lm9y
+Zy9pbmRleC5waHA/aWQ9MTAwNAYJYIZIAYb4QgEIBCcWJWh0dHA6Ly93d3cuQ0Fj
+ZXJ0Lm9yZy9pbmRleC5waHA/aWQ9MTAwUAYJYIZIAYb4QgENBEMWQVRvIGdldCB5
+b3VyIG93biBjZXJ0aWZpY2F0ZSBmb3IgRlJFRSwgZ28gdG8gaHR0cDovL3d3dy5D
+QWNlcnQub3JnMA0GCSqGSIb3DQEBCwUAA4ICAQApKIWuRKm5r6R5E/CooyuXYPNc
+7uMvwfbiZqARrjY3OnYVBFPqQvX56sAV2KaC2eRhrnILKVyQQ+hBsuF32wITRHhH
+Va9Y/MyY9kW50SD42CEH/m2qc9SzxgfpCYXMO/K2viwcJdVxjDm1Luq+GIG6sJO4
+D+Pm1yaMMVpyA4RS5qb1MyJFCsgLDYq4Nm+QCaGrvdfVTi5xotSu+qdUK+s1jVq3
+VIgv7nSf7UgWyg1I0JTTrKSi9iTfkuO960NAkW4cGI5WtIIS86mTn9S8nK2cde5a
+lxuV53QtHA+wLJef+6kzOXrnAzqSjiL2jA3k2X4Ndhj3AfnvlpaiVXPAPHG0HRpW
+Q7fDCo1y/OIQCQtBzoyUoPkD/XFzS4pXM+WOdH4VAQDmzEoc53+VGS3FpQyLu7Xt
+hbNc09+4ufLKxw0BFKxwWMWMjTPUnWajGlCVI/xI4AZDEtnNp4Y5LzZyo4AQ5OHz
+0ctbGsDkgJp8E3MGT9ujayQKurMcvEp4u+XjdTilSKeiHq921F73OIZWWonO1sOn
+ebJSoMbxhbQljPI/lrMQ2Y1sVzufb4Y6GIIiNsiwkTjbKqGTqoQ/9SdlrnPVyNXT
+d+pLncdBu8fA46A/5H2kjXPmEkvfoXNzczqA6NXLji/L6hOn1kGLrPo8idck9U60
+4GGSt/M3mMS+lqO3ig==
+-----END CERTIFICATE-----
+-----BEGIN CERTIFICATE-----
+MIIHPTCCBSWgAwIBAgIBADANBgkqhkiG9w0BAQQFADB5MRAwDgYDVQQKEwdSb290
+IENBMR4wHAYDVQQLExVodHRwOi8vd3d3LmNhY2VydC5vcmcxIjAgBgNVBAMTGUNB
+IENlcnQgU2lnbmluZyBBdXRob3JpdHkxITAfBgkqhkiG9w0BCQEWEnN1cHBvcnRA
+Y2FjZXJ0Lm9yZzAeFw0wMzAzMzAxMjI5NDlaFw0zMzAzMjkxMjI5NDlaMHkxEDAO
+BgNVBAoTB1Jvb3QgQ0ExHjAcBgNVBAsTFWh0dHA6Ly93d3cuY2FjZXJ0Lm9yZzEi
+MCAGA1UEAxMZQ0EgQ2VydCBTaWduaW5nIEF1dGhvcml0eTEhMB8GCSqGSIb3DQEJ
+ARYSc3VwcG9ydEBjYWNlcnQub3JnMIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIIC
+CgKCAgEAziLA4kZ97DYoB1CW8qAzQIxL8TtmPzHlawI229Z89vGIj053NgVBlfkJ
+8BLPRoZzYLdufujAWGSuzbCtRRcMY/pnCujW0r8+55jE8Ez64AO7NV1sId6eINm6
+zWYyN3L69wj1x81YyY7nDl7qPv4coRQKFWyGhFtkZip6qUtTefWIonvuLwphK42y
+fk1WpRPs6tqSnqxEQR5YYGUFZvjARL3LlPdCfgv3ZWiYUQXw8wWRBB0bF4LsyFe7
+w2t6iPGwcswlWyCR7BYCEo8y6RcYSNDHBS4CMEK4JZwFaz+qOqfrU0j36NK2B5jc
+G8Y0f3/JHIJ6BVgrCFvzOKKrF11myZjXnhCLotLddJr3cQxyYN/Nb5gznZY0dj4k
+epKwDpUeb+agRThHqtdB7Uq3EvbXG4OKDy7YCbZZ16oE/9KTfWgu3YtLq1i6L43q
+laegw1SJpfvbi1EinbLDvhG+LJGGi5Z4rSDTii8aP8bQUWWHIbEZAWV/RRyH9XzQ
+QUxPKZgh/TMfdQwEUfoZd9vUFBzugcMd9Zi3aQaRIt0AUMyBMawSB3s42mhb5ivU
+fslfrejrckzzAeVLIL+aplfKkQABi6F1ITe1Yw1nPkZPcCBnzsXWWdsC4PDSy826
+YreQQejdIOQpvGQpQsgi3Hia/0PsmBsJUUtaWsJx8cTLc6nloQsCAwEAAaOCAc4w
+ggHKMB0GA1UdDgQWBBQWtTIb1Mfz4OaO873SsDrusjkY0TCBowYDVR0jBIGbMIGY
+gBQWtTIb1Mfz4OaO873SsDrusjkY0aF9pHsweTEQMA4GA1UEChMHUm9vdCBDQTEe
+MBwGA1UECxMVaHR0cDovL3d3dy5jYWNlcnQub3JnMSIwIAYDVQQDExlDQSBDZXJ0
+IFNpZ25pbmcgQXV0aG9yaXR5MSEwHwYJKoZIhvcNAQkBFhJzdXBwb3J0QGNhY2Vy
+dC5vcmeCAQAwDwYDVR0TAQH/BAUwAwEB/zAyBgNVHR8EKzApMCegJaAjhiFodHRw
+czovL3d3dy5jYWNlcnQub3JnL3Jldm9rZS5jcmwwMAYJYIZIAYb4QgEEBCMWIWh0
+dHBzOi8vd3d3LmNhY2VydC5vcmcvcmV2b2tlLmNybDA0BglghkgBhvhCAQgEJxYl
+aHR0cDovL3d3dy5jYWNlcnQub3JnL2luZGV4LnBocD9pZD0xMDBWBglghkgBhvhC
+AQ0ESRZHVG8gZ2V0IHlvdXIgb3duIGNlcnRpZmljYXRlIGZvciBGUkVFIGhlYWQg
+b3ZlciB0byBodHRwOi8vd3d3LmNhY2VydC5vcmcwDQYJKoZIhvcNAQEEBQADggIB
+ACjH7pyCArpcgBLKNQodgW+JapnM8mgPf6fhjViVPr3yBsOQWqy1YPaZQwGjiHCc
+nWKdpIevZ1gNMDY75q1I08t0AoZxPuIrA2jxNGJARjtT6ij0rPtmlVOKTV39O9lg
+18p5aTuxZZKmxoGCXJzN600BiqXfEVWqFcofN8CCmHBh22p8lqOOLlQ+TyGpkO/c
+gr/c6EWtTZBzCDyUZbAEmXZ/4rzCahWqlwQ3JNgelE5tDlG+1sSPypZt90Pf6DBl
+Jzt7u0NDY8RD97LsaMzhGY4i+5jhe1o+ATc7iwiwovOVThrLm82asduycPAtStvY
+sONvRUgzEv/+PDIqVPfE94rwiCPCR/5kenHA0R6mY7AHfqQv0wGP3J8rtsYIqQ+T
+SCX8Ev2fQtzzxD72V7DX3WnRBnc0CkvSyqD/HMaMyRa+xMwyN2hzXwj7UfdJUzYF
+CpUCTPJ5GhD22Dp1nPMd8aINcGeGG7MW9S/lpOt5hvk9C8JzC6WZrG/8Z7jlLwum
+GCSNe9FINSkYQKyTYOGWhlC0elnYjyELn8+CkcY7v2vcB5G5l1YjqrZslMZIBjzk
+zk6q5PYvCdxTby78dOs6Y5nCpqyJvKeyRKANihDjbPIky/qbn3BHLt4Ui9SyIAmW
+omTxJBzcoTWcFbLUvFUufQb1nA5V9FrWk9p2rSVzTMVD
+-----END CERTIFICATE-----
diff --git a/help-files/PARAM-files b/help-files/PARAM-files
new file mode 100644
index 0000000..ee7d5fb
--- /dev/null
+++ b/help-files/PARAM-files
@@ -0,0 +1,21 @@
+/includes/mysql.php configs:
+
+.. $_SESSION['mconn'] = TRUE;
+.. $_SESSION['_config']['normalhostname'] = "www.cacert.org";
+.. $_SESSION['_config']['securehostname'] = "secure.cacert.org";
+.. $_SESSION['_config']['tverify'] = "tverify.cacert.org";
+
+
+/includes/general.php
+
+.. $_SESSION['_config']['filepath']
+
+
+/includes/lib/L10n.php
+
+$_SERVER['HTTP_ACCEPT_LANGUAGE']
+$_REQUEST["lang"]
+.. $_SESSION['_config']['language']
+.. $_SESSION['_config']['recode']
+$_SESSION['_config']['filepath'].'/locale'
+.. ENV "LANG"
diff --git a/help-files/PROGRAM-files b/help-files/PROGRAM-files
new file mode 100644
index 0000000..a716fcf
--- /dev/null
+++ b/help-files/PROGRAM-files
@@ -0,0 +1,34 @@
+account_delete includes/notary.inc.php
+account_domain_delete includes/notary.inc.php
+account_email_delete includes/notary.inc.php
+check_client_cert_running includes/notary.inc.php
+check_email_exists includes/notary.inc.php
+check_gpg_cert_running includes/notary.inc.php
+check_is_orgadmin includes/notary.inc.php
+check_server_cert_running includes/notary.inc.php
+checkEmail includes/general
+checkWeakKeyCSR includes/lib/check_weak_key.php
+checkWeakKeySPKAC includes/lib/check_weak_key.php
+checkWeakKeyX509 includes/lib/check_weak_key.php
+clean_csr includes/general.php
+csrf_check includes/general.php
+extractit includes/general.php
+generatecertpath includes/general.php
+get_user_agreement_status includes/notary.inc.php
+get_user_id_from_cert includes/lib/general.php
+getalt includes/general.php
+getcn includes/general.php
+HashAlgorithms:: includes/lib/account.php
+loadem includes/general.php
+L10n:: includes/lib/l10n.php
+make_hash includes/general.php
+revoke_all_private_cert includes/notary.inc.php
+runCommand includes/lib/general.php
+sanitizeHTML includes/general.php
+sendmail includes/mysql.php
+showfooter includes/account_stuff.php
+showheader includes/account_stuff.php
+valid_ticket_number includes/notary.inc.php
+waitForResult includes/general.php
+write_se_log includes/notary.inc.php
+write_user_agreement includes/notary.inc.php
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..8d7bd8d
--- /dev/null
+++ b/source/DIR-includes.rst
@@ -0,0 +1,1138 @@
+.. 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://blog.CAcert.org/feed/"
+
+ "http://bugs.CAcert.org/"
+
+ "https://lists.cacert.org/wws"
+
+ "http://wiki.CAcert.org/"
+
+ "http://wiki.cacert.org/Board"
+
+ "http://wiki.cacert.org/FAQ/Privileges"
+
+ "www/policy/"
+
+ "www/src-lic.php"
+
+ :file:`about_menu.php` is a part (<div>) of a PHP-Page, containing most of
+ the CAcert-related links. It uses :php:global:`$_SESSION['mconn']`
+
+
+
+.. sourcefile:: includes/account_stuff.php
+
+
+
+
+
+ :uses:
+
+ includes/about_menu.php
+
+ :file:`includes/account_stuff.php` provides two procedures to be used for building the output of some HTML-pages.
+
+ It uses the global variables:
+ :php:global:`$_REQUEST['id']`
+
+ .. php:function:: showheader($title = "CAcert.org", $title2 = "")
+
+ This function renders a page depending on the calling file.
+ It uses the global variables:
+ :php:global:`$_SERVER['PHP_SELF']`,
+ :php:global:`$_SESSION['_config']['header']`,
+ :php:global:`$_SESSION['_config']['normalhostname']`,
+ :php:global:`$_SESSION['profile']['adadmin']`,
+ :php:global:`$_SESSION['profile']['admin']`,
+ :php:global:`$_SESSION['profile']['assurer']`,
+ :php:global:`$_SESSION['profile']['dob']`,
+ :php:global:`$_SESSION['profile']['email']`,
+ :php:global:`$_SESSION['profile']['fname']`,
+ :php:global:`$_SESSION['profile']['id']`,
+ :php:global:`$_SESSION['profile']['lname']`,
+ :php:global:`$_SESSION['profile']['locadmin']`,
+ :php:global:`$_SESSION['profile']['mname']`,
+ :php:global:`$_SESSION['profile']['orgadmin']`,
+ :php:global:`$_SESSION['profile']['points']`,
+ :php:global:`$_SESSION['profile']['suff']`
+
+ :param string $title:
+ :param string $title2:
+ :global: * *(int)* - $id:
+ :global: * *(string)* - $PHP_SELF:
+
+ .. php:function:: showfooter()
+
+ This function renders a page-footer.
+
+
+.. sourcefile:: includes/account.php
+ :uses:
+ includes/loggedin.php
+ includes/lib/l10n.php
+ includes/lib/check_weak_key.php
+ includes/notary.inc.php
+
+ :file:`includes/account.php` first loads some more includefiles via :php:func:`loadem`. It defines two functions and read the global variables
+ :php:global:`$_REQUEST['id']`,
+ :php:global:`$_REQUEST['oldid']`,
+ :php:global:`$_REQUEST['process']`,
+ :php:global:`$_REQUEST['showdetails']`,
+ :php:global:`$_REQUEST['cert']`,
+ :php:global:`$_REQUEST['orgid']`,
+ :php:global:`$_REQUEST['memid']`,
+ :php:global:`$_REQUEST['domid']`,
+ :php:global:`$_REQUEST['action']`,
+ :php:global:`$_REQUEST['ticketno']`,
+ :php:global:`$_SESSION['mconn']`
+
+ .. php:function:: buildSubject(array $domains, $include_xmpp_addr = true)
+
+ Build a subject string as needed by the signer.
+ This function uses
+ :php:func:`account_domain_delete`,
+ :php:func:`account_email_delete`,
+ :php:func:`buildSubjectFromSession`,
+ :php:func:`check_client_cert_running`,
+ :php:func:`check_gpg_cert_running`,
+ :php:func:`check_is_orgadmin`,
+ :php:func:`check_server_cert_running`,
+ :php:func:`checkEmail`,
+ :php:func:`checkpw`,
+ :php:func:`checkWeakKeyCSR`,
+ :php:func:`checkWeakKeySPKAC`,
+ :php:func:`checkWeakKeyX509`,
+ :php:func:`clean_csr`,
+ :php:meth:`HashAlgorithms::clean`,
+ :php:func:`csrf_check`,
+ :php:func:`extractit`,
+ :php:func:`generatecertpath`,
+ :php:meth:`L10n::get_translation`,
+ :php:func:`getalt`,
+ :php:func:`getalt2`,
+ :php:func:`getcn`,
+ :php:func:`getcn2`,
+ :php:func:`make_hash`,
+ :php:func:`revoke_all_private_cert`,
+ :php:func:`runCommand`,
+ :php:func:`sanitizeHTML`,
+ :php:func:`sendmail`,
+ :php:meth:`L10n::set_recipient_language`,
+ :php:meth:`L10n::set_translation`,
+ :php:func:`showheader`,
+ :php:func:`showfooter`,
+ :php:attr:`L10n::$translations`,
+ :php:func:`valid_ticket_number`,
+ :php:func:`waitForResult`,
+ :php:func:`write_se_log`,
+ :php:func:`write_user_agreement`
+
+
+ :param array(string) $domains: First domain is used as CN and repeated in subjectAltName. Duplicates should already been removed
+ :param bool $include_xmpp_addr: [default: true] Whether to include the XmppAddr in the subjectAltName. This is needed if the Jabber server is jabber.example.com but a Jabber ID on that server would be alice@example.com
+ :return: * (string) - subject string as needed by the signer
+
+ .. php:function:: buildSubjectFromSession()
+
+ Builds the subject string from the session variables $_SESSION['_config']['rows'] and $_SESSION['_config']['altrows']
+
+ :return: * (string) -
+
+
+.. sourcefile:: includes/general_stuff.php
+ :uses:
+ includes/lib/l10n.php
+
+ This process uses
+ :php:func:`showbodycontent`,
+ :php:func:`showfooter`,
+ :php:func:`showheader`
+
+ .. php:function:: showbodycontent($title = "CAcert.org", $title2 = "")
+
+
+
+
+
+.. sourcefile:: includes/general.php
+
+ .. php:function:: loadem
+
+.. sourcefile:: includes/keygen.php
+
+.. sourcefile:: includes/loggedin.php
+ :uses:
+ includes/lib/general.php
+ SOME__get_user_id_from_cert
+ includes/lib/l10n.php
+ SOME__L10n::get_translation
+ SOME__L10n::set_translation
+ SOME__L10n::init_gettext
+ includes/mysql.php
+ includes/notary.inc.php
+ SOME__get_user_agreement_status
+
+
+ .. todo:: analyze the module
+
+
+
+
+.. 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 :php:global:`$_SESSION['mconn']` while connecting to that database. It also defines the session variables
+ :php:global:`$_SESSION['_config']['normalhostname']`, :php:global:`$_SESSION['_config']['securehostname']` and :php:global:`$_SESSION['_config']['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
+
+ :file:`includes/notary.inc.php` defines the global constants :php:const:`NULL_DATETIME` and :php:const:`THAWTE_REVOCATION_DATETIME`. It also provides a set of funktions; here listed in the given order:
+
+ .. php:function:: query_init ($query)
+
+ Accesss the database to execute the passed query.
+
+ :param string $query: query to execute
+ :return: * (resource) - result of the passed query.
+
+ .. php:function:: query_getnextrow ($res)
+
+ Return the next row of a previous received result of a database query.
+
+ :param resource $res: Result of a previous database query.
+ :return: * (object) - next row in the passed resource
+
+ .. php:function:: query_get_number_of_rows ($resultset)
+
+ Return the number of rows of the passed $resource which has to be the result of a previous database query, select-statement
+
+ :param resource $resultset: Result of a previous database query
+ :return: * (int) - number of rows in the passed resource
+
+ .. php:function:: get_number_of_assurances ($userid)
+
+ Returns the number of assurances the user with the passed userid has given. Uses :php:func:`query_init` and :php:func:`query_getnextrow`.
+
+ :param int $userid: userid of be controled
+ :return: * (int) - number of given assurances
+
+ .. php:function:: get_number_of_ttpassurances ($userid)
+
+ Returns the number of TTP-assurances the user with the passed userid has received. Uses :php:func:`query_init` and :php:func:`query_getnextrow`.
+
+ :param int $userid: userid of be controled
+ :return: * (int) - number of received TTP-assurances
+
+ .. php:function:: get_number_of_assurees ($userid)
+
+ Returns the number of assurances the user with the passed userid has received. Uses :php:func:`query_init` and :php:func:`query_getnextrow`.
+
+ :param int $userid: userid of be controled
+ :return: * (int) - number of received assurances
+
+ .. php:function:: get_top_assurer_position ($no_of_assurances)
+
+ Returns the ranking of an assurer with the passed number of given assurances. Uses :php:func:`query_init` and :php:func:`query_get_number_of_rows`.
+
+ :param int $no_of_assurances: number of assurances
+ :return: * (int) - position at the list of top assurers
+
+ .. php:function:: get_top_assuree_position ($no_of_assurees)
+
+ Returns the ranking of an assuree with the passed number of received assurances. Uses :php:func:`query_init` and :php:func:`query_get_number_of_rows`.
+
+ :param int $no_of_assurances: number of assurances
+ :return: * (int) - position at the list of top assurees
+
+ .. php:function:: get_given_assurances($userid, $log=0)
+
+ Get the list of assurances given by the user. Uses :php:func:`query_init`.
+
+ :param int $userid: id of the assurer
+ :param int $log: if set to 1 also includes deleted assurances
+ :return: * (resource) - a MySQL result set
+
+ .. php:function:: get_received_assurances($userid, $log=0)
+
+ Get the list of assurances received by the user. Uses :php:func:`query_init`.
+
+ :param int $userid: id of the assuree
+ :param int $log: if set to 1 also includes deleted assurances
+ :return: * (resource) - a MySQL result set
+
+ .. php:function:: get_given_assurances_summary ($userid)
+
+ Get the count of given assurances of the user with the passed userid grouped by points, awarded, method. Uses :php:func:`query_init`.
+
+ :param int $userid: id of the assurer
+ :return: * (resource) - list of number of given assurances grouped by points, awarded, method
+
+ .. php:function:: get_received_assurances_summary ($userid)
+
+ Get the count of received assurances of the user with the passed userid grouped by points, awarded, method. Uses :php:func:`query_init`.
+
+ :param int $userid: id of the assuree
+ :return: * (resource) - list of number of received assurances grouped by points, awarded, method
+
+ .. php:function:: get_user ($userid)
+
+ Get data of user with the passed userid. Uses :php:func:`query_init`.
+
+ :param int $userid: id of the user
+ :return: * (resource) - data frum table users belonging to passed userid.
+
+ .. php:function:: get_cats_state ($userid)
+
+ Get the number of passed CATS for the given userid. Uses :php:func:`query_init`.
+
+ :param int $userid: id of a user
+ :return: * (int) - number of passed CATS
+
+ .. php:function:: calc_awarded($row)
+
+ Calculate awarded points (corrects some issues like out of range points or points that were issued by means that have been deprecated)
+
+ :param array $row: associative array containing the data from the `notary` table
+ :return: * (int) - the awarded points for this assurance
+
+ .. php:function:: calc_experience(&$row, &$sum_points, &$sum_experience)
+
+ Calculate the experience points from a given Assurance. Uses :php:func:`calc_awarded`.
+
+ :param array $row: [inout] associative array containing the data from the `notary` table, the keys 'experience' and 'calc_awarded' will be added
+ :param int $sum_points: [inout] the sum of already counted assurance points the assurer issued
+ :param int $sum_experience: [inout] the sum of already counted experience points that were awarded to the assurer
+
+ .. php:function:: calc_assurances(&$row, &$sum_points, &$sum_experience)
+
+ Calculate the points received from a received Assurance. Uses :php:func:`calc_awarded`.
+
+ :param array $row: [inout] associative array containing the data from the `notary` table, the keys 'experience' and 'calc_awarded' will be added
+ :param int $sum_points: [inout] the sum of already counted assurance points the assuree received
+ :param int $sum_experience: [inout] the sum of already counted experience points that were awarded to the assurer
+
+ .. php:function:: show_user_link($user)
+
+ Generate a link to the support engineer page for the user with the name of the user as link text. Uses :php:func:`sanitizeHTML`.
+
+ :param array $user: associative array containing the data from the `user` table
+ :return: * (string) - name of the user with the passed userid or System or deleted
+
+ .. php:function:: show_email_link($user)
+
+ Generate a link to the support engineer page for the user with the email address as link text. Uses :php:func:`sanitizeHTML`.
+
+ :param array $user: associative array containing the data from the `user` table
+ :return: * (string) - email-address
+
+ .. php:function:: get_assurer_ranking($userid,&$num_of_assurances,&$rank_of_assurer)
+
+ Getting the number of given assurances and the rank of the user with the passed userid. Uses :php:func:`get_number_of_assurances` and :php:func:`get_top_assurer_position`.
+
+ :param int $userid: id of an user
+ :param int $num_of_assurances: [inout] number of given assurances
+ :param int $rank_of_assurer: [inout] rank in assurer-list
+
+ .. php:function:: get_assuree_ranking($userid,&$num_of_assurees,&$rank_of_assuree)
+
+ Getting the number of received assurances and the rank of the user with the passed userid. Uses :php:func:`get_number_of_assurees` and :php:func:`get_top_assuree_position`.
+
+ :param int $userid: id of an user
+ :param int $num_of_assurees: [inout] number of received assurances
+ :param int $rank_of_assuree: [inout] rank in assuree-list
+
+ .. php:function:: output_ranking($userid)
+
+ Generating HTML-code for showing the assurer/assuree data. Uses :php:func:`get_assurer_ranking` and :php:func:`get_assuree_ranking`.
+
+ :param int $userid: userid to build the page format
+
+ .. php:function:: output_assurances_header($title, $support, $log)
+
+ Render header for the assurance table (same for given/received)
+
+ :param string $title: The title for the table
+ :param int $support: set to 1 if the output is for the support interface
+ :param int $log: if set to 1 also includes deleted assurances
+
+ .. php:function:: output_assurances_footer($points_txt,$sumpoints,$experience_txt,$sumexperience,$support,$log)
+
+ Render footer for the assurance table (same for given/received)
+
+ :param string $points_txt: Description for sum of assurance points
+ :param int $sumpoints: sum of assurance points
+ :param string $experience_txt: Description for sum of experience points
+ :param int $sumexperience: sum of experience points
+ :param int $support: set to 1 if the output is for the support interface
+ :param int $log: if set to 1 also includes deleted assurances
+
+ .. php:function:: output_assurances_row($assurance,$userid,$other_user,$support,$ticketno,$log)
+
+ Render an assurance for a view. Uses :php:func:`show_email_link`, :php:func:`show_user_link`, :php:func:`sanitizeHTML` and :php:func:`make_csrf`.
+
+ :param array $assurance: associative array containing the data from the `notary` table
+ :param int $userid: Id of the user whichs given/received assurances are displayed
+ :param array $other_user: associative array containing the other users data from the `users` table
+ :param int $support: set to 1 if the output is for the support interface
+ :param string $ticketno: ticket number currently set in the support interface
+ :param int $log: if set to 1 also includes deleted assurances
+
+ .. php:function:: output_summary_header()
+
+ Render the header for the summary.
+
+ .. php:function:: output_summary_footer()
+
+ Render the footer for the summary.
+
+ .. php:function:: output_summary_row($title,$points,$points_countable,$remark)
+
+ Render a row of the summary of points
+
+ :param string $title: The description of the row
+ :param inf $points:
+ :param int $points_countable:
+ :param string $remark:
+
+ .. todo:: check points and points_countable
+
+ .. php:function:: output_given_assurances_content($userid,&$sum_points,&$sum_experience,$support,$ticketno,$log)
+
+ Helper function to render assurances given by the user. Uses :php:func:`get_given_assurances`, :php:func:`get_user`, :php:func:`calc_experience` and :php:func:`output_assurances_row`.
+
+ :param int $userid: id of a user
+ :param int &$sum_points: [out] sum of given points
+ :param int &$sum_experience: [out] sum of experience points gained
+ :param int $support: set to 1 if the output is for the support interface
+ :param string $ticketno: the ticket number set in the support interface
+ :param int $log: if set to 1 also includes deleted assurances
+
+ .. php:function:: output_received_assurances_content($userid,&$sum_points,&$sum_experience,$support,$ticketno,$log)
+
+ Helper function to render assurances received by the user. Uses :php:func:`get_received_assurances`, :php:func:`get_user`, :php:func:`calc_assurances` and :php:func:`output_assurances_row`.
+
+ :param int $userid: id of a user
+ :param int& $sum_points: [out] sum of received points
+ :param int& $sum_experience: [out] sum of experience points the assurers gained
+ :param int $support: set to 1 if the output is for the support interface
+ :param string $ticketno: the ticket number set in the support interface
+ :param int $log: if set to 1 also includes deleted assurances
+
+ .. php:function:: check_date_limit ($userid,$age)
+
+ Checks if the user with the passed userid has reached a given age. Uses :php:func:`query_init`, :php:func:`query_get_number_of_rows`.
+
+ :param int $userid: id of a user
+ :param int $age: the age to be checked against
+ :return: * (int) - 1: if the given age is reached; 0 else
+
+ .. php:function:: max_points($userid)
+
+ Determin, how many points the user can issue at most. Uses :php:func:`output_summary_content`.
+
+ :param int $userid: id of a user
+ :return: * (int) - max to issue points
+
+ .. php:function:: output_summary_content($userid,$display_output)
+
+ Calculate points and render them for output. Uses :php:func:`check_date_limit`, :php:func:`get_received_assurances_summary`, :php:func:`calc_awarded`, :php:func:`get_given_assurances_summary`, :php:func:`get_cats_state`, :php:func:`output_summary_row`.
+
+ :param int $userid: id of a user
+ :param int $display_output: flag if to display (1) or not (0)
+ :retur: * (int) - max to issue points
+
+ .. php:function:: output_given_assurances($userid, $support=0, $ticketno='', $log=0)
+
+ Render assurances given by the user. Uses :php:func:`output_assurances_header`, :php:func:`output_given_assurances_content`, :php:func:`output_assurances_footer`.
+
+ :param int $userid: id of a user
+ :param int $support: set to 1 if the output is for the support interface
+ :param string $ticketno: the ticket number set in the support interface
+ :param int $log: if set to 1 also includes deleted assurances
+
+ .. php:function:: output_received_assurances($userid, $support=0, $ticketno='', $log=0)
+
+ Render assurances received by the user. Uses :php:func:`output_assurances_header`, :php:func:`output_received_assurances_content`, :php:func:`output_assurances_footer`.
+
+ :param int $userid: id of a user
+ :param int $support: set to 1 if the output is for the support interface
+ :param string $ticketno: the ticket number set in the support interface
+ :param int $log: if set to 1 also includes deleted assurances
+
+ .. php:function:: output_summary($userid)
+
+ Render the page output for a user. Uses :php:func:`output_summary_header`, :php:func:`output_summary_content`, :php:func:`output_summary_footer`.
+
+ :param int $userid: id of a user
+
+ .. php:function:: output_end_of_page()
+
+ Adds a goBack-button to the page.
+
+ .. php:function:: write_user_agreement($memid, $document, $method, $comment, $active=1, $secmemid=0)
+
+ Writes a new record to the table user_agreement.
+
+ :param mixed $memid: id of a user
+ :param mixed $document:
+ :param mixed $method:
+ :param mixed $comment:
+ :param integer $active:
+ :param integer $secmemid:
+ :return:
+
+ .. php:function:: get_user_agreement_status($memid, $type="CCA")
+
+ Returns 1 if the user has an entry for the given type in user_agreement, 0 if no entry is recorded
+
+ :param mixed $memid: userid
+ :param string $type: "CCA"
+ :return: * (int) - 1 if the user has an entry for the given type in user_agreement, 0 if no entry is recorded
+
+ .. php:function:: get_first_user_agreement($memid, $type=null, $active=null)
+
+ Get the first user_agreement entry of the requested type
+
+ :param int $memid:
+ :param string $type: the type of user agreement, by default all agreements are listed
+ :param int $active: whether to get active or passive agreements:
+
+ * 0 := passive
+ * 1 := active
+ * null := both
+
+ :return: * (array(string=>mixed)) - an associative array containing 'document', 'date', 'method', 'comment', 'active'.
+
+ .. php:function:: get_last_user_agreement($memid, $type=null, $active=null)
+
+ Get the last user_agreement entry of the requested type
+
+ :param int $memid:
+ :param string $type: the type of user agreement, by default all agreements are listed
+ :param int $active: whether to get active or passive agreements:
+
+ * 0 := passive
+ * 1 := active
+ * null := both
+
+ :return: * (array(string=>mixed)) - an associative array containing 'document', 'date', 'method', 'comment', 'active'.
+
+ .. php:function:: get_user_agreements($memid, $type=null, $active=null)
+
+ Get all user_agreement entrys of the requested type
+
+ :param int $memid:
+ :param string $type: the type of user agreement, by default all agreements are listed
+ :param int $active: whether to get active or passive agreements:
+
+ * 0 := passive
+ * 1 := active
+ * null := both
+
+ :return: * (resource) - a mysql result set containing all agreements
+
+ .. php:function:: delete_user_agreement($memid, $type=false)
+
+ Deletes all entries for a given type from user_agreement of a given user, if type is not given, delete all all
+
+ :param mixed $memid: Member-id
+ :param string $type: the type of user agreement ; if false all
+
+ .. :php:function:: AssureHead($confirmation,$checkname)
+
+ Render the header for assurance-page /pages/wot/6.php
+
+ :param string $confirmation: text of title
+ :param string $checkname: textline including then ame of the person to be assured
+
+ .. php:function:: AssureTextLine($field1,$field2)
+
+ Prepares a text line for assurance-page /pages/wot/6.php; two cells in a row
+
+ :param string $field1: text string
+ :param string $field2: text string
+
+ .. php:function:: AssureBoxLine($type,$text,$checked)
+
+ Prepares a box line for assurance-page /pages/wot/6.php; two cells in a row, a checkbox with stats and a text
+
+ :param string $type: type/name of checkbox
+ :param string $text: text to present
+ :param string $checked: status of the ceckbox
+
+ .. php:function:: AssureMethodLine($text,$methods,$remark)
+
+ Prepares another row for assurance-page /pages/wot/6.php containing the methods of the assurance
+
+ :param string $text$: text
+ :param array(string) $methods: possible methods of assurance
+ :param string $remark: a possible remark to the assurance
+
+ .. php:function:: AssureInboxLine($type,$field,$value,$description)
+
+ Prepare an inBox line.
+
+ :param string $type: name of the information shown in line
+ :param string $field: readable name of the information of the line
+ :param string $value: value of the information
+ :param string $description: description/remarks to displayed the information
+
+ .. php:function:: AssureFoot($oldid,$confirm)
+
+ Prepares the footer of the assurance page /pages/wot/6.php.
+
+ :param int $oldid: field to hide containing the actual id of the dialog
+ :param string $confirm: text for confirmation
+
+ .. php:function:: account_email_delete($mailid)
+
+ Deletes an email entry from an acount, revolkes all certifcates for that email address. Uses :php:func:`revoke_all_client_cert`.
+
+ :param int $mailid: Id of the email address to be deleted
+
+ .. php:function:: account_domain_delete($domainid)
+
+ Deletes an domain entry from an acount, revolkes all certifcates for that domain address. Uses :php:func:`revoke_all_server_cert`.
+
+ :param int $domainid: Id of the domain to be deleted
+
+ .. php:function:: account_delete($id, $arbno, $adminid)
+
+ Deletes an account following the deleted account routnie V3 and change password (arbitration). Uses :php:func:`account_email_delete`, :php:func:`account_domain_delete`,
+
+ :param int $id: Id of the account to be deleted
+ :param string $arbno: Arbitrationnumber that justifies the deletion.
+ :param int $adminid: ID of the administrator who fullfilled the deletion
+
+ .. php:function:: check_email_exists($email)
+
+ Checks if an email address exists.
+
+ :param string $email: Email address to be checked
+ :returns: * (bool): true if email exists; else false
+
+ .. php:function:: check_gpg_cert_running($uid,$cca=0)
+
+ Checks if a non-expired gpg certificatation exists.
+
+ :param int $uid: account ID to be checked for gpg certification
+ :param int $cca: 0 if just expired, =1 if CCA retention +3 month should be obeyed
+ :returns: * (bool) - true if a gpg certification exists; else false
+
+ .. php:function:: check_client_cert_running($uid,$cca=0)
+
+ Checks if a non-expired, non-revoked client certificate exists for an account.
+
+ :param int $uid: account ID to be checked for client certificates
+ :param int $cca: 0 if just expired, =1 if CCA retention +3 month should be obeyed
+ :returns: * (bool) - true if a client certificate exists; else false
+
+ .. php:function:: check_server_cert_running($uid,$cca=0)
+
+ Checks if a non-expired, non-revoked server certificate exists for an account.
+
+ :param int $uid: account ID to be checked for server certificates
+ :param int $cca: 0 if just expired, =1 if CCA retention +3 month should be obeyed
+ :returns: * (bool) - true if a server certificate exists; else false
+
+ .. php:function:: check_is_orgadmin($uid)
+
+ Checks if a given account is an organisation administrator.
+
+ :param int $uid: account ID to be checked as organisation administrator
+ :returns: * (bool) - true if the account belongs to an organisation administrator; else false
+
+ .. php:function:: revoke_all_client_cert($mailid)
+
+ Revokes all client certificates for a given email address.
+
+ :param int $mailid: ID of an email address.
+
+ .. php:function:: function revoke_all_server_cert($domainid)
+
+ Revokes all server certs for an domain.
+
+ :param int $domainid: ID of an domain.
+
+ .. php:function:: revoke_all_private_cert($uid)
+
+ Revokes all certificates linked to a personal accounts, gpg revokation needs to be added to a later point. Uses :php:func:`revoke_all_client_cert`, :php:func:`revoke_all_server_cert`.
+
+ :param int $uid: ID of the account whos certificates have to be rovoked
+
+ .. php:function:: check_date_format($date, $year=2000)
+
+ Checks if the date is entered in the right date format YYYY-MM-DD and if the date is after the 1st January of the given year
+
+ :param mixed $date: Date to check
+ :param integer $year: Year to check against
+ :returns: * (bool) - true if date is valid; false if not
+
+ .. php:function:: check_date_difference($date, $diff=1)
+
+ Checks if the given date is less or equal then today plus a given time difference
+
+ :param mixed $date: Date to be checked
+ :param integer $diff: difference in days (positive future, negative past) to add to the current date
+ :returns: * (bool) - returns false if the date is larger then today + time difference
+
+ .. php:function:: write_se_log($uid, $adminid, $type, $info)
+
+ Records all support engineer actions changing a user account writing the information to the adminlog.
+
+ :param int $uid: id of the user account
+ :param int $adminid: id of the admin
+ :param string $type: the operation that was performed on the user account
+ :param string $info: the ticket / arbitration number or other information
+ :returns: * (bool) - true := success, false := error
+
+ .. php:function:: valid_ticket_number($ticketno)
+
+ Check if the entered information is a valid ticket or arbitration number.
+
+ :param string $ticketno:
+ :returns: * (bool) -
+
+ .. php:function:: get_user_data($userid, $deleted=0)
+
+ Get all data of an account given by the id from the `users` table (function for handling account/43.php)
+
+ :param int $userid: account id
+ :param int $deleted: states if deleted data should be visible , default = 0 - not visible
+ :returns: * (resource) - a mysql result set
+
+ .. php:function:: get_alerts($userid)
+
+ Get the alert settings for a user (function for handling account/43.php)
+
+ :param int $userid: for the requested account
+ :returns: * (array) - associative array
+
+ .. php:function:: get_email_addresses($userid, $exclude, $deleted=0)
+
+ Get all email addresses linked to the account (should be entered in account/2.php)
+
+ :param int $userid:
+ :param string $exclude: if given the email address will be excluded
+ :param int $deleted: states if deleted data should be visible, default = 0 - not visible
+ :returns: * (resource) - a mysql result set
+
+ .. php:function:: get_domains($userid, $deleted=0)
+
+ Get all domains linked to the account (should be entered in account/9.php).
+
+ :param int $userid:
+ :param int $deleted: states if deleted data should be visible, default = 0 - not visible
+ :returns: * (resource) - a mysql result set
+
+ .. php:function:: get_training_results($userid)
+
+ Get all training results for the account (should be entered in account/55.php)
+
+ :param int $userid:
+ :returns: * (resource) - a mysql result set
+
+ .. php:function:: get_se_log($userid)
+
+ Get all SE log entries for the account
+
+ :param int $userid:
+ :returns: * (resource) - a mysql result set
+
+ .. php:function:: get_client_certs($userid, $viewall=0)
+
+ Get all client certificates linked to the account (add to account/5.php)
+
+ :param int $userid:
+ :param int $viewall: states if expired certs should be visible, default = 0 - not visible
+ :returns: * (resource) - a mysql result set
+
+ .. php:function:: get_server_certs($userid, $viewall=0)
+
+ Get all server certs linked to the account (add to account/12.php)
+
+ :param int $userid:
+ :param int $viewall: states if expired certs should be visible, default = 0 - not visible
+ :returns: * (resource - a mysql result set)
+
+ .. php:function:: get_gpg_certs($userid, $viewall=0)
+
+ Get all gpg certs linked to the account (add to gpg/2.php)
+
+ :param int $userid:
+ :param int $viewall: states if expired certs should be visible, default = 0 - not visible
+ :returns: * (resource) - a mysql result set
+
+ .. php:function:: output_log_email_header()
+
+ Show the table header to the email table for the admin log
+
+ .. php:function:: output_log_email($row, $primary)
+
+ Show all email data for the admin log
+
+ :param array $row: associative array containing the column data
+ :param string $primary: if given the primary address is highlighted
+
+ .. php:function:: output_log_domains_header()
+
+ Show the table header to the domains table for the admin log.
+
+ .. php:function:: output_log_domains($row)
+
+ Show the domain data for the admin log
+
+ :param array $row: associative array containing the column data
+
+ .. php:function:: output_log_agreement_header()
+
+ Show the table header to the user agreement table for the admin log.
+
+ .. php:function:: output_log_agreement($row)
+
+ Show the agreement data for the admin log.
+
+ :param array $row: associative array containing the column data
+
+ .. php:function:: output_log_training_header()
+
+ Show the table header to the training table (should be entered in account/55.php).
+
+ .. php:function:: output_log_training($row)
+
+ Show the training data (should be entered in account/55.php).
+
+ :param array $row: associative array containing the column data
+
+ .. php:function:: output_log_se_header($support=0)
+
+ Show the table header to the SE log table for the admin log.
+
+ :param int $support: if support = 1 more information is visible
+
+ .. php:function:: output_log_se($row, $support=0)
+
+ Show the SE log data for the admin log (should be entered in account/55.php)
+
+ :param array $row: associative array containing the column data
+ :param int $support: if support = 1 more information is visible
+
+ .. php:function:: output_client_cert_header($support=0, $readonly=true)
+
+ Shows the table header to the client cert table (should be added to account/5.php)
+
+ :param int $support: if support = 1 some columns ar not visible
+ :param bool $readonly: whether elements to modify data should be hidden, default is `true`
+
+ .. php:function:: output_client_cert($row, $support=0, $readonly=true)
+
+ Show the client cert data (should be entered in account/5.php)
+
+ :param array $row: associative array containing the column data
+ :param int $support: if support = 1 some columns are not visible
+ :param bool $readonly: whether elements to modify data should be hidden, default is `true`
+
+ .. php:function:: output_server_certs_header($support=0, $readonly=true)
+
+ Show the table header to the server cert table (should be entered in account/12.php)
+
+ :param int $support: if support = 1 some columns ar not visible
+ :param bool $readonly: whether elements to modify data should be hidden, default is `true`
+
+ .. php:function:: output_server_certs($row, $support=0, $readonly=true)
+
+ Show the server cert data (should be entered in account/12.php)
+
+ :param array $row: associative array containing the column data
+ :param int $support: if support = 1 some columns are not visible
+ :param bool $readonly: whether elements to modify data should be hidden, default is `true`
+
+ .. php:function:: output_gpg_certs_header($support=0, $readonly=true)
+
+ Show the table header to the gpg cert table.
+
+ :param int $support: if support = 1 some columns ar not visible
+ :param bool $readonly: whether elements to modify data should be hidden, default is `true` ($readonly is currently ignored but kept for consistency)
+
+ .. php:function:: output_gpg_certs($row, $support=0, $readonly=true)
+
+ Show the gpg cert data (should be entered in account/55.php)
+
+ :param array $row: associative array containing the column data
+ :param int $support: if support = 1 some columns are not visible
+ :param bool $readonly: whether elements to modify data should be hidden, default is `true`
+
+.. 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
+
+ :file:`include/lib/account.php` defines a function and a class for use by other precedures.
+
+ .. php:function:: fix_assurer_flag($userID = NULL)
+
+ Function to recalculate the cached Assurer status. Update Assurer-Flag on users table if 100 points and CATS passed. We may have some performance issues here if no userID is given there are ~150k assurances and ~220k users currently but the exists-clause on cats_passed should be a good filter.
+
+ :param int $userID: if the user ID is not given the flag will be recalculated for all users
+ :returns: * (bool) - false if there was an error on fixing the flag. This does NOT return the new value of the flag
+
+ .. php:class:: HashAlgorithms
+
+ Supported hash algorithms for signing certificates.
+
+ .. php:attr:: $default
+
+ Default hash algorithm identifier for signing
+
+ .. php:staticmethod:: getInfo()
+
+ Get display strings for the supported hash algorithms.
+
+ :returns: * (array(string=>array('name'=>string, 'info'=>string)))
+
+ #. [$hash_identifier]['name'] = Name that should be displayed in UI
+ #. [$hash_identifier]['info'] = Additional information that can help with the selection of a suitable algorithm
+
+ .. php:staticmethod:: clean($hash_identifier)
+
+ Check if the input is a supported hash algorithm identifier otherwise return the identifier of the default hash algorithm
+
+ :param string $hash_identifier:
+ :returns: * (string) - The cleaned identifier
+
+.. sourcefile:: includes/lib/check_weak_key.php
+
+ :uses:
+ includes/lib/general.php
+
+ :file:`includes/lib/check_weak_key.php` does the checking of keys for vulnaribilities and therefore provides some functions to be used by other procedures.
+
+ .. php:function:: checkWeakKeyCSR($csr, $encoding = "PEM")
+
+ Checks whether the given CSR contains a vulnerable key.
+ This function uses:
+ :php:func:`checkWeakKeyText`,
+ :php:func:`failWithId`,
+ :php:func:`runCommand`
+
+ :param string $csr: The CSR to be checked
+ :param string [optional] $encoding: The encoding the CSR is in (for the "-inform" parameter of OpenSSL, currently only "PEM" (default) or "DER" allowed)
+ :returns: * (string) - containing the reason if the key is considered weak, empty string otherwise
+
+ .. php:function:: checkWeakKeyX509($cert, $encoding = "PEM")
+
+ Checks whether the given X509 certificate contains a vulnerable key.
+ This function uses:
+ :php:func:`checkWeakKeyText`,
+ :php:func:`failWithId`,
+ :php:func:`runCommand`
+
+ :param string $cert: The X509 certificate to be checked
+ :param string [optional] $encoding: The encoding the certificate is in (for the "-inform" parameter of OpenSSL, currently only "PEM" (default), "DER" or "NET" allowed)
+ :returns: * (string) - String containing the reason if the key is considered weak, empty string otherwise
+
+ .. php:function:: checkWeakKeySPKAC($spkac, $spkacname = "SPKAC")
+
+ Checks whether the given SPKAC certificate contains a vulnerable key.
+ This function uses:
+ :php:func:`checkWeakKeyText`,
+ :php:func:`failWithId`,
+ :php:func:`runCommand`
+
+ :param string $spkac: The SPKAC to be checked
+ :param string [optional] $spkacname: The name of the variable that contains the SPKAC. The default is "SPKAC"
+ :returns: * (string) - String containing the reason if the key is considered weak, empty string otherwise
+
+ .. php:function:: checkWeakKeyText($text)
+
+ Checks whether the given text representation of a CSR or a SPKAC contains a weak key.
+ This function uses:
+ :php:func:`checkDebianVulnerability`,
+ :php:func:`failWithId`,
+ :php:func:`runCommand`
+
+ :param string $text: The text representation of a key as output by the "openssl <foo> -text -noout" commands
+ :returns: * (string) - String containing the reason if the key is considered weak, empty string otherwise
+
+ .. php:function:: checkDebianVulnerability($text, $keysize = 0)
+
+ Reimplement the functionality of the openssl-vulnkey tool.
+
+ It triggers the exeptions:
+ :php:exc:`E_USER_NOTICE`,
+ :php:exc:`E_USER_WARNING`,
+ :php:exc:`E_USER_ERROR`
+
+
+ :param string $text: The text representation of a key as output by the "openssl <foo> -text -noout" commands
+ :param int [optional] $keysize: If the key size is already known it can be provided so it doesn't have to be parsed again. This also skips the check whether the key is an RSA key => use wisely.
+ :returns: * (mixed) - TRUE if key is vulnerable, FALSE otherwise, NULL in case of error
+
+.. sourcefile:: includes/lib/general.php
+
+ :file:`includes/lib/general.php` provides the system with four functions.
+
+ .. php:function:: get_user_id_from_cert($serial, $issuer_cn)
+
+ Checks if the user may log in and retrieve the user id. Usually called with $_SERVER['SSL_CLIENT_M_SERIAL'] and $_SERVER['SSL_CLIENT_I_DN_CN']
+
+ :param string $serial: usually $_SERVER['SSL_CLIENT_M_SERIAL']
+ :param string $issuer_cn: usually $_SERVER['SSL_CLIENT_I_DN_CN']
+ :return: * (int) - the user id, -1 in case of error
+
+ .. php:function:: failWithId($errormessage)
+
+ Produces a log entry with the error message with log level E_USER_WARN and a random ID an returns a message that can be displayed to the user including the generated ID
+
+ :param $errormessage string: The error message that should be logged
+ :return: * (string) - containing the generated ID that can be displayed to the user
+
+ .. php:function:: runCommand($command, $input = "", &$output = null, &$errors = true)
+
+ Runs a command on the shell and return it's exit code and output
+
+ :param string $command: The command to run. Make sure that you escapeshellarg() any non-constant parts as this is executed on a shell!
+ :param string|bool $input: The input that is passed to the command via STDIN, if true the real STDIN is passed through
+ :param string|bool $output: The output the command wrote to STDOUT (this is passed as reference), if true the output will be written to the real STDOUT. Output is ignored by default
+ :param string|bool $errors: The output the command wrote to STDERR (this is passed as reference), if true (default) the output will be written to the real STDERR
+ :return: * (int|bool) - The exit code of the command, true if the execution of the command failed (true because then <code>if (runCommand('echo "foo"')) handle_error();</code> will work)
+
+ .. php:function:: get_assurer_status($userID)
+
+ Determine if the user with the passed userid is an assurer.
+
+ :param int $userid: id of the user to be checked.
+ :return: * (int) - 0 if user is an assurer; 3,7,11,15 if 100 ssurance points not reached; 5,7,13,15 if assurer test is missing; 9,11,13,15 if not allowed to be an assurer.
+
+
+.. sourcefile:: includes/lib/l10n.php
+
+ :file:`includes/lib/l10n.php` defines the class L10n. Some methods use and manipulate the global variables:
+
+ .. php:global:: $_SESSION['_config']['language']
+
+ .. php:global:: $_SESSION['_config']['recode']
+
+ .. php:class:: L10n
+
+ .. php:attr:: $translations
+
+ An array of possible translations ("ISO-language code" => "native name of the language"). At the moment with values: "ar", "bg", "cs", "da", "de", "el", "en", "es", "fi", "fr", "hu", "it", "ja", "lv", "nl", "pl", "pt", "pt-br", "ru", "sv", "tr", "zh-cn", "zh-tw".
+
+ .. php:attr:: $locales
+
+ An array of allowed locales. Values at the moment: "ar_JO", "bg_BG", "cs_CZ", "da_DK", "de_DE", "el_GR", "en_US", "es_ES", "fa_IR", "fi_FI", "fr_FR", "he_IL", "hr_HR", "hu_HU", "id_ID", "is_IS", "it_IT", "ja_JP", "ka_GE", "ko_KR", "lv_LV", "nb_NO", "nl_NL", "pl_PL", "pt_PT", "pt_BR", "ro_RO", "ru_RU", "sl_SI", "sv_SE", "th_TH", "tr_TR", "uk_UA", "zh_CN", "zh_TW".
+
+ .. php:staticmethod:: detect_language()
+
+ It auto-detects the language that should be used and sets it. Only works for HTTP, not in a command line script. Priority:
+
+ #. explicit parameter "lang" passed in HTTP (e.g. via GET)
+ #. existing setting in the session (stick to the setting we had before)
+ #. auto-detect via the HTTP Accept-Language header sent by the user agent
+
+ Uses the global variables :php:global:`$_REQUEST["lang"]`, :php:global:`$_SERVER['HTTP_ACCEPT_LANGUAGE']`.
+
+ .. php:staticmethod:: normalise_translation($translation_code)
+
+ Normalise the translation code (e.g. from the old codes to the new)
+
+ :param string $translation_code: the translation code as specified in the keys of $translations
+ :return: * (string) - a translation code or the empty string if it can't be normalised
+
+ .. php:staticmethod:: get_translation()
+
+ Get the set translation. The method uses :php:global:`$_SESSION['_config']['language']`
+
+ :returns: * (string) - a translation code or the empty string if not set
+
+ .. php:staticmethod:: set_translation($translation_code)
+
+ Set the translation to use. Sets also the :php:global:`ENV LANG=` and if run in a session :php:global:`$_SESSION['_config']['language']` and :php:global:`$_SESSION['_config']['recode']`.
+
+ :param string $translation_code: the translation code as specified in the keys of {@link $translations}
+ :returns: * (bool) - true if the translation has been set successfully; false if the $translation_code was not contained in the white list or could not be set for other reasons (e.g. setlocale() failed because the locale has not been set up on the system - details will be logged)
+
+ .. php:staticmethod:: init_gettext($domain = 'messages')
+
+ Sets up the text domain used by gettext. Uses :php:global:`$_SESSION['_config']['filepath']` and appends '/locale'.
+
+ :param string $domain: the gettext domain that should be used, defaults to "messages"
+
+ .. php:staticmethod:: set_recipient_language($accountid)
+
+ Returns the language of a recipient to make sure that the language is correct
+
+ :param int $accountid: accountnumber of the recipient
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..6ebed43
--- /dev/null
+++ b/source/DIR-pages.rst
@@ -0,0 +1,282 @@
+.. 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/20.php
+
+ The file :file:`pages/index/20.php` doesn't exist but is linked to.
+
+.. 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..5d0317f
--- /dev/null
+++ b/source/DIR-www.rst
@@ -0,0 +1,382 @@
+.. 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
+ :uses:
+ includes/lib/l10n.php
+ includes/notary.inc.php
+ pages/index/17.php
+ pages/index/20.php
+ includes/general.php-loadem
+ includes/mysql.php-sendmail
+ includes/general.php-checkpw
+
+ The :file:`index.php` is the main page of the CAcert website. Depending on an id transfered to this module different actions are performed.
+
+ ids
+
+.. todo:: Check where/when includes/general.php and includes/mysql.php is loaded
+
+
+.. 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/_static/.keep b/source/_static/.keep
new file mode 100644
index 0000000..e69de29
--- /dev/null
+++ b/source/_static/.keep
diff --git a/source/building.rst b/source/building.rst
new file mode 100644
index 0000000..fec9e5d
--- /dev/null
+++ b/source/building.rst
@@ -0,0 +1,95 @@
+==========================
+Building the documentation
+==========================
+
+This documentation is maintained as a set of ReStructuredText documents and
+uses `Sphinx <http://www.sphinx-doc.org/>`_ to build HTML formatted
+representations of the documents.
+
+Getting the documentation source
+--------------------------------
+
+The documentation is available from the git repository cacert-codedocs on
+git.cacert.org. You can browse the :cacertgit:`cacert-codedocs` via gitweb.
+
+You can clone the repository anonymously by executing::
+
+ git clone git://git.cacert.org/cacert-codedocs.git
+
+There is a github mirror of this repository available at
+
+ https://github.com/CAcertOrg/cacert-codedocs
+
+You make fork from that clone and contribute your changes via pull requests.
+Merged pull requests will be applied to the repository at git.cacert.org.
+
+If you just want to contribute to the documentation you are encouraged to use
+Github and pull requests.
+
+Please ask git-admin@cacert.org to setup a user in the group git-doc on
+git.cacert.org for you to get push access to the git.cacert.org repository.
+You will have to provide an SSH public key (either RSA with at least 2048 Bits
+modulus or an ECDSA or ED25519 key with similar strength) with your request.
+
+If you have a user in the git-doc group you can clone the repository by
+executing::
+
+ git clone ssh://<username>@git.cacert.org/var/cache/git/cacert-codedocs.git
+
+.. note:: replace ``<username>`` with your actual username
+
+Building with Sphinx
+--------------------
+
+To build this documentation you need a Python 3 installation. To isolate the
+documentation build from your system Python 3 packages using a virtual
+environment is recommended. Management of the virtual environment can be done
+with pipenv as described below.
+
+Python 3 installation instructions can be found on the `Python website`_.
+
+.. _Python website: https://www.python.org/
+
+.. topic:: Building the documentation on a Debian system
+
+ The following example shows how to build the documentation on a Debian system:
+
+ .. code-block:: bash
+
+ # Install required operating system packages
+ sudo apt-get install python3 python3-pip make
+ # install pipenv
+ python3 -m pip install -U pip pipenv
+ # use pipenv to install require dependencies into a virtual environment
+ pipenv install
+ # Build the documentation
+ pipenv run make html
+
+ .. note::
+
+ You may need to add :file:`~/.local/bin` to the :envvar:`$PATH`
+ environment variable before you will be able to run :program:`pipenv`.
+ You can do this by adding ``export PATH=~/.local/bin:$PATH`` to your
+ shell initialization file like :file:`~/.bashrc` or :file:`~/.zshrc`.
+
+ The above commands should be run from the root directory of a git clone
+ of the cacert-codedocs git repository. The result of the :program:`make`
+ exection will be available in the :file:`build/html/` directory
+ directory.
+
+Continuous integration
+----------------------
+
+If changes are pushed to the cacert-codedocs git repository on git.cacert.org
+a `Jenkins Job <https://jenkins.cacert.org/job/cacert-codedocs/>`_ is
+automatically triggered. If the documentation is built successfully it can be
+viewed in the `docs/_build/html directory of the Job's workspace
+<https://jenkins.cacert.org/job/cacert-codedocs/ws/build/html/>`_. You may
+open `index.html
+<https://jenkins.cacert.org/job/cacert-codedocs/ws/build/html/index.html>`_
+to browse the documentation (there are some JavaScript and SVG glitches due to
+Content-Security-Policy settings).
+
+If the documentation build is successful the result is pushed to a webserver
+document root on :doc:`infradocs:systems/webstatic` and is publicly available at
+https://codedocs.cacert.org/.
diff --git a/source/conf.py b/source/conf.py
index a80f538..4e0e14b 100644
--- a/source/conf.py
+++ b/source/conf.py
@@ -14,10 +14,26 @@
#
from datetime import datetime
import os
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
+import certifi
+import requests
+import sys
+sys.path.insert(0, os.path.abspath('.'))
from git import repo
+from docutils import nodes, utils
+
+try:
+ print('Checking connection to infradocs.cacert.org')
+ requests.head('https://infradocs.cacert.org/')
+ print('Connection to infradocs.cacert.org OK')
+except requests.exceptions.SSLError as err:
+ print('SSL Error. Adding CAcert certificates to Certifi store...')
+ cafile = certifi.where()
+ with open(os.path.join(
+ os.path.dirname(__file__), '..', 'cacert.pem'), 'rb') as infile:
+ cacertca = infile.read()
+ with open(cafile, 'ab') as outfile:
+ outfile.write(cacertca)
# -- Project information -----------------------------------------------------
@@ -29,10 +45,8 @@ author = 'CAcert development team'
version = '0.1'
# The full version, including alpha/beta/rc tags
release = "{}-git:{} built:{}".format(
- version,
- repo.Repo('..').git.describe('--always', '--dirty'),
- datetime.utcnow().replace(microsecond=0))
-
+ version, repo.Repo('..').git.describe('--always', '--dirty'),
+ datetime.utcnow().replace(microsecond=0))
# -- General configuration ---------------------------------------------------
@@ -48,6 +62,10 @@ extensions = [
'sphinx.ext.extlinks',
'sphinx.ext.todo',
'sphinx.ext.ifconfig',
+ 'sphinxcontrib.phpdomain',
+ 'sphinxcontrib.blockdiag',
+ 'sphinxcontrib.seqdiag',
+ 'sphinxext.cacert',
]
# Add any paths that contain templates here, relative to this directory.
@@ -197,7 +215,7 @@ epub_exclude_files = ['search.html']
# -- Options for intersphinx extension ---------------------------------------
# Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {'https://docs.python.org/': None}
+intersphinx_mapping = {'infradocs': ('https://infradocs.cacert.org', None)}
# -- Options for todo extension ----------------------------------------------
@@ -206,9 +224,10 @@ todo_include_todos = True
extlinks = {
'wiki': ('https://wiki.cacert.org/%s', 'Wiki '),
+ 'cacertgit': ('https://git.cacert.org/gitweb/?p=%s.git', 'CAcert Git repository '),
+ 'github': ('https://github.com/CAcertOrg/%s', 'Github repository '),
}
-
def cacert_bug(name, rawtext, text, lineno, inliner, options={}, content=[]):
try:
bugnum = int(text)
diff --git a/source/database.rst b/source/database.rst
new file mode 100644
index 0000000..ee8ac46
--- /dev/null
+++ b/source/database.rst
@@ -0,0 +1,6 @@
+==================
+Database structure
+==================
+
+This part of the documentation describes the database schema of the CAcert
+web application.
diff --git a/source/directories.rst b/source/directories.rst
new file mode 100644
index 0000000..c006bd4
--- /dev/null
+++ b/source/directories.rst
@@ -0,0 +1,30 @@
+===================
+Directory structure
+===================
+
+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
+- a :file:`README` file with very rudimentary documentation stating the
+ license and a list of system requirements
+
+.. _GPL: https://www.gnu.org/licenses/old-licenses/gpl-2.0
+
+
+.. toctree::
+ :maxdepth: 2
+ :caption: Documentation for subdirectories
+ :name: directorytoc
+
+ DIR-cgi-bin
+ DIR-CommModule
+ DIR-includes
+ DIR-locale
+ DIR-pages
+ DIR-scripts
+ DIR-stamp
+ DIR-tmp
+ DIR-tverify
+ DIR-www
+
diff --git a/source/general.rst b/source/general.rst
new file mode 100644
index 0000000..908a017
--- /dev/null
+++ b/source/general.rst
@@ -0,0 +1,26 @@
+====================
+General observations
+====================
+
+License
+=======
+
+The code is licensed under the terms of the GPL version 2 upgrading to GPL 3
+would require consent from all former contributors. Copyright years of files
+have not been consistently incremented/updated on changes.
+
+Languages
+=========
+
+The code base is a mix of Perl, Shell and PHP code. Most of the code is
+implemented in PHP.
+
+Code structure
+==============
+
+Comments and inline documentation
+=================================
+
+The code base is not documented in a good way, there are neither class nor
+method or function comments. Comments are just used for the license header
+in most of the files. \ No newline at end of file
diff --git a/source/globals.rst b/source/globals.rst
new file mode 100644
index 0000000..cf82d63
--- /dev/null
+++ b/source/globals.rst
@@ -0,0 +1,161 @@
+.. index:: scripts
+.. index:: PHP
+
+================
+Global Variables
+================
+
+ As the modules this website includes have to communicate together there are some global variables defined as arrays
+
+
+.. index:: $_REQUEST
+
+:php:global:`$_REQUEST`
+=======================
+.. php:global:: $_REQUEST['action']
+
+.. php:global:: $_REQUEST['cert']
+
+.. php:global:: $_REQUEST['domid']
+
+.. php:global:: $_REQUEST['id']
+
+.. php:global:: $_REQUEST["lang"]
+
+.. php:global:: $_REQUEST['memid']
+
+.. php:global:: $_REQUEST['oldid']
+
+.. php:global:: $_REQUEST['orgid']`
+
+.. php:global:: $_REQUEST['process']
+
+.. php:global:: $_REQUEST['showdetails']
+
+.. php:global:: $_REQUEST['ticketno']
+
+.. index:: $_SERVER
+
+:php:global:`$_SERVER`
+======================
+
+.. php:global:: $_SERVER['HTTP_ACCEPT_LANGUAGE']
+
+.. php:global:: $_SERVER['PHP_SELF']
+
+
+.. index:: $_SESSION
+
+:php:global:`$_SESSION`
+========================
+
+.. php:global:: $_SESSION['mconn']
+
+This global variable defines the status of the database connection
+
+* TRUE if a connection could be established
+* FALSE otherwise
+
+.. index:: $_SESSION['_config']
+
+----------------------------------
+:php:global:`$_SESSION['_config']`
+----------------------------------
+
+.. php:global:: $_SESSION['_config']['errmsg']
+
+.. php:global:: $_SESSION['_config']['filepath']
+
+.. php:global:: $_SESSION['_config']['header']
+
+.. php:global:: $_SESSION['_config']['language']
+
+.. php:global:: $_SESSION['_config']['normalhostname']
+
+This global variable defines the main CAcert-website
+
+* "www.cacert.org" for production
+* "test.cacert.org" for testing
+
+.. php:global:: $_SESSION['_config']['recode']
+
+.. php:global:: $_SESSION['_config']['securehostname']
+
+This global variable defines the secure CAcert-website
+
+* "secure.cacert.org" for production
+* " cacert.org" for testing
+
+ .. php:global:: $_SESSION['_config']['tverify']
+
+ This global variable defines TVERIFY
+
+ * "tverify.cacert.org" for production
+ * " " for testing
+
+
+
+.. todo:: checkout what TVERIFY means, check names for test-system
+
+.. index:: $_SESSION['profile']
+
+----------------------------------
+:php:global:`$_SESSION['profile']`
+----------------------------------
+
+.. php:global:: $_SESSION['profile']['adadmin']
+
+.. php:global:: $_SESSION['profile']['admin']
+
+.. php:global:: $_SESSION['profile']['assurer']
+
+.. php:global:: $_SESSION['profile']['dob']
+
+.. php:global:: $_SESSION['profile']['email']
+
+.. php:global:: $_SESSION['profile']['fname']
+
+.. php:global:: $_SESSION['profile']['id']
+
+.. php:global:: $_SESSION['profile']['lname']
+
+.. php:global:: $_SESSION['profile']['locadmin']
+
+.. php:global:: $_SESSION['profile']['mname']
+
+.. php:global:: $_SESSION['profile']['orgadmin']
+
+.. php:global:: $_SESSION['profile']['points']
+
+.. php:global:: $_SESSION['profile']['suffix']
+
+.. index:: globalConstants
+
+================
+Global Constants
+================
+
+.. php:const:: NULL_DATETIME
+
+ This constant has the value '0000-00-00 00:00:00'
+
+.. php:const:: THAWTE_REVOCATION_DATETIME
+
+ This constant has the value '2010-11-16 00:00:00'.
+
+
+
+
+==========
+Exceptions
+==========
+
+.. php:exception:: E_USER_NOTICE
+
+.. php:exception:: E_USER_WARNING
+
+.. php:exception:: E_USER_ERROR
+
+
+
+
diff --git a/source/glossary.rst b/source/glossary.rst
new file mode 100644
index 0000000..b3b2383
--- /dev/null
+++ b/source/glossary.rst
@@ -0,0 +1,16 @@
+========
+Glossary
+========
+
+.. glossary::
+
+ CRL
+ Definition from :rfc:`5280`:
+
+ X.509 defines one method of certificate revocation. This method
+ involves each CA periodically issuing a signed data structure called
+ a certificate revocation list (CRL). A CRL is a time-stamped list
+ identifying revoked certificates that is signed by a CA or CRL
+ issuer and made freely available in a public repository. Each
+ revoked certificate is identified in a CRL by its certificate serial
+ number. \ No newline at end of file
diff --git a/source/index.rst b/source/index.rst
index bb39a6d..1d87e9d 100644
--- a/source/index.rst
+++ b/source/index.rst
@@ -3,20 +3,31 @@
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
-Welcome to CAcert code documentation
-====================================
+CAcert code documentation
+=========================
This is a work in progress documentation of the CAcert web application source
-code at https://git.cacert.org/gitweb/?p=cacert.git.
+code in the `release` branch of the :cacertgit:`cacert-devel`.
The goal is to document the existing code base to give insight into its
functionality and to support writing a specification for a potential
reimplementation.
+The code repository is mirrored to the :github:`cacert-devel` to encourage
+contribution. The canonical repository is the :cacertgit:`cacert-devel` though.
+
.. toctree::
:maxdepth: 2
:caption: Contents:
+ general
+ globals
+ directories
+ database
+ signer
+ building
+ glossary
+
Filesystem structure
--------------------
@@ -32,5 +43,4 @@ Indices and tables
==================
* :ref:`genindex`
-* :ref:`modindex`
* :ref:`search`
diff --git a/source/signer.rst b/source/signer.rst
new file mode 100644
index 0000000..fb930d4
--- /dev/null
+++ b/source/signer.rst
@@ -0,0 +1,486 @@
+===================
+The Signer Protocol
+===================
+
+Communication with the signer is performed via a serial connection. That
+connection has to be established by the client before speaking the protocol
+defined here.
+
+.. _signer-request-data-format:
+
+Signer request data format specification
+========================================
+
+Protocol request data is encoded in the following format:
+
+.. table:: signer request message format
+
+ ======= ==============================================================
+ Byte Data
+ ======= ==============================================================
+ 0-2 length of header + data in network byte order
+ 3-5 length of header network byte order
+ 6-14 action specific header
+ 15-17 length of first action specific content in network byte order
+ 18-N fist action specific content string
+ N+1-N+3 length of second action specific content in network byte order
+ N+4-M second action specific content string
+ M+1-M+3 lenght of third action specific content in network byte order
+ M+4-End third action specific content string
+ ======= ==============================================================
+
+Due to the length encoding in 3 bytes the messages can have a maximum length
+of 8\ :sup:`3` = 2\ :sup:`24` Bytes which is around 16 MiB.
+
+General request header format
+-----------------------------
+
+Every protocol request header (bytes 3-12 of protocol request message) follows
+the same 9 byte structure. The content of bytes 3-8 are protocol action
+specific.
+
+.. table:: general request header format
+
+ ==== ===========================
+ Byte Value
+ ==== ===========================
+ 0 Version (``0x01``)
+ 1 Action
+ 2 System (used crypto system)
+ 3 8 bits root
+ 4 8 bits configuration
+ 5 8 bits parameter
+ 6-7 16 bits parameter
+ 8 8 bits parameter
+ ==== ===========================
+
+.. _signer-nul-request-format:
+
+Format of NUL requests
+----------------------
+
+NUL requests are sent at the end of each iteration in
+:sourcefile:`client.pl <CommModule/client.pl>`'s main loop.
+
+.. table:: NUL request header format
+
+ ==== ==================
+ Byte Value
+ ==== ==================
+ 0 Version (``0x01``)
+ 1 Action (``0x00``)
+ 2 System (``0x00``)
+ 3 ``0x00``
+ 4 ``0x00``
+ 5 ``0x00``
+ 6-7 ``0x0000``
+ 8 ``0x00``
+ ==== ==================
+
+**NUL Request Payload:**
+
+- GMT timestamp in %m%d%H%M%Y.%S format
+- ""
+- ""
+
+.. note::
+
+ The timestamp sent with the NUL request is used to create a
+ script to synchronize the time on the signer using :program:`date` and
+ :program:`hwclock`.
+
+.. _signer-x509-request-format:
+
+Format of X.509 signing request messages
+----------------------------------------
+
+X.509 signing request messages are sent in
+:sourcefile:`client.pl <CommModule/client.pl>`'s main loop for each requested
+certificate.
+
+.. table:: X.509 certificate signing request header format
+
+ ==== ===================================================================
+ Byte Value
+ ==== ===================================================================
+ 0 Version (``0x01``)
+ 1 Action (``0x01``)
+ 2 System (``0x01`` for X.509)
+ 3 Root (see table :ref:`table-cert-roots`)
+ 4 Profile (see table :ref:`table-cert-profiles`)
+ 5 Message Digest Id (see table :ref:`table-md-ids`)
+ 6-7 Days in big-endian format
+ 8 Key type [#unused-server]_
+ ==== ===================================================================
+
+The key type is stored in the column *keytype* of the certificate request
+table which is one of
+
+- *domaincerts*
+- *emailcerts*
+- *orgdomaincerts*
+- *orgemailcerts*
+
+**X.509 Signing Request Payload:**
+
+- PEM encoded PKCS#10 / :rfc:`2986` certifcate signing request or SPKAC
+ (Netscape) signed public key and challenge (i.e. generated from a
+ `\<keygen\> HTML form element <keygen>`_)
+- comma separated list of SubjectAlternative names in a format that is
+ accepted by openssl configuration file directive ``subjectAltName`` (see
+ https://www.openssl.org/docs/man1.0.2/apps/x509v3_config.html#Subject-Alternative-Name)
+- The requested subject DN in openssl format (parts separated by ``/``)
+
+.. _keygen: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/keygen
+
+.. _table-cert-roots:
+
+.. table:: CA root certificate identifiers
+
+ == =================================================
+ Id CA root
+ == =================================================
+ 0 CAcert root (aka CAcert class 1 root)
+ 1 CAcert class3
+ 2 CAcert class3s
+ x root{}
+ == =================================================
+
+.. note::
+
+ The CA root identifier is retrieved from the database by
+ :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 :sourcefile:`server.pl <CommModule/server.pl>` restricts the
+ allowed root id in its ``CheckSystem`` function.
+
+.. _table-cert-profiles:
+
+.. table:: Certificate profile ids
+
+ == ======================
+ Id Profile
+ == ======================
+ 0 Client (personal)
+ 1 Client (Organization)
+ 2 Client (Code signing)
+ 3 Client (Machine)
+ 4 Client (ADS)
+ 5 Server (personal)
+ 6 Server (Organization)
+ 7 Server (Jabber)
+ 8 Server (OCSP)
+ 9 Server (Timestamp)
+ 10 Proxy
+ 11 SubCA
+ == ======================
+
+.. note::
+
+ :sourcefile:`client.pl <CommModule/client.pl>` supports profiles 0, 1, 2, 4,
+ 5, 6, 8 and 9 only.
+
+.. _table-md-ids:
+
+.. table:: Message digest ids
+
+ == ==========
+ Id Algorithm
+ == ==========
+ 1 MD5
+ 2 SHA-1
+ 3 RIPE-MD160
+ 8 SHA-256
+ 9 SHA-384
+ 10 SHA-512
+ == ==========
+
+.. _signer-openpgp-request-format:
+
+Format of OpenPGP key signing request messages
+----------------------------------------------
+
+OpenPGP key signing request messages are sent in
+:sourcefile:`client.pl <CommModule/client.pl>`'s main loop for each requested
+OpenPGP key.
+
+.. table:: OpenPGP key signing request header format
+
+ ==== =============================
+ Byte Value
+ ==== =============================
+ 0 Version (``0x01``)
+ 1 Action (``0x01``)
+ 2 System (``0x02`` for OpenPGP)
+ 3 ``0x00``
+ 4 ``0x00``
+ 5 ``0x02`` [#unused-server]_
+ 6-7 366 encoded as ``0x016e``
+ 8 ``0x00``
+ ==== =============================
+
+**OpenPGP Signing Request Payload:**
+
+- OpenPGP public keyring in binary format (see :rfc:`4880`)
+- ""
+- ""
+
+.. [#unused-server] the field is unused in
+ :sourcefile:`server.pl <CommModule/server.pl>`
+
+.. _signer-csr-request-format:
+
+Format of X.509 certificate revocation request messages
+-------------------------------------------------------
+
+X.509 certificate revocation request messages are sent in
+:sourcefile:`client.pl <Commmodule/client.pl>`'s main loop for each requested
+X.509 certificate revocation.
+
+ ==== ===========================
+ Byte Value
+ ==== ===========================
+ 0 Version (``0x01``)
+ 1 Action (``0x02``)
+ 2 System (``0x01`` for X.509)
+ 3 Root
+ 4 ``0x00``
+ 5 ``0x00``
+ 6-7 365 encoded as ``0x016d``
+ 8 ``0x00``
+ ==== ===========================
+
+**X.509 Certificate Revocation Request Payload:**
+
+- PEM encoded certificate data of the certificate to be revoked
+- ""
+- hexadecimal encoded SHA-1 hash of the CRL known CRL file of the requested
+ CA Root (header byte 3)
+
+.. _signer-response-data-format:
+
+Signer response data format specification
+=========================================
+
+Protocol response data is encoded in the following format:
+
+.. table:: signer response message format:
+
+ ======= =======================================================
+ Byte Data
+ ======= =======================================================
+ 0-2 length of header + data in network byte order
+ 3-5 length of header network byte order
+ 6-9 header data
+ 10-12 length of payload data 1 in network byte order
+ 13-N payload data 1
+ N+1-N+3 length of payload data 2 network byte order
+ N+4-M payload data 2
+ M+1-M+3 length of payload data 3 network byte order
+ M+4-End payload data 3
+ ======= =======================================================
+
+General response header format
+------------------------------
+
+Every protocol response header (bytes 6-9 of protocol response message)
+follows the same 4 byte structure. The content of bytes 3 and 4 are not used
+yet.
+
+.. table:: general response header format
+
+ ==== ==================
+ Byte Value
+ ==== ==================
+ 0 Version (``0x01``)
+ 1 Action
+ 2 ``0x00`` unused
+ 3 ``0x00`` unused
+ ==== ==================
+
+.. _signer-nul-response-format:
+
+Format of NUL Responses
+-----------------------
+
+NUL responses are sent in response to
+:ref:`NUL requests <signer-nul-request-format>`.
+
+.. table:: NUL response header format
+
+ ==== ==================
+ Byte Value
+ ==== ==================
+ 0 Version (``0x01``)
+ 1 Action (``0x00``)
+ 2 ``0x00`` unused
+ 3 ``0x00`` unused
+ ==== ==================
+
+**NUL Response Payload:**
+
+- ""
+- ""
+- ""
+
+Format of X.509 certificate response messages
+---------------------------------------------
+
+X.509 certificate response messages are sent in response to
+:ref:`X.509 certificate signing request messages <signer-x509-request-format>`.
+
+.. table:: X.509 certificate response header format
+
+ ==== ==================
+ Byte Value
+ ==== ==================
+ 0 Version (``0x01``)
+ 1 Action (``0x01``)
+ 2 ``0x00`` unused
+ 3 ``0x00`` unused
+ ==== ==================
+
+**X.509 certificate response payload:**
+
+- PEM encoded X.509 certificate
+- ""
+- ""
+
+.. _signer-openpgp-response-format:
+
+Format of OpenPGP key signature response messages
+-------------------------------------------------
+
+OpenPGP key signature response messages are sent in response to
+:ref:`OpenPGP key signing request messages <signer-openpgp-request-format>`.
+
+.. table:: OpenPGP key signature response header format
+
+ ==== ==================
+ Byte Value
+ ==== ==================
+ 0 Version (``0x01``)
+ 1 Action (``0x02``)
+ 2 ``0x00`` unused
+ 3 ``0x00`` unused
+ ==== ==================
+
+**OpenPGP key signature response payload:**
+
+- ASCII armored PGP public key block
+- ""
+- ""
+
+Format of X.509 certificate revocation response messages
+--------------------------------------------------------
+
+X.509 certificate revocation response messages are sent in response to
+:ref:`X.509 certificate revocation request messages
+<signer-csr-request-format>`.
+
+.. table:: X.509 certificate revocation response header format
+
+ ==== =====================================
+ Byte Value
+ ==== =====================================
+ 0 Version (``0x01``)
+ 1 Action (``0x02``) [#overlap-openpgp]_
+ 2 ``0x00`` unused
+ 3 ``0x00`` unused
+ ==== =====================================
+
+.. [#overlap-openpgp] this response type uses the same action byte as the
+ :ref:`OpenPGP key signature response message <signer-openpgp-response-format>`
+
+**X.509 certificate revocation response payload:**
+
+- CRL diff in :program:`xdelta` format or "" if the original CRL specified
+ by the SHA-1 hash in the third payload field of the request is not
+ available
+- ""
+- ""
+
+
+Protocol messages
+=================
+
+.. _signer-message-handshake:
+
+Handshake
+---------
+
+#. client sends 1 byte ``0x02`` to serial port
+#. client reads 1 byte from serial port (with a 20 second timeout)
+#. client checks whether the byte is ``0x10``
+
+.. seqdiag::
+
+ seqdiag handhake {
+ client -> server [label = "0x02"];
+ client <-- server [label = "0x10"];
+ }
+
+If anything different is received there was a protocol error and no further
+messages should be sent over the serial connection.
+
+.. _signer-message-senddata:
+
+Send data
+---------
+
+:Preconditions:
+ successful :ref:`Handshake <signer-message-handshake>`,
+ data is encoded according to the :ref:`signer-request-data-format`
+
+#. client builds byte wise xor of all data bytes into 1 byte $xor
+#. client sends concatenated $data string + xor-Byte + "rie4Ech7"
+#. client reads 1 byte (with a 5 second timeout)
+#. if received byte is ``0x11`` try again
+#. if received byte is ``0x10`` the message has been sent successfully
+
+.. seqdiag::
+
+ seqdiag request_with_retry {
+ client -> client [label = "xor $data"];
+ client -> server [label = "$data . $xor . \"rie4Ech7\""];
+ server -> server [label = "detect corruption"];
+ client <-- server [label = "0x11"];
+ client -> server [label = "$data . $xor . \"rie4Ech7\""];
+ client <-- server [label = "0x10"];
+ }
+
+If anything different is received there was a protocol error and no further
+messages should be sent over the serial connection.
+
+Receive data
+------------
+
+:Preconditions:
+ client :ref:`sent data <signer-message-senddata>`
+
+#. client waits for a response (with a 120 second timeout)
+#. server builds byte wise xor of all data bytes in 1 byte $xor
+#. server sends ``0x02`` to start transmission
+#. client sends ``0x10`` to confirm receipt (server timeout 1 second)
+#. server sends concatenated $data string + xor-Byte + "rie4Ech7"
+#. client reads data in 100 byte segments (5 second timeout)
+#. client sends ``0x11`` in case of corrupted data and retries reading
+#. client sends ``0x10`` if successful
+#. server waits for response for 5 seconds
+#. server sends concatenated $data string + xor-Byte + "rie4Ech7" if client
+ response is ``0x11``
+
+.. seqdiag::
+
+ seqdiag response_with_retry {
+ client -> server [label = "wait"];
+ server -> server [label = "xor $data"];
+ client <- server [label = "0x02"];
+ client --> server [label = "0x10"];
+ client <- server [label = "$data . $xor . \"rie4Ech7\""];
+ client -> client [label = "detect corruption"];
+ client --> server [label = "0x11"];
+ client <- server [label = "$data . $xor . \"rie4Ech7\""];
+ client --> server [label = "0x10"];
+ }
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__}
diff --git a/source/structure.txt b/source/structure.txt
index c4f5993..9d6bfc6 100644
--- a/source/structure.txt
+++ b/source/structure.txt
@@ -193,7 +193,8 @@
│   │   ├── version2.sh
│   │   ├── version3.sh
│   │   ├── version4.sh
-│   │   └── version5.sh
+│   │   ├── version5.sh
+│   │   └── version6.sh
│   ├── DumpWeakCerts.pl
│   ├── findexp3.pl
│   ├── findnull.pl
@@ -365,17 +366,36 @@
├── logos.php
├── news.php
├── policy
+ │   ├── AssurancePolicy.html
│   ├── AssurancePolicy.php
+ │   ├── CAcertCommunityAgreement.html
│   ├── CAcertCommunityAgreement.php
- │   ├── cacert-draft.png
+ │   ├── CertificationPracticeStatement.html
│   ├── CertificationPracticeStatement.php
+ │   ├── ConfigurationControlSpecification.html
+ │   ├── DisputeResolutionPolicy.html
│   ├── DisputeResolutionPolicy.php
+ │   ├── images
+ │   │   ├── cacert-draft.png
+ │   │   ├── cacert-policy.png
+ │   │   ├── valid-html401-blue.png
+ │   │   ├── valid-html50-blue.png
+ │   │   └── valid-xhtml11-blue.png
│   ├── index.php
- │   ├── NRPDisclaimerAndLicence.php
+ │   ├── OrganisationAssurancePolicy_Australia.html
+ │   ├── OrganisationAssurancePolicy_Europe.html
+ │   ├── OrganisationAssurancePolicy_Germany.html
+ │   ├── OrganisationAssurancePolicy.html
│   ├── OrganisationAssurancePolicy.php
+ │   ├── PolicyOnJuniorAssurersMembers.html
+ │   ├── PolicyOnPolicy.html
│   ├── PolicyOnPolicy.php
│   ├── PrivacyPolicy.html
- │   └── RootDistributionLicense.php
+ │   ├── PrivacyPolicy.php
+ │   ├── RootDistributionLicense.html
+ │   ├── RootDistributionLicense.php
+ │   ├── SecurityPolicy.html
+ │   └── TTPAssistedAssurancePolicy.html
├── rss.php
├── sealgen.php
├── siteimages
@@ -584,4 +604,4 @@
├── verify.php
└── wot.php
-36 directories, 548 files
+37 directories, 567 files