documentation updated

nodejs/doc/documentation.dox

@@ -7,40 +7,51 @@
 
 /** @mainpage SafeChat
 
-    SafeChat runs on:
+    SafeChat runs on: https://safechat.ch
-    https://safechat.ch
 
-    SafeChat development is on:
+    SafeChat is a chat program designed to protect your privacy. It's
-    https://dev.marc.waeckerlin.org/redmine/projects/safechat
+    open, cool, easy, open source and free.
 
-    Implementation Details: @ref security, @ref api, @ref protocol,
+    See @ref features for more goodies, and @ref why for a rationale.
-    @ref database, @ref design
 
-    SafeChat is a chat program designed to protect your privacy. It is
+    Implementation Details, see @ref security, @ref api, @ref
-    designed to be:
+    protocol, @ref database, @ref design */
+
+/** @page features Features and Benefits
+
+    Best features of SafeChat:
     
     -# 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
+       -# Android App available (later also for other phones)
     -# all cool features
-       -# pseudonym accounts, no phone number, no email,nothing required
+       -# full privacy:
-       -# send images and other attachments
+           -# pseudonym accounts, no phone number, no email, no private data required
+           -# still allows to identify yourself to your chat partners
+           -# all private data is stored on your computer
+           -# you decide who may see what
+           -# safechat.ch knows nothing about you
+       -# send images, videos and any other file attachments
+       -# make fotos on the handy and send them directly
        -# build groups
        -# no need to be online, receive messages on next login
-       -# central user directory
+       -# or, when online, open a direct 1:1 connection line
+       -# direct audio and video chat
+       -# distributed user directory
+       -# chat to mail, mail to chat gateways
+       -# send chat invitation links to friends
     -# 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
+           -# server only stores minimal data
            -# no access to plain data, not even through server confiscation
        -# double secured internet transport
-         -# messages are encrypted for the recipents only
+         -# messages are encrypted for the recipients 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
@@ -48,10 +59,11 @@
          -# 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
+         -# the private key in the user's browser storage
     -# fully open source
+    -# security concept and implementatino can be reviewed */
 
-    @section why Why I Created SafeChat
+/** @page why Why I Created SafeChat
 
     The Swiss parliament has decided to increase the power of police
     (BÜPF: Bundesgesetz zur Überwachung des Post- und
@@ -77,35 +89,26 @@
     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
+    So I present the safe chat program for dummies */
 
-    @page design Design
+/** @page design Design
 
     Safechat is designed to provide a safe chat program for
     dummies. Everything is simple to use, everything is strong
     enrcrypted, everything is open source. You can chat and you can
-    write encrypted e-mails from the same address.
+    write encrypted e-mails from the same address. The GUI shall be
-
+    minimal and straight forward.
-    <a href="https://www.eff.org/de/node/82654">SafeChat provides</a>:
-      - Encrypted in transit ✓
-      - Encrypted so the provider can't read it ✓
-      - You can verify contacts' identities ✓
-      - Past communications are secure if your key is stolen ✓
-      - Code is open to independent review ✓
-      - Security design is properly documented ✓
-      - Audit not yet done, we invite you to audit our code ✗
 
     @section overview System Overview
 
     @startuml{overview.png}
-      interface "user"
+      "user"
-      interface "user" as otheruser
+      "user" as otheruser
       [secret password]
       [secret password] as otherpassword
       user -up- [secret password]
       otheruser -up- [otherpassword]
       node "browser" {
-        [engine]
         folder "ecrypted local storage" {
           [public key]
 	  [private key]
@@ -114,7 +117,6 @@
         }
       }
       node "browser" as otherbrowser {
-        [engine] as otherengine
         folder "encrypted local storage" as otherstorage {
           [public key] as otherpubkey
           [private key] as otherprivkey
@@ -122,36 +124,57 @@
           [chat history] as otherhistory
         }
       }
-      cloud {
+      cloud "internet" {
-        node "safechat.ch" {
+       () WebRTC
+        node "safechat.ch" as safechatch {
+          () HTTPS
+          () WebSocket
           [safechat]
+          folder "mailservice" {
+            [roundcube] -down-  [DoveCot]
+            [DoveCot] -down- [postfix]
+          }
           database "sql" {
           }
+          [safechat] -up- HTTPS
+          [safechat] -up- WebSocket
+          [roundcube] -up- HTTPS
+          [safechat] -down- sql
         }
-        node "safechat.biz" {
+        node "safechat.biz" as safechatbiz {
+          () HTTPS as HTTPS2
+          () WebSocket as WebSocket2
           [safechat] as safechat2
+          folder "mailservice" as mailservice2 {
+            [roundcube] as roundcube2
+            [DoveCot] as DoveCot2
+            [postfix] as postfix2
+            [roundcube2] -down-  [DoveCot2]
+            [DoveCot2] -down- [postfix2]
+          }
           database "sql" as sql2 {
           }
+          [safechat2] -up- HTTPS2
+          [safechat2] -up- WebSocket2
+          [roundcube2] -up- HTTPS2
+          [safechat2] -down- sql2
         }
         node "keyserver" {
+          database "keys" {
+            folder "users / keys" {
+            }
+          }
         }
-        [engine] --down-- HTTP
-        [otherengine] --down-- HTTP
-        [engine] --down-- WebSocket
-        [otherengine] --down-- WebSocket
-        HTTP - [safechat]
-	HTTP - [safechat2]
-        WebSocket - [safechat]
-	WebSocket - [safechat2]
-        [engine] --down-- WebRTC
-        [otherengine] --down-- WebRTC
-        [engine] --down-- keyserver
-        [otherengine] --down-- keyserver
-        [safechat] -- keyserver
-	[safechat2] -- keyserver
       }
-      user - engine
+      safechatch --right-- safechatbiz
-      otheruser - otherengine
+      browser --down-- HTTPS
+      otherbrowser --down-- HTTPS2
+      browser --down-- WebSocket
+      otherbrowser --down-- WebSocket2
+      browser --down-- WebRTC
+      otherbrowser --down-- WebRTC
+      user -- browser
+      otheruser - otherbrowser
     @enduml
 
     @section registration Registration of New User
@@ -182,9 +205,18 @@
       "safechat.ch" -> keyserver [label="lookup(username)"];
       "safechat.ch" -> browser [label="logon success"];
       browser -> user [label="ready to chat"];
-    @endmsc
+    @endmsc */
 
-    @page security Password and Secrets Concept
+/** @page security Password and Secrets Concept
+
+    <a href="https://www.eff.org/de/node/82654">SafeChat provides</a>:
+      - Encrypted in transit ✓
+      - Encrypted so the provider can't read it ✓
+      - You can verify contacts' identities ✓
+      - Past communications are secure if your key is stolen ✓
+      - Code is open to independent review ✓
+      - Security design is properly documented ✓
+      - Audit not yet done, we invite you to audit our code ✗
 
     Neither the password nor the private key are sent to the
     server. They remain under the user's control and in the user's
@@ -200,9 +232,9 @@
     There are two secret security tokens: The password, that is in the
     user's mind and the private key, which is in the user's device, in
     the local storage of his browser. Messages can only be sent or
-    read with access to both security tokens.
+    read with access to both security tokens. */
 
-    @page protocol SafeChat Protocol
+/** @page protocol SafeChat Protocol
 
     @tableofcontents
 
@@ -228,25 +260,27 @@
     browser -> server [label="login.php(username, public-key)"];
     server -> server [label="if user name does not exist:\nstore username/public-key"];
     server -> browser [label="success"];
-    @endmsc
+    @endmsc */
 
-*/
+/** @page api API Calls
+    
+    Different users can be on different servers. Servers are connected
+    through @ref serverapi. The client browser first loads the
+    index.html file with HTTPS from server, which loads the javascript
+    code. From then on, everything happens through JSON over
+    WebSockets using @ref clientapi.
 
-/** @page api Server API Calls
+    There are several APIs provided by safechat:
+     - @ref clientapi
+     - @ref serverapi
+     - Webmail with Roundcube
+     - SMTP using e.g. postfix
+     - IMAP using e.g. DoveCot */
 
-    @tableofcontents
+/** @page clientapi Client - Server API Calls
 
-    List of server REST API calls. SafeChat server implement s REST
+    @tableofcontents */
-    API, so that all API calls are in the following form, where
-    parameters and values are url encoded:
 
-    @code
+/** @page serverapi Server - Server API Calls
-    https://safechat.ch/api-call.php?param1=value1&param2=value2[...]
-    @endcode
 
-    So for method get() a valid call could be:
+    @tableofcontents */
-    @code
-    https://safechat.ch/get.php?start=100
-    @endcode
-    
-*/