more docs

9 years ago · 0d2eeb25e0
parent 28a943f4eb
commit 0d2eeb25e0
10 changed files with 252 additions and 10 deletions
--- a/9
+++ b/9
@ -1,3 +1,12 @@
+2015-07-15 13:54  marc
+
+	* ChangeLog, ax_check_qt.m4, ax_init_standard_project.m4,
+	  bootstrap.sh, configure.ac, doc, doc/doxyfile.in,
+	  doc/makefile.am, html/checknewuser.php, html/documentation.dox,
+	  html/functions.php, html/makefile.am, html/newuser.html,
+	  html/safechat.js, mac-create-app-bundle.sh, makefile.am: added
+	  some comments and dokus
+
 2015-07-09 11:14  marc

 	* ChangeLog: but one change is necessary for the test to succeed:
--- a/html/checknewuser.php
+++ b/html/checknewuser.php
@ -1,6 +1,16 @@
 <?php
 /*! @file

+    @id $Id$
+
+    @see @ref apichecknewuser
+
+    @page api Server API
+
+    @tableofcontents
+
+    @section apichecknewuser Check If User Exists
+
    API-call checknewuser.php

    Check if a user exists in the server's user table.
@ -9,8 +19,6 @@
    @return json encoded value:
      - 'user name as string', if user does exist
      - null, if user does not exist or in case of error
-
-    @id $Id$
 */
 //       1         2         3         4         5         6         7         8
 // 45678901234567890123456789012345678901234567890123456789012345678901234567890
--- a/html/documentation.dox
+++ b/html/documentation.dox
@ -5,11 +5,81 @@
 //       1         2         3         4         5         6         7         8
 // 45678901234567890123456789012345678901234567890123456789012345678901234567890

-/** @page protocol SafeChat Protocol
+/** @mainpage SafeChat

-    @tableofcontents
+    SafeChat runs on:
+    https://safechat.ch
+
+    SafeChat development is on:
+    https://dev.marc.waeckerlin.org/redmine/projects/safechat
+
+    Implementation Details: @ref security, @ref api, @ref protocol,
+    @ref database
+
+    SafeChat is a chat program designed to protect your privacy. It is
+    designed to be:
+    
+    -# extremely easy to use
+       -# zero installation
+       -# simple registration, within seconds
+       -# web 2.0 - works in any modern browser
+       -# user does not have to care about keys, security, encryption
+    -# all cool features
+       -# pseudonym accounts, no phone number, no email,nothing required
+       -# send images and other attachments
+       -# build groups
+       -# no need to be online, receive messages on next login
+       -# central user directory
+    -# absolutely secure
+       -# tap-proof
+       -# no metadata available
+         -# all messages are sent to all users, only the authorized users can decrypt it
+       -# server can be untrusted
+         -# thin server, rich client
+           -# all encryption is done in the client
+           -# server only stores minimal user data (name, public key) and encrypted messages
+           -# no access to plain data, not even through server confiscation
+       -# double secured internet transport
+         -# messages are encrypted for the recipents only
+         -# server connection is SSL secured in addition
+       -# private data fully in the user's hand
+         -# password is stored in the user's brain only
+         -# private key is password encrypted
+         -# private key is stored in the user's local machine only
+       -# two factor security, access needs two tokens
+         -# the password in the user's brain
+         -# the private key in the user's browser memory
+    -# fully open source
+
+    @section why Why I Created SafeChat
+
+    The Swiss parliament has decided to increase the power of police
+    (BÜPF: Bundesgesetz zur Überwachung des Post- und
+    Fernmeldeverkehrs) and secret service (NDG:
+    Nachrichtendienstgesetz). This increases global enforced data
+    preservation without any suspicion. This even allows the police to
+    run a trojan in computers of suspicious persons.

-    @section security Security Concept
+    That was the point, when I started to think about secure
+    communication that defeats these attacks against our
+    privacy. Noone should be able to read what's not for his eyes,
+    even if he controls the server. There should be no metadata,
+    i.e. no one should know, who is communicating to each other.
+
+    There are secure means of communication, i.e. Jabber/OTR and
+    PGP-Mail (but with unprotected metadata). But these are too
+    complicated for the avarage user. He has to take care about keys
+    and their distribution. In some chat programs, there is no offline
+    message store, so you can only send a message, if the receiver is
+    online. Some chat programs require to identify you, they ask your
+    phone number and some even steal your address book
+    (i.e. WhatsApp). Not here! Use any pseudonym. No special knowledge
+    needed. User is guided as much as possible, the interface is as
+    simple as possible. Data is only collected, if it is necessary.
+
+    So I present here the safe chat program for dummies
+
+    @page security Password and Secrets Concept

    Neither the password nor the private key are sent to the
    server. They remain under the user's control and in the user's
@ -27,6 +97,10 @@
    the local storage of his browser. Messages can only be sent or
    read with access to both security tokens.

+    @page protocol SafeChat Protocol
+
+    @tableofcontents
+
    @section newuser Create New User

    If no credentials exist in the browser's local storage, the
--- a/html/get.php
+++ b/html/get.php
@ -1,4 +1,33 @@
 <?php
+/*! @file
+
+    @id $Id$
+
+    @see @ref apiget
+
+    @page api
+
+    @section apiget Get Messages
+
+    API-call get.php
+
+    Get all messages that are newer than start.
+
+    @param start Number of message to start with.
+    @return json encoded array of messages:
+       @code
+           [
+             {
+               id: message-id,
+               time: unix-time-stamp,
+               user: 'sender's user name',
+               msg: 'armored and encrypted message as string'
+             }, ...
+           ]
+       @endcode
+*/
+//       1         2         3         4         5         6         7         8
+// 45678901234567890123456789012345678901234567890123456789012345678901234567890
 require_once("messagetable.php");
 try {
  $start = $db->real_escape_string($_REQUEST['start']);
--- a/html/login.php
+++ b/html/login.php
@ -1,4 +1,29 @@
 <?php
+/*! @file
+    
+    @id $Id$
+
+    @see @ref apilogin
+
+    @page api
+
+    @section apilogin Login
+
+    API-call login.php
+
+    Check if a user is consistent to the data in the server's database
+    or create a user, if he does not yet exist in the @ref usertable
+    (and the user name is available).
+
+    @param user user's name
+    @param pubkey user's public key
+
+    @return json encoded status with text:
+       - success() in case of success (user exists or has been created)
+       - error() in case of mismatch
+*/
+//       1         2         3         4         5         6         7         8
+// 45678901234567890123456789012345678901234567890123456789012345678901234567890
 try {
  require_once("usertable.php");
  $user = $db->real_escape_string($_REQUEST['user']);
@ -18,6 +43,6 @@ try {
    error("server database defect");
  }
 } catch (Exception $e) {
-  echo json_encode(array('success' => false, 'txt' => "login failed"));
+  error("login failed");
 }
 ?>
--- a/html/messagetable.php
+++ b/html/messagetable.php
@ -1,4 +1,26 @@
 <?php
+/*! @file
+
+    @id $Id$
+
+    @see @ref messagetable for the database schema
+
+    @page database Database
+
+    @section messagetable Message Table
+
+    <table>
+    <caption>Table: message</caption>
+    <tr><th>Colum Name</th><th>SQL Type</th><th>Description</th></tr>
+    <tr><td>id</td><td>int</td><td>Incrementing message id starting at 1.</td></tr>
+    <tr><td>time</td><td>timestamp</td><td>Time when message has been stored in the database.</td></tr>
+    <tr><td>user</td><td>varchar(50)</td><td>The sender's user name (pseudonym).</td></tr>
+    <tr><td>msg</td><td>longtext</td><td>The encryped and armored message text.</td></tr>
+    </table>
+*/
+//       1         2         3         4         5         6         7         8
+// 45678901234567890123456789012345678901234567890123456789012345678901234567890
+
 require_once("functions.php");
 mysqli_report(MYSQLI_REPORT_STRICT);
 try {
--- a/html/pubkey.php
+++ b/html/pubkey.php
@ -1,4 +1,30 @@
 <?php
+/*! @file
+
+    @id $Id$
+
+    @see @ref apipubkey
+
+    @page api
+
+    @section apipubkey Get Public Key
+
+    API-call pubkey.php
+
+    Get the public key of a user.
+
+    @param user Name of the user to ge public key from.
+
+    @return json encoded value:
+     - @c null in case of error (user does not exist)
+     - @code
+       {
+         pubkey: 'armored public key string'
+       }
+       @endcode
+*/
+//       1         2         3         4         5         6         7         8
+// 45678901234567890123456789012345678901234567890123456789012345678901234567890
 try {
  require_once("usertable.php");
  $user = $db->real_escape_string($_REQUEST['user']);
--- a/html/safechat.js
+++ b/html/safechat.js
@ -1,5 +1,7 @@
 /*! @file

+    @id $Id$
+
    This is the main application as it is fully run in the user's browser.

    @dot
@ -31,8 +33,6 @@
    sendmessage -> chat [label="remain in chat"];
    }
    @enddot
-
-    @id $Id$
 */
 //       1         2         3         4         5         6         7         8
 // 45678901234567890123456789012345678901234567890123456789012345678901234567890
@ -70,7 +70,7 @@ function error(data, stay) {

 /// Show notice messsage
 /** Fades in an notice message and logs to console.
-    @param data (optional) The data is a string. */
+    @param text (optional) The data is a string. */
 function notice(text) {
    $("#status").fadeOut("slow", function() {
        $("#status").addClass("notice")
@ -89,7 +89,7 @@ function notice(text) {

 /// Show notice messsage
 /** Fades in an success message and logs to console.
-    @param data (optional) The data is a string. */
+    @param text (optional) The data is a string. */
 function success(text) {
    $("#status").fadeOut("slow", function() {
        $("#status").addClass("success")
--- a/html/send.php
+++ b/html/send.php
@ -1,4 +1,30 @@
 <?php
+/*! @file
+
+    @id $Id$
+
+    @see @ref apisend
+
+    @page api
+
+    @section apisend Send Message To Server
+
+    API-call send.php
+
+    Send a message to the server. Sever checks if user exists and has
+    a valid public key. More test could be added later.
+
+    @param user The name of the user that send the message.
+
+    @param msg The armored signed and encrypted message. There is a
+               limit of 100000 bytes for the message.
+
+    @return
+      - success() if the message has been stored successfully
+      - error() in case of any error
+*/
+//       1         2         3         4         5         6         7         8
+// 45678901234567890123456789012345678901234567890123456789012345678901234567890
 try {
  require_once("usertable.php");
  $user = $db->real_escape_string($_REQUEST['user']);
--- a/html/usertable.php
+++ b/html/usertable.php
@ -1,4 +1,27 @@
 <?php
+/*! @file
+
+    @id $Id$
+
+    @see @ref usertable for the database schema
+
+    @page database Database
+
+    @tableofcontents
+
+    @section usertable User Table
+
+    <table>
+    <caption>Table: user</caption>
+    <tr><th>Colum Name</th><th>SQL Type</th><th>Description</th></tr>
+    <tr><td>name</td><td>varchar(50)</td><td>The user's name (pseudonym).</td></tr>
+    <tr><td>pubkey</td><td>text</td><td>The user's public key.</td></tr>
+    </table>
+
+*/
+//       1         2         3         4         5         6         7         8
+// 45678901234567890123456789012345678901234567890123456789012345678901234567890
+
 require_once("functions.php");
 mysqli_report(MYSQLI_REPORT_STRICT);
 try {