be43d1ab1752c82120c6cc8340e3857f09b46af2
[cacert-codedocs.git] / source / DIR-includes.rst
1 .. index:: includes
2 .. index:: PHP
3
4 ==========================
5 Directory :file:`includes`
6 ==========================
7
8 .. sourcefile:: includes/.cvsignore
9
10 :file:`.cvsignore` includes the parameters for CVS, which files to ignore by
11 versioning
12
13 .. note:: CVS is long dead, is this still used?
14
15 .. sourcefile:: includes/.gitignore
16
17 :file:`.gitignore` contains file patterns to be ignored by Git.
18
19 .. sourcefile:: includes/about_menu.php
20 :links:
21 http://blog.cacert.org/
22 http://wiki.CAcert.org/
23 www/policy/
24 //wiki.cacert.org/FAQ/Privileges
25 www/index.php?id=47
26 www/logos.php
27 www/stats.php
28 http://blog.CAcert.org/feed/
29 www/index.php?id=7
30 //wiki.cacert.org/Board
31 https://lists.cacert.org/wws
32 www/src-lic.php
33
34 :file:`about_menu.php` is a part (<div>) of a PHP-Page, containing most of
35 the CAcert-related links.
36
37 .. sourcefile:: includes/account_stuff.php
38
39 :file:`includes/account_stuff.php` provides two procedures to be used for building the output of some HTML-pages.
40
41 .. php:function:: showheader($title = "CAcert.org", $title2 = "")
42
43 This function renders a page depending on the calling file. It is expected that only files
44
45 www/wot.php (web-of-trust),
46
47 www/gpg.php (gpg-key),
48
49 www/disputes.php (disputes) and
50
51 www/advertising.php (advertising)
52
53 are using this function.
54
55 :param string $title:
56 :param string $title2:
57 :global: * *(int)* - $id:
58 :global: * *(string)* - $PHP_SELF:
59
60 .. php:function:: showfooter()
61
62 This function renders a page-footer.
63
64
65 .. sourcefile:: includes/account.php
66 :uses:
67 includes/loggedin.php
68 includes/lib/l10n.php
69 includes/lib/check_weak_key.php
70 includes/notary.inc.php
71 includes/general.php
72 includes/account_stuff.php
73 includes/notary.inc.php
74 SOME__sanitizeHTML
75 .. ?-check_email
76 .. ?-make_hash
77 includes/mysql.php__sendmail
78 .. ?-account_email_delete
79 .. ?-checkWeakKeySPKAC
80 .. ?-write_user_agreement
81 .. ?-generatecertpath
82 .. ?-checkWeakKeyCSR
83 .. ?-waitForResult
84 .. ?-checkEmail
85 .. ?-account_domain_delete
86 .. ?-clean_csr
87 .. ?-extractit
88 .. ?-getcn
89 .. ?-getalt
90 .. ?-HashAlgorithms::clean_csr
91 .. ?-checkWeakKeyX509
92 .. ?-unset
93 .. ?-valid_ticket_number
94 .. ?-write_se_log
95 .. ?-revoke_all_private_cert
96 .. ?-runCommand
97 .. ?-check_client_cert_running
98 .. ?-check_server_cert_running
99 .. ?-check_gpg_cert_running
100 .. ?-check_is_orgadmin
101 .. ?-account_delete
102
103
104
105 .. php:function:: buildSubject(array $domains, $include_xmpp_addr = true)
106
107 Build a subject string as needed by the signer
108
109 :param array(string) $domains: First domain is used as CN and repeated in subjectAltName. Duplicates should already been removed
110 :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
111 :return: * (string) - subject string as needed by the signer
112
113 .. php:function:: buildSubjectFromSession()
114
115 Builds the subject string from the session variables $_SESSION['_config']['rows'] and $_SESSION['_config']['altrows']
116
117 :return: * (string) -
118
119 .. sourcefile:: includes/general_stuff.php
120
121 .. sourcefile:: includes/general.php
122
123 .. sourcefile:: includes/keygen.php
124
125 .. sourcefile:: includes/loggedin.php
126
127 .. sourcefile:: includes/mysql.php
128
129 :file:`includes/mysql.php` is not contained in the :cacertgit:`cacert-devel`
130 repository but is used by several other files. The file is copied from
131 :sourcefile:`includes/mysql.php.sample` and defines the database connection
132 information.
133
134 This file is parsed directly by :sourcefile:`CommModule/client.pl`
135 format changes might break the CommModule code.
136
137 .. sourcefile:: includes/mysql.php.sample
138
139 :file:`mysql.php.sample` is a template for the database connection handling
140 code that is meant to be copied to :file:`mysql.php`.
141
142 The template defines the MySQL connection as a session variable `mconn` and
143 tries to connect to that database. It also defines the session variables
144 `normalhostname`, `securehostname` and `tverify`.
145
146 The template defines a function :php:func:`sendmail` for sending mails.
147
148 .. php:function:: sendmail($to, $subject, $message, $from, $replyto="", \
149 $toname="", $fromname="", $errorsto="returns@cacert.org", \
150 $use_utf8=true)
151
152 Send an email. The function reimplements functionality that is readily
153 available in PHP. The function does not properly escape headers and
154 sends raw SMTP commands.
155
156 :param string $to: recipient email address
157 :param string $subject: subject
158 :param string $message: email body
159 :param string $from: from email address
160 :param string $replyto: reply-to email address
161 :param string $fromname: unused in the code
162 :param string $toname: unused in the code
163 :param string $errorsto: email address used for Sender and Errors-To
164 headers
165 :param bool $use_utf8: decides whether the Content-Type header uses
166 a charset parameter of utf-8 or iso-8859-1
167
168 Configuration and actual code are mixed. It would be better to have a
169 separate file that just includes configuration.
170
171 .. sourcefile:: includes/notary.inc.php
172
173 :file:`includes/notary.inc.php` provides a set of funktions; here listed in the given order:
174
175 .. php:function:: query_init ($query)
176
177 Accesss the database to execute the passed query.
178
179 :param string $query: query to execute
180 :return: * (resource) - result of the passed query.
181
182 .. php:function:: query_getnextrow ($res)
183
184 Return the next row of a previous received result of a database query.
185
186 :param resource $res: Result of a previous database query.
187 :return: * (object) - next row in the passed resource
188
189 .. php:function:: query_get_number_of_rows ($resultset)
190
191 Return the number of rows of the passed $resource which has to be the result of a previous database query, select-statement
192
193 :param resource $resultset: Result of a previous database query
194 :return: * (int) - number of rows in the passed resource
195
196 .. php:function:: get_number_of_assurances ($userid)
197
198 Returns the number of assurances the user with the passed userid has given.
199
200 :param int $userid: userid of be controled
201 :return: * (int) - number of given assurances
202
203 .. php:function:: get_number_of_ttpassurances ($userid)
204
205 Returns the number of TTP-assurances the user with the passed userid has received.
206
207 :param int $userid: userid of be controled
208 :return: * (int) - number of received TTP-assurances
209
210 .. php:function:: get_number_of_assurees ($userid)
211
212 Returns the number of assurances the user with the passed userid has received.
213
214 :param int $userid: userid of be controled
215 :return: * (int) - number of received assurances
216
217 .. php:function:: get_top_assurer_position ($no_of_assurances)
218
219 Returns the ranking of an assurer with the passed number of given assurances.
220
221 :param int $no_of_assurances: number of assurances
222 :return: * (int) - position at the list of top assurers
223
224 .. php:function:: get_top_assuree_position ($no_of_assurees)
225
226 Returns the ranking of an assuree with the passed number of received assurances.
227
228 :param int $no_of_assurances: number of assurances
229 :return: * (int) - position at the list of top assurees
230
231 .. php:function:: get_given_assurances($userid, $log=0)
232
233 Get the list of assurances given by the user
234
235 :param int $userid: id of the assurer
236 :param int $log: if set to 1 also includes deleted assurances
237 :return: * (resource) - a MySQL result set
238
239 .. php:function:: get_received_assurances($userid, $log=0)
240
241 Get the list of assurances received by the user
242
243 :param int $userid: id of the assuree
244 :param int $log: if set to 1 also includes deleted assurances
245 :return: * (resource) - a MySQL result set
246
247 .. php:function:: get_given_assurances_summary ($userid)
248
249 Get the count of given assurances of the user with the passed userid grouped by points, awarded, method
250
251 :param int $userid: id of the assurer
252 :return: * (resource) - list of number of given assurances grouped by points, awarded, method
253
254 .. php:function:: get_received_assurances_summary ($userid)
255
256 Get the count of received assurances of the user with the passed userid grouped by points, awarded, method
257
258 :param int $userid: id of the assuree
259 :return: * (resource) - list of number of received assurances grouped by points, awarded, method
260
261 .. php:function:: get_user ($userid)
262
263 Get data of user with the passed userid.
264
265 :param int $userid: id of the user
266 :return: * (resource) - data frum table users belonging to passed userid.
267
268 .. php:function:: get_cats_state ($userid)
269
270 Get the number of passed CATS for the given userid.
271
272 :param int $userid: id of a user
273 :return: * (int) - number of passed CATS
274
275 .. php:function:: calc_awarded($row)
276
277 Calculate awarded points (corrects some issues like out of range points or points that were issued by means that have been deprecated)
278
279 :param array $row: associative array containing the data from the `notary` table
280 :return: * (int) - the awarded points for this assurance
281
282 .. php:function:: calc_experience(&$row, &$sum_points, &$sum_experience)
283
284 Calculate the experience points from a given Assurance.
285
286 :param array $row: [inout] associative array containing the data from the `notary` table, the keys 'experience' and 'calc_awarded' will be added
287 :param int $sum_points: [inout] the sum of already counted assurance points the assurer issued
288 :param int $sum_experience: [inout] the sum of already counted experience points that were awarded to the assurer
289
290 .. php:function:: calc_assurances(&$row, &$sum_points, &$sum_experience)
291
292 Calculate the points received from a received Assurance.
293
294 :param array $row: [inout] associative array containing the data from the `notary` table, the keys 'experience' and 'calc_awarded' will be added
295 :param int $sum_points: [inout] the sum of already counted assurance points the assuree received
296 :param int $sum_experience: [inout] the sum of already counted experience points that were awarded to the assurer
297
298 .. php:function:: show_user_link($user)
299
300 Generate a link to the support engineer page for the user with the name of the user as link text
301
302 :param array $user: associative array containing the data from the `user` table
303 :return: * (string) - name of the user with the passed userid or System or deleted
304
305 .. php:function:: show_email_link($user)
306
307 Generate a link to the support engineer page for the user with the email address as link text
308
309 :param array $user: associative array containing the data from the `user` table
310 :return: * (string) - email-address
311
312 .. php:function:: get_assurer_ranking($userid,&$num_of_assurances,&$rank_of_assurer)
313
314 Getting the number of given assurances and the rank of the user with the passed userid.
315
316 :param int $userid: id of an user
317 :param int $num_of_assurances: [inout] number of given assurances
318 :param int $rank_of_assurer: [inout] rank in assurer-list
319
320 .. php:function:: get_assuree_ranking($userid,&$num_of_assurees,&$rank_of_assuree)
321
322 Getting the number of received assurances and the rank of the user with the passed userid.
323
324 :param int $userid: id of an user
325 :param int $num_of_assurees: [inout] number of received assurances
326 :param int $rank_of_assuree: [inout] rank in assuree-list
327
328 .. php:function:: output_ranking($userid)
329
330 Generating HTML-code for showing the assurer/assuree data
331
332 :param int $userid: userid to build the page format
333
334 .. php:function:: output_assurances_header($title, $support, $log)
335
336 Render header for the assurance table (same for given/received)
337
338 :param string $title: The title for the table
339 :param int $support: set to 1 if the output is for the support interface
340 :param int $log: if set to 1 also includes deleted assurances
341
342 .. php:function:: output_assurances_footer($points_txt,$sumpoints,$experience_txt,$sumexperience,$support,$log)
343
344 Render footer for the assurance table (same for given/received)
345
346 :param string $points_txt: Description for sum of assurance points
347 :param int $sumpoints: sum of assurance points
348 :param string $experience_txt: Description for sum of experience points
349 :param int $sumexperience: sum of experience points
350 :param int $support: set to 1 if the output is for the support interface
351 :param int $log: if set to 1 also includes deleted assurances
352
353 .. php:function:: output_assurances_row($assurance,$userid,$other_user,$support,$ticketno,$log)
354
355 Render an assurance for a view
356
357 :param array $assurance: associative array containing the data from the `notary` table
358 :param int $userid: Id of the user whichs given/received assurances are displayed
359 :param array $other_user: associative array containing the other users data from the `users` table
360 :param int $support: set to 1 if the output is for the support interface
361 :param string $ticketno: ticket number currently set in the support interface
362 :param int $log: if set to 1 also includes deleted assurances
363
364 .. php:function:: output_summary_header()
365
366 Render the header for the summary.
367
368 .. php:function:: output_summary_footer()
369
370 Render the footer for the summary.
371
372 .. php:function:: output_summary_row($title,$points,$points_countable,$remark)
373
374 Render a row of the summary of points
375
376 :param string $title: The description of the row
377 :param inf $points:
378 :param int $points_countable:
379 :param string $remark:
380
381 .. todo:: check points and points_countable
382
383 .. php:function:: output_given_assurances_content($userid,&$sum_points,&$sum_experience,$support,$ticketno,$log)
384
385 Helper function to render assurances given by the user
386
387 :param int $userid: id of a user
388 :param int &$sum_points: [out] sum of given points
389 :param int &$sum_experience: [out] sum of experience points gained
390 :param int $support: set to 1 if the output is for the support interface
391 :param string $ticketno: the ticket number set in the support interface
392 :param int $log: if set to 1 also includes deleted assurances
393
394 .. php:function:: output_received_assurances_content($userid,&$sum_points,&$sum_experience,$support,$ticketno,$log)
395
396 Helper function to render assurances received by the user
397
398 :param int $userid: id of a user
399 :param int& $sum_points: [out] sum of received points
400 :param int& $sum_experience: [out] sum of experience points the assurers gained
401 :param int $support: set to 1 if the output is for the support interface
402 :param string $ticketno: the ticket number set in the support interface
403 :param int $log: if set to 1 also includes deleted assurances
404
405 .. php:function:: check_date_limit ($userid,$age)
406
407 Checks if the user with the passed userid has reached a given age.
408
409 :param int $userid: id of a user
410 :param int $age: the age to be checked against
411 :return: * (int) - 1: if the given age is reached; 0 else
412
413 .. php:function:: max_points($userid)
414
415 Determin, how many points the user can issue at most.
416
417 :param int $userid: id of a user
418 :return: * (int) - max to issue points
419
420 .. php:function:: output_summary_content($userid,$display_output)
421
422 Calculate points and render them for output.
423
424 :param int $userid: id of a user
425 :param int $display_output: flag if to display (1) or not (0)
426 :retur: * (int) - max to issue points
427
428 .. php:function:: output_given_assurances($userid, $support=0, $ticketno='', $log=0)
429
430 Render assurances given by the user
431
432 :param int $userid:
433 :param int $support: set to 1 if the output is for the support interface
434 :param string $ticketno: the ticket number set in the support interface
435 :param int $log: if set to 1 also includes deleted assurances
436
437 .. php:function:: output_received_assurances($userid, $support=0, $ticketno='', $log=0)
438
439 Render assurances received by the user
440
441 :param int $userid:
442 :param int $support: set to 1 if the output is for the support interface
443 :param string $ticketno: the ticket number set in the support interface
444 :param int $log: if set to 1 also includes deleted assurances
445
446 .. php:function:: output_summary($userid)
447
448 Render the page output for a user.
449
450 :param int $userid:
451
452 .. todo:: more documentation from line 833 on
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472 .. sourcefile:: includes/shutdown.php
473
474 .. sourcefile:: includes/sponsorinfo.php
475
476 .. sourcefile:: includes/tverify_stuff.php
477
478
479 .. index:: includes/lib
480 .. index:: PHP
481
482 Directory :file:`includes/lib`
483 ==============================
484
485 .. sourcefile:: includes/lib/account.php
486
487 .. sourcefile:: includes/lib/check_weak_key.php
488
489 .. sourcefile:: includes/lib/general.php
490
491 .. sourcefile:: includes/lib/l10n.php