added global variables into doctree
[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 www/policy/
22 www/index.php?id=47
23 www/logos.php
24 www/stats.php
25 www/index.php?id=7
26 www/src-lic.php
27
28 :file:`about_menu.php` is a part (<div>) of a PHP-Page, containing most of
29 the CAcert-related links.
30 It uses hardcoded links to some CAcert-sites :samp:`http://blog.cacert.org`, :samp:`http://wiki.CAcert.org/`, :samp:`http://wiki.cacert.org/FAQ/Privileges`, :samp:`http://blog.CAcert.org/feed/`, :samp:`http://wiki.cacert.org/Board`, :samp:`https://lists.cacert.org/wws`
31
32 .. sourcefile:: includes/account_stuff.php
33
34 :file:`includes/account_stuff.php` provides two procedures to be used for building the output of some HTML-pages.
35
36 .. php:function:: showheader($title = "CAcert.org", $title2 = "")
37
38 This function renders a page depending on the calling file. It is expected that only files
39
40 www/wot.php (web-of-trust),
41
42 www/gpg.php (gpg-key),
43
44 www/disputes.php (disputes) and
45
46 www/advertising.php (advertising)
47
48 are using this function.
49
50 :param string $title:
51 :param string $title2:
52 :global: * *(int)* - $id:
53 :global: * *(string)* - $PHP_SELF:
54
55 .. php:function:: showfooter()
56
57 This function renders a page-footer.
58
59
60 .. sourcefile:: includes/account.php
61 :uses:
62 includes/loggedin.php
63 includes/lib/l10n.php
64 includes/lib/check_weak_key.php
65 includes/notary.inc.php
66
67 :file:`includes/account.php` first loads some more includefiles via :php:func:`loadem`. It defines two functions and read the global variables
68 :php:global:`$_REQUEST['id']`,
69 :php:global:`$_REQUEST['oldid']`,
70 :php:global:`$_REQUEST['process']`,
71 :php:global:`$_REQUEST['showdetails']`,
72 :php:global:`$_REQUEST['cert']`,
73 :php:global:`$_REQUEST['orgid']`,
74 :php:global:`$_REQUEST['memid']`,
75 :php:global:`$_REQUEST['domid']`,
76 :php:global:`$_REQUEST['action']`,
77 :php:global:`$_REQUEST['ticketno']`,
78 :php:global:`$_SESSION['mconn']`
79
80 .. php:function:: buildSubject(array $domains, $include_xmpp_addr = true)
81
82 Build a subject string as needed by the signer.
83 This function uses
84 :php:func:`account_domain_delete`,
85 :php:func:`account_email_delete`,
86 :php:func:`buildSubjectFromSession`,
87 :php:func:`check_client_cert_running`,
88 :php:func:`check_gpg_cert_running`,
89 :php:func:`check_is_orgadmin`,
90 :php:func:`check_server_cert_running`,
91 :php:func:`checkEmail`,
92 :php:func:`checkpw`,
93 :php:func:`checkWeakKeyCSR`,
94 :php:func:`checkWeakKeySPKAC`,
95 :php:func:`checkWeakKeyX509`,
96 :php:func:`clean_csr`,
97 :php:meth:`HashAlgorithms::clean`,
98 :php:func:`csrf_check`,
99 :php:func:`extractit`,
100 :php:func:`generatecertpath`,
101 :php:meth:`L10n::get_translation`,
102 :php:func:`getalt`,
103 :php:func:`getalt2`,
104 :php:func:`getcn`,
105 :php:func:`getcn2`,
106 :php:func:`make_hash`,
107 :php:func:`revoke_all_private_cert`,
108 :php:func:`runCommand`,
109 :php:func:`sanitizeHTML`,
110 :php:func:`sendmail`,
111 :php:meth:`L10n::set_recipient_language`,
112 :php:meth:`L10n::set_translation`,
113 :php:func:`showheader`,
114 :php:func:`showfooter`,
115 :php:attr:`L10n::$translations`,
116 :php:func:`valid_ticket_number`,
117 :php:func:`waitForResult`,
118 :php:func:`write_se_log`,
119 :php:func:`write_user_agreement`
120
121
122 :param array(string) $domains: First domain is used as CN and repeated in subjectAltName. Duplicates should already been removed
123 :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
124 :return: * (string) - subject string as needed by the signer
125
126 .. php:function:: buildSubjectFromSession()
127
128 Builds the subject string from the session variables $_SESSION['_config']['rows'] and $_SESSION['_config']['altrows']
129
130 :return: * (string) -
131
132
133 .. sourcefile:: includes/general_stuff.php
134 :uses:
135 /includes/lib/l10n.php
136
137 This process uses
138 :php:func:`showbodycontent`,
139 :php:func:`showfooter`,
140 :php:func:`showheader`
141
142 .. php:function:: showbodycontent($title = "CAcert.org", $title2 = "")
143
144
145
146
147
148 .. sourcefile:: includes/general.php
149
150 .. php:function:: loadem
151
152 .. sourcefile:: includes/keygen.php
153
154 .. sourcefile:: includes/loggedin.php
155 :uses:
156 includes/lib/general.php
157 SOME__get_user_id_from_cert
158 includes/lib/l10n.php
159 SOME__L10n::get_translation
160 SOME__L10n::set_translation
161 SOME__L10n::init_gettext
162 includes/mysql.php
163 includes/notary.inc.php
164 SOME__get_user_agreement_status
165
166
167 .. todo:: analyze the module
168
169
170
171
172 .. sourcefile:: includes/mysql.php
173
174 :file:`includes/mysql.php` is not contained in the :cacertgit:`cacert-devel`
175 repository but is used by several other files. The file is copied from
176 :sourcefile:`includes/mysql.php.sample` and defines the database connection
177 information.
178
179 This file is parsed directly by :sourcefile:`CommModule/client.pl`
180 format changes might break the CommModule code.
181
182 .. sourcefile:: includes/mysql.php.sample
183
184 :file:`mysql.php.sample` is a template for the database connection handling
185 code that is meant to be copied to :file:`mysql.php`.
186
187 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
188 :php:global:`$_SESSION['_config']['normalhostname']`, :php:global:`$_SESSION['_config']['securehostname']` and :php:global:`$_SESSION['_config']['tverify']`.
189
190 .. php:global:: $_SESSION['mconn']
191
192 This global variable defines the status of the database connection
193
194 * TRUE if a connection could be established
195 * FALSE otherwise
196
197 .. php:global:: $_SESSION['_config']['normalhostname']
198
199 This global variable defines the main CAcert-website
200
201 * "www.cacert.org" for production
202 * "test.cacert.org" for testing
203
204 .. php:global:: $_SESSION['_config']['securehostname']
205
206 This global variable defines the secure CAcert-website
207
208 * "secure.cacert.org" for production
209 * " cacert.org" for testing
210
211 .. php:global:: $_SESSION['_config']['tverify']
212
213 This global variable defines TVERIFY
214
215 * "tverify.cacert.org" for production
216 * " " for testing
217
218 .. todo:: checkout what TVERIFY means, check names for test-system
219
220
221
222
223
224 The template defines a function :php:func:`sendmail` for sending mails.
225
226 .. php:function:: sendmail($to, $subject, $message, $from, $replyto="", \
227 $toname="", $fromname="", $errorsto="returns@cacert.org", \
228 $use_utf8=true)
229
230 Send an email. The function reimplements functionality that is readily
231 available in PHP. The function does not properly escape headers and
232 sends raw SMTP commands.
233
234 :param string $to: recipient email address
235 :param string $subject: subject
236 :param string $message: email body
237 :param string $from: from email address
238 :param string $replyto: reply-to email address
239 :param string $fromname: unused in the code
240 :param string $toname: unused in the code
241 :param string $errorsto: email address used for Sender and Errors-To
242 headers
243 :param bool $use_utf8: decides whether the Content-Type header uses
244 a charset parameter of utf-8 or iso-8859-1
245
246 Configuration and actual code are mixed. It would be better to have a
247 separate file that just includes configuration.
248
249 .. sourcefile:: includes/notary.inc.php
250
251 :file:`includes/notary.inc.php` provides a set of funktions; here listed in the given order:
252
253 .. php:function:: query_init ($query)
254
255 Accesss the database to execute the passed query.
256
257 :param string $query: query to execute
258 :return: * (resource) - result of the passed query.
259
260 .. php:function:: query_getnextrow ($res)
261
262 Return the next row of a previous received result of a database query.
263
264 :param resource $res: Result of a previous database query.
265 :return: * (object) - next row in the passed resource
266
267 .. php:function:: query_get_number_of_rows ($resultset)
268
269 Return the number of rows of the passed $resource which has to be the result of a previous database query, select-statement
270
271 :param resource $resultset: Result of a previous database query
272 :return: * (int) - number of rows in the passed resource
273
274 .. php:function:: get_number_of_assurances ($userid)
275
276 Returns the number of assurances the user with the passed userid has given. Uses :php:func:`query_init` and :php:func:`query_getnextrow`.
277
278 :param int $userid: userid of be controled
279 :return: * (int) - number of given assurances
280
281 .. php:function:: get_number_of_ttpassurances ($userid)
282
283 Returns the number of TTP-assurances the user with the passed userid has received. Uses :php:func:`query_init` and :php:func:`query_getnextrow`.
284
285 :param int $userid: userid of be controled
286 :return: * (int) - number of received TTP-assurances
287
288 .. php:function:: get_number_of_assurees ($userid)
289
290 Returns the number of assurances the user with the passed userid has received. Uses :php:func:`query_init` and :php:func:`query_getnextrow`.
291
292 :param int $userid: userid of be controled
293 :return: * (int) - number of received assurances
294
295 .. php:function:: get_top_assurer_position ($no_of_assurances)
296
297 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`.
298
299 :param int $no_of_assurances: number of assurances
300 :return: * (int) - position at the list of top assurers
301
302 .. php:function:: get_top_assuree_position ($no_of_assurees)
303
304 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`.
305
306 :param int $no_of_assurances: number of assurances
307 :return: * (int) - position at the list of top assurees
308
309 .. php:function:: get_given_assurances($userid, $log=0)
310
311 Get the list of assurances given by the user. Uses :php:func:`query_init`.
312
313 :param int $userid: id of the assurer
314 :param int $log: if set to 1 also includes deleted assurances
315 :return: * (resource) - a MySQL result set
316
317 .. php:function:: get_received_assurances($userid, $log=0)
318
319 Get the list of assurances received by the user. Uses :php:func:`query_init`.
320
321 :param int $userid: id of the assuree
322 :param int $log: if set to 1 also includes deleted assurances
323 :return: * (resource) - a MySQL result set
324
325 .. php:function:: get_given_assurances_summary ($userid)
326
327 Get the count of given assurances of the user with the passed userid grouped by points, awarded, method. Uses :php:func:`query_init`.
328
329 :param int $userid: id of the assurer
330 :return: * (resource) - list of number of given assurances grouped by points, awarded, method
331
332 .. php:function:: get_received_assurances_summary ($userid)
333
334 Get the count of received assurances of the user with the passed userid grouped by points, awarded, method. Uses :php:func:`query_init`.
335
336 :param int $userid: id of the assuree
337 :return: * (resource) - list of number of received assurances grouped by points, awarded, method
338
339 .. php:function:: get_user ($userid)
340
341 Get data of user with the passed userid. Uses :php:func:`query_init`.
342
343 :param int $userid: id of the user
344 :return: * (resource) - data frum table users belonging to passed userid.
345
346 .. php:function:: get_cats_state ($userid)
347
348 Get the number of passed CATS for the given userid. Uses :php:func:`query_init`.
349
350 :param int $userid: id of a user
351 :return: * (int) - number of passed CATS
352
353 .. php:function:: calc_awarded($row)
354
355 Calculate awarded points (corrects some issues like out of range points or points that were issued by means that have been deprecated)
356
357 :param array $row: associative array containing the data from the `notary` table
358 :return: * (int) - the awarded points for this assurance
359
360 .. php:function:: calc_experience(&$row, &$sum_points, &$sum_experience)
361
362 Calculate the experience points from a given Assurance. Uses :php:func:`calc_awarded`.
363
364 :param array $row: [inout] associative array containing the data from the `notary` table, the keys 'experience' and 'calc_awarded' will be added
365 :param int $sum_points: [inout] the sum of already counted assurance points the assurer issued
366 :param int $sum_experience: [inout] the sum of already counted experience points that were awarded to the assurer
367
368 .. php:function:: calc_assurances(&$row, &$sum_points, &$sum_experience)
369
370 Calculate the points received from a received Assurance. Uses :php:func:`calc_awarded`.
371
372 :param array $row: [inout] associative array containing the data from the `notary` table, the keys 'experience' and 'calc_awarded' will be added
373 :param int $sum_points: [inout] the sum of already counted assurance points the assuree received
374 :param int $sum_experience: [inout] the sum of already counted experience points that were awarded to the assurer
375
376 .. php:function:: show_user_link($user)
377
378 Generate a link to the support engineer page for the user with the name of the user as link text. Uses :php:func:`sanitizeHTML`.
379
380 :param array $user: associative array containing the data from the `user` table
381 :return: * (string) - name of the user with the passed userid or System or deleted
382
383 .. php:function:: show_email_link($user)
384
385 Generate a link to the support engineer page for the user with the email address as link text. Uses :php:func:`sanitizeHTML`.
386
387 :param array $user: associative array containing the data from the `user` table
388 :return: * (string) - email-address
389
390 .. php:function:: get_assurer_ranking($userid,&$num_of_assurances,&$rank_of_assurer)
391
392 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`.
393
394 :param int $userid: id of an user
395 :param int $num_of_assurances: [inout] number of given assurances
396 :param int $rank_of_assurer: [inout] rank in assurer-list
397
398 .. php:function:: get_assuree_ranking($userid,&$num_of_assurees,&$rank_of_assuree)
399
400 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`.
401
402 :param int $userid: id of an user
403 :param int $num_of_assurees: [inout] number of received assurances
404 :param int $rank_of_assuree: [inout] rank in assuree-list
405
406 .. php:function:: output_ranking($userid)
407
408 Generating HTML-code for showing the assurer/assuree data. Uses :php:func:`get_assurer_ranking` and :php:func:`get_assuree_ranking`.
409
410 :param int $userid: userid to build the page format
411
412 .. php:function:: output_assurances_header($title, $support, $log)
413
414 Render header for the assurance table (same for given/received)
415
416 :param string $title: The title for the table
417 :param int $support: set to 1 if the output is for the support interface
418 :param int $log: if set to 1 also includes deleted assurances
419
420 .. php:function:: output_assurances_footer($points_txt,$sumpoints,$experience_txt,$sumexperience,$support,$log)
421
422 Render footer for the assurance table (same for given/received)
423
424 :param string $points_txt: Description for sum of assurance points
425 :param int $sumpoints: sum of assurance points
426 :param string $experience_txt: Description for sum of experience points
427 :param int $sumexperience: sum of experience points
428 :param int $support: set to 1 if the output is for the support interface
429 :param int $log: if set to 1 also includes deleted assurances
430
431 .. php:function:: output_assurances_row($assurance,$userid,$other_user,$support,$ticketno,$log)
432
433 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`.
434
435 :param array $assurance: associative array containing the data from the `notary` table
436 :param int $userid: Id of the user whichs given/received assurances are displayed
437 :param array $other_user: associative array containing the other users data from the `users` table
438 :param int $support: set to 1 if the output is for the support interface
439 :param string $ticketno: ticket number currently set in the support interface
440 :param int $log: if set to 1 also includes deleted assurances
441
442 .. php:function:: output_summary_header()
443
444 Render the header for the summary.
445
446 .. php:function:: output_summary_footer()
447
448 Render the footer for the summary.
449
450 .. php:function:: output_summary_row($title,$points,$points_countable,$remark)
451
452 Render a row of the summary of points
453
454 :param string $title: The description of the row
455 :param inf $points:
456 :param int $points_countable:
457 :param string $remark:
458
459 .. todo:: check points and points_countable
460
461 .. php:function:: output_given_assurances_content($userid,&$sum_points,&$sum_experience,$support,$ticketno,$log)
462
463 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`.
464
465 :param int $userid: id of a user
466 :param int &$sum_points: [out] sum of given points
467 :param int &$sum_experience: [out] sum of experience points gained
468 :param int $support: set to 1 if the output is for the support interface
469 :param string $ticketno: the ticket number set in the support interface
470 :param int $log: if set to 1 also includes deleted assurances
471
472 .. php:function:: output_received_assurances_content($userid,&$sum_points,&$sum_experience,$support,$ticketno,$log)
473
474 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`.
475
476 :param int $userid: id of a user
477 :param int& $sum_points: [out] sum of received points
478 :param int& $sum_experience: [out] sum of experience points the assurers gained
479 :param int $support: set to 1 if the output is for the support interface
480 :param string $ticketno: the ticket number set in the support interface
481 :param int $log: if set to 1 also includes deleted assurances
482
483 .. php:function:: check_date_limit ($userid,$age)
484
485 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`.
486
487 :param int $userid: id of a user
488 :param int $age: the age to be checked against
489 :return: * (int) - 1: if the given age is reached; 0 else
490
491 .. php:function:: max_points($userid)
492
493 Determin, how many points the user can issue at most. Uses :php:func:`output_summary_content`.
494
495 :param int $userid: id of a user
496 :return: * (int) - max to issue points
497
498 .. php:function:: output_summary_content($userid,$display_output)
499
500 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`.
501
502 :param int $userid: id of a user
503 :param int $display_output: flag if to display (1) or not (0)
504 :retur: * (int) - max to issue points
505
506 .. php:function:: output_given_assurances($userid, $support=0, $ticketno='', $log=0)
507
508 Render assurances given by the user. Uses :php:func:`output_assurances_header`, :php:func:`output_given_assurances_content`, :php:func:`output_assurances_footer`.
509
510 :param int $userid: id of a user
511 :param int $support: set to 1 if the output is for the support interface
512 :param string $ticketno: the ticket number set in the support interface
513 :param int $log: if set to 1 also includes deleted assurances
514
515 .. php:function:: output_received_assurances($userid, $support=0, $ticketno='', $log=0)
516
517 Render assurances received by the user. Uses :php:func:`output_assurances_header`, :php:func:`output_received_assurances_content`, :php:func:`output_assurances_footer`.
518
519 :param int $userid: id of a user
520 :param int $support: set to 1 if the output is for the support interface
521 :param string $ticketno: the ticket number set in the support interface
522 :param int $log: if set to 1 also includes deleted assurances
523
524 .. php:function:: output_summary($userid)
525
526 Render the page output for a user. Uses :php:func:`output_summary_header`, :php:func:`output_summary_content`, :php:func:`output_summary_footer`.
527
528 :param int $userid: id of a user
529
530 .. php:function:: output_end_of_page()
531
532 Adds a goBack-button to the page.
533
534 .. php:function:: write_user_agreement($memid, $document, $method, $comment, $active=1, $secmemid=0)
535
536 Writes a new record to the table user_agreement.
537
538 :param mixed $memid: id of a user
539 :param mixed $document:
540 :param mixed $method:
541 :param mixed $comment:
542 :param integer $active:
543 :param integer $secmemid:
544 :return:
545
546 .. php:function:: get_user_agreement_status($memid, $type="CCA")
547
548 Returns 1 if the user has an entry for the given type in user_agreement, 0 if no entry is recorded
549
550 :param mixed $memid: userid
551 :param string $type: "CCA"
552 :return: * (int) - 1 if the user has an entry for the given type in user_agreement, 0 if no entry is recorded
553
554 .. php:function:: get_first_user_agreement($memid, $type=null, $active=null)
555
556 Get the first user_agreement entry of the requested type
557
558 :param int $memid:
559 :param string $type: the type of user agreement, by default all agreements are listed
560 :param int $active: whether to get active or passive agreements:
561
562 * 0 := passive
563 * 1 := active
564 * null := both
565
566 :return: * (array(string=>mixed)) - an associative array containing 'document', 'date', 'method', 'comment', 'active'.
567
568 .. php:function:: get_last_user_agreement($memid, $type=null, $active=null)
569
570 Get the last user_agreement entry of the requested type
571
572 :param int $memid:
573 :param string $type: the type of user agreement, by default all agreements are listed
574 :param int $active: whether to get active or passive agreements:
575
576 * 0 := passive
577 * 1 := active
578 * null := both
579
580 :return: * (array(string=>mixed)) - an associative array containing 'document', 'date', 'method', 'comment', 'active'.
581
582 .. php:function:: get_user_agreements($memid, $type=null, $active=null)
583
584 Get all user_agreement entrys of the requested type
585
586 :param int $memid:
587 :param string $type: the type of user agreement, by default all agreements are listed
588 :param int $active: whether to get active or passive agreements:
589
590 * 0 := passive
591 * 1 := active
592 * null := both
593
594 :return: * (resource) - a mysql result set containing all agreements
595
596 .. php:function:: delete_user_agreement($memid, $type=false)
597
598 Deletes all entries for a given type from user_agreement of a given user, if type is not given, delete all all
599
600 :param mixed $memid: Member-id
601 :param string $type: the type of user agreement ; if false all
602
603 .. :php:function:: AssureHead($confirmation,$checkname)
604
605 Render the header for assurance-page /pages/wot/6.php
606
607 :param string $confirmation: text of title
608 :param string $checkname: textline including then ame of the person to be assured
609
610 .. php:function:: AssureTextLine($field1,$field2)
611
612 Prepares a text line for assurance-page /pages/wot/6.php; two cells in a row
613
614 :param string $field1: text string
615 :param string $field2: text string
616
617 .. php:function:: AssureBoxLine($type,$text,$checked)
618
619 Prepares a box line for assurance-page /pages/wot/6.php; two cells in a row, a checkbox with stats and a text
620
621 :param string $type: type/name of checkbox
622 :param string $text: text to present
623 :param string $checked: status of the ceckbox
624
625 .. php:function:: AssureMethodLine($text,$methods,$remark)
626
627 Prepares another row for assurance-page /pages/wot/6.php containing the methods of the assurance
628
629 :param string $text$: text
630 :param array(string) $methods: possible methods of assurance
631 :param string $remark: a possible remark to the assurance
632
633 .. php:function:: AssureInboxLine($type,$field,$value,$description)
634
635 Prepare an inBox line.
636
637 :param string $type: name of the information shown in line
638 :param string $field: readable name of the information of the line
639 :param string $value: value of the information
640 :param string $description: description/remarks to displayed the information
641
642 .. php:function:: AssureFoot($oldid,$confirm)
643
644 Prepares the footer of the assurance page /pages/wot/6.php.
645
646 :param int $oldid: field to hide containing the actual id of the dialog
647 :param string $confirm: text for confirmation
648
649 .. php:function:: account_email_delete($mailid)
650
651 Deletes an email entry from an acount, revolkes all certifcates for that email address. Uses :php:func:`revoke_all_client_cert`.
652
653 :param int $mailid: Id of the email address to be deleted
654
655 .. php:function:: account_domain_delete($domainid)
656
657 Deletes an domain entry from an acount, revolkes all certifcates for that domain address. Uses :php:func:`revoke_all_server_cert`.
658
659 :param int $domainid: Id of the domain to be deleted
660
661 .. php:function:: account_delete($id, $arbno, $adminid)
662
663 Deletes an account following the deleted account routnie V3 and change password (arbitration). Uses :php:func:`account_email_delete`, :php:func:`account_domain_delete`,
664
665 :param int $id: Id of the account to be deleted
666 :param string $arbno: Arbitrationnumber that justifies the deletion.
667 :param int $adminid: ID of the administrator who fullfilled the deletion
668
669 .. php:function:: check_email_exists($email)
670
671 Checks if an email address exists.
672
673 :param string $email: Email address to be checked
674 :returns: * (bool): true if email exists; else false
675
676 .. php:function:: check_gpg_cert_running($uid,$cca=0)
677
678 Checks if a non-expired gpg certificatation exists.
679
680 :param int $uid: account ID to be checked for gpg certification
681 :param int $cca: 0 if just expired, =1 if CCA retention +3 month should be obeyed
682 :returns: * (bool) - true if a gpg certification exists; else false
683
684 .. php:function:: check_client_cert_running($uid,$cca=0)
685
686 Checks if a non-expired, non-revoked client certificate exists for an account.
687
688 :param int $uid: account ID to be checked for client certificates
689 :param int $cca: 0 if just expired, =1 if CCA retention +3 month should be obeyed
690 :returns: * (bool) - true if a client certificate exists; else false
691
692 .. php:function:: check_server_cert_running($uid,$cca=0)
693
694 Checks if a non-expired, non-revoked server certificate exists for an account.
695
696 :param int $uid: account ID to be checked for server certificates
697 :param int $cca: 0 if just expired, =1 if CCA retention +3 month should be obeyed
698 :returns: * (bool) - true if a server certificate exists; else false
699
700 .. php:function:: check_is_orgadmin($uid)
701
702 Checks if a given account is an organisation administrator.
703
704 :param int $uid: account ID to be checked as organisation administrator
705 :returns: * (bool) - true if the account belongs to an organisation administrator; else false
706
707 .. php:function:: revoke_all_client_cert($mailid)
708
709 Revokes all client certificates for a given email address.
710
711 :param int $mailid: ID of an email address.
712
713 .. php:function:: function revoke_all_server_cert($domainid)
714
715 Revokes all server certs for an domain.
716
717 :param int $domainid: ID of an domain.
718
719 .. php:function:: revoke_all_private_cert($uid)
720
721 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`.
722
723 :param int $uid: ID of the account whos certificates have to be rovoked
724
725 .. php:function:: check_date_format($date, $year=2000)
726
727 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
728
729 :param mixed $date: Date to check
730 :param integer $year: Year to check against
731 :returns: * (bool) - true if date is valid; false if not
732
733 .. php:function:: check_date_difference($date, $diff=1)
734
735 Checks if the given date is less or equal then today plus a given time difference
736
737 :param mixed $date: Date to be checked
738 :param integer $diff: difference in days (positive future, negative past) to add to the current date
739 :returns: * (bool) - returns false if the date is larger then today + time difference
740
741 .. php:function:: write_se_log($uid, $adminid, $type, $info)
742
743 Records all support engineer actions changing a user account writing the information to the adminlog.
744
745 :param int $uid: id of the user account
746 :param int $adminid: id of the admin
747 :param string $type: the operation that was performed on the user account
748 :param string $info: the ticket / arbitration number or other information
749 :returns: * (bool) - true := success, false := error
750
751 .. php:function:: valid_ticket_number($ticketno)
752
753 Check if the entered information is a valid ticket or arbitration number.
754
755 :param string $ticketno:
756 :returns: * (bool) -
757
758 .. php:function:: get_user_data($userid, $deleted=0)
759
760 Get all data of an account given by the id from the `users` table (function for handling account/43.php)
761
762 :param int $userid: account id
763 :param int $deleted: states if deleted data should be visible , default = 0 - not visible
764 :returns: * (resource) - a mysql result set
765
766 .. php:function:: get_alerts($userid)
767
768 Get the alert settings for a user (function for handling account/43.php)
769
770 :param int $userid: for the requested account
771 :returns: * (array) - associative array
772
773 .. php:function:: get_email_addresses($userid, $exclude, $deleted=0)
774
775 Get all email addresses linked to the account (should be entered in account/2.php)
776
777 :param int $userid:
778 :param string $exclude: if given the email address will be excluded
779 :param int $deleted: states if deleted data should be visible, default = 0 - not visible
780 :returns: * (resource) - a mysql result set
781
782 .. php:function:: get_domains($userid, $deleted=0)
783
784 Get all domains linked to the account (should be entered in account/9.php).
785
786 :param int $userid:
787 :param int $deleted: states if deleted data should be visible, default = 0 - not visible
788 :returns: * (resource) - a mysql result set
789
790 .. php:function:: get_training_results($userid)
791
792 Get all training results for the account (should be entered in account/55.php)
793
794 :param int $userid:
795 :returns: * (resource) - a mysql result set
796
797 .. php:function:: get_se_log($userid)
798
799 Get all SE log entries for the account
800
801 :param int $userid:
802 :returns: * (resource) - a mysql result set
803
804 .. php:function:: get_client_certs($userid, $viewall=0)
805
806 Get all client certificates linked to the account (add to account/5.php)
807
808 :param int $userid:
809 :param int $viewall: states if expired certs should be visible, default = 0 - not visible
810 :returns: * (resource) - a mysql result set
811
812 .. php:function:: get_server_certs($userid, $viewall=0)
813
814 Get all server certs linked to the account (add to account/12.php)
815
816 :param int $userid:
817 :param int $viewall: states if expired certs should be visible, default = 0 - not visible
818 :returns: * (resource - a mysql result set)
819
820 .. php:function:: get_gpg_certs($userid, $viewall=0)
821
822 Get all gpg certs linked to the account (add to gpg/2.php)
823
824 :param int $userid:
825 :param int $viewall: states if expired certs should be visible, default = 0 - not visible
826 :returns: * (resource) - a mysql result set
827
828 .. php:function:: output_log_email_header()
829
830 Show the table header to the email table for the admin log
831
832 .. php:function:: output_log_email($row, $primary)
833
834 Show all email data for the admin log
835
836 :param array $row: associative array containing the column data
837 :param string $primary: if given the primary address is highlighted
838
839 .. php:function:: output_log_domains_header()
840
841 Show the table header to the domains table for the admin log.
842
843 .. php:function:: output_log_domains($row)
844
845 Show the domain data for the admin log
846
847 :param array $row: associative array containing the column data
848
849 .. php:function:: output_log_agreement_header()
850
851 Show the table header to the user agreement table for the admin log.
852
853 .. php:function:: output_log_agreement($row)
854
855 Show the agreement data for the admin log.
856
857 :param array $row: associative array containing the column data
858
859 .. php:function:: output_log_training_header()
860
861 Show the table header to the training table (should be entered in account/55.php).
862
863 .. php:function:: output_log_training($row)
864
865 Show the training data (should be entered in account/55.php).
866
867 :param array $row: associative array containing the column data
868
869 .. php:function:: output_log_se_header($support=0)
870
871 Show the table header to the SE log table for the admin log.
872
873 :param int $support: if support = 1 more information is visible
874
875 .. php:function:: output_log_se($row, $support=0)
876
877 Show the SE log data for the admin log (should be entered in account/55.php)
878
879 :param array $row: associative array containing the column data
880 :param int $support: if support = 1 more information is visible
881
882 .. php:function:: output_client_cert_header($support=0, $readonly=true)
883
884 Shows the table header to the client cert table (should be added to account/5.php)
885
886 :param int $support: if support = 1 some columns ar not visible
887 :param bool $readonly: whether elements to modify data should be hidden, default is `true`
888
889 .. php:function:: output_client_cert($row, $support=0, $readonly=true)
890
891 Show the client cert data (should be entered in account/5.php)
892
893 :param array $row: associative array containing the column data
894 :param int $support: if support = 1 some columns are not visible
895 :param bool $readonly: whether elements to modify data should be hidden, default is `true`
896
897 .. php:function:: output_server_certs_header($support=0, $readonly=true)
898
899 Show the table header to the server cert table (should be entered in account/12.php)
900
901 :param int $support: if support = 1 some columns ar not visible
902 :param bool $readonly: whether elements to modify data should be hidden, default is `true`
903
904 .. php:function:: output_server_certs($row, $support=0, $readonly=true)
905
906 Show the server cert data (should be entered in account/12.php)
907
908 :param array $row: associative array containing the column data
909 :param int $support: if support = 1 some columns are not visible
910 :param bool $readonly: whether elements to modify data should be hidden, default is `true`
911
912 .. php:function:: output_gpg_certs_header($support=0, $readonly=true)
913
914 Show the table header to the gpg cert table.
915
916 :param int $support: if support = 1 some columns ar not visible
917 :param bool $readonly: whether elements to modify data should be hidden, default is `true` ($readonly is currently ignored but kept for consistency)
918
919 .. php:function:: output_gpg_certs($row, $support=0, $readonly=true)
920
921 Show the gpg cert data (should be entered in account/55.php)
922
923 :param array $row: associative array containing the column data
924 :param int $support: if support = 1 some columns are not visible
925 :param bool $readonly: whether elements to modify data should be hidden, default is `true`
926
927 .. sourcefile:: includes/shutdown.php
928
929 .. sourcefile:: includes/sponsorinfo.php
930
931 .. sourcefile:: includes/tverify_stuff.php
932
933
934 .. index:: includes/lib
935 .. index:: PHP
936
937 Directory :file:`includes/lib`
938 ==============================
939
940 .. sourcefile:: includes/lib/account.php
941
942 :file:`include/lib/account.php` defines a function and a class for use by other precedures.
943
944 .. php:function:: fix_assurer_flag($userID = NULL)
945
946 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.
947
948 :param int $userID: if the user ID is not given the flag will be recalculated for all users
949 :returns: * (bool) - false if there was an error on fixing the flag. This does NOT return the new value of the flag
950
951 .. php:class:: HashAlgorithms
952
953 Supported hash algorithms for signing certificates.
954
955 .. php:attr:: $default
956
957 Default hash algorithm identifier for signing
958
959 .. php:staticmethod:: getInfo()
960
961 Get display strings for the supported hash algorithms.
962
963 :returns: * (array(string=>array('name'=>string, 'info'=>string)))
964
965 #. [$hash_identifier]['name'] = Name that should be displayed in UI
966 #. [$hash_identifier]['info'] = Additional information that can help with the selection of a suitable algorithm
967
968 .. php:staticmethod:: clean($hash_identifier)
969
970 Check if the input is a supported hash algorithm identifier otherwise return the identifier of the default hash algorithm
971
972 :param string $hash_identifier:
973 :returns: * (string) - The cleaned identifier
974
975 .. sourcefile:: includes/lib/check_weak_key.php
976
977 :uses:
978 includes/lib/general.php
979
980 :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.
981
982 .. php:function:: checkWeakKeyCSR($csr, $encoding = "PEM")
983
984 Checks whether the given CSR contains a vulnerable key.
985 This function uses:
986 :php:func:`checkWeakKeyText`,
987 :php:func:`failWithId`,
988 :php:func:`runCommand`
989
990 :param string $csr: The CSR to be checked
991 :param string [optional] $encoding: The encoding the CSR is in (for the "-inform" parameter of OpenSSL, currently only "PEM" (default) or "DER" allowed)
992 :returns: * (string) - containing the reason if the key is considered weak, empty string otherwise
993
994 .. php:function:: checkWeakKeyX509($cert, $encoding = "PEM")
995
996 Checks whether the given X509 certificate contains a vulnerable key.
997 This function uses:
998 :php:func:`checkWeakKeyText`,
999 :php:func:`failWithId`,
1000 :php:func:`runCommand`
1001
1002 :param string $cert: The X509 certificate to be checked
1003 :param string [optional] $encoding: The encoding the certificate is in (for the "-inform" parameter of OpenSSL, currently only "PEM" (default), "DER" or "NET" allowed)
1004 :returns: * (string) - String containing the reason if the key is considered weak, empty string otherwise
1005
1006 .. php:function:: checkWeakKeySPKAC($spkac, $spkacname = "SPKAC")
1007
1008 Checks whether the given SPKAC certificate contains a vulnerable key.
1009 This function uses:
1010 :php:func:`checkWeakKeyText`,
1011 :php:func:`failWithId`,
1012 :php:func:`runCommand`
1013
1014 :param string $spkac: The SPKAC to be checked
1015 :param string [optional] $spkacname: The name of the variable that contains the SPKAC. The default is "SPKAC"
1016 :returns: * (string) - String containing the reason if the key is considered weak, empty string otherwise
1017
1018 .. php:function:: checkWeakKeyText($text)
1019
1020 Checks whether the given text representation of a CSR or a SPKAC contains a weak key.
1021 This function uses:
1022 :php:func:`checkDebianVulnerability`,
1023 :php:func:`failWithId`,
1024 :php:func:`runCommand`
1025
1026 :param string $text: The text representation of a key as output by the "openssl <foo> -text -noout" commands
1027 :returns: * (string) - String containing the reason if the key is considered weak, empty string otherwise
1028
1029 .. php:function:: checkDebianVulnerability($text, $keysize = 0)
1030
1031 Reimplement the functionality of the openssl-vulnkey tool
1032
1033 :param string $text: The text representation of a key as output by the "openssl <foo> -text -noout" commands
1034 :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.
1035 :returns: * (mixed) - TRUE if key is vulnerable, FALSE otherwise, NULL in case of error
1036
1037 .. sourcefile:: includes/lib/general.php
1038
1039 :file:`includes/lib/general.php` provides the system with four functions.
1040
1041 .. php:function:: get_user_id_from_cert($serial, $issuer_cn)
1042
1043 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']
1044
1045 :param string $serial: usually $_SERVER['SSL_CLIENT_M_SERIAL']
1046 :param string $issuer_cn: usually $_SERVER['SSL_CLIENT_I_DN_CN']
1047 :return: * (int) - the user id, -1 in case of error
1048
1049 .. php:function:: failWithId($errormessage)
1050
1051 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
1052
1053 :param $errormessage string: The error message that should be logged
1054 :return: * (string) - containing the generated ID that can be displayed to the user
1055
1056 .. php:function:: runCommand($command, $input = "", &$output = null, &$errors = true)
1057
1058 Runs a command on the shell and return it's exit code and output
1059
1060 :param string $command: The command to run. Make sure that you escapeshellarg() any non-constant parts as this is executed on a shell!
1061 :param string|bool $input: The input that is passed to the command via STDIN, if true the real STDIN is passed through
1062 :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
1063 :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
1064 :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)
1065
1066 .. php:function:: get_assurer_status($userID)
1067
1068 Determine if the user with the passed userid is an assurer.
1069
1070 :param int $userid: id of the user to be checked.
1071 :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.
1072
1073
1074 .. sourcefile:: includes/lib/l10n.php
1075
1076 :file:`includes/lib/l10n.php` defines the class L10n. Some methods use and manipulate the global variables:
1077
1078 .. php:global:: $_SESSION['_config']['language']
1079
1080 .. php:global:: $_SESSION['_config']['recode']
1081
1082 .. php:class:: L10n
1083
1084 .. php:attr:: $translations
1085
1086 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".
1087
1088 .. php:attr:: $locales
1089
1090 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".
1091
1092 .. php:staticmethod:: detect_language()
1093
1094 It auto-detects the language that should be used and sets it. Only works for HTTP, not in a command line script. Priority:
1095
1096 #. explicit parameter "lang" passed in HTTP (e.g. via GET)
1097 #. existing setting in the session (stick to the setting we had before)
1098 #. auto-detect via the HTTP Accept-Language header sent by the user agent
1099
1100 Uses the global variables :php:global:`$_REQUEST["lang"]`, :php:global:`$_SERVER['HTTP_ACCEPT_LANGUAGE']`.
1101
1102 .. php:staticmethod:: normalise_translation($translation_code)
1103
1104 Normalise the translation code (e.g. from the old codes to the new)
1105
1106 :param string $translation_code: the translation code as specified in the keys of $translations
1107 :return: * (string) - a translation code or the empty string if it can't be normalised
1108
1109 .. php:staticmethod:: get_translation()
1110
1111 Get the set translation. The method uses :php:global:`$_SESSION['_config']['language']`
1112
1113 :returns: * (string) - a translation code or the empty string if not set
1114
1115 .. php:staticmethod:: set_translation($translation_code)
1116
1117 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']`.
1118
1119 :param string $translation_code: the translation code as specified in the keys of {@link $translations}
1120 :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)
1121
1122 .. php:staticmethod:: init_gettext($domain = 'messages')
1123
1124 Sets up the text domain used by gettext. Uses :php:global:`$_SESSION['_config']['filepath']` and appends '/locale'.
1125
1126 :param string $domain: the gettext domain that should be used, defaults to "messages"
1127
1128 .. php:staticmethod:: set_recipient_language($accountid)
1129
1130 Returns the language of a recipient to make sure that the language is correct
1131
1132 :param int $accountid: accountnumber of the recipient