README.md
author Roker <roker@pep-project.org>
Thu, 07 Jun 2018 12:44:11 +0200
branchJSON-93
changeset 537 ff1cdc290c32
parent 517 81d5fff0b732
child 541 030b53a59cab
permissions -rw-r--r--
JSON-94: re-implement combining of UTF-16 surrogate pairs. the 1st implementation was nuts. :-9
Thomas@233
     1
# p≡p JSON Server Adapter
roker@0
     2
roker@231
     3
## Introduction
roker@240
     4
The p≡p JSON Server Adapter provides a REST-like jQuery-compatible API to
roker@240
     5
connect with the p≡p engine.  It is language-independent and can be used by
roker@240
     6
any client.
roker@231
     7
damiano@275
     8
## Requirements
damiano@275
     9
In order to use the p≡p JSON Server Adapter, you need to build and run it.
roker@290
    10
Currently, Linux (Debian 9, Ubuntu 16.04) and MacOS (10.11, 10.12) are
roker@290
    11
supported, Windows is about to follow.  Newer versions should also work
roker@290
    12
(file a bug report if not) but are not in our main focus, yet.
roker@231
    13
damiano@275
    14
## Dependencies
roker@252
    15
* C++ compiler: tested with g++ 4.8 and 4.9, and clang++ 2.8. Newer versions should work, too.
roker@2
    16
* GNU make
roker@252
    17
* libboost-thread-dev (tested with 1.58)
roker@252
    18
* libboost-program-options-dev  (tested with 1.58)
roker@252
    19
* libboost-filesystem-dev (tested with 1.58)
roker@252
    20
* libevent-dev 2.0.21 or 2.0.22 (or build from source, see below)
roker@290
    21
* [p≡p Engine](https://letsencrypt.pep.foundation/trac/wiki/Basic%20Concepts%20of%20p%E2%89%A1p%20engine)
roker@290
    22
  (which needs gpgme-thread, a patched libetpan, libboost-system-dev)
damiano@275
    23
* OSSP libuuid
roker@0
    24
damiano@275
    25
## Building/Installing
damiano@275
    26
### Install the dependencies
damiano@275
    27
Debian 9:
roker@0
    28
damiano@275
    29
~~~~~
roker@318
    30
apt install -y build-essential libboost1.62-dev libboost-system1.62-dev \
roker@318
    31
    libboost-filesystem1.62-dev libboost-program-options1.62-dev \
roker@478
    32
    libboost-thread1.62-dev libgpgme-dev uuid-dev googletest
damiano@275
    33
~~~~~
roker@0
    34
damiano@275
    35
macOS 10.12:
damiano@275
    36
damiano@275
    37
Use homebrew or macports to install the required libraries.
damiano@275
    38
roker@318
    39
For more explicit instructions on how to do this with macports, see the
roker@318
    40
section below.
damiano@275
    41
roker@290
    42
Build and install the pEp Engine.  Instructions can be found here:
roker@290
    43
[https://cacert.pep.foundation/dev/repos/pEpEngine/file/ef23982e4744/README.md](https://cacert.pep.foundation/dev/repos/pEpEngine/file/ef23982e4744/README.md).
damiano@275
    44
damiano@275
    45
### Build and install libevent
damiano@275
    46
~~~~~
damiano@275
    47
mkdir ~/code/json-ad
damiano@275
    48
hg clone https://cacert.pep.foundation/dev/repos/pEpJSONServerAdapter/ ~/code/json-ad
damiano@428
    49
cd ~/code/json-ad/libevent-2.0.22-stable
damiano@275
    50
./configure --prefix="$HOME/code/json-ad/libevent-2.0.22-stable/build/" --disable-openssl
Thomas@233
    51
make
damiano@275
    52
make install
damiano@275
    53
~~~~~
Thomas@233
    54
damiano@275
    55
### Build and install the JSON server
damiano@275
    56
~~~~~
damiano@429
    57
cd ~/code/json-ad/server
damiano@275
    58
~~~~~
Thomas@233
    59
roker@290
    60
Edit the build configuration to your needs in `./Makefile.conf`, or create a
roker@290
    61
`./local.conf` that sets any of the make variables documented in
roker@290
    62
`./Makefile.conf`.
Thomas@233
    63
roker@290
    64
If a dependency is not found in your system's default include or library
roker@290
    65
paths, you will have to specify the according paths in a make variable. 
roker@290
    66
Typically, this has to be done at least for the pEp Engine, libetpan and
roker@290
    67
libevent.
Thomas@233
    68
damiano@275
    69
Below are two sample `./local.conf` files, for orientation.
Thomas@233
    70
damiano@275
    71
macOS 10.12:
Thomas@233
    72
damiano@275
    73
~~~~~
damiano@275
    74
PREFIX=$(HOME)/code/json-ad/build
damiano@275
    75
HTML_DIRECTORY=$(PREFIX)/share/pEp/json-adapter/html
damiano@424
    76
GTEST_DIR=$(HOME)/code/gtest/googletest
Thomas@233
    77
damiano@275
    78
BOOST_INC=-I$(HOME)/Cellar/boost/1.65.1/include
damiano@275
    79
BOOST_LIB=-L$(HOME)/Cellar/boost/1.65.1/lib
Thomas@233
    80
damiano@275
    81
ENGINE_INC=-I$(HOME)/code/engine/build/include
damiano@275
    82
ENGINE_LIB=-L$(HOME)/code/engine/build/lib
Thomas@233
    83
damiano@275
    84
ETPAN_INC=-I$(HOME)/code/libetpan/build/include
damiano@275
    85
ETPAN_LIB=-L$(HOME)/code/libetpan/build/lib
Thomas@233
    86
damiano@275
    87
EVENT_INC=-I$(HOME)/code/json-ad/libevent-2.0.22-stable/build/include
damiano@275
    88
EVENT_LIB=-L$(HOME)/code/json-ad/libevent-2.0.22-stable/build/lib
damiano@275
    89
damiano@275
    90
GPGME_INC=-I$(HOME)/Cellar/gpgme/1.9.0_1/include
damiano@275
    91
GPGME_LIB=-L$(HOME)/Cellar/gpgme/1.9.0_1/lib
damiano@275
    92
damiano@275
    93
UUID_INC=-I$(HOME)/Cellar/ossp-uuid/1.6.2_2/include
damiano@275
    94
UUID_LIB=-L$(HOME)/Cellar/ossp-uuid/1.6.2_2/lib
damiano@275
    95
~~~~~
damiano@275
    96
damiano@275
    97
Debian 9:
damiano@275
    98
damiano@275
    99
~~~~~
damiano@275
   100
PREFIX=$(HOME)/code/json-ad/build
damiano@275
   101
HTML_DIRECTORY=$(PREFIX)/share/pEp/json-adapter/html
roker@477
   102
GTEST_DIR=/usr/src/googletest/googletest/
damiano@275
   103
damiano@275
   104
ENGINE_INC=-I$(HOME)/code/engine/build/include
damiano@275
   105
ENGINE_LIB=-L$(HOME)/code/engine/build/lib
damiano@275
   106
damiano@275
   107
ETPAN_INC=-I$(HOME)/code/libetpan/build/include
damiano@275
   108
ETPAN_LIB=-L$(HOME)/code/libetpan/build/lib
damiano@275
   109
damiano@275
   110
EVENT_INC=-I$(HOME)/code/json-ad/libevent-2.0.22-stable/build/include
damiano@275
   111
EVENT_LIB=-L$(HOME)/code/json-ad/libevent-2.0.22-stable/build/lib
damiano@275
   112
~~~~~
damiano@275
   113
damiano@275
   114
Now, build and install the server:
damiano@275
   115
damiano@275
   116
~~~~~
damiano@275
   117
make all
damiano@275
   118
make install
damiano@275
   119
~~~~~
damiano@275
   120
damiano@275
   121
With `make test` you can execute the server's tests.
damiano@275
   122
damiano@275
   123
### Macports
damiano@275
   124
[Install MacPorts](https://www.macports.org/install.php) for your version of macOS.
Thomas@233
   125
roker@240
   126
If MacPorts is already installed on your machine, but was installed by a
roker@240
   127
different user, make sure your `PATH` variable is set as follows in
roker@240
   128
`~/.profile`:
Thomas@233
   129
Thomas@233
   130
```
Thomas@233
   131
export PATH="/opt/local/bin:/opt/local/sbin:$PATH"
Thomas@233
   132
```
Thomas@233
   133
Thomas@233
   134
Install dependencies packaged with MacPorts as follows.
Thomas@233
   135
Thomas@233
   136
```
damiano@275
   137
sudo port install gpgme boost ossp-uuid
Thomas@233
   138
```
Thomas@233
   139
damiano@275
   140
## Running the pEp JSON Adapter
damiano@275
   141
You can use `make run` to start the server.
roker@0
   142
roker@231
   143
1. Run ./pep-json-server.  This creates a file that is readable only by the
roker@517
   144
   current user (~/.pEp/json-token-${USER}) and contains the address and
roker@231
   145
   port the JSON adapter is listening on, normally 127.0.0.1:4223 and a
roker@231
   146
   "security-token" that must be given in each function call to authenticate
roker@240
   147
   you as the valid user.
Thomas@233
   148
Thomas@233
   149
   ```
Thomas@233
   150
   ./pep-json-server
roker@240
   151
   ```
Thomas@233
   152
roker@231
   153
2. Visit that address (normally http://127.0.0.1:4223/) in your
roker@254
   154
   JavaScript-enabled web browser to see the "JavaScript test client".
Thomas@233
   155
3. Call any function ("version()" or "get_gpg_path()" should work just
roker@231
   156
   fine) with the correct security token.
roker@2
   157
roker@231
   158
## Using the p≡p JSON Adapter
roker@2
   159
roker@231
   160
In the following section, you'll find background information on how to use
roker@231
   161
the adapter and its functions.
roker@2
   162
roker@277
   163
### Server startup and shutdown
roker@277
   164
roker@277
   165
The JSON Server Adapter can be started on demand.
roker@277
   166
It checks automatically whether an instance for the same user on the machine
roker@277
   167
is already running and if yes it ends itself gracefully.
roker@277
   168
roker@277
   169
If there is no running server found the newly started server creates the
roker@277
   170
server token file and forks itself into background (if not prevented via
roker@277
   171
"-d" commandline switch).
roker@277
   172
roker@277
   173
roker@240
   174
### Session handling
roker@0
   175
roker@240
   176
When using the p≡p engine, a session is needed to which any adapter can
hernani@251
   177
connect. The p≡p JSON Server Adapter automatically creates one session per
roker@240
   178
HTTP client connection (and also closes that session automatically when the
hernani@251
   179
client connections is closed). Therefore, the client does not need to take
hernani@251
   180
care of the session management. However, the client has to set up a [HTTP
roker@240
   181
persistent
roker@240
   182
connection](https://en.wikipedia.org/wiki/HTTP_persistent_connection).
roker@1
   183
Thomas@233
   184
### API Principles
roker@2
   185
roker@240
   186
All C data types are mapped the same way, so some day the JSON wrapper can
roker@240
   187
be generated from the p≡p Engine header files (or the JSON wrapper and the
roker@240
   188
p≡p engine header are both generated from a common interface description
hernani@251
   189
file).
roker@2
   190
Thomas@233
   191
| C type | JSON mapping |
Thomas@233
   192
|--|--|
Thomas@233
   193
| `bool` | JSON boolean |
roker@240
   194
| `int` | JSON decimal number |
roker@240
   195
| `size_t` | JSON decimal number |
Thomas@233
   196
| `char*` (representing a UTF-8-encoded NULL-terminated string | JSON string |
Thomas@233
   197
| `char*` (representing a binary string | base64-encoded JSON string |
roker@240
   198
| `enum` | either JSON decimal number or JSON object containing one decimal number as member |
Thomas@233
   199
| `struct` | JSON object |
Thomas@233
   200
| linked lists (e.g. `bloblist_t`, `stringlist_t`, `identity_list` etc.) | JSON array of their member data type (without the `next` pointer) |
roker@159
   201
roker@240
   202
The parameter type PEP_SESSION is handled automatically by the JSON Server
roker@240
   203
Adapter and the PEP_SESSION parameter is omitted from the JSON API.
roker@240
   204
roker@240
   205
#### enum types
hernani@251
   206
roker@240
   207
Enum types are represented as JSON objects with one member, whose name is
roker@240
   208
derived from the enum type name, holding the numeric value of the enum.
roker@240
   209
roker@240
   210
Some enum types are still represented directly as JSON decimal number. It
roker@240
   211
shall be changed in a future version of the JSON Adapter.
roker@240
   212
roker@240
   213
#### String types
hernani@251
   214
roker@240
   215
The JSON Server Adapter does automatic memory management for string
roker@240
   216
parameters. The current p≡p Engine's API distinguish between `const char*`
roker@240
   217
parameters and `char*` parameters.  `const char*` normally means: the
roker@240
   218
"ownership" of the string remains at the caller, so the JSON Adapter frees
roker@240
   219
the string automatically after the call.  `char*` normally means: the
roker@240
   220
"ownership" of the string goes to the Engine, so the JSON Adapter does _not_
roker@240
   221
free string.
roker@240
   222
roker@240
   223
If there are functions that have a different semantics the behavior of the
roker@240
   224
JSON wrapper has to be changed.
roker@240
   225
hernani@251
   226
#### Parameter (value) restrictions
roker@240
   227
roker@240
   228
Some API functions have restrictions on their parameter values.  The JSON
roker@240
   229
Adapter does not know these restrictions (because it does not know the
roker@240
   230
semantics of the wrapped functions at all).  So it is the client's
roker@240
   231
responsibility to fulfill these parameter restrictions!  Especially when
roker@240
   232
there are restrictions that are checked with assert() within the p≡p Engine,
roker@240
   233
it is impossible for the JSON Adapter to catch failed assertions - the
roker@240
   234
Engine and the Adapter process will be terminated immediatetely when the
roker@240
   235
Engine is compiled in debug mode (= with enabled assert() checking).
roker@240
   236
roker@240
   237
Currently there are no range checks for numerical parameter types (e.g. a
roker@240
   238
JSON decimal number can hold a bigger value than the `int` parameter type of
roker@240
   239
a certain C function).
roker@240
   240
Thomas@233
   241
### API Reference
roker@2
   242
roker@240
   243
An complete overview with all functions that are callable from the client
roker@240
   244
can be found in the [API Reference](pEp JSON Server Adapter/API Reference).
roker@231
   245
roker@254
   246
That API reference is a generated file that shows the current API briefly.
roker@254
   247
There is also a (currently manually written) file that holts a copy of the
roker@254
   248
documentation from the Engine's header files: [API reference detail.md]
roker@254
   249
roker@240
   250
Most of the callable functions are functions from the C API of the p≡p
roker@240
   251
Engine.  They are described in detail, incl.  pre- and post-conditions in
roker@240
   252
the appropriate C header files of the Engine.
roker@240
   253
roker@240
   254
roker@277
   255
### Authentication
roker@277
   256
hernani@279
   257
The JSON Server Adapter and the client have to authenticate to each other.
roker@277
   258
"Authentication" in this case means "run with the same user rights". This is
roker@277
   259
done by proving that each communication partner is able to read a certain
roker@277
   260
file that has user-only read permissions.
roker@277
   261
roker@290
   262
0. There is a common (between client & server) algorithm to create the path
roker@318
   263
   and filename of the "server token file", for a given user name.
roker@318
   264
   The token file and its directory MUST be owned by the user and MUST be
roker@318
   265
   readable and writable only by the user, nobody else.  Client and server
roker@318
   266
   check for the right ownership and access rights of the token file and its
roker@318
   267
   directory. (TODO: What shall be done if that check fails?)
roker@277
   268
roker@517
   269
1. The server creates a "server token file" containing a "server token" (a
roker@517
   270
   random-generated string of printable ASCII characters) and the IP address
roker@517
   271
   and port where the server listens on.  This file can only be read by
roker@517
   272
   client programs that run with the same user rights.
roker@277
   273
roker@318
   274
2. The client checks the path, reads the "server token" from the file and
roker@290
   275
   authenticates itself to the server in each JSON RPC call with that "server
roker@290
   276
   token".
roker@277
   277
roker@277
   278
roker@240
   279
## Extending / customizing
roker@231
   280
roker@231
   281
If you want to extend or customize the p≡p JSON Adapter, there are several
roker@240
   282
rules and definitions to take into account.
roker@231
   283
roker@231
   284
### Definitions
roker@1
   285
roker@302
   286
* The `FunctionMap function` in `ev_server.cc` defines which functions
roker@240
   287
  are callable via the JSON-RPC interface.  The existing entries show the
roker@240
   288
  syntax of that map.
roker@517
   289
  Non-static member functions can be called, too. Thanks to `std::function<>`
roker@302
   290
  a member function `Foo::func(Params...)` is handled like a free-standing
roker@302
   291
  function `func(Foo* f, Params...)`.
roker@1
   292
roker@1
   293
* For each type there must exist specializations of the template classes
roker@1
   294
  "In" (for input parameters) and "Out" (for output parameters).
roker@231
   295
  The linker will tell you, which specializations are needed.
roker@1
   296
roker@240
   297
* The specializations for "generic types" are in `function_map.cc`.
roker@1
   298
roker@240
   299
* The specializations for "p≡p-specific types" are in `pep-types.cc`.
roker@1
   300
Thomas@233
   301
roker@517
   302
#### Parameter directions (In, Out, InOut)
roker@517
   303
roker@517
   304
The p≡p JSON Server Adapter supports Input, Output and two ways of "In/Out"
roker@517
   305
parameters.  You have to annotate the direction in the FunctionMap with
roker@517
   306
`In<>` for input, `Out<>` for output and InOut<> or InOutP<> for in/out
roker@517
   307
parameters.  These wrapper classes have an optional second template
roker@517
   308
parameter (parameter type flag) that is explained below.
roker@517
   309
roker@517
   310
Return values are always "output" parameters, so they don't have to be
roker@517
   311
wrapped with `Out<>`, but this wrapper is necessary when you need
roker@517
   312
non-default wrapper semantics, see below.
roker@517
   313
roker@517
   314
roker@517
   315
Input parameters of fundamental or simple struct types are
roker@517
   316
usually by-value parameters. Complex structs (or structs that are only
roker@517
   317
forward-declared in the public API) are usually pointer
roker@517
   318
parameters. Both ways are supported. You have to specialize `In<T>` or
roker@517
   319
`In<T*>`, depending how your type is used.
roker@517
   320
roker@517
   321
Output parameters of fundamental or simple struct types `T` are usually
roker@517
   322
declared as a paremeter of type `T*`. The p≡p JSON Server Adapter manages
roker@517
   323
the memory allocated by the called C function automatically and calls the
roker@517
   324
appropriate de-allocating function after use.
roker@517
   325
roker@517
   326
Calling a function with output parameters requires a dummy value (`null` or
roker@517
   327
empty string is fine) at the JSON side for each output parameter to keep the
roker@517
   328
number of parameters at the JSON side the same with the C side.
roker@517
   329
roker@517
   330
For In/Out parameters there exist two calling conventions for
roker@517
   331
call-by-pointer types:
roker@517
   332
roker@517
   333
1. caller allocates object and fills with input values, callee can only change members.
roker@517
   334
The C type of the parameter is usually `struct T*`. Use the wrapper `InOut<>`
roker@517
   335
for these parameters.
roker@517
   336
roker@517
   337
2. caller allocates object and fills with input values, callee might
roker@517
   338
change/reallocate the whole object. The C type of the parameter is
roker@517
   339
`struct T**`. Use the wrapper `InOutP<>` in these cases.
roker@517
   340
roker@517
   341
`InOutP<>` is also the right wrapper for in/out parameters of fundamental or
roker@517
   342
enum types due to the additional indirection in the C function call
roker@517
   343
signature.
roker@517
   344
roker@517
   345
roker@517
   346
#### Parameter type flags
roker@517
   347
roker@517
   348
The wrapper classes might be instantiated with special "parameter type
roker@517
   349
flags". If no flag is given the `DefaultFlag` is used with means the
roker@517
   350
semantics described already above.
roker@517
   351
roker@517
   352
At the moment there exist two parameter type flags which are interpreted as
roker@517
   353
bitfield, so they can be combined:
roker@517
   354
roker@517
   355
* NoInput : This flags a parameter at the C side that shall not be exposed
roker@517
   356
  at the JSON side. So the value cannot be specified by the client, it is
roker@517
   357
  provided by the JSON Server Adapter internally (e.g. for PEP_SESSION)
roker@517
   358
roker@517
   359
* DontOwn : Used for pointer types who don't "own" the referred ressource,
roker@517
   360
  so it is not released automatically by the JSON Server Adapter after the
roker@517
   361
  call.
roker@517
   362
roker@517
   363
More flags will be added when different semantics will be needed.
roker@517
   364
roker@517
   365
roker@231
   366
## TODOs
roker@1
   367
roker@231
   368
The following issues are planned but not yet implemented.
roker@231
   369
roker@517
   370
* More sensible unit tests
roker@2
   371
Thomas@233
   372
* Generate all the tedious boiler plate code
roker@1
   373
    * the content of pep-types.cc
roker@1
   374
    * perhaps the FunctionMap 'function' in mt-server.cc
roker@1
   375
    * perhaps the JavaScript side of the HTML test page to ensure to be
roker@1
   376
      consistent with the server side in pep-types.cc
roker@2
   377
Thomas@233
   378
* Adapt the "p≡p Transport API", when it is final. (either manually or by
roker@231
   379
  code generator, if ready)
roker@290
   380
roker@290
   381
roker@291
   382
## Appendix A: Attack scenarios on the authentication
roker@290
   383
roker@290
   384
Let's discuss different attack / threat scenarios. I don't know which are
roker@290
   385
realistic or possible, yet.
roker@290
   386
roker@293
   387
### General ideas / improvements
roker@293
   388
roker@318
   389
Currently the JSON Server Adapter writes its server token file in a
roker@318
   390
directory that is only readable & writable by the user itself.
roker@293
   391
roker@318
   392
The server token file is written in $HOME/.pEp/json-token on
roker@318
   393
UNIX/Linux/MacOS and %LOCALAPPDATA%/pEp/json-token on MS Windows.
roker@293
   394
roker@293
   395
The JSON Server Adapter also checks whether .pEp has 0700 access rights
roker@293
   396
on unixoid systems.
roker@293
   397
roker@293
   398
roker@291
   399
### Attacker with the same user rights
roker@291
   400
roker@291
   401
If the attacker is able to run his malicious code with the same user
roker@318
   402
rights as the JSON Server Adapter and his legitimate client, it is (and
roker@318
   403
always will be) *impossible* to prevent this attack. Such an attacker also
roker@291
   404
can just start a legitimate client that is under his control.
roker@291
   405
roker@291
   406
The same applies to an attacker who gains root / admin access rights.
roker@291
   407
roker@292
   408
### Fake Server with different user rights
roker@292
   409
roker@292
   410
```
roker@292
   411
 ,----------.      ,--------.
roker@292
   412
 | Attacker | <==> | Client |
roker@292
   413
 `----------'      `--------'
roker@292
   414
```
roker@292
   415
roker@292
   416
If no real JSON Adapter runs an attacker can create a fake server that
roker@292
   417
pretends to be a legitimate JSON Adapter. It creates its own server token
roker@292
   418
file, with different and conspicuous access rights, but a limited
roker@292
   419
JavaScript client might be unable to detect the file permissions.
roker@292
   420
roker@292
   421
This fake server cannot access the private key of the user but it might
roker@292
   422
get sensitive plaintext data the client wants to encrypt. The fake server
roker@292
   423
cannot sign the encrypted data so the fake would be conspicuous, too. But
roker@292
   424
that would be too late, because the sensitive plaintext data could
roker@292
   425
already be leaked by the fake server.
roker@292
   426
roker@318
   427
This attack needs a user's home directory that is writable by someone else
roker@318
   428
(to create a ~/.pEp/ directory) or a foreign-writable ~/.pEp/ directory.
roker@318
   429
roker@318
   430
The pEpEngine creates a ~/.pEp/ directory (if not yet exists) and sets the
roker@318
   431
permissions to 0700 explicitly.
roker@292
   432
roker@291
   433
roker@290
   434
### Man-in-the-middle with different user rights
roker@290
   435
roker@290
   436
```
roker@290
   437
 ,---------------------.      ,----------.      ,--------.
roker@290
   438
 | JSON Server Adapter | <==> | Attacker | <==> | Client |
roker@290
   439
 `---------------------'      `----------'      `--------'
roker@290
   440
```
roker@290
   441
roker@290
   442
* The attacker cannot read "client token file" nor "server token file".
roker@290
   443
* The server cannot check "who" connects to it, until the client
roker@290
   444
  authenticates itself, which might be relayed by the attacker from the
roker@290
   445
  original client.
roker@290
   446
* The attacker has to convince the client that it is a legitimate server. It
roker@290
   447
  has to create a fake "server token file" to divert the client to the
roker@291
   448
  attacker's port. But that fake file cannot contain the right server token
roker@291
   449
  because the attacker does not know it.
roker@290
   450
  * if the server started before the attacker the "server token file"'s
roker@290
   451
    access rights should prevent this (no write access for the attacker, no
roker@290
   452
    "delete" right in common TEMP dir (sticky bit on the directory)
roker@290
   453
  * if the attacker starts before the server it can write a fake toke file.
roker@290
   454
    The server could detect it but is unable to notice the legitimate
roker@290
   455
    client. The client could detect it when it can check the file access
roker@290
   456
    rights.
roker@290
   457
    There might be race conditons...
roker@291
   458
roker@291
   459
* Is it possible for the attacker to let the client send the right server
roker@291
   460
  token to him, at least temporarily (e.g. within a race condition)?
roker@291
   461
  * As long as the server runs, the attacker cannot bind to the same address
roker@291
   462
    & port. Finding and binding of the port is done by the server before the
roker@291
   463
    server token file is created and filled.
roker@291
   464
  * When the server that created the "server token file" dies, its port
roker@291
   465
    becomes available for the attacker, but the server token is no longer
roker@291
   466
    valid and no longer useful for the attacker.
roker@291
   467
* there _might_ be a very _small_ chance for a race condition:
roker@291
   468
  1. The attacker opens a connection to the running server but does not
roker@291
   469
    use it. To find the server it cannot read the server configuration
roker@291
   470
    file, but it can ask the OS for ports that are open in "listen" mode.
roker@291
   471
    Normally the JSON Adapter listens on 4223 or some port numbers above
roker@291
   472
    that. That means: guessing the server's address is quite easy.
roker@291
   473
  2. when the server shuts down, the attacker immediately binds itself to
roker@291
   474
    that port. If a client connects just in this moment it sends the server
roker@291
   475
    token to the attacker, not to the server. But the attacker can use that
roker@291
   476
    token now to the server via the already opened TCP connection.
roker@291
   477
  3. To prevent this the server should call shutdown(2) on its listening
roker@291
   478
    socket to block any new client connection, but still block the port.
roker@291
   479
    (is that the case on all platforms?) Than close(2) all TCP connections
roker@291
   480
    to the clients (if any) and than also delete the server token file.
roker@291
   481
    Finally call close(2) on the listening socket.